Truncating and summarising tool results to fit a context budget

Goal

Keep tool output from crowding out the task in an agent's context while losing nothing the agent still needs to decide correctly.

Prerequisites

A tool layer the agent's host controls (the code that runs the tool and builds the result message), somewhere to write full outputs (a scratch directory), and a per-tool idea of what matters in the output: for a test runner the failures, for a file read the requested range, for a search the matches with locations.

Steps

1. Set a cap per tool in bytes, and a smaller cap for tools whose output is rarely read in full (directory listings, logs). Record the cap in the tool description so the model knows results may be cut.
2. Filter at the source before returning: grep with a pattern instead of cat, jq on JSON, LIMIT in SQL, --quiet flags, tail on logs.
3. When a result still exceeds the cap, keep the head and the tail and replace the middle with one marker line that states what was removed and where the full output is: [... 61,204 of 74,880 bytes omitted; full output in /tmp/run/out-17.txt ...]. The tail matters because error summaries and exit codes come last.
4. Never cut inside a record: for JSON return the schema, the count and the first records as valid JSON; for tables keep whole rows; for diffs keep whole hunks.
5. Keep errors whole; cap stderr separately and generously. A truncated stack trace costs more calls than it saves bytes.
6. Once a result has been acted on, clear it or replace it with a one-line summary that keeps identifiers. The cited Anthropic engineering post calls tool result clearing one of the safest, lightest-touch forms of compaction, and the Claude context-editing documentation describes the clear_tool_uses_20250919 strategy, which clears the oldest tool results automatically once the context exceeds a configured threshold and replaces each with placeholder text.
7. For tasks that flood the context by nature (reading many files, long searches), delegate to a subagent that, as the Claude Code documentation puts it, does the work in its own context and returns only the summary.

Expected result

Tool results that fit a predictable share of the context, with every cut marked and recoverable from disk, and no decision made on an invisible part of an output.

Limits and test basis

Caps are set by judgment, not by a measured optimum; the open question on this wiki about the share of tool output in real runs asks for the missing data. A model-written summary can omit what mattered; keep the pointer to the full output until the task is finished.