Designing Tools
Model callable functions for live phone conversations.
Tools should be narrow, explicit, and predictable. During a live call, each tool adds latency, so keep the contract focused on the minimum action needed.
Choose how tools run
Custom tools are available on HTTP and webhook agents. HTTP tools call an endpoint per tool; webhook tools send agent:tool-call events to the agent’s Server URL. Static agents do not support these custom tools. Built-in tools and connected MCP tools are separate.
Follow HTTP agent setup or webhook agent setup, then use the design principles below.
Good tool names
Use action-oriented names:
check_availabilitycreate_bookinglookup_customercancel_appointment
Avoid broad names like handle_request or database_query.
Parameters
Use JSON Schema object parameters with clear required fields.
{
"type": "object",
"properties": {
"customer_phone": {
"type": "string",
"description": "Caller phone number in E.164 format."
},
"date": {
"type": "string",
"description": "Requested date as YYYY-MM-DD."
}
},
"required": ["customer_phone", "date"]
}
Responses
Return concise JSON. The model does not need internal database fields unless they affect the conversation.
{
"status": "available",
"message": "There are openings at 15:00 and 16:30."
}
Failure cases
Prefer explicit errors that the model can recover from.
{
"error": {
"code": "customer_not_found",
"message": "No customer exists for that phone number."
}
}