Claude Platform Docs
MessagesTools

Troubleshooting tool use

Fix the most common tool-use errors with symptom-to-fix diagnostic tables.

Find the symptom or error you see, and then apply the fix listed for it.

Claude calls the wrong tool

SymptomLikely causeFix
Claude calls tool A when you wanted tool BDescription ambiguitySharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do. See Define tools.
Claude never calls your toolTool name collision or overly generic schemaCheck for duplicate names across your tool list. Add input_examples to make the intended use concrete.
Claude calls with wrong parameter typesAmbiguous schemaAdd strict: true (if your schema is in the supported subset) or add input_examples.

Claude invents tool parameters

SymptomLikely causeFix
Parameter that doesn’t exist in your schemaModel over-generation without strict modeAdd strict: true if your schema is in the supported subset.
Parameter values outside your enumMissing strict mode or too-large enumShrink the enum or add input_examples showing valid choices.

Parallel tool calls don’t work

SymptomLikely causeFix
Claude calls tools sequentially when parallel would be betterMessage history formattingSend multiple tool_result blocks in ONE user message, not one per turn. See Parallel tool use.
disable_parallel_tool_use seems ignoredSet too late in the conversationSet it on the request that returns tool_use. Setting it on a later request has no effect on earlier tool calls.

Cache keeps invalidating

SymptomLikely causeFix
Every request is a cache misstool_choice, the thinking configuration, or output_config.effort varying between requestsKeep tool_choice stable or place the cache_control breakpoint before the variation point; hold the thinking configuration and effort level constant for the life of a cached conversation. See Tool use with prompt caching and Thinking and prompt caching.
Adding a tool mid-conversation breaks cacheTool prepended to the tools arrayDeclare the tool with defer_loading: true from the first request and let tool search load it inline, instead of adding it to the array later.

Errors at request time

The Error column shows part of each message, and ... stands for text that varies.

ErrorCauseFix
tool_use ids were found without tool_result blocks immediately afterMissing tool_result for some tool_use IDs, or tool_result is not the first content block in the user messageReturn one tool_result for every tool_use block in the assistant response. Put tool_result blocks before any text. See Handle tool calls and Parallel tool use.
was found without a corresponding ... blockThe follow-up request keeps a waiting server tool from runningSee A server tool call has no result block.
Unsupported regex feature in pattern field: ...A strict tool’s pattern uses a regex feature that strict mode can’t compile, such as a backreference, a word boundary, or a large {n,m} rangeSimplify the pattern. See JSON Schema limitations.
Invalid regex in pattern field: ...A strict tool’s pattern has a lookahead, a lookbehind, or a syntax errorRemove any lookahead or lookbehind and fix any syntax errors. See JSON Schema limitations.
All tools have defer_loading: trueNo tools visible to the modelAt least one tool must be immediately loaded. The tool search tool itself must never have defer_loading: true.

A server tool call has no result block

A server tool is still waiting to run when its server_tool_use or mcp_tool_use block has no result block. The error was found without a corresponding ... block means the follow-up request keeps the waiting tool from running. The error message and the previous stop_reason show why. Use the first case that matches:

  • The message ends with but no `<name>` tool was provided or is not available after the last message: Here, <name> is the tool’s name, such as web_search. The request no longer defines the tool. Send the same tools array as before, and the same mcp_servers for an MCP tool.
  • The previous stop_reason was tool_use: Your user message had content after the tool_result blocks. Send only the tool_result blocks, one for each client tool_use block.
  • The previous stop_reason was pause_turn: You added a user message. Remove it so that the request ends with the paused response as an assistant message.

For the full steps, see When a server tool is still waiting and the pause_turn stop reason.

Error: thinking blocks cannot be modified

If a request fails with a 400 invalid_request_error whose message contains `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified when continuing a conversation after a tool call, your application is altering the assistant’s thinking blocks before sending them back. Send the entire assistant message back unchanged, then append your tool_result.

See Thinking blocks cannot be modified for the full error and fix steps.

Claude flags tool results as prompt injection

SymptomLikely causeFix
Claude refuses to act on a tool result, or asks the user to confirm instructions that came from itYour own instructions are being delivered inside the tool_result contentClaude is trained to treat instructions inside tool results as potentially untrusted third-party content. Move your instructions out of the tool result: send them in a user turn after the tool_result block, or, on supported models, in a mid-conversation system message. Keep the tool result to just the data. See Mitigate jailbreaks and prompt injections.

JSON escaping differences between model versions

SymptomCauseFix
String comparison on tool inputs fails with newer modelsUnicode and forward-slash escaping differs between model versionsParse with json.loads() or JSON.parse(). Never do raw string matching on serialized input.

Next steps

Write schemas and descriptions that steer Claude toward the right tool.

Run tools and return results in the required message format.

Full directory of Anthropic-provided tools and their version strings.

Was this page helpful?