Claude · Advanced

Tool use

Write clear tool descriptions, keep the tool list short, report errors Claude can act on, and get JSON that matches a schema.

Tool use with Claude

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.

Frequently asked
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.