Tool Descriptions That Steer the Model

PROJECT CONTEXT:
My agent picks the wrong tool: shell commands where a search tool exists, whole-file rewrites where an edit tool fits. Framework analyses treat descriptions as the primary steering surface - models choose tools by reading them.

GOAL:
Rewrite every tool description with purpose, when-to-use, when-NOT-to-use, and examples - then verify tool choice improves on a routing test.

REQUIREMENTS:
- Every description answers: what it does, when to use it, when not to (and what to use instead)
- Overlapping tools explicitly disambiguated in both descriptions
- One concise worked example per non-trivial tool
- A tool-routing test: scenarios with a known-correct tool choice
- Description length discipline - steering, not documentation dumps

CONSTRAINTS:
- Descriptions are for the model, not the API docs - write to steer decisions
- Every 'do not use for X' must name the right alternative

DEFINITION OF DONE:
- A 12-scenario routing test passes with the correct tool chosen each time
- Every pair of overlapping tools cross-references the boundary between them
- Descriptions stay under a token budget while covering use/not-use/example
- Real misroutes from transcripts no longer reproduce

COMMON FAILURES TO AVOID:
- Descriptions that restate the tool name ('search_files: searches files')
- No negative guidance, so adjacent tools stay interchangeable in the model's eyes
- Documentation-length descriptions that bloat every single context
- Fixing misroutes with system-prompt patches instead of at the source