Debugging Claude Tool-Calling Failures: A Troubleshooting Checklist

When an agent uses tools badly, the first reaction is often to add more instructions to the prompt. That rarely fixes it. Most tool-calling problems come from a short list of causes in the tool definitions and the code around them.

1. The description is vague

Claude chooses tools based on their names and descriptions. A tool called get_data with the description "Gets data" gives it very little to go on. Explain what the tool returns, when to use it and when not to: "Look up an invoice by ID. Use only when the user provides an invoice number; for general customer questions, use search_customers."

2. The schema is too loose

If a parameter can only take three values, define it as an enum. Mark required fields as required. Add strict: true to the tool definition when the arguments must always match the schema.

3. There are too many similar tools

Twenty tools with overlapping purposes make any model less accurate. Combine near-duplicates, remove tools that are rarely needed, or use tool search so tools are loaded only when relevant.

4. Tool results are sent back incorrectly

Check what your code returns:

• Every tool_result needs the tool_use_id of the call it answers.
• When Claude requests several tools at once, send all the results together in a single user message.
• If a call fails, return an error message with is_error: true instead of nothing.
• Very large responses hide the useful information. Return only what the model needs.

5. Tool inputs are handled as text

Parse tool inputs as JSON. Different model versions can escape characters differently, so matching on the raw text can fail unexpectedly.

6. The response ran out of space

If stop_reason is max_tokens, Claude hit the output limit before it finished, sometimes in the middle of a tool call. Increase max_tokens.

7. The loop never stops

An agent can repeat a failing call indefinitely. Limit the number of iterations, detect identical repeated calls and tell Claude what to do when a tool keeps failing, such as asking the user or escalating.

8. Server tools report errors differently

Server-side tools like web search return errors inside the result block, with a normal HTTP 200 status. Check the result content rather than waiting for an exception.

Debugging approach

Log the complete request and response for failing turns, including the tool definitions. Reproduce the problem from a saved transcript, change one thing at a time and keep the transcript as a test once it's fixed.

Check the tool definitions and the loop code before rewriting the prompt.