An agent calls a tool, the tool returns forty thousand tokens of log output, and every one of those tokens lands in the context window — where it will sit, competing for the model's attention, for the rest of the session. This is the quiet way agents get worse the longer they run. The fix that has hardened into a pattern over the last year is almost rude in its simplicity: don't read it.

Context offloading is a tool-layer discipline. When a tool returns more material than the agent needs to reason about right now, the wrapper writes the full payload to a file and hands the model a short summary plus a reference — a path, a preview, a note on what's inside. The bulky result sits on disk, available on demand. The active window stays focused on the work. Anthropic frames the underlying constraint plainly: an LLM has a finite attention budget, and good context engineering is "finding the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome."

The mechanism is boring; the timing is the idea#

LangChain's Deep Agents ships this as a default. When a tool call result exceeds 20,000 tokens, the response is offloaded to the configured backend and replaced with a file-path reference plus a preview of the first ten lines. The agent can then grep or read the file to retrieve exactly the span it needs. Cursor applied the same principle to a different payload — MCP tool descriptions rather than tool outputs — syncing them to files the agent searches on demand. In an A/B test on runs that called an MCP tool, that cut total agent tokens by 46.9%.

The interesting part isn't the disk. It's when the retrieval decision gets made. Pasting the whole result inline is a write-time decision: you commit, at the moment the tool returns, to keeping everything, and you pay attention tax on all of it forever. Offloading defers that decision to read-time: the payload waits, and the agent fetches only the slice the current step needs.

Offloading is the same move databases made when they stopped scanning whole tables and started keeping an index: don't carry the data, carry a way to find it.

That reframing matters because it tells you where offloading helps and where it doesn't. It is worthless for a small, high-signal result — the pointer costs more than the payload. It shines exactly where bulk dwarfs relevance: full-file reads, verbose API envelopes, multi-megabyte logs, the transcript of a sub-agent that did an hour of work you need three sentences from.

The pointer is the whole product#

Here is the failure mode nobody warns you about. By default, the model sees only the summary. If that summary is good — "build failed; 2 of 340 tests failed, both in auth/token_test.go; full log at /tmp/run-8842.log" — the agent knows precisely when and why to reopen the file. If it's lazy — "tool output saved to file" — the agent has no signal that the file is worth reading, reasons on the stub, and confidently proceeds on nothing.

So offloading has a sharp edge: done without disciplined retrieval, it doesn't reduce context bloat, it hides it. You've swapped a window full of noise for a window full of blind spots. The engineering that makes it work is not the write-to-disk call, which is trivial. It's the summary the wrapper composes — the one artifact the model actually reads — and the retrieval tools (grep, read, head) that let the agent go back in cheaply and precisely. This is why the pattern travels with the broader context-engineering discipline rather than living alone: the point is to keep high-signal tokens dense, and a pointer that doesn't tell the model what it's pointing at is not high-signal.

Offloading also composes with, but is distinct from, compaction. Compaction summarizes history you've already accumulated; offloading prevents bulk from accumulating in the first place. One is cleanup, the other is a filter at the door.

What to actually do#

This is the sharp end of the broader question of what a tool should return: offloading is one answer — a handle instead of a payload — and it lives or dies on the note attached to the handle. Wrap your high-volume tools so they write results over a threshold to a file and return a structured summary — what the result is, its shape and size, the one or two facts the next step probably needs, and the path. Keep the threshold honest (20K tokens is a reasonable starting line, not a law). Give the agent real retrieval tools so fetching a slice is cheap. And spend your effort on the summaries, because in an offloaded system the summary is the interface between the model and everything it chose not to read.

The context window is the scarcest shared resource an agent has. The best thing you can do with a forty-thousand-token tool result is usually to not spend it — and to leave behind a note good enough that the agent knows when to go get it.