Describe Tools Like You'd Brief a New Hire

A tool-design principle for function calling: write each tool's description and parameter docs as if briefing a capable new hire who's never seen your system — what it does, when to use it (and when not), what each argument means, and what happens on failure — rather than a terse one-liner.

Claude decides whether and how to call a tool almost entirely from its description and schema. A vague 'gets user data' leaves the model guessing which tool fits, what to pass, and when to reach for it — so it calls the wrong one, omits arguments, or invents values. A description written like an onboarding brief gives it the judgement to choose correctly, and clear parameter docs make well-formed calls the default instead of a coin flip. Tool descriptions are prompt engineering; they deserve the same care.

Any tool-use or function-calling setup, MCP servers, and agents — especially when the model has several similar tools and has to pick the right one.

There isn't really a 'don't' here for production tool use, but for a single obvious tool in a throwaway script, an exhaustive brief is overkill. Match the effort to how often the tool is chosen wrongly.

Review my tool definitions for Claude. For each, rewrite the description and parameter docs as if briefing a new hire: what it does, when to use it and when NOT to (especially vs. the other tools), what each parameter means with an example value, and what it returns or does on failure. Flag any two tools that could be confused for each other.

<tool definitions>

Renaming a tool from 'search' to a description that says 'Full-text search over indexed docs; use for finding content, NOT for exact-ID lookup (use get_by_id for that)' stops Claude from reaching for search when it has an ID — a whole class of wrong calls gone.

When two tools keep getting confused, disambiguate them inside their descriptions with an explicit 'use this NOT that when…' contrast. Models pick correctly far more often when the boundary between overlapping tools is spelled out rather than implied.

• One-line descriptions that force the model to guess intent and arguments.
• Overlapping tools with no stated boundary, so the wrong one gets called.
• Documenting the happy path but never what a failed call returns, so errors aren't handled.