Expire Tool Results Before They Expire Your Context

A capable agent can fill its own working memory with evidence it has already used. A repository listing, a web-search page, a 2,000-row query response, or a full file read may be valuable for one decision and dead weight two turns later. If every raw result stays in the conversation forever, the next decision has to compete with old payloads for attention. Eventually the agent either hits a context limit or reasons from a crowded, low-signal transcript.

The practical move is to give every tool result an expiry class when it enters the workflow. Keep the small facts that still authorize or constrain later work; clear or externalize bulky material once its job is complete. This is different from blindly deleting old turns. The question is not “is this old?” It is “what future decision would become unsafe if this disappeared?”

That distinction matters because tool results count as context. Anthropic documents that tool results, messages, tool definitions, and generated output all consume the context window.^[2] Its context-editing feature can clear older tool results once a configured threshold is reached, while keeping recent uses; it specifically identifies old file contents and search results as material that may no longer be needed after processing.^[1]

Keep the receipt, not the payload

A raw result often serves one of four jobs. Classify it before choosing what survives:

• Ephemeral evidence: a search-result page, directory listing, or fetched HTML used only to select the next target.
• Derived working material: a large result that has been distilled into a small table, summary, or list of stable IDs.
• Durable decision evidence: the source URL, version, record ID, approval, validation outcome, or tool receipt that justifies a later move.
• Recovery state: an operation ID, external result ID, current version, or failed-item list required to resume safely.

The first class can usually expire after its selection decision is recorded. The second can expire after the derived artifact is checked and saved somewhere durable. The last two should stay visible or be written to a scoped state store with a stable pointer. A model should not need the full response from list_customers after it has selected customer_id=1842; it may need that ID, the selection rule, and the record version before it can safely update anything.

Copy this tool-result expiry contract

Use this in an agent harness, a workflow review, or a tool wrapper. It works even if your provider does not offer automatic clearing.

AFTER EVERY TOOL RESULT

1. CLASSIFY
   expiry: ephemeral | derived | durable | recovery
   purpose: [which next decision it supports]
   stable_refs: [URLs, record IDs, versions, operation IDs]

2. PRESERVE THE MINIMUM SAFE RECEIPT
   receipt = {
     tool: [name],
     status: success | failure | partial,
     decision: [selected target / no match / blocked],
     stable_refs: [...],
     constraints: [scope, version, approval, or timestamp],
     next_safe_action: [one bounded action],
     artifact_ref: [durable path or null]
   }

3. EXPIRE ONLY AFTER A CHECK
   - Ephemeral: clear after the receipt names the selected IDs or says no match.
   - Derived: save and validate the summary/table; clear the raw payload afterward.
   - Durable: retain the receipt and source reference through the dependent decision.
   - Recovery: retain until the operation is terminal and reconciliation is complete.

4. BEFORE CLEARING
   - Confirm no pending step needs the raw payload for a cited claim or retry.
   - Preserve failures separately; an error is not a non-match.
   - Never clear the only proof of scope, approval, target, or result.

5. ON RESUME
   - Re-read the named artifact or source by stable reference.
   - Re-check volatile state instead of trusting an old snapshot.

The receipt is intentionally small. It should let a later turn answer: What happened? Which exact object did we choose? What boundary still applies? What can happen next? If it cannot, the raw result was cleared too early. If it contains a 20-page response pasted into JSON, it is not a receipt; it is the original problem with braces around it.

Set the clearing policy around dependencies

Do not use a simple “keep the last three calls” rule without looking at workflow shape. A web search may be safe to clear immediately after a researcher stores the two chosen URLs. A database read cannot be cleared until a proposal captures the record version needed for optimistic concurrency. A deployment response may be short, but its release ID should survive until external verification completes.

Automatic clearing can be useful for high-volume read loops. Anthropic’s documented tool-result-clearing strategy removes the oldest results first, can retain a chosen number of recent tool uses, and can exclude named tools from clearing.^[1] Those settings are mechanisms, not the policy. Decide which tools produce disposable discovery material and which produce the receipts that govern a later write. Clearing tool results can invalidate cached prompt prefixes, while cached prefixes still occupy context capacity; measure both effects rather than treating either as a universal priority.^[1][2]

Failure mode: clearing the evidence that made an action safe

Aggressive pruning can turn a well-instrumented agent into one that merely sounds certain. If a later answer must cite a source passage, retain that passage or store it in a retrievable evidence artifact. If a retry depends on the original normalized payload, persist the payload and operation ID outside the conversation. A summary that says “customer approved” is not an approval record.

Test the policy with a long task containing a large search result, a failed lookup, a selected record, and a pending write. Clear the disposable material, start from only the receipts, and ask whether the next action, source attribution, and recovery path are still unambiguous. If not, strengthen the receipt before lowering the threshold.