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.
| # | 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() |
{
"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"]
}
}
execute_action(type, data)). The agent can't reason about what it does.