Debugging Claude MCP agents: loops, bad tool calls

The first time a Claude agent reaches a real production system through MCP, the bugs change character. It is no longer a flaky prompt that returns slightly wrong prose. It is an agent that calls refund_order nine times in a row, passes a customer ID that never existed, or spins in a polite loop asking the same database the same question until your token budget evaporates. These are not model defects so much as integration defects — and debugging them well is the difference between an agent you can trust on a Friday night and one you babysit.

This post is a practical taxonomy of the failure modes that actually show up once an agent built on the Claude Agent SDK starts touching live MCP servers, and the concrete instrumentation that lets you catch each one before a customer does.

Why agent bugs hide better than ordinary bugs

A traditional function either returns the right value or throws. An agentic step can do something far more insidious: succeed mechanically while failing semantically. The MCP server returns HTTP 200, Claude gets valid JSON back, and the run completes — but the tool it picked was the wrong one, or the argument it filled in was invented. Nothing crashes. Your logs look green. The damage is in the meaning, not the stack trace.

The second reason these bugs hide is non-determinism. Run the same prompt twice and Claude may take two different paths, only one of which trips the bug. Reproducing a failure therefore requires capturing the exact transcript — system prompt, every tool definition exposed, every tool call and result, and the model's intermediate reasoning — at the moment it happened. If your tracing throws any of that away, you are debugging blind. The single most valuable thing you can build early is a durable, replayable trace of every agent turn.

The three classic failure modes

Most production incidents reduce to one of three patterns. Loops happen when the agent cannot tell that it has already made progress, so it re-issues the same tool call or oscillates between two of them. Wrong tool calls happen when two tools have overlapping descriptions and the model picks the plausible-but-incorrect one — calling search_invoices when it needed search_orders. Hallucinated arguments happen when a required field is missing from context and the model fills it with a confident guess rather than asking or failing.

flowchart TD
  A["Agent turn"] --> B{"Tool call repeated >N times?"}
  B -->|Yes| C["Loop guard: halt & summarize"]
  B -->|No| D{"Args validate against schema?"}
  D -->|No| E["Reject: return validation error to Claude"]
  D -->|Yes| F{"Tool matches intent?"}
  F -->|Uncertain| G["Log low-confidence pick for review"]
  F -->|Yes| H["Execute MCP tool"]
  E --> A
  C --> I["Escalate to human"]
  H --> J["Record trace span"]

Killing loops without lobotomizing the agent

The naive fix for a loop is a hard turn limit. That works, but it converts a loop into a silent truncation — the agent just stops mid-task. A better approach treats repetition as a signal. Track a rolling hash of recent (tool name, normalized arguments) pairs. If the same pair recurs more than two or three times, do not simply kill the run; inject a system-level observation back to Claude: "You have already called this tool with these arguments and received this result. The state has not changed. Choose a different action or conclude." Models respond well to being told they are stuck, because the loop usually stems from the agent not realizing its previous call already answered the question.

Loops also come from tools that return ambiguous "empty" results. If a search returns [] with no explanation, the agent may assume it phrased the query wrong and try again endlessly. Make your MCP tool results self-describing: distinguish "no matching records exist" from "query was malformed" from "you lack permission to see these." That single change eliminates a surprising share of loops, because it gives the model a reason to stop rather than retry.

Stopping wrong tool calls at the source

Wrong-tool selection is almost always a tool-description problem, not a model problem. When you expose a dozen MCP tools, Claude chooses among them using their names and descriptions the way a developer scans an API. If two descriptions could each plausibly answer the user's request, the model is being asked to guess. Audit your tool surface as if it were public API copy: every description should state what the tool is for, what it is not for, and when to prefer a sibling tool. A line like "Use this only for paid invoices; for draft invoices use draft_invoice_lookup" removes the ambiguity that causes misfires.

For high-stakes tools, add a confirmation gate rather than trusting selection alone. Anything that mutates state — issuing a refund, sending an email, deleting a record — should either require an explicit confirmation step or run against a dry-run mode first. When you see the agent reach for a destructive tool, you want a checkpoint, not a leap of faith.

Catching hallucinated arguments before execution

Hallucinated arguments are the most dangerous failure because they pass straight through to your system as real-looking data. The defense is strict, server-side validation on every MCP tool. Define a precise input schema and reject anything that does not conform — but critically, return the rejection to Claude as a structured error, not as a thrown exception that aborts the run. When Claude receives "order_id must match pattern ORD-[0-9]{8}; you supplied 'the customer's recent order'", it will typically recover, go find the real ID, and retry correctly. Validation thus becomes a teaching signal, not just a gate.

Go further for fields that reference real entities. An ID that is well-formed can still be invented. Where it is cheap, verify existence before acting: confirm the order actually belongs to the requesting customer, confirm the account is active. The pattern is to make hallucinated arguments fail loudly and early, close to the model, where the feedback loop can correct them — rather than deep in your business logic where the failure is expensive and hard to trace back.

Building the trace you will actually debug from

Every defense above depends on observability. Instrument each agent turn as a span: the model's input context size, the tools offered, the tool chosen, the raw arguments, the validation outcome, the MCP result, and latency. Tag spans with a run ID so you can reconstruct a full session. When something goes wrong, you want to open one trace and watch the agent's decisions unfold step by step. Aggregate across runs too — a dashboard of "top tools by validation-rejection rate" or "runs that hit the loop guard" surfaces systemic problems long before they become incidents. Debugging agents is ultimately an exercise in making the invisible visible.

Frequently asked questions

What is the most common cause of agent loops with MCP?

Ambiguous or non-informative tool results. When an MCP tool returns an empty or opaque response, Claude often assumes it asked incorrectly and retries. Making results self-describing — clearly distinguishing "no data," "bad query," and "not permitted" — eliminates most loops at the source.

How do I stop Claude from calling the wrong tool?

Treat tool descriptions as precise API documentation. State what each tool is for, what it is not for, and which sibling tool to prefer in overlapping cases. Reduce the number of simultaneously exposed tools, and add confirmation gates for any tool that mutates state.

How should MCP tools handle invalid arguments from the model?

Validate against a strict schema and return failures as structured errors back to Claude rather than throwing. A clear message like "field X must match pattern Y; you supplied Z" lets the model correct itself and retry, turning validation into a recovery mechanism.

Do I need full transcripts to debug agents?

Yes. Agent failures are non-deterministic and often semantic, so you need the exact captured transcript — system prompt, exposed tools, every call and result, and intermediate reasoning — to reproduce and understand them. Lossy logging makes serious debugging nearly impossible.

Bringing agentic AI to your phone lines

CallSphere takes the same debugging discipline — loop guards, validated tool calls, and full traces — and applies it to voice and chat agents that answer every call and message, use tools mid-conversation, and book work around the clock. See it live 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.