Large Tool Responses, Explained: Keep Payloads Accessible Without Flooding Context

A tool can return the right data in the wrong shape for model reasoning. Large-response handling separates possession of the payload from immediate attention to every byte.

1. Correct data can still be operationally hostile

An MCP tool can answer successfully and still damage the run. A repository API may return hundreds of pull requests with long descriptions. A metrics tool may emit every time series. A CRM search may attach nested histories to each account. The payload is relevant in principle, but the model may need only three fields.

If the full result enters context, several things happen at once: input grows, later reasoning inherits the bulk, important facts compete with irrelevant fields, and follow-up calls can push the run toward the model’s limit. Asking the tool for less is preferable when its API supports projection, pagination, or filtering. The runtime still needs a fallback because many tools do not expose adequate controls.

TrueForge’s documented response handling writes an oversized result to a sandbox file and places a short preview plus file path in context. The agent retains access without being forced to attend to the entire payload.

2. The single-response threshold

The first rule applies to one tool result. If the estimated response exceeds the configured per-call threshold, TrueForge writes the full result to the sandbox. The context receives a notice, file path, and bounded preview. The current default threshold is 6,000 tokens; the current default preview contains the first and last 100 characters.

The preview is navigation, not a summary. Boundary characters may reveal the object type, top-level keys, total count, or final metadata, but they can omit the exact records the task needs. A competent next step is to inspect structure, search for a target, or run a small parser—not to infer the full contents from the preview.

3. Parallel calls create an aggregate failure mode

Per-call limits are insufficient when an agent issues tools concurrently. Four 4,000-token results each pass a 6,000-token check, yet together they inject 16,000 tokens into one model step.

TrueForge therefore documents a second threshold for the combined tool-call content returned together. The current default is 10,000 tokens. When the sum exceeds that limit, the harness offloads responses one at a time, beginning with the largest, until the remaining inline content falls below the threshold.

This largest-first policy preserves more small results inline while removing the biggest contributors quickly. It is a context heuristic, not a relevance judgment. The largest response could contain the most important evidence; the file path keeps it retrievable.

4. Why offloading requires a sandbox

The full payload needs a durable execution surface that the agent can inspect. TrueForge’s feature is enabled by default but requires the agent’s sandbox to be enabled because the offloaded result is stored as a sandbox file.

The sandbox is not where the entire agent loop runs. TrueForge documentation describes it as an isolated environment used for code, files, and shell work, provisioned when needed. The model receives a path and can use sandbox operations to inspect or transform the file.

This design has a useful separation: the harness controls the run and credentials, while the sandbox handles payload processing. It also creates a lifecycle question. If the task, user, or retention policy is sensitive, teams need to know how long the file persists, who can download it, what telemetry references it, and how deletion propagates.

5. The right recovery behavior is progressive inspection

Once a response is offloaded, the agent should narrow it deliberately:

1. Inspect a small prefix or infer the schema.
2. Confirm the expected top-level shape and record count.
3. Search for the specific entity or fields relevant to the request.
4. Use deterministic code for filtering, grouping, or joins.
5. Print only the evidence or summary needed by the next reasoning step.
6. Preserve a reference to the source file for debugging when policy permits.

TrueForge’s documentation explicitly connects this pattern to Code Mode. A script can read the offloaded file, compute a result, and return only printed lines to the model context.

6. Offloading, truncation, summarization, and retrieval are different

‍