Tool Calling

Give your voice agent the ability to act during a live call. It can look up an order, check an appointment slot, file a ticket, or fetch a balance. You do not rebuild the runtime. You declare a set of tools on the agent. The model sees each tool’s name, description, and argument schema. The model decides when to call a tool. ClutchCall Voice executes the tool and feeds the result back, so the model can keep talking. This is the same tool model that the Agent DAG uses under the hood. An llm (or realtime) node advertises tools by name, and the runtime resolves and runs them. On this page, you configure the tools themselves.

How a tool call flows through a turn

Advertise

On the first audio frame of a new session, the runtime hydrates the agent’s tool list. It advertises each tool’s name, description, and parameter schema to the model.

Call

The model emits a structured tool_call with JSON arguments. The runtime validates those arguments against the tool’s JSON Schema before dispatch. Thus a malformed call fails fast and does not hit your endpoint.

Execute

The runtime runs the tool. This is an outbound HTTP request, an MCP tools/call, or a push to your SDK. The runtime captures the result as a JSON string.

Feed back

The result returns to the model as a tool_result. The model reasons over the result. It then answers the caller or calls another tool. Mark a tool silent to hand the result back without a prompt for a new spoken response.

Tool invokes are synchronous within the model turn. A slow upstream eats the turn budget, and the caller hears dead air. Keep each tool fast. Sub-second is ideal. Chain multiple short LLM turns instead of several tool calls inside one turn.

Where tools live

You declare tools on the agent. They are not baked into the runtime. The control plane persists them under the agent’s config (agent:<agent_id>:config.tools[]). The runtime hydrates them per session. Thus edits in the agent console apply to the next call with no redeploy. Each session builds its tool set as a union. It unions your operator-defined tools with a built-in telephony toolset that the runtime advertises automatically. The toolset includes transfer, hold/unhold, DTMF, disconnect, supervisor request, and more. See below and AI ↔ human handoffs. On a name collision, the operator tool wins. Thus a declared tool named transfer_call overrides the built-in.

If a tool’s spec fails to parse, the runtime skips the tool at registration. The runtime does not register a broken tool. Thus a typo in one tool’s spec cannot shadow a built-in of the same name, and cannot wedge the session. If a tool you expected never reaches the model, check the agent console’s validation banner.

Built-in telephony tools

Every session ships with a built-in telephony toolset. The model can call these tools with no operator config. They drive the live call itself. The model can move the caller, place them on hold, dial a human, hang up, punch DTMF into a downstream IVR, or pull in a supervisor. These are the same operations that ISV apps get as CSTA verbs on CTI call-control. Here they are tools that the LLM calls itself, in the middle of the conversation, when it decides that a human or a different destination should take over.

Every transfer passes the realm’s transfer-rule policy. A destination can be disallowed, for example a blocked cross-realm hop. Then the tool returns a structured error instead of a connection. Thus the model can react in-turn: apologize, try route_to_skill, or read the reason back to the caller. The tool does not fail silently.

Picking a transfer style

The model has three ways to hand a caller off. The right way depends on two questions. Does a human need a brief? Should the caller hear that brief?

Style	Tool(s)	Does the AI stay?	Does the caller hear the brief?	Reach for it when
Blind	`transfer_call`	No — leaves at once	No brief happens	You already know the exact destination, and no handoff brief is needed.
Warm / attended	`warm_transfer` → `complete_transfer`	Yes, until it steps out	Yes — everyone is in one conference	You want to brief the human out loud, with the caller present, before you drop.
Private consult	`consult` → `consult_transfer` \| `consult_cancel`	Yes, speaking privately	No — caller is on hold	You need to check with a third party privately, and you may decide not to transfer.

This is a one-step blind transfer (SIP REFER). The runtime hands the caller to the destination. The AI leaves the call immediately. There is no briefing phase. Use it when you know the destination and no context needs to pass by voice.

string

required

Where to send the caller. Accepts an E.164 number (+15551234567), a SIP URI (sip:queue@pbx.example.com), or a tel: URI.

string

Optional Referred-By identity presented on the REFER. If you omit it, the default is the trunk’s identity.

Warm transfer — `warm_transfer` then `complete_transfer`

This is an attended transfer where the caller hears the handoff. The AI dials the destination and joins everyone into a conference, so it can speak the brief. The caller is live throughout and hears the whole exchange.

warm_transfer { destination }

The AI dials destination and joins a conference with the caller. All three parties are connected. The AI delivers the handoff brief out loud while the caller listens.

string

required

A skill name, extension, SIP URI, or PSTN number (E.164) to bring into the conference.

complete_transfer { }

When the brief is done, the AI steps out of the conference. The caller and the destination stay connected. Only the AI leg stops. There are no parameters.

Private consult — `consult` then `consult_transfer` or `consult_cancel`

This is an attended, one-to-one consult where the caller does not hear anything. The AI dials a third party and speaks privately while the caller waits on hold. It then either connects them or returns to the caller.

consult { destination }

The runtime effectively places the caller on hold. The AI dials destination on a private leg. The AI and the consulted party can talk, and the caller does not hear them.

string

required

A skill name, extension, SIP URI, or PSTN number (E.164) to consult privately.

Then resolve it one of two ways

consult_transfer { }
consult_cancel { }

Connects the caller to the consulted party. The AI drops out. The two parties are left in conversation. There are no parameters.

The rest of the toolset

The remaining built-in tools control the caller’s own leg or pull in a human. They take effect the moment the model calls them.

Tool	Params	What it does
`route_to_skill`	`skill?`	Queues the caller to a human skill / queue (ACD), and the AI steps out. Use it for “get me a human” when there is no specific number. Omit `skill` to use the agent’s default queue.
`hold_call`	—	Places the caller on hold. The caller hears the trunk’s hold treatment.
`unhold_call`	—	Takes the caller back off hold.
`disconnect_call`	`reason?`	Hangs up the call. The CDR records `reason`.
`send_dtmf`	`digit` (`0-9*#A-D`), `duration_ms?` (default `100`), `mode` (`rfc2833` \| `inband`)	Punches a DTMF digit down the line to navigate a downstream IVR.
`request_supervisor`	`reason`, `urgency` (`low` \| `medium` \| `high`)	Signals a supervisor to join / assist. The caller is not transferred away.

You can override any of these tools. Declare an operator tool of the same name; the operator tool wins the union. You can also pull a tool from a tenant entirely. See Hiding tools per tenant below.

Per-tool spec

Every entry in tools[] shares the same envelope. The kind-specific fields go inside spec:

string

required

http, mcp, or client. Selects which executor runs the tool.

string

required

Unique within the agent. This is the function name that the model sees and calls.

string

required

The human-readable purpose, advertised to the model. Write it for the model. It is the primary signal for when to call the tool.

boolean

default:"false"

When true, the runtime hands the tool result back and does not ask the model to generate a fresh spoken turn. This is useful for fire-and-forget side effects (log a disposition, tag the call), where you do not want the agent to narrate the action.

object

required

Kind-specific configuration. Every kind accepts a parameters field, which is a standard JSON Schema for the tool’s arguments. If you omit it on an http tool, the runtime synthesizes one from the {{placeholder}} tokens in your URL and body.

Tool kinds

Kind	Status	What it does
`http`	shipped	Calls an HTTP(S) endpoint you own. URL, headers, and body templates substitute `{{argument}}` from the model’s tool arguments. Auth: `bearer`, `basic`, or custom header. 10s default timeout.
`mcp`	shipped	JSON-RPC 2.0 `tools/call` against a remote MCP server over Streamable HTTP. You declare each tool explicitly (no `tools/list` auto-discovery yet). Same auth shapes as `http`.
`client`	scaffolded	The runtime advertises the tool and parses the call, but pushes it to your SDK to fulfil. See the status note below.

http
mcp
client

{
  "kind": "http",
  "name": "lookup_order",
  "description": "Look up an order by its ID and return its status.",
  "silent": false,
  "spec": {
    "method": "GET",
    "url": "https://api.example.com/orders/{{order_id}}",
    "headers": { "X-Tenant": "acme" },
    "auth": { "type": "bearer", "token": "sk_live_..." },
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string", "description": "Order id to look up." }
      },
      "required": ["order_id"]
    },
    "timeout_ms": 10000
  }
}

The runtime replaces {{name}} tokens in url, headers, and body with the matching top-level property from the model’s arguments. URL substitutions are percent-encoded. Body substitutions are inserted verbatim. Thus, if your endpoint expects JSON, write JSON in the body template. auth accepts { "type": "bearer", "token": ... }, { "type": "basic", "user": ..., "pass": ... }, or { "type": "header", "name": ..., "value": ... }. The runtime returns the response body to the model as the tool result.

{
  "kind": "mcp",
  "name": "search_orders",
  "description": "Search a customer's recent orders.",
  "silent": false,
  "spec": {
    "server_url": "https://mcp.example.com/messages",
    "tool_name": "search_orders",
    "transport": "http",
    "auth": { "type": "bearer", "token": "..." },
    "parameters": {
      "type": "object",
      "properties": {
        "query": { "type": "string" }
      },
      "required": ["query"]
    },
    "timeout_ms": 10000
  }
}

The runtime forwards each call as a JSON-RPC 2.0 tools/call to server_url, with params.name = tool_name and params.arguments = the model’s arguments. The tool result is the concatenated text from the response’s result.content[*].text. On failure, it is a structured error envelope. The model gets a JSON string either way.

You declare each remote MCP tool explicitly. Dynamic discovery via tools/list (connect → enumerate → auto-register) is not wired yet. Rich content types (images, embeddings) collapse to their text parts for now. A declaration by name keeps the tool set available in the model’s very first turn, without a per-session handshake.

{
  "kind": "client",
  "name": "approve_refund",
  "description": "Show the operator an approval dialog and report the choice.",
  "silent": false,
  "spec": {
    "timeout_ms": 10000,
    "parameters": {
      "type": "object",
      "properties": {
        "amount": { "type": "number" }
      },
      "required": ["amount"]
    }
  }
}

A client tool flips the direction. The runtime does not call out. Instead, the runtime pushes the tool call to your SDK and waits for the SDK to return a result. Use it for actions that only the caller’s environment can perform: read local state, show an approval dialog, or run code in the user’s sandbox. You register a handler on the SDK side (see the JavaScript SDK).

client tools are scaffolded, not live. You can configure them today, and the model will call them. But invoke currently returns a not_yet_plumbed error. The runtime→SDK envelope ships alongside the move of the supervise channel onto media-over-QUIC. Do not put a client tool on the critical path of a production agent yet.

Hiding tools per tenant

You can pull a built-in telephony tool out of a tenant’s agents without an edit to each agent. Write the tool names as a JSON array to ClutchCall:tenant:<tenant_id>:telephony_disabled_tools. The runtime filters out disabled tools before the tool set reaches the model. It re-checks the list at invoke time. Thus a stale provider session cannot slip a call through for a name you disabled mid-call.

Native tools

Some tools need privileged access to the live call: realm-policy evaluation, telephony dispatch, recording control, and supervisor signalling. For these, the built-in telephony toolset is implemented as first-class runtime code, not as http/mcp entries. That path is for platform developers who build into the runtime itself. Tenants and operators should use the http, mcp, and (soon) client kinds above. Those kinds need no rebuild.

Runtime overview

Learn how agents, pipelines, and providers fit together.

Session lifecycle

Learn when tools hydrate and how the turn budget is spent.

AI ↔ human handoffs

See the built-in transfer / supervisor toolset in context.

CTI call-control verbs

The same operations as CSTA verbs, for ISV apps to drive over the CTI leg.

BYO ASR / LLM / TTS

Learn which providers surface tool calling in a cascaded pipeline.

Build a Voice Agent

How a tool call flows through a turn

Where tools live

Built-in telephony tools

Picking a transfer style

Blind transfer — `transfer_call`

Warm transfer — `warm_transfer` then `complete_transfer`

Private consult — `consult` then `consult_transfer` or `consult_cancel`

The rest of the toolset

Per-tool spec

Tool kinds

Hiding tools per tenant

Native tools

Runtime overview

Session lifecycle

AI ↔ human handoffs

CTI call-control verbs

BYO ASR / LLM / TTS

​How a tool call flows through a turn

​Where tools live

​Built-in telephony tools

​Picking a transfer style

​Blind transfer — transfer_call

​Warm transfer — warm_transfer then complete_transfer

​Private consult — consult then consult_transfer or consult_cancel

​The rest of the toolset

​Per-tool spec

​Tool kinds

​Hiding tools per tenant

​Native tools

​Related

Runtime overview

Session lifecycle

AI ↔ human handoffs

CTI call-control verbs

BYO ASR / LLM / TTS

How a tool call flows through a turn

Where tools live

Built-in telephony tools

Picking a transfer style

Blind transfer — `transfer_call`

Warm transfer — `warm_transfer` then `complete_transfer`

Private consult — `consult` then `consult_transfer` or `consult_cancel`

The rest of the toolset

Per-tool spec

Tool kinds

Hiding tools per tenant

Native tools

Related