How do you write a good tool definition for an agent?

Checklist

1. Name: verb_noun, unambiguous: search_orders, not query or tool2.
2. Description (the most important part):
   • What it does, and when to use it vs similar tools.
   • Expected inputs with examples ("date in YYYY-MM-DD").
   • What it returns and any limits ("returns at most 20 results").
3. Parameters:
   • Use enums wherever possible (status: "open" | "closed").
   • Mark required vs optional; give defaults.
   • Avoid parameters the model can't know. Don't ask it for an internal UUID it has never seen.
4. Output:
   • Return what the model needs, not the raw 5,000-line API response. Use natural identifiers (names) alongside IDs.
   • Paginate or truncate large results and tell the model they were truncated.
5. Errors: return actionable messages. "Error: 'date' must be YYYY-MM-DD; you sent '5th Oct'" lets the model self-correct. "500 Internal Error" doesn't.

Bad vs good

// Bad
{"name": "get_data", "description": "Gets data", "parameters": {"q": {"type": "string"}}}

// Good
{"name": "search_customer_orders",
 "description": "Search a customer's orders by email. Use when the user asks about order status, delivery or refunds. Returns up to 10 most recent orders with id, date, status and total. Do NOT use for product catalogue questions; use search_products instead.",
 "parameters": {
   "email": {"type": "string", "description": "Customer email, e.g. a@b.com"},
   "status": {"type": "string", "enum": ["any","pending","shipped","delivered","refunded"], "default": "any"}
 }}

Common mistakes

• Exposing a one-to-one wrapper of every REST endpoint. Agents do better with fewer, task-level tools (see Q45).

Follow-ups to expect

• How would you test whether a tool description is good? Run evals on tool-selection accuracy.

Related

• Previous: Q7. What is MCP (Model Context Protocol), and why does it matter?
• Next: Q9. What should go into an agent's system prompt?
• LangChain
• Model Context Protocol