How Do You Write Tool Descriptions Claude Can Use?
Write each description as you'd brief a new hire: what the tool does, when to use it and when not to, what each parameter means, and what it won't return. Anthropic's docs say this is by far the most important factor in tool performance, and to aim for at least 3 to 4 sentences per tool, or more if it's complex.
Review these tool definitions for Claude. For each tool, rewrite the description in at least 3 or 4 sentences: - what it does, and exactly what it returns - when to use it, and when not to, naming the other tool to use instead - what each parameter means, with an example value - caveats, including what it doesn't return Also flag: - any two tools a new hire could confuse - unclear parameter names, such as "user" where "user_id" is meant - any parameter that asks for reasoning. Rename it so it asks for a short explanation or evidence. [paste your tools array]
- "Gets the stock price"
- no parameter description
- silent on what it won't return
- what it does and returns
- when to use it, and when not
- what each parameter means
- 3 to 4sentences per tool, at least
- 128characters at most in a name
- 4,096characters before Claude Code cuts16,384 via tool search
Try it now
- 1Pull one tool definition from your code, ideally the one Claude most often gets wrong.
- 2Run the review prompt above on it, and replace the description.
- 3Send 10 test requests through it, including two where the tool shouldn't be used.
- 4You'll know it worked if wrong calls drop on the same requests. Log which tool was called, with what input, so you're comparing like with like.
Use it when
Use it for any tool definition or MCP server, and especially when Claude picks the wrong tool, leaves out arguments or invents values. Anthropic's docs say an invalid call usually means Claude didn't have enough information, so a better description is the first fix to try.
Skip it when
A single obvious tool in a throwaway script doesn't need a long brief, and you can skip the examples entirely. Don't use descriptions to hold your business rules or error handling, since those belong in your system prompt and your code.
Why it works
When you pass tools, the API builds a system prompt from your definitions, so a description is really prompt text. It's what Claude reads when deciding whether to call a tool and what to send. Anthropic's tool-writing guide says small description changes can have large effects, and describes how refining a web search tool's description stopped Claude from appending the year to queries. Names are limited to ^[a-zA-Z0-9_-]{1,128}$. Unambiguous parameter names matter too, such as user_id rather than user.
Example
You have a tool called search with the description "Searches data". Rewrite it as docs_search: "Full-text search over published help articles. Use it to find content by topic. Don't use it for an exact article ID, for which you should call docs_get. Returns up to 10 titles with slugs and snippets, and doesn't return the full article body." The query parameter gets its own description and an example.
Going further
For nested or format-sensitive inputs, add input_examples. Anthropic says these cost about 20 to 50 tokens for simple examples and 100 to 200 for complex ones, and each must match the schema or you get a 400 error. They aren't supported on server tools. One trap on current models: a parameter asking for Claude's thinking or step-by-step reasoning can trigger a reasoning_extraction refusal, so ask for a short explanation instead. In Claude Code, MCP tool descriptions are cut at 4,096 characters, or 16,384 for tools loaded through search, so put the key details first.
Common mistakes
- Writing one-line descriptions and treating wrong calls as a model problem.
- Leaving parameters undescribed, because the name seemed obvious to you.
- Writing descriptions that overlap, with no statement of when to use one rather than the other.
- Adding a
reasoningparameter to log why a tool was called, and then getting refusals. Useexplanation.
Sources
- Define tools, Claude Platform Docs
- Handle tool calls, Claude Platform Docs
- Writing tools for agents, Anthropic Engineering
- Connect Claude Code to MCP, Claude Code Docs
Checked 6 November 2026. Products change often, so confirm details with the vendor.