Debugging Claude Managed Agents: Loops, Bad Tool Calls (Managed Agents Sandboxes Tunnels)

The first time a self-hosted Claude managed agent goes wrong inside its sandbox, it rarely throws a clean stack trace. Instead you get something worse: a run that quietly burns forty turns calling the same tool with slightly different arguments, never converging, until your token budget alarm fires. When an agent runs inside a sandbox you control and reaches your systems over an MCP tunnel, the bug surface is no longer just "the model said something dumb." It spans the prompt, the tool schema, the transport, and the environment the sandbox can actually see. Debugging that stack is a skill of its own, and it is mostly about making the agent's hidden reasoning and tool I/O visible.

This post walks through the three failure modes that account for the overwhelming majority of broken managed-agent runs — infinite or near-infinite loops, wrong tool selection, and hallucinated arguments — and gives you a concrete way to instrument, reproduce, and fix each. The examples assume a Claude agent (Opus 4.8 or Sonnet 4.6) running in a sandbox with tools exposed over the Model Context Protocol.

Key takeaways

• Most agent bugs are observability bugs first. Log every tool call's name, raw arguments, latency, and the verbatim result before you touch the prompt.
• Loops usually mean the agent can't tell it already succeeded — fix the tool's return value, not the system prompt.
• Wrong tool calls trace back to vague tool descriptions and overlapping schemas far more often than to model weakness.
• Hallucinated arguments come from under-constrained JSON schemas; tighten enums, required fields, and validation at the MCP server boundary.
• Replay beats re-running. Capture the full transcript so you can reproduce a failure deterministically instead of rolling the dice on a live agent.

Why managed-agent debugging is different

A managed agent is an autonomous loop: Claude reads context, decides on a tool, the sandbox executes it, the result is fed back, and the cycle repeats until the task is done or a stop condition trips. Every one of those hops can fail independently. The model can pick the wrong tool. The MCP server can return a result the model misreads. The sandbox can lack a file or network route the agent assumes exists. Because the loop is automated, a single bad decision compounds — the agent acts on its own wrong output and digs deeper.

The practical consequence is that you cannot debug a managed agent by reading the final answer. You debug it by reading the trajectory: the ordered sequence of (thought, tool call, arguments, result) tuples. If you are not capturing that trajectory verbatim — including the exact JSON arguments Claude emitted and the exact bytes the tool returned — you are guessing. The single highest-leverage thing you can do is structured logging at the MCP boundary.

{
  "turn": 7,
  "tool": "search_orders",
  "arguments": { "customer_id": "cus_4812", "status": "opn" },
  "result_preview": "[]  (0 rows)",
  "latency_ms": 142,
  "tokens_in": 38,
  "tokens_out": 0
}

That one log line tells a whole story: the agent passed "opn" instead of "open", the query returned zero rows, and on turn 8 the agent will probably try again with another guess — the start of a loop. Catching it requires logging the raw arguments, not a sanitized summary.

How a failure flows through the sandbox

flowchart TD
  A["Claude decides on a tool"] --> B["MCP tunnel forwards call to sandbox"]
  B --> C{"Args valid & tool exists?"}
  C -->|No| D["Server returns typed error"]
  C -->|Yes| E["Tool runs, returns result"]
  D --> F{"Result clearly signals state?"}
  E --> F
  F -->|No| G["Agent loops / re-guesses"]
  F -->|Yes| H["Agent advances or stops"]
  G --> A

The decision point that matters is F: does the tool result clearly tell the agent what state it's in? Most loops live on the No branch from F back to A. Fixing them is usually about the message the tool sends back, not the prompt that started the run.

Failure mode 1: runaway loops

A loop happens when the agent cannot distinguish "I succeeded" from "I should try again." The classic case is an empty result that looks identical to a not-yet-tried state. If search_orders returns [] for both "no matching orders" and "bad status filter," Claude has no signal and will retry with variations. The fix is to make the tool's return value self-describing: return { "matched": 0, "valid_statuses": ["open", "closed", "shipped"], "note": "status 'opn' is not a recognized value" }. Now the next turn has the information it needs to correct course or stop.

The second-most-common loop is the "polite retry" — the agent calls a write tool, gets an ambiguous success message, isn't sure it worked, and calls it again, creating duplicates. Guard against this with idempotency keys at the MCP server and explicit confirmation in the result ("created": true, "id": "..."). And always set a hard max-turns ceiling on the managed-agent run plus a no-progress detector: if the last N tool calls have identical names and near-identical arguments, halt and surface the trajectory for review rather than letting it grind.

Failure mode 2: wrong tool calls

When Claude reaches for the wrong tool, the root cause is almost always the tool descriptions, not the model. Tools whose descriptions overlap ("get user data" vs "fetch account details") force the model to guess. Write descriptions that say exactly when to use the tool and when not to: "Use to look up a customer's current subscription tier. Do NOT use for billing history — use get_invoices for that." Negative guidance is disproportionately effective.

The other big driver is exposing too many tools. A managed agent with 40 tools in scope spends reasoning budget on selection and picks wrong more often. Scope the toolset to the task. If a run only ever needs read access to three systems, mount only those three over the MCP tunnel. Fewer, sharper tools beat a giant grab-bag every time, and they make the trajectory far easier to read when something does go wrong.

Failure mode 3: hallucinated arguments

Hallucinated arguments — a plausible-looking but invented order ID, a made-up date format, a field the agent assumed exists — are a schema problem. If your JSON Schema marks a field as a free-form string, the model will fill it with something that looks right. Constrain it. Use enum for closed sets, pattern for IDs, format for dates, and mark genuinely required fields as required so the model can't silently omit them.

{
  "name": "refund_order",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^ord_[a-z0-9]{12}$" },
      "reason": { "type": "string", "enum": ["defective", "late", "duplicate"] }
    },
    "required": ["order_id", "reason"]
  }
}

Then validate again inside the MCP server and return a typed error — never a generic 500 — when validation fails. A message like { "error": "order_id not found; did you mean ord_8821ka93mq01?" } lets the agent self-correct in one turn instead of hallucinating a second guess.

Common pitfalls

• Logging summaries instead of raw I/O. A "tidy" log that hides the actual arguments is useless for debugging. Capture verbatim, redact secrets separately.
• Patching the system prompt for a tool-result bug. If the agent loops because the tool returns ambiguous output, no amount of prompt tweaking fixes it reliably. Fix the return value.
• Returning bare 500s from the MCP server. Generic errors give the model nothing to act on. Always return structured, actionable errors.
• No max-turns or no-progress guard. Without a ceiling, a single loop bug can drain a token budget in one run. Set both limits.
• Debugging on live infrastructure. Replay captured transcripts against a mock sandbox so you can iterate without side effects or cost.

Debug a broken run in 6 steps

1. Pull the full trajectory: every (thought, tool, arguments, result) tuple in order, with timestamps and token counts.
2. Find the first turn where the agent went off the rails — not where you noticed, but where the first wrong decision happened.
3. Classify it: loop (repeated calls), wrong tool (mis-selection), or hallucinated args (invented values).
4. Inspect the tool result that preceded the bad turn — ambiguous output is usually the trigger.
5. Apply the matching fix: self-describing return values, sharper tool descriptions, or a tighter schema plus typed errors.
6. Replay the captured transcript against the patched tool to confirm the agent now advances, then add the case to your eval set.

Failure mode cheat sheet

Symptom	Likely root cause	Fix
Same tool, slightly different args, repeated	Result doesn't signal success/failure	Self-describing return values + max-turns guard
Picks a tool that can't do the job	Overlapping/vague descriptions	Negative guidance, scope the toolset
Passes invented IDs or fields	Loose JSON schema	enum/pattern/required + typed server errors
Duplicate writes	Ambiguous success message	Idempotency keys + explicit confirmation

Frequently asked questions

What is a managed-agent trajectory and why does it matter?

A trajectory is the full ordered record of an agent run: each reasoning step, the tool it called, the exact arguments, and the exact result it received. It matters because managed agents act on their own outputs, so a single early mistake compounds. Reading the trajectory lets you find the first wrong decision instead of guessing from the final answer.

How do I stop a Claude agent from looping forever?

Combine three guards: make tool results self-describing so the agent can tell success from failure, set a hard max-turns ceiling on the run, and add a no-progress detector that halts when recent tool calls are near-identical. The result-quality fix prevents most loops; the ceilings cap the damage from the rest.

Should I fix hallucinated arguments in the prompt or the schema?

The schema, almost always. Free-form string fields invite invented values. Constrain with enum, pattern, and required, validate again at the MCP server, and return a typed error that suggests the correct value so Claude can self-correct in the next turn.

Can I reproduce a failure without re-running the live agent?

Yes — capture the full transcript and replay it against a mock or recorded version of your tools. Deterministic replay lets you iterate on fixes quickly, avoids real side effects, and gives you a ready-made regression case to add to your eval suite.

Bringing agentic AI to your phone lines

CallSphere takes the same trajectory-logging, loop-guarding, and schema-tightening discipline and applies it to voice and chat — multi-agent assistants that answer every call, call tools mid-conversation, and book work around the clock without looping or hallucinating. 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.