Tools

A tool lets the agent do something instead of only saying something: look up an order, search your knowledge base, text a link, transfer to a person, hang up.

Caller:  "Where's my order? It's 4-8-2-9-1."
Agent:   [calls lookup_order with order_id 48291]
Agent:   "That one shipped Tuesday. It's due with you tomorrow."

You never tell the agent when to call a tool. On every turn the model reads each tool's description and decides for itself, which makes the description an instruction rather than a label.

Tools live on the Tools page of the agent editor. The left side lists the agent's tools, and clicking one opens its editor on the right. On a phone you drill into a tool and back out again.

Two kinds of tool

Builtin tools run inside Meddle. We write and maintain the handler, so there is nothing to configure. You pick one and tune its description.

Webhook tools call your own HTTPS endpoint. This is how the agent reaches your CRM, your ordering system, or anything else you run.

Most agents mix both: the builtin search_knowledge_base and transfer_to_human next to a webhook lookup_order that hits your own system.

The full catalogue of builtins is on Builtin tools.

Building a webhook tool

A webhook tool describes one HTTP request. You fill in four cards.

Identity

A snake_case name the model sees, such as lookup_order, and a description that tells the model when to call it. Write the description for the model, not for a human reader.

Request

The URL, the method, and the parameters the model fills in from the conversation.

• GET sends parameters as a query string. Use it for lookups.
• POST sends parameters as a JSON body. Use it for anything that changes something.

GET   https://api.example.com/orders?order_id=...
POST  https://api.example.com/returns      (parameters go in the JSON body)

Each parameter has a name, a type, a description and an optional required flag. The parameter description matters as much as the tool description, because it tells the model what to put there.

Miss a required parameter and the runtime returns an error naming it rather than sending a broken request. The model supplies it on the next turn.

Headers

Static headers sent with every request, usually authentication.

Variables and secrets

Write {{token}} anywhere in the URL, a header or the body and the runtime substitutes the value at call time.

URL:    {{crm_base_url}}/customers
Header: Authorization: Bearer {{crm_api_key}}

Use a plain variable for a base URL or an account ID, and a secret variable for an API key. Secrets are stored encrypted and read only by the runtime, so a key never enters the model's context. See variables and secrets.

Prerequisites

Some tools should only run after another has succeeded. The usual case: do not reveal order details until the caller has passed verify_order_code.

List the tools that must run first under the later tool's prerequisites.

lookup_order        requires: verify_order_code
get_order_status    requires: verify_order_code
start_return        requires: verify_order_code

That is a list of names, not a diagram.

Call a tool before its prerequisites have run and it does not fire. The runtime returns a short precondition_unmet message naming the tools that still need to run, and the model self-corrects on its next turn, usually by calling the missing one first.

The gate is success-aware. A prerequisite counts only if it actually succeeded, so a failed verification never unlocks the tools it guards.

Tool errors are instructions

A failing tool does not crash the call and does not invent a result. It returns a short message written for the model, saying what happened and what to do next.

• A timeout tells the model to apologise and offer a transfer or another try.
• Your endpoint's own error body is handed back, so the model can read the real reason.
• A missing input is named, so the model can supply it and call again.

That is why a broken integration usually sounds like a graceful recovery rather than a dead end.

Writing a good description

Four rules that hold up on real calls.

• Say when to call it, not just what it is. "Search the knowledge base before answering a question about pricing, hours or policies" beats "searches the knowledge base".
• State the order when order matters. "Call this first, before revealing any order details" is what makes a verification tool actually run first.
• Name the recovery. If the tool can fail or return nothing, say what the agent should do then.
• Describe every parameter. Vague parameters produce wrong calls.

What the caller hears while a tool runs

The agent speaks no scripted holding line. A quiet typing sound covers the wait instead, so the caller knows something is happening. You control it on the agent's Ambience page.

A read-only lookup with no side effects can be marked background-safe. The agent then keeps talking while it runs, and voices a brief "still working on it" if the lookup drags. Anything that changes something, such as a booking, is not background-safe: the agent waits.

Testing with a mock

You do not need a finished endpoint to test an agent.

1. Build the tool's identity, request and parameters as if the endpoint existed.
2. Turn on mock response and paste a realistic body. You can reference {{variables}} in it.
3. Add a delay if you want to hear how the agent handles a slow lookup.
4. Test the agent.
5. When your endpoint is ready, turn the mock off. The same tool now calls the real URL.

The model sees a mock exactly as it would see a real result, with no marker saying it is fake. Mocks still enforce required parameters and can reject a non-matching input, so you can test a verification gate honestly rather than only the happy path.

Tool edits are saved explicitly, land in a draft, and reach live callers only when you publish.