Tools Overview
Give your voice agents the ability to take actions during calls -- make API requests, transfer calls, or end conversations programmatically.
What you'll learn
- How tools work inside the voice pipeline
- The four tool types and when to use each
- How to create tools and attach them to agents
Tools extend what your agents can do beyond conversation. During a call, the LLM analyzes the conversation context and decides when to invoke a tool based on its name, description, and the user's intent. The tool executes, and its result is fed back to the LLM so it can continue the conversation with the new information.
How Tools Work in the Voice Pipeline
Every tool invocation follows the same four-step lifecycle, regardless of type:
User speaks -- the caller says something that implies an action ("Book me an appointment for Tuesday" or "Transfer me to a manager").
LLM decides -- based on the tool's name and description, the LLM determines that a tool call is appropriate and extracts the required parameters from the conversation.
Tool executes -- the platform runs the tool (sends an HTTP request, initiates a call transfer, or ends the call).
Result returns to LLM -- for HTTP API tools, the response body is passed back to the LLM. The LLM uses this to formulate its next spoken response.
The LLM never sees your tool's internal configuration (URL, headers, credentials). It only sees the tool name, description, and parameter definitions -- these are what guide its decision to call the tool and what values to pass.
Tool Types
zoxaAI supports four tool types. Each serves a different purpose in the voice pipeline.
| Type | Category | Description | Use case |
|---|---|---|---|
| HTTP API | function | Make HTTP requests to external APIs during calls | Fetch data, submit forms, trigger webhooks |
| Call Transfer | transferCall | Blind transfer the call to a phone number or SIP endpoint | Hand off to human agents, route to departments |
| End Call | endCall | Programmatically end the call with optional goodbye message | Hang up when the issue is resolved or on voicemail |
| Knowledge Base | query | Search uploaded documents during calls using RAG retrieval | Answer questions from docs, policies, FAQs, product specs |
All four tool types share the same LLM-driven invocation model. The LLM reads the tool's description, decides when the tool is appropriate, and triggers it. You never need to write code to invoke a tool -- configure it once and the LLM handles the rest.
Choosing the Right Tool Type
Creating a Tool
Navigate to Tools in the dashboard sidebar.
Click Create Tool.
Select the tool type: HTTP API, Call Transfer, End Call, or Knowledge Base.
Enter a name and description. These are the primary signals the LLM uses to decide when to call the tool.
Configure the type-specific settings (endpoint URL for HTTP API, destination number for Call Transfer, etc.).
Save the tool. It will be created with Active status by default.
Writing Effective Tool Descriptions
The description is critical -- it is the primary signal the LLM uses to decide when to call the tool. Write it from the LLM's perspective.
| Approach | Example | Quality |
|---|---|---|
| Vague | "Appointment API" | Bad -- the LLM doesn't know when to use it |
| Action-oriented | "Use this tool when the caller wants to book, reschedule, or cancel an appointment. Extract the desired date and time from the conversation." | Good -- clear trigger and parameter guidance |
| Over-constrained | "Only use this tool if the caller says the exact words 'book an appointment'" | Bad -- too restrictive, will miss natural variations |
The LLM sees only the tool name, description, and parameter definitions. If your description is ambiguous, the LLM may call the wrong tool or fail to call the right one. Be specific about the trigger condition and what information to extract.
Attaching Tools to Agents
Tools are reusable across your organization. After creating a tool, attach it to each agent that should be able to use it: in the agent editor, go to the Tools tab and select the tools the agent can use.
A tool is only available to the LLM during a call if it has been explicitly attached. You can attach the same tool to multiple agents.
Attaching multiple tools to a single agent is fully supported. The LLM will evaluate all available tools on every turn and choose the most appropriate one (or none) based on the conversation context.
Tool Statuses
Every tool has a lifecycle status that controls its availability.
| Status | Value | Description |
|---|---|---|
| Active | active | Tool is available for use in calls. This is the default status when a tool is created. |
| Draft | draft | Tool is being configured and not yet ready for use. Draft tools cannot be attached to agents. |
| Archived | archived | Tool is soft-deleted and hidden from selection. Archiving is reversible -- you can unarchive a tool at any time. |
API Reference
Tools are managed via the REST API under /api/v1/tools.
Create a Tool
curl -X POST https://dashboard.zoxa.ai/api/v1/tools \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Book Appointment",
"description": "Use this tool when the caller wants to book an appointment. Extract the date, time, and service type from the conversation.",
"category": "function",
"definition": {
"schema_version": 1,
"type": "function",
"config": {
"method": "POST",
"url": "https://api.example.com/appointments",
"timeout_ms": 5000,
"parameters": [
{
"name": "date",
"type": "string",
"description": "The requested appointment date (YYYY-MM-DD format)",
"required": true
},
{
"name": "time",
"type": "string",
"description": "The requested appointment time (HH:MM format)",
"required": true
}
]
}
}
}'List Tools
curl https://dashboard.zoxa.ai/api/v1/tools?status=active \
-H "Authorization: Bearer YOUR_API_KEY"Tool Response Shape
{
"id": 42,
"tool_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Book Appointment",
"description": "Use this tool when the caller wants to book an appointment.",
"category": "function",
"icon": "globe",
"icon_color": "#3B82F6",
"status": "active",
"definition": {
"schema_version": 1,
"type": "function",
"config": { ... }
},
"created_at": "2026-05-22T10:30:00Z",
"updated_at": "2026-05-22T10:30:00Z"
}