Agent Tools
Tools transform your agent from a simple chatbot into a powerful assistant capable of taking real actions. Without tools, an agent can only have conversations. With tools, it can look up information, make calculations, call APIs, and integrate with your business systems.
Understanding Tools
Think of tools as "superpowers" you grant to your agent. Each tool gives the agent a specific capability it can use during conversations.
How Tools Work
- Agent receives a request - User asks something that might need a tool
- Agent decides - Based on tool descriptions, agent chooses whether to use a tool
- Tool executes - The platform runs the tool and returns results
- Agent responds - Agent incorporates tool results into its response
User: "What's 15% tip on a $47.50 bill?"
↓
Agent thinks: "I need to calculate this precisely"
↓
Agent calls: Calculator tool with "47.50 * 0.15"
↓
Tool returns: 7.125
↓
Agent responds: "A 15% tip on $47.50 would be $7.13"The Agent Decides When to Use Tools
You don't tell the agent when to use each tool—you describe what each tool does. The agent's AI model decides whether a tool is needed based on the conversation context and your tool descriptions.
Available Tool Types
| Tool Type | Purpose | Complexity |
|---|---|---|
| Built-in Functions | Basic calculations and date/time | None (just enable) |
| API Integration | Call external REST APIs | Medium (configure endpoint) |
| Knowledge Base | Search your documents (RAG) | Low (select knowledge base) |
| Manual Tools | Custom logic in your backend | High (requires coding) |
| MCP Servers | Model Context Protocol integrations | Medium-High (server setup) |
Choosing the Right Tool Type
Decision Tree
Need basic math or current time?
→ Built-in Functions
Need to answer questions from your documents?
→ Knowledge Base
Need to call an external API?
→ API Integration
Need complex logic or multiple steps?
→ Manual Tools (your code processes it)
Want standardized AI integrations?
→ MCP ServersTool Type Comparison
| Scenario | Best Tool Type | Why |
|---|---|---|
| Calculate pricing | Built-in (Calculator) | Simple math, no API needed |
| Check order status | API Integration | Single REST call to your system |
| Answer product questions | Knowledge Base | Searches your documentation |
| Process refund request | Manual Tools | Requires complex business logic |
| Query Salesforce CRM | MCP Servers | Standardized integration available |
Tool Configuration Best Practices
1. Write Clear Descriptions
The tool description is how the agent knows when to use it. Be specific:
❌ Vague:
"Gets customer information"
✅ Clear:
"Retrieves customer account details including name, email, subscription tier, and account balance. Use when customer asks about their account status or when you need to verify their identity."
2. Start Simple
Begin with the minimum tools needed:
- Week 1: Enable built-in functions (Calculator, Date/Time)
- Week 2: Add Knowledge Base for FAQs
- Week 3: Add API integrations for live data
- Month 2: Add Manual Tools for complex workflows
Too Many Tools Can Confuse
An agent with 20 tools might struggle to choose the right one. Start with 3-5 essential tools and add more as needed.
3. Test Tool Selection
In the Playground, test scenarios where you expect specific tools to be used. Verify the agent:
- Chooses the correct tool
- Doesn't use tools unnecessarily
- Handles tool errors gracefully
4. Handle Tool Failures
Configure your instructions to handle cases where tools fail:
## Tool Error Handling
If a tool returns an error or unexpected result:
- Apologize briefly: "I'm having trouble accessing that information."
- Offer an alternative: "Would you like me to try a different approach?"
- Never expose technical error details to customers.On-demand loading and tool search
With many tools, sending all of them to the model on every message fills the context and costs more. When enabled, the agent receives only the always-available tools directly (calculator, date/time, web search and page reader) and searches for the rest when needed, with search_tools and load_tool. The search understands Portuguese queries and tolerates accents and near names.
In Tools > Settings:
| Control | What it does | Default |
|---|---|---|
| Load tools on demand | Enables on-demand loading | On |
| Enable from how many tools | Only activates when the agent has strictly more tools than this, counting MCP ones | 10 |
| Show tool catalog in context | Shows the name and description of the available tools; off, it shows only the count | On |
| Max steps per response | Maximum number of tool-call rounds (model call plus tool execution) in one response before the agent answers | 30 |
An agent without explicit values uses the defaults. The advanced settings below, in the same tab, define how much of the conversation tools can take up.
Advanced settings
Tools visible in search
How many tool names and descriptions the agent sees listed in the prompt. Applies while Load tools on demand is on. With the default of 30, up to that number the agent loads tools directly, without searching; above it, it sees only categories and counts and has to search. The limit does not restrict what search can find. If it is lower than the agent's total number of tools, the agent validation shows a warning.
Tool results kept in the conversation
How many tool results stay in the conversation history. The default is 10 and the range is 1 to 20. In long conversations, the oldest results are dropped from that number on: keeping more helps in long flows but takes up more context. Results are only dropped once the conversation passes about 75% of the model's context.
Maximum size of each result
Results larger than that size are trimmed before they enter the conversation, including large MCP and code execution responses. Increase it if the agent complains about missing information; decrease it to use less context. The default appears in the field itself.
Tools and Voice Agents
When using tools with voice agents, consider:
Response Time
Tools add latency to responses. For voice calls:
- Use background sounds to mask processing time
- Acknowledge the request before calling slow tools: "Let me look that up for you..."
- Prefer faster tools when multiple options exist
Verbal Acknowledgment
Instruct your agent to acknowledge tool usage:
When using tools during a call:
- Before calling: "I'm checking that for you now..."
- After receiving results: Paraphrase naturally, don't read raw dataTool Security
API Keys and Credentials
- Store API keys in the secure credentials section, not in tool configurations
- Use the minimum permissions necessary for each integration
- Rotate credentials regularly
Data Exposure
Consider what data tools return and whether it should be shared:
## Sensitive Data Handling
When tools return customer data:
- Only share information the customer specifically requested
- Never read out full credit card numbers or SSNs
- Mask sensitive data: "Your card ending in 4242"Related Documentation
- Built-in Functions - Calculator and date/time tools
- API Integration - Connect to REST APIs
- Knowledge Base - Document search (RAG)
- Manual Tools - Custom backend integrations
- MCP Servers - Model Context Protocol