Tool use
Write clear tool descriptions, keep the tool list short, report errors Claude can act on, and get JSON that matches a schema.
-
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. Level 4: Multi-tool systemsToo thinleaves questions open
- "Gets the stock price"
- no parameter description
- silent on what it won't return
A real briefat least 3 to 4 sentences- what it does and returns
- when to use it, and when not
- what each parameter means
-
How Many Tools Should You Give Claude? Give Claude as few tools as cover the job, with clearly separate purposes. Level 4: Multi-tool systems
- ~55ktokens in tool definitionsfive servers, before any work
- 85%+typical cut with tool search
- 30 to 50tools before selection degrades
- 3 to 5tools loaded for a request
-
How Should Tools Report Errors to Claude? Return the failure as a tool_result with is_error: true, and say what went wrong and what Claude should try next. Level 4: Multi-tool systemsDo
- Set is_error: true
- Say what went wrong
- Say what to try next
Don't- Return only "failed"
- Send a raw stack trace
- Send an empty success
-
How Do You Get Reliable JSON From Claude? On the API, set output_config.format with a JSON schema for the response, or strict: true on a tool for its inputs. Level 4: Multi-tool systemsOld tricks400 on current models
- prefilling the response with {
- forced tool_choice on current models
Use todayschema enforced- output_config.format for answers
- strict: true for tool inputs
What current models changed
Old tool-use code can break on an upgrade. Forced tool_choice now returns a 400 error on Opus 5.5, Sonnet 5.5 and Fable 5.1, and prefilled responses return a 400 from the Claude 4.6 models on. Use strict tool use and structured outputs instead. Parameters that ask for Claude's reasoning can also trigger refusals, so ask for a short explanation.
Where the real gains are
Anthropic's docs say detailed descriptions are by far the most important factor in tool performance, so start there. Then cut the tool list, since selection degrades past 30 to 50 tools. Then look at what tools return, in both success and failure. In each case you're writing for a reader with limited context. Log which tool was called with what input, so you can measure changes against real requests.
What is the difference between tool use and function calling?
They're the same idea. Claude's docs call it tool use. You describe a function, Claude asks to call it with specific inputs, your code runs it, and you return the result as a tool_result block.
How many tools can Claude handle?
Anthropic says the ability to pick the right tool degrades past 30 to 50 tools. With the tool search tool, a request can defer up to 10,000 tools and load only those it needs, which the docs suggest once you have 10 or more.
Why does tool_choice return a 400 error?
On Opus 5.5, Sonnet 5.5, Fable 5.1 and Mythos 5.1, forced tool_choice values any and tool aren't supported. Use auto with strict tool use for schema-valid inputs, or structured outputs when you need a fixed JSON shape.
How do I get JSON from Claude reliably?
Use structured outputs on the API, setting output_config.format with a JSON schema. Anthropic says responses will parse and match the schema, with exceptions for refusals and hitting max_tokens, so check the stop reason before you use the result.
How should a tool report an error to Claude?
Return a tool_result with is_error set to true, and say what went wrong and what to try next. Anthropic's docs say Claude will retry an invalid request 2 to 3 times with corrections, so a specific message helps it recover.