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

1. Agent receives a request - User asks something that might need a tool
2. Agent decides - Based on tool descriptions, agent chooses whether to use a tool
3. Tool executes - The platform runs the tool and returns results
4. 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 Servers

Tool 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:

1. Week 1: Enable built-in functions (Calculator, Date/Time)
2. Week 2: Add Knowledge Base for FAQs
3. Week 3: Add API integrations for live data
4. 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.

---

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 data

---

Tool 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