Effective Tool Descriptions

Definition

Design guidance for a tool's description field — the single most important factor in tool-use performance — plus how to structure tools and their return values so Claude routes correctly.

Key points

• Write ≥ 3–4 sentences: what the tool does, when to use it (and when NOT), what each parameter means, caveats/returns.
• Consolidate related operations into one tool with an action parameter (e.g. github_pr: create | review | merge) rather than many near-duplicate tools.
• Use prefixes to namespace tools (github_list_prs).
• Tool responses should return high-signal fields + stable IDs (slugs / UUIDs), not opaque internal references.
• The description drives routing — poor descriptions are the root cause of tool misrouting.

Why it matters for the exam

• "Which change most improves tool selection?" → almost always improve the description, not the model or tool_choice.
• Tool-misrouting diagnosis questions point back to weak descriptions.

Common gotchas

• Returning opaque internal refs instead of stable IDs breaks downstream chaining.
• One-line descriptions underperform; the exam favours the detailed multi-sentence answer.

See also

• Tool Definition Schema
• Tool Name Regex
• Input Examples
• Structured Tool Errors

Sources

• docs-tools-agents
• netlight-study-guide
• blog-writing-tools