Tools

A tool lets an agent do something mid-conversation: look up an order, check a calendar, create a ticket. Without tools an agent can only talk about what it already knows.

Creating a tool

Tools are created once under Tools and reused by any agent. A tool has:

• a name and description - the model reads these to decide when to call it, so write them for the model, not for yourself. The model sees the name as a function name: lowercased, with spaces and punctuation turned into underscores (Lookup Order becomes lookup_order)
• a kind - what it actually does
• parameters - a JSON schema describing its arguments
• a configuration - what the kind needs: a URL, a server, a connection

Kinds

An Integration tool names its connection in the tool's own configuration. The model never picks the destination, only fills in the arguments, so a caller cannot talk an agent into posting somewhere it was not given.

A tool is what the agent calls during a conversation, to look something up or act on it and then use the answer. Reacting to a call after it ends is a different job: use an automation or a webhook on session.completed.

Parameters

The parameters schema is the contract between the model and your tool. It is what the model fills in:

{
  "type": "object",
  "properties": {
    "order_id": { "type": "string", "description": "The order number the caller gave" }
  },
  "required": ["order_id"]
}

Describe each field. A field the model cannot understand is a field it will guess.

Arguments in the configuration

The model's arguments reach your system through {{name}} placeholders in the tool's configuration. For an HTTP tool:

{
  "method": "POST",
  "url": "https://api.example.com/orders/lookup",
  "headers": { "X-Api-Key": "<your service's key>" },
  "body": { "order_id": "{{order_id}}", "source": "voice-agent" }
}

When the model calls the tool, {{order_id}} is replaced with the argument of that name. Things to know:

• Only the model's arguments are available to a tool the model calls. Session variables are not substituted here; a placeholder that names something the model did not send becomes an empty string.
• A placeholder always becomes text. If the model sends the number 3, your API receives "3". Accept strings on your side, or put fixed non-string values in the configuration directly ("limit": 5 stays a number).
• An optional argument the model left out arrives as "", not as a missing field.
• Placeholders work anywhere in the configuration, URL and headers included. A value placed in a URL is inserted as-is, not URL-encoded, so prefer the body for anything free-form.

Giving a tool to an agent

Attach saved tools to the agent. During a conversation the model decides when to call them, calls them with arguments it extracted from what the caller said, and answers from the result.

Where each kind works

HTTP, Integration, Static, MCP and Code tools work the same on a call and in chat. Client tools are the exception: they need a browser on the other end, so they work only in a web call. On a phone call or in chat nothing can answer them and the call fails, so keep Client tools off agents that also take phone calls or chats.

When a call fails

A non-2xx response, a timeout or an unreachable server does not end the conversation. The model is told the tool failed and why, and answers accordingly - so say in the prompt what the agent should do when a lookup fails.

• HTTP, MCP and Code tools give up after 30 seconds without a response.
• An HTTP response that is JSON is handed to the model as parsed JSON; anything else is handed over as text. A response over the platform's size limit counts as a failure.
• A browser answering a Client tool has 30 seconds to respond before the call counts as failed.

Several calls in one turn

In chat, a turn can take up to six rounds of tool calls before the agent must answer, and when the model asks for several tools at once they run one after another, not in parallel. Keep chains short: every round is another model call the user waits through.

Running in the background (voice)

On a voice call the caller normally waits while a tool runs. Where your platform offers it, the tool form shows Run in the background during voice calls for HTTP, MCP, Integration and Code tools: the agent keeps talking while the tool works, delivers the result when it arrives, and a caller speaking over the wait does not cancel it.

This applies to voice calls only, and only on the standard speech engine; on a speech-to-speech engine and in chat, the tool runs normally. A background tool is still bounded by a time limit.

Tools as a workflow step

In a workflow you can also place a tool node, which runs the tool at a fixed point in the flow rather than leaving the decision to the model. Use a node when the call must always happen; use an attached tool when the model should decide.

A tool node has no model arguments to draw on, so its {{placeholders}} are filled from the conversation's variables instead. Set the node's output name to store the result in a variable that later steps can use.

Safety

Outbound requests are validated before they are made: a tool cannot be pointed at internal or private network addresses. If you need a specific host allowed, that is an operator setting.

Every tool call and its result is recorded on the session, so you can see exactly what the agent called and what came back.