Tools - Cartesia Docs

Tools let an agent end a call, transfer a caller, retrieve data, or trigger an action in your application. The model chooses a tool from its name, description, and the conversation.

System tools

Built-in actions you configure directly on an agent.

Webhook tools

HTTP requests that Cartesia sends to your server.

Client tools

Functions that your application handles over the WebSocket API.

Add a tool dialog in the Playground offering Webhook and Client function — Add a webhook or client tool from the Tools page in the Playground.

Describe a tool

The model uses a tool’s name and description to decide when to invoke it. State what the tool does and when to use it.

Looks up an order by its number. Use it when the caller asks about an order's status or delivery date.

Execution settings

Webhook and client tools share these settings:

Field	Description
`pre_tool_speech`	`auto` lets the agent decide whether to speak first. `force` asks it to speak before invoking the tool.
`execution_mode`	`immediate` runs in the current turn and can be interrupted by the caller. `async` runs separately while the turn can finish.
`response_timeout_secs`	Maximum time to wait for a result, from `1` to `120` seconds. The default is `20`. On timeout, the agent continues the conversation with a tool timeout result.

Attach tools to an agent

Webhook and client tools are shared resources. Create one with POST /v1/agents/tools, then add its ID to config.tools. An agent can reference up to 32 tools. An update to config.tools replaces the complete list. A referenced tool cannot be deleted until you remove it from every current agent configuration. System tools are configured separately on config.system_tools.

System tools

Webhook tools

Client tools

​Describe a tool

​Execution settings

​Attach tools to an agent

Describe a tool

Execution settings

Attach tools to an agent