Overview
Client tools are custom functions that the voice agent can use during the conversation. They are defined and implemented on the client side.Simple Example
Here’s a complete example with one tool:Step 1: Define the Tool
Tool schemas are OpenAI compatible. See the OpenAI Function Calling guide for more details on defining functions.
Step 2: Implement the Function
The return value from your function is sent directly to the AI model, which uses it to generate its response to the user.
- Data tools (weather, calculations): Return the actual data
- Action tools (generate image, open browser): Return acknowledgment like “Image generated successfully” or “Browser tab opened”
- On failure: Return error description like “Failed to generate image: rate limit error”
Step 3: Configure Session
- Call your
getTime()
function - Receive the return value (e.g., “2:30:45 PM”)
- Use that information to respond to the user
Advanced Example with Context
Here’s a more complex tool with typed parameters and context usage:context
parameter provides access to conversation methods like sendText()
for sending messages back to the AI after your tool completes.
Tool Schema Format
Tool schemas are OpenAI compatible. See the OpenAI Function Calling guide for more details on defining functions.Best Practices
Tool Design
- Clear descriptions: Help the AI understand when and how to use each tool
- Specific parameters: Define precise parameter types and descriptions
- Single purpose: Each tool should do one thing well
- Predictable naming: Use descriptive, consistent naming conventions
Implementation
Always return meaningful values - the AI uses your return value to respond to the user:Performance
- Cache results: Cache API responses when appropriate
- Timeout handling: Set reasonable timeouts for external calls
- Rate limiting: Respect API rate limits
- Graceful degradation: Provide fallbacks when tools fail