Tool description basics
When Claude decides whether and how to call a tool, the only information it has is the tool's name, its description, and its parameter schema (plus whatever descriptions those parameters carry). There is no hidden context beyond that -- which means a vague or incomplete description doesn't just risk a slightly worse call, it can be the entire reason a tool is picked incorrectly, skipped when it should be used, or called with wrong arguments.
What a strong description covers
- What it does -- stated plainly, not just implied by the tool's name.
- When to use it -- the situations/phrases that should trigger this tool.
- When NOT to use it -- especially important if a similar tool exists.
- Parameters -- each one named descriptively, with its own short description, and required vs. optional (with defaults) stated explicitly.
- Return shape -- what comes back, and in what format.
- Known gotchas -- any field or behavior that doesn't work the way its name would suggest.
This repo's own real tool/skill descriptions already follow this discipline in practice -- see subagentskills.com's catalog, where every row's description is copied verbatim from a real SKILL.md frontmatter, and several explicitly state "do NOT use this for X".
General, well-established tool-use prompt-engineering guidance; see the full practices catalog for individual, sourced rows.