How tools work
When a caller says something that matches a tool’s trigger (defined in itsdescription field), the agent fires that tool automatically mid-conversation.
The key thing to understand: tools are attached to LLM models, not to agents directly.
Tool types
| Type | What the agent does | Best for |
|---|---|---|
api_call | Calls your HTTP endpoint | Lookups, CRM updates, custom logic |
transfer_call | Transfers to a phone number | Routing to humans |
extract_information | Saves structured data from the conversation | Capturing name, email, budget |
end_call | Hangs up the call | Completing a flow cleanly |
send_sms | Sends a text message | Follow-ups, confirmations |
send_email | Sends an email | Lead handoffs, summaries |
schedule_calendar_event | Books a calendar event | Demo scheduling, appointments |
Step 1 — Create a tool
send_sms
Sends a text message to a fixed number when triggered. Use this to notify your team the moment a lead is captured, or to send a confirmation to the caller.
| Field | What it does |
|---|---|
description | How the agent decides when to fire this tool — write it as a trigger condition |
messaging_config.to | Destination phone number in E.164 format (e.g. +15555550000) |
messaging_config.body_template | Message text. Use {{variable_name}} for dynamic values pulled from the conversation |
send_email
Sends an email when triggered. Use this to deliver lead summaries to your sales team, send follow-up emails to callers, or notify someone when a key moment happens in a call.
| Field | What it does |
|---|---|
description | How the agent decides when to fire this tool — write it as a trigger condition |
messaging_config.to | Recipient email address |
messaging_config.subject_template | Email subject line. Use {{variable_name}} for dynamic values |
messaging_config.body_template | Email body text. Use {{variable_name}} for dynamic values pulled from the conversation |
schedule_calendar_event
Books a calendar event when triggered. Use this when you want the agent to schedule a demo or follow-up meeting directly during the call.
| Field | What it does |
|---|---|
description | Trigger condition — tell the agent exactly when to fire this (e.g. “when the caller agrees to a meeting”) |
calendar_config.calendar_id | Calendar to book on. Use "primary" for the default calendar |
calendar_config.duration_minutes | Length of the event in minutes |
calendar_config.timezone | IANA timezone string (e.g. "Asia/Tokyo", "Europe/London", "America/New_York") |
api_call
Calls your own HTTP endpoint during the call. Use this to look up information (e.g. order status, account details), push data to your CRM, or trigger custom business logic based on what the caller says.
| Field | What it does |
|---|---|
url | Your endpoint URL — must be publicly reachable |
method | HTTP method (GET, POST, PUT, PATCH) |
headers | Any auth headers your endpoint requires |
parameters | Fields the agent extracts from the conversation and passes to your API as the request body |
run_in_background | true = agent keeps talking while the API call runs in parallel. false = agent pauses and waits for the response |
speak_during_execution | true = agent says something like “Let me check that for you…” while the API call is in progress |
transfer_call
Transfers the caller to a real phone number. Use this when the caller asks to speak with a human or needs to reach a specific team. The agent says a brief handoff message, then the call is transferred.
| Field | What it does |
|---|---|
description | Trigger condition — be explicit so the agent knows exactly when to transfer |
transfer_to | The phone number to transfer the call to, in E.164 format |
extract_information
Silently captures structured data from the conversation as it happens — the agent doesn’t announce it to the caller. Use this to save lead qualification data, capture names and emails, or record key facts from the call.
| Field | What it does |
|---|---|
description | Tells the agent when to run the extraction — not a phrase trigger, but a condition (e.g. “once the caller has answered the qualifying questions”) |
extraction_schema.fields | List of fields to extract. Each field has a name, type (string, boolean, number), optional required, and a description that guides the extraction |
end_call
Hangs up the call cleanly. Use this at the end of a flow — after a booking, after the caller says goodbye, or when the agent has completed its task. Without this tool, the call continues until the silence timeout is reached.
Step 2 — Attach tools to your LLM model
Creating a tool makes it available in your account, but the agent can’t use it yet. You need to attach it to the LLM model linked to your agent. Use thellm_id from your agent’s create response — this is the AI brain that decides what to do during a call.
llm_id picks up the change immediately — no restart required. To attach multiple tools, list all their IDs in the array.
Step 3 — Update your system prompt
Thedescription on each tool is the trigger signal — it tells the agent when to fire the tool. But the system prompt gives the agent the context and instructions for how to use it in the flow. Be explicit about when and in what order tools should fire.
Reading tool results after a call
After the call ends, the extracted data and tool activity appear in the call record. Stop the call first, wait a few seconds, then fetch:messages and analysis are only available after the call ends — both are empty while the call is active.
Manage tools
List all tools
Retrieve every tool in your account. Useful for finding tool IDs when you need to attach or update them.Update a tool
Change a tool’s name, description, or config. For example, update the trigger description to make the agent more (or less) sensitive to firing it.Delete a tool
Remove a tool permanently. If the tool is attached to an LLM model, detach it first by PATCHing the model with an updatedtool_ids array that excludes the deleted tool’s ID.