Debugging Claude Agents: Loops, Bad Tool Calls, Fixes (Prompt Caching With Claude)

The first time a Claude agent works, it feels like magic. The fifth time it silently burns through 200,000 tokens calling the same search tool in a loop, it feels like a production incident. Debugging agentic systems is its own discipline, and most of the failures are not in the model — they are in the seam between your prompt, your tool definitions, and the feedback the agent gets back. This post walks through the failure modes you will actually hit when running Claude (Opus 4.8, Sonnet 4.6, or Haiku 4.5) in an agent loop, and how to find and fix them without accidentally torching your prompt cache in the process.

Key takeaways

• Most agent bugs trace to three causes: ambiguous tool descriptions, lossy tool results, and a stop condition the model never reaches.
• Log the full message array per turn — input tokens, cache read tokens, the exact tool call, and the raw tool result — or you are debugging blind.
• Tool-call loops are usually a feedback problem: the agent cannot tell that its last action failed or already succeeded.
• Hallucinated arguments almost always mean your JSON schema is too loose; tighten required, enum, and descriptions.
• Keep the cacheable prefix of your prompt byte-stable while debugging, or every fix invalidates the cache and inflates cost.

Why agent debugging is different from prompt debugging

A single prompt either returns what you want or it does not, and you iterate in seconds. An agent is a loop: the model emits a tool call, your code runs it, you append the result, and you call Claude again. A bug can appear on turn 1 or turn 14, and the state that caused it is spread across a growing message array. By the time the agent misbehaves, the relevant evidence is buried six tool results back.

The single most valuable thing you can do is instrument the loop before you need it. For every turn, log the turn index, the model's stop reason, the tool name and arguments it chose, the raw tool result you fed back, and the token accounting from the response — specifically usage.input_tokens, usage.cache_read_input_tokens, and usage.output_tokens. That last triple tells you whether your prompt cache is even being hit, which matters because a debugging session that re-runs an agent fifty times can cost real money if every run is a cache miss.

A definition worth keeping handy: an agent loop failure mode is any pattern where the agent's tool-use cycle fails to converge on a correct terminal answer — by repeating actions, selecting the wrong action, or supplying invalid inputs to a correct action. Those three branches map cleanly to the three bugs below.

The three failure modes and how they look in logs

Loops are the loudest. The agent calls search_orders, gets a result, then calls search_orders again with nearly identical arguments, forever. In the logs you will see the same tool name repeating with monotonically growing input tokens. Loops happen when the tool result does not clearly tell the model whether it succeeded, or when the system prompt never defines a stopping condition.

Wrong tool calls are quieter. The agent picks create_ticket when it should have picked update_ticket, and the run technically completes. You only catch these with assertions on the final state or with evals. In logs, look for a tool call whose arguments do not match the user's stated intent — a strong sign two tool descriptions overlap.

Hallucinated arguments are the sneakiest. The agent calls the right tool but invents an order_id that was never in the conversation, or passes a date in the wrong format. This is a schema problem: the model is filling a required field it has no real value for.

flowchart TD
  A["Agent emits tool call"] --> B{"stop_reason == tool_use?"}
  B -->|No| C["Final answer — assert on state"]
  B -->|Yes| D{"Same tool + args as last turn?"}
  D -->|Yes| E["LOOP: result not informative"]
  D -->|No| F{"Args valid vs schema?"}
  F -->|No| G["HALLUCINATED ARGS: tighten schema"]
  F -->|Yes| H{"Tool matches intent?"}
  H -->|No| I["WRONG TOOL: disambiguate descriptions"]
  H -->|Yes| A

Fixing loops: make the result speak

An agent loops because it cannot perceive progress. The cleanest fix is to make every tool result self-describing. Instead of returning a bare array, return a small envelope that states what happened and what is left to do. Compare a silent result to an informative one:

// Silent — invites a loop
{ "results": [] }

// Informative — gives the model a stop signal
{
  "status": "no_matches",
  "message": "No orders found for email 'x@y.com'. Do not retry the same query; ask the user to confirm the email.",
  "results": []
}

The second form tells Claude that retrying is pointless and what to do instead. Pair this with a hard turn cap in your loop — break after, say, 12 tool turns and return a graceful failure. The cap is a seatbelt, not a fix; if you are hitting it routinely, your results are not informative enough.

Fixing wrong tool selection

When Claude reaches for the wrong tool, the model is doing exactly what your descriptions told it to. Two tools with descriptions like "Look up an order" and "Find order details" are indistinguishable. Rewrite descriptions to be mutually exclusive and to state when NOT to use each. Lead with the trigger condition: "Use this ONLY when the user has already provided a numeric order ID." Add negative guidance in the system prompt for the few pairs that still confuse the model. Reordering tools rarely helps and may hurt cache hits if your tool list is part of the cached prefix.

Fixing hallucinated arguments with strict schemas

Loose JSON schemas are an open invitation to invention. Make every truly-required field required, constrain strings with enum or pattern, and put format examples directly in the field description. If an argument can only come from a previous tool result, say so: "Must be an order_id returned by search_orders; never construct one." When a value is genuinely unknown, the right behavior is for the agent to ask the user — so give it a tool to do that, or instruct it to respond in text rather than guess.

{
  "name": "refund_order",
  "description": "Issue a refund. Use ONLY after confirming the order exists via search_orders.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^ORD-[0-9]{8}$",
        "description": "Exact order_id from search_orders. Never invent." },
      "reason": { "type": "string", "enum": ["damaged", "late", "wrong_item"] }
    },
    "required": ["order_id", "reason"]
  }
}

Common pitfalls

• Invalidating the cache every edit. If you tweak a single word near the top of a cached system prompt mid-debug, every subsequent call is a cache miss. Make debug edits below the cache breakpoint, or accept the cost knowingly.
• Swallowing tool errors. Catching an exception and returning {} hides the failure from the model, which then loops. Always surface errors as structured, readable results.
• Logging only the final answer. The bug lives in the intermediate turns. Capture the full message array, not just the last assistant message.
• Trusting temperature for determinism. Even at temperature 0, tool-use paths can vary. Reproduce bugs by replaying the exact recorded message array, not by re-running the user's query.
• Over-prompting. Adding three paragraphs of warnings to fix one loop often introduces new conflicts. Fix the tool result first; touch the prompt last.

Debug an agent loop in 6 steps

1. Add per-turn logging: turn index, stop reason, tool name, arguments, raw result, and token usage including cache reads.
2. Reproduce by replaying the recorded message array, not the original user query.
3. Classify the failure using the flowchart above: loop, wrong tool, or bad args.
4. Apply the targeted fix — informative results, disambiguated descriptions, or strict schema.
5. Add a hard turn cap and an assertion on final state so regressions are loud.
6. Re-run on a saved set of failing transcripts before shipping, keeping the cached prefix stable.

Symptom in logs	Root cause	Fix
Same tool + args repeating	Uninformative result	Self-describing result envelope + turn cap
Plausible run, wrong final state	Overlapping tool descriptions	Mutually exclusive descriptions, negative guidance
Invalid or invented argument	Loose JSON schema	required, enum, pattern, "never invent" notes
Cost spikes during debugging	Cache misses from prefix edits	Edit below the cache breakpoint

Frequently asked questions

How do I stop a Claude agent from calling the same tool repeatedly?

Make the tool result explicitly state success, failure, or "no further action needed," and instruct the model not to retry on a known-empty result. Back it with a hard turn cap so a regression can never run unbounded.

Why does my agent invent IDs and arguments?

Because the schema lets it. Mark fields required, constrain them with patterns or enums, and state in the description that certain values must come from a prior tool result and must never be fabricated. Give the agent an explicit path to ask the user when a value is unknown.

Does debugging affect my prompt cache cost?

Yes. Every edit above your cache breakpoint forces a full re-read at full input price. During a debug session, keep the cacheable prefix byte-stable and confine experiments to the dynamic tail, then watch cache_read_input_tokens to confirm you are getting hits.

What is the fastest way to reproduce an intermittent agent bug?

Record the full message array for every run in production or staging. When a bug appears, replay that exact array rather than re-issuing the user's query. Replaying the recorded state removes the nondeterminism of the upstream turns and isolates the failing step.

Bringing agentic AI to your phone lines

CallSphere puts these same debugging disciplines behind voice and chat agents that answer every call, call tools mid-conversation, and recover gracefully when a step fails. See the agents in action at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.