Debugging Claude Agents: Loops, Bad Tool Calls, Hallucinated Args (Skills For Organizations)

The first time an agent works, it feels like magic. The tenth time it silently burns through your token budget calling the same tool with the same wrong argument, it feels like a haunting. When you build skills and agents on top of Claude — whether in Claude Code, the Claude Agent SDK, or a custom orchestrator — most of your real engineering time goes not into the happy path but into the failure modes. This post is about the three failures you will hit again and again, why they happen at the model and harness level, and the concrete moves that fix them.

Agentic failures are rarely random. They follow patterns rooted in how a model decides to act: it reads its context, predicts a tool call, sees a result, and predicts the next step. When that loop misfires, it does so in recognizable ways. Learn the shapes and debugging stops being guesswork.

Key takeaways

• The three dominant agent failures are infinite loops, wrong tool selection, and hallucinated arguments — each has a distinct root cause and fix.
• Turn on full transcript logging first: you cannot debug what you cannot see, and Claude's tool-use blocks are inspectable JSON.
• Tighten tool input_schema with enums, required fields, and descriptions — most hallucinated args come from loose schemas.
• Add a loop breaker: cap turns, detect repeated identical calls, and surface a stop reason instead of spinning.
• Make tool results explicit about success and failure so the model stops retrying a call that already worked.

Why agents fail: the act-observe loop

A Claude agent runs a loop. The model receives the conversation plus tool definitions, emits a tool_use block, your harness executes it and returns a tool_result, and the model continues. Every failure mode is a defect in that cycle. A loop is the model never deciding it's done. A wrong tool call is the model picking the wrong action from an ambiguous menu. A hallucinated argument is the model inventing a value the result schema invited it to invent.

The single most useful debugging habit is to stop reading the agent's final answer and start reading its turns. Each turn contains the exact tool name, the exact arguments as JSON, and the exact result string the model saw next. Ninety percent of bugs are visible the moment you print that sequence.

Reading the transcript: your primary instrument

Before any clever fix, instrument the loop. Log every tool call and result with a turn index. In the Agent SDK or a raw API loop, that means capturing each assistant message's content blocks. Here is a minimal logger you can drop into a Python loop using the Anthropic SDK:

for turn, msg in enumerate(transcript):
    for block in msg.content:
        if block.type == "tool_use":
            print(f"[{turn}] CALL {block.name} {json.dumps(block.input)}")
        elif block.type == "tool_result":
            ok = not block.is_error
            print(f"[{turn}] RESULT ok={ok} {str(block.content)[:160]}")

Run a failing case through this and the pattern jumps out: the same search_orders call with {"id": "unknown"} three turns in a row is a loop plus a hallucinated arg in one trace. Now you know exactly what to fix.

flowchart TD
  A["User goal"] --> B["Claude emits tool_use"]
  B --> C{"Same call as last turn?"}
  C -->|Yes, 2nd+ time| D["Loop breaker: stop & report"]
  C -->|No| E["Validate args vs schema"]
  E -->|Invalid| F["Return is_error tool_result"]
  E -->|Valid| G["Execute tool"]
  G --> H["Return explicit success/failure"]
  H --> B
  F --> B

Failure 1: infinite and near-infinite loops

Loops happen when the model never receives a signal that the task is complete, or when a tool result is ambiguous enough that the model retries forever. A classic case: a tool returns an empty list, the model interprets emptiness as "try again with a different filter," and it cycles through filters indefinitely.

Three fixes, applied together. First, a hard turn cap — most production agents should stop at a sane ceiling and return a partial result with a reason. Second, a repeat detector: hash (tool_name, arguments) per turn and break if the same hash appears twice in a row, since identical inputs will produce identical outputs and there is no value in repeating. Third, make terminal states unambiguous: a result like {"status": "no_match", "action": "ask_user"} teaches the model what to do next instead of leaving it to improvise.

Failure 2: wrong tool calls

When you give a model twelve tools with overlapping descriptions, it will sometimes call list_customers when it wanted get_customer. This is a design problem disguised as a model problem. The model picks tools the way it picks words: by likelihood given the descriptions. Vague or near-duplicate descriptions raise the error rate.

Fix it by writing tool descriptions for a confused reader. Say what the tool does, when to use it, and explicitly when not to. Add disambiguating phrases: "Use get_customer when you already have an exact customer ID. If you only have a name or email, use search_customers first." Fewer, sharper tools beat many fuzzy ones. If two tools are routinely confused, merge them or rename them so their purposes don't collide.

There is a subtler variant worth naming: the model picks the right tool but calls it in the wrong order, skipping a prerequisite. It tries to fetch a record before searching for its ID, or acts before gathering the context it needs. The cure is the same family of fix — encode the dependency in the description ("call search_orders first; get_order requires an ID from that result") and enforce it in your executor by rejecting a call whose prerequisite has not run, returning an instructive error so the model reorders its steps on the next turn.

Failure 3: hallucinated arguments

A hallucinated argument is a plausible-looking value the model fabricated rather than derived — an order ID it never saw, a date it guessed, a UUID it pattern-matched into existence. The deepest cause is a schema that accepts free-form strings without constraints. The model fills the blank because the blank exists.

Constrain the schema. Use enum for fixed choices, mark fields required only when they truly are, and describe each field with where its value should come from: "order_id: must be a value returned by a prior search_orders call; never invent one." Then validate on your side and return an is_error tool result when validation fails. The model reads the error and corrects, which is far better than executing a fabricated call against your database.

{
  "name": "get_order",
  "description": "Fetch one order by ID. Only call with an order_id returned by search_orders.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "pattern": "^ord_[0-9a-f]{12}$",
                   "description": "Must come from a prior tool result."}
    },
    "required": ["order_id"]
  }
}

Common pitfalls

• Debugging the final answer instead of the turns. The bug lives in the tool sequence; read that, not the summary.
• Swallowing tool errors. If your executor returns a clean empty string on failure, the model can't tell success from failure and will loop. Always set is_error and explain what went wrong.
• Over-broad schemas. A plain string field is an invitation to hallucinate. Add patterns, enums, and provenance hints.
• No turn ceiling. An agent without a turn cap is a billing incident waiting to happen. Cap it and return partial progress.
• Changing two things at once. When debugging, fix one variable per run so you can attribute the change. Agentic systems are noisy; isolate.

Debug an agent failure in 6 steps

1. Reproduce the failure deterministically by pinning the model version and lowering temperature for the debug run.
2. Print the full turn-by-turn transcript of tool calls and results.
3. Classify the failure: loop, wrong tool, or hallucinated arg.
4. Apply the matching fix — loop breaker, sharper descriptions, or tighter schema with validation.
5. Re-run the same case and confirm the trace changed as expected.
6. Add the case to your regression set so the bug can't return silently.

Failure-to-fix reference

Frequently asked questions

What is an agentic loop failure?

An agentic loop failure is when an autonomous model repeats tool calls without making progress toward its goal, usually because a tool result is ambiguous or no completion signal exists. The fix is a combination of repeat detection, turn caps, and explicit terminal states in tool results.

How do I stop Claude from hallucinating tool arguments?

Constrain the tool's input_schema with enums and patterns, describe where each value must originate, and validate arguments server-side — returning an is_error result when a value looks fabricated so the model can self-correct.

Why does my agent pick the wrong tool?

Usually because two tool descriptions overlap. Rewrite descriptions to state exactly when to use and not use each tool, and merge tools whose purposes collide. The model selects tools probabilistically from their descriptions, so clarity directly lowers the error rate.

What is the fastest way to debug a misbehaving agent?

Log and read the full turn-by-turn transcript of tool calls and their results. Most agent bugs are immediately visible in that sequence — you'll see the loop, the wrong call, or the invented argument right there.

From debugging to dependable phone agents

The same discipline — read the trace, constrain the tools, break the loops — is exactly how CallSphere keeps its voice and chat agents reliable on live calls, using tools mid-conversation and booking work around the clock. See it 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.