Tool interfaces and descriptions

• Tool descriptions are the primary mechanism for tool selection; minimal descriptions cause misrouting among similar tools.
• Descriptions should include input formats, example queries, edge cases, and boundary explanations.
• Near-identical descriptions (analyze_content versus analyze_document) cause requests to land on the wrong tool.
• Keyword-sensitive wording in the system prompt can create unintended tool associations.
• Generic catch-all tools lack clear input/output contracts.

• Write descriptions that differentiate purpose, inputs, outputs, and when to use each tool versus alternatives.
• Rename and re-describe tools to remove functional overlap (for example a web-specific extract_web_results).
• Split a generic tool into purpose-specific tools with defined contracts (extract_data_points, summarize_content, verify_claim_against_source).
• Review system prompts for keyword-sensitive instructions that override good descriptions.

• "The tool name is enough for the model to choose." The description carries the real signal.
• "Few-shot examples are the first fix for misrouting." Fix the descriptions first; examples add tokens to every call.
• "One flexible tool is simpler than several specific ones." Its outputs become unpredictable.

One-line descriptions, two tools that could be swapped without anyone noticing, and prompt phrases that trigger a tool on a single keyword.

• 2.3Tool distribution and tool_choice
• 2.4MCP servers in Claude Code and agents
• 4.2Few-shot prompting