Tool descriptions are the primary mechanism the model uses to choose between tools. Not a documentation nicety — the actual selection mechanism. A minimal, one-line description produces unreliable selection whenever two or more tools could plausibly apply to the same request.
Three repairs, in order of leverage (cheapest and most targeted first):
- Expand the description — inputs, example queries, edge cases, boundaries, and explicitly when to use this tool versus the similar alternative.
- Rename to remove overlap — a generically-named tool like
analyze_contentcompeting with a more specific need becomesextract_web_resultswith a web-specific description, removing the ambiguity at the name level too. - Split an overly generic tool —
analyze_documentbecomesextract_data_points,summarize_content, andverify_claim_against_source, each with a narrow, unambiguous purpose.
The subtle trap worth knowing by name: system-prompt wording aimed at something else entirely — "when users ask about documents, be thorough" — can create an unintended keyword association that overrides a perfectly well-written tool description. Misrouting isn't always a tool-description problem; sometimes it's a stray instruction elsewhere in the prompt creating a competing signal.
The discriminator: misrouting between similar tools is a description problem first. When a stem asks for the most effective first step, that's almost always expanding and differentiating descriptions — not building a keyword-parsing routing layer (over-engineered, and it bypasses the model's own language understanding) and not necessarily consolidating tools into one generic tool (defensible, but more effort than "first step" calls for, and it just relocates the ambiguity into a parameter).
For a full diagnostic sequence when misrouting shows up in practice — descriptions, naming overlap, stray system-prompt instructions, overly generic tools, tool count, and built-in competition, in the order most worth checking — see ccar-m2-tool-misrouting-checklist.md.