[ ABORT TO HUD ]
SEQ. 1
SEQ. 2
SEQ. 3
SEQ. 4
SEQ. 5
SEQ. 6
Tool Design Best Practices
Designing Tools That Agents Actually Use Correctly
The tools you give your agent are just as important as the prompt. Poorly designed tools lead to hallucinated arguments, wrong tool selection, and catastrophic errors. Here's how to design bulletproof tools.
The 7 Rules of Agent Tool Design
| # | Rule | Why It Matters | Bad Example | Good Example |
|---|---|---|---|---|
| 1 | Clear, verb-based names | Agent must instantly understand purpose | data_handler | search_customer_orders |
| 2 | Detailed descriptions | The description is the agent's only instruction manual | "Gets data" | "Searches the orders database by customer email. Returns last 20 orders" |
| 3 | Minimal parameters | More params = more hallucination risk | 12 optional fields | 2-3 required fields |
| 4 | Use enums over strings | Constrain agent choices | "type": "string" | "enum": ["asc","desc"] |
| 5 | Return structured errors | Agent needs to understand failures | "Error 500" | {"error": "not_found", "suggestion": "Try a different email"} |
| 6 | Idempotent when possible | Safe to retry if agent calls twice | add_item() duplicates | set_item(id, data) upserts |
| 7 | Scope tightly | One tool = one responsibility | manage_database() | read_row(), update_row() |
The Tool Description Template
{
"name": "search_knowledge_base",
"description": "Search the internal knowledge base for articles matching a query. Returns the top 5 most relevant articles with title, snippet, and URL. Use this when the user asks about company policies, procedures, or internal documentation. Do NOT use for general web searches.",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Natural language search query. Be specific."
},
"category": {
"type": "string",
"enum": ["hr", "engineering", "legal", "finance"],
"description": "Filter by knowledge base category."
}
},
"required": ["query"]
}
}
💡 Key Insight: The most common agent failure is calling the wrong tool or passing wrong arguments. 80% of these errors are fixed by improving tool descriptions, NOT by changing the system prompt.
Anti-Patterns to Avoid
- God Tools: A single tool that does everything (
execute_action(type, data)). The agent can't reason about what it does. - Missing Negative Instructions: Not telling the agent when NOT to use a tool is as important as telling it when to use it.
- Trusting Agent Input: Always validate and sanitize arguments server-side. Never execute raw SQL from agent inputs.
- Silent Failures: If a tool fails, return a clear error message. Don't return empty or null - the agent will hallucinate.
SYNAPSE VERIFICATION
QUERY 1 // 3
What is the most common cause of agents calling the wrong tool or passing wrong arguments?
The model is too small
Poor tool descriptions and schema design
Network latency
Too many tokens in the prompt