Tool Definitions & Descriptions

Tool definitions are the primary input Claude uses to decide which tool to call. Clear, comprehensive tool descriptions are the single highest-leverage improvement for tool selection reliability.

Anatomy of a Good Tool Definition

1. Name: Clear, action-oriented (e.g., lookup_order not data_fetch)
2. Description: What it does, when to use it, when NOT to use it
3. Input schema: JSON Schema with parameter descriptions
4. Examples: Input formats it accepts
5. Boundaries: How it differs from similar tools

Common Mistakes

• Minimal descriptions: "Retrieves customer information" -- too vague
• Overlapping names: analyze_content vs analyze_document -- ambiguous
• Missing boundaries: Not explaining when to use this tool vs. similar alternatives

Fix: Rich Tool Descriptions

{
  "name": "lookup_order",
  "description": "Retrieves order details by order ID or tracking number. Use when the customer asks about order status, shipping, or delivery. Accepts formats: #12345, ORD-12345, or tracking numbers. Do NOT use for customer account lookups -- use get_customer instead."
}

Splitting Generic Tools

When a tool is too generic (e.g., analyze_document), split it into purpose-specific tools with clear contracts:

• extract_data_points -- pulls structured data from documents
• summarize_content -- generates concise summaries
• verify_claim_against_source -- fact-checks claims against source material

Each specific tool has a narrower, clearer description that reduces selection ambiguity.