Tool Output Truncation: When an Agent Reasons Over a Result It Never Fully Saw

Tool output truncation is the failure mode where a tool call returns successfully, but the data reaching the agent has already been cut down to a size limit before the model ever sees it, with nothing in the payload marking that a cut happened. The agent does not get an error. It gets a complete-looking fragment, and it reasons over that fragment as if it were the whole result. A file-search tool that found 400 matches but returns the first 50; a log tail truncated at 10 KiB with the actual error three lines past the cut; a database query that silently caps at 1,000 rows out of 10,000. In every case, the agent's next action is built on a result that looks like ground truth and is actually a prefix.

This is a narrow, specific mechanism, not a synonym for context running out. It happens at the moment a single tool call's output is prepared for the model, before that output ever enters the running transcript, which is what separates it from the context-window-level failures already covered on this site.

The mechanism

Every agent framework that calls tools has to decide what happens when a tool's raw output is larger than it wants to pass to the model. Nearly all of them cap it, because an unbounded tool result can blow a context budget in one call. The cap itself is not the problem; it is a reasonable engineering default. The failure mode is specifically what happens at the boundary: whether the agent is told the cap was hit, and whether it has any way to get the rest.

A 2026 survey of agent framework defaults by engineer Tian Pan lays out how inconsistent that boundary behavior actually is across widely used tools (Tian Pan, "Silent Tool Truncation," May 2026):

The same post documents a case where a transport-layer limit, not an application-level truncation policy, produced the same symptom through a different path: a Node.js child process's stdout maxBuffer limit cut a Claude Code MCP response, throwing ERR_CHILD_PROCESS_STDIO_MAXBUFFER, while the complete output sat in a temp file the agent had no access to. The failure was never surfaced to the model; it just received less than the tool had actually produced. That is the general shape of the mechanism: truncation can happen at the tool layer, the framework's result-passing layer, or the underlying transport, and from the model's seat, all three look identical, a result that ends cleanly and claims nothing is missing.

Why it fails silently rather than loudly

A 2026 audit of agent-to-tool interactions across 15 real scientific tools, built specifically to find this class of problem, defines the pattern precisely: a tool call "appears to succeed, but some or all of the information or functionality returned through its API or wrapper is incomplete or missing," with neither the agent nor the user told the gap exists (Singh, Gopalan, and Narayanan, "Silent Failures in Agent-Tool Interaction: An Audit of ToolUniverse," arXiv:2609.26836). Across that audit, the authors manually validated 91 such failures and found the majority originated at the API layer or the wrapper layer around it, meaning the truncation or omission often starts upstream of the agent framework entirely and simply propagates through.

The reason this specific failure stays hidden where a crash would not: a language model is not built to notice an input is incomplete unless the incompleteness is marked. Pan's post makes the mechanical point directly: a reasoner does not error out on a truncated prompt. It infers, fills gaps with what's plausible, and answers confidently, because confident completion is what the model is doing on every turn regardless of whether the input behind it is whole. The failure mode shifts from a stack trace, which gets noticed immediately, to a plausible, well-formed, wrong conclusion, which often doesn't get noticed until someone checks the tool's actual full output against what the agent reported.

This is also what separates tool output truncation from context compaction failure modes. Compaction failures happen when a summarization step, applied across an accumulated transcript, drops something the agent still needed; that is a context-management decision made deliberately, even if tuned wrong. Tool output truncation happens one call earlier and often outside the agent's own context logic entirely, inside the tool, the SDK, or a transport layer the agent framework doesn't control. An agent can have a perfectly tuned compaction strategy and still build a wrong conclusion on a tool result that was cut before compaction ever had a chance to touch it. It is also distinct from tool-use drift, which is about choosing the wrong tool for the step; truncation can happen to a correctly chosen tool's output, no selection error involved.

Why this compounds in long-running agents

A single truncated result is a data problem. It becomes a behavioral-state problem, the kind this site tracks under behavioral state decay, once the agent treats that fragment as settled fact and keeps building on it. A coding agent that greps for all callers of a function, gets 50 of 400 hits back with no total count, and concludes the function is lightly used, will plan a refactor on that false premise and keep planning on it for the rest of the session, because nothing in its own context ever flags the number as a lower bound. That is the same mechanism behind hallucination cascades: an early, unflagged error becomes an input to every later step, each of which looks locally reasonable and is built on a foundation nobody re-checked. The research into observation handling inside SWE-agent-style coding agents gives a sense of how much of an agent's turn is actually this kind of tool output in the first place: a 2026 study comparing context-management strategies for SWE-agent on SWE-bench Verified notes that observation tokens, the raw output of tool calls, dominate an average agent turn, which is exactly why a silent cap on that channel has outsized leverage over what the agent ends up believing (Lindenbauer, Slinko, Felder, Bogomolov, and Zharov, "The Complexity Trap," arXiv:2508.21433).

Detection

The audit signal to build is a mismatch check, not a bug report: log the byte or token size of what the tool actually produced against the size of what reached the model, for every tool call, and flag the difference. A few cheaper proxies work without full instrumentation:

• Round-number endings. A result that stops at exactly 50, 100, 256 lines, or a suspiciously clean byte boundary is a stronger truncation signal than it looks, because real data rarely ends on a framework's default cap by coincidence.
• Missing totals. Any tool result that returns a list or a count without also stating how many items exist in total should be treated as a lower bound until proven otherwise, not as the complete answer.
• Synthetic probe. Run a known-oversized query against each tool in a staging pass (a search guaranteed to return more results than the suspected cap, a file guaranteed to be longer than the suspected limit) and check whether the agent's reported total matches reality.

Mitigation

The fix that actually closes the gap is structural, not a bigger cap: the tool's result needs to carry its own completeness information, not rely on the agent inferring it. A result that explicitly states a total count, whether it was truncated, and a cursor or offset for retrieving the rest gives the agent something to act on, re-query, ask for more, or at minimum caveat its answer, rather than something to silently finish reasoning over. Raising the cap number alone doesn't fix this; it just moves the same silent failure to a larger input. Pairing a completeness flag with state externalization also helps at the plan level: if a tool result that might be partial gets written to durable, provenance-tagged state rather than folded straight into the working transcript, a later agent stopping criteria check has something concrete to verify before letting the agent declare the task done on top of it.

Related terms

• Context compaction failure modes: the adjacent but distinct failure where summarization, not a single tool call, drops needed information.
• Tool-use drift: the failure mode where the agent's tool *selection* degrades, as opposed to a correctly chosen tool's result being cut.
• Hallucination cascades: the propagation pattern that turns one unflagged truncated result into a chain of downstream wrong conclusions.
• State externalization: the mitigation pattern that gives a completeness-flagged tool result somewhere durable to live before the agent builds further plan steps on it.
• Behavioral state decay: the umbrella phenomenon this failure mode feeds, once a truncated result gets treated as settled fact.

FAQ

What is tool output truncation? It's the failure mode where a tool call succeeds but its result has been cut to a size cap before reaching the model, with no marker in the payload indicating anything was cut, so the agent reasons over a partial result as if it were complete.

Is this the same as running out of context? No. Running out of context is a window-level limit hit across an accumulated transcript. Tool output truncation happens to a single tool call's result, often before that result ever enters the running context, and often in a layer, the tool, the SDK, or the transport, that the agent's own context management never touches.

Which agent frameworks are affected? The pattern isn't framework-specific; it is a property of any system that caps tool-result size, which is nearly all of them. Published defaults vary widely, from roughly 10 KiB in Codex CLI to a 25,000-token default in Claude Code, and the inconsistency across tools inside the same agent is itself part of the risk, since a developer tuning for one tool's limit can still be surprised by another's.

Does increasing the size cap fix it? No. A larger cap delays the point at which a given result gets cut, but any fixed cap still produces an uncaught truncation on a large enough result, with the same lack of signal to the model. The fix that holds regardless of result size is a completeness flag and a total count returned with every result, not a bigger number.

How is this different from a tool simply failing? A tool failure (an error, a timeout, a non-200 response) is usually visible to the agent framework and often to the model. Tool output truncation produces a response that looks exactly like a successful, complete call; that resemblance to success is what makes it a silent failure rather than an error to handle.