Back to Blog

Claude API Context Editing: When to Clear Tool Results

Tutorials and Guides6028
Claude API Context Editing: When to Clear Tool Results

A coding assistant reads the same repository several times. A research agent opens pages that later become irrelevant. A support assistant retrieves account records, solves the issue, then carries those records through every subsequent turn.

The immediate temptation is to buy a larger context window. That can postpone a capacity problem while leaving the underlying history policy untouched. The application is still paying to repeatedly present information that may no longer help its next decision.

Claude API context editing offers a more selective option: clear eligible old tool results while retaining the conversation structure. For teams using an API relay, the important decision is not simply whether to enable a request parameter. It is which information the model can safely stop seeing, how the gateway carries that instruction, and how the application proves that task quality survived.

This memo proposes a conservative policy for a read-only research or repository assistant. It does not assume that every Claude-compatible endpoint implements native context management. The 4SAPI integration overview is a starting point for connection details; feature support must be checked on the particular model route you intend to use.

The decision in one paragraph

Keep the complete application transcript in your own controlled state store. Allow Claude to clear selected old tool results from the context it processes. Preserve a compact, explicit record of current objectives, decisions, unresolved questions, and evidence identifiers. Begin with tools whose output can be retrieved again without side effects. Expand the policy only after comparing successful task completion, evidence accuracy, latency, and total workflow cost against a baseline.

That arrangement separates three things that are often accidentally combined: the audit history, the working context shown to the model, and the durable state of the task. They have different purposes and should have different retention rules.

What the API feature actually changes

The official Claude context editing documentation describes tool-result clearing through the clear_tool_uses_20250919 strategy. Its beta header is context-management-2025-06-27. Clearing is performed on the server; the client continues to send its unmodified conversation history. Applied edits can be reported in the response.

This is distinct from Claude compaction, which addresses long histories through summarization. A team should evaluate the information-loss behavior of each mechanism separately. Clearing a search result and replacing an entire conversation with a summary are different interventions, even if both reduce what the model must process.

The distinction matters during an incident. If the final answer loses a necessary qualification, an engineer should be able to identify the relevant tool result, the clearing policy, and the subsequent retrieval behavior. “The context was optimized” is too vague to explain a failed customer interaction.

Classify tool output before setting a token threshold

Start with the properties of the data, rather than the size of the current bill. A repository file, a weather observation, a customer entitlement response, and a payment confirmation may all appear as text to the model, but removing them has very different consequences.

Output classExampleInitial treatmentReason
Reproducible referenceFile at a pinned commitCandidate for clearingThe same evidence can be fetched again
Changing observationCurrent inventory responseRefresh deliberatelyReusing old output may itself be wrong
Irreversible action resultRefund confirmationPreserve in durable task stateRepeating the action could be harmful
Unresolved evidenceConflicting policy passagesKeep until conflict is settledRemoving one side can distort the answer
Bulky intermediate materialUnused search resultsCandidate for early clearingMuch of it may never support a decision

This classification should be owned by the application team. A gateway cannot infer from a JSON blob whether the contents are a disposable search result or the only proof that an external action happened.

There is also a difference between recoverable and cheap to recover. A document may be retrievable, yet require a slow database query or a paid downstream API call. Clearing it can trade model input cost for retrieval cost. Record those tradeoffs before declaring the change successful.

For document-heavy workloads, the existing Claude Files API document reuse guide covers another part of the lifecycle. File reuse and working-context retention should be evaluated as separate decisions.

Give the agent a task ledger, not a second transcript

A useful task ledger tells the next model turn what remains true and what it must do next. It does not repeat every observation. For a repository assistant, an application-owned ledger might contain the requested change, the relevant commit, confirmed constraints, test results, and open questions.

Evidence references should be stable. “The third result above” becomes meaningless when histories are transformed. “Policy document P-17, revision 8, section 4” can be retrieved and checked. Similarly, a repository path without a commit identifier may point to different contents after a deployment.

Do not silently let an unverified model summary overwrite authoritative state. A model can propose a ledger update, but the application can validate simple fields: a referenced document exists, a test command actually ran, an action identifier belongs to the current task, and a claimed status follows the allowed state transitions.

For example, a support workflow should not accept “refund completed” merely because the assistant wrote that phrase. The state transition should require the payment system's confirmed result. Context editing then becomes a presentation policy rather than a fragile substitute for transaction tracking.

Teams that need a broader evidence trail can use the Claude finance audit trail article as a related implementation discussion. The core rule remains the same: information required to establish what happened must not depend exclusively on what the model currently remembers.

A small policy builder you can inspect offline

The following Python example prepares a native Messages request from a saved transcript. It does not call an API, consume tokens, or modify the transcript. The numeric thresholds are illustrative test settings, not recommended defaults for every workload.

The transcript file must contain a valid Claude messages array. If your workflow uses tools, the tool definitions must also be supplied. Do not paste a production conversation containing sensitive information into a public test fixture.

python
import copy
import json
import os
from pathlib import Path


def prepare_request(messages, tools, model):
    if not isinstance(messages, list) or not messages:
        raise ValueError("A non-empty Messages transcript is required")
    if not isinstance(tools, list):
        raise ValueError("tools must be a list")

    payload = {
        "model": model,
        "max_tokens": 1200,
        "messages": copy.deepcopy(messages),
        "context_management": {
            "edits": [{
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 3},
                "clear_at_least": {
                    "type": "input_tokens", "value": 5000
                },
                "clear_tool_inputs": False
            }]
        }
    }
    if tools:
        payload["tools"] = copy.deepcopy(tools)
    return payload


def summarize_edit_response(response):
    management = response.get("context_management")
    if not isinstance(management, dict):
        return {"diagnostics": "absent", "applied_edits": None}
    edits = management.get("applied_edits")
    if not isinstance(edits, list):
        return {"diagnostics": "unexpected_shape", "applied_edits": None}
    return {"diagnostics": "present", "applied_edits": edits}


if __name__ == "__main__":
    source = json.loads(Path("transcript.json").read_text())
    request = prepare_request(
        source["messages"],
        source.get("tools", []),
        os.environ["CLAUDE_MODEL"]
    )
    Path("prepared-request.json").write_text(
        json.dumps(request, ensure_ascii=False, indent=2)
    )
    print("Prepared locally; no API request was sent.")

The keep setting protects recent tool uses; it is not a guarantee that every important business fact remains available. A minimum-clear setting can also prevent an edit when too little eligible material exists. Review the official feature documentation before changing either setting.

Inspect the prepared request with your integration tests. The model identifier must come from the route you actually have access to. A model family name in a comparison article is not sufficient evidence that a gateway account accepts a particular identifier or beta feature.

Treat the relay as part of the compatibility test

The documented 4SAPI native Claude Messages endpoint is a better starting point for this evaluation than assuming a generic Chat Completions route can carry every Claude field. Its published request example uses the Authorization header for the gateway credential. Confirm the current credential format and model group in your own account.

A documented Messages endpoint does not establish support for context editing. Before sending the prepared request through it, verify that the route accepts the beta header, forwards context_management, preserves required conversation blocks, and returns the relevant diagnostics. The applicable account key is a gateway credential, not an Anthropic credential.

Use an acceptance record with four outcomes: supported and observed, accepted but not triggered, rejected, and unverified. A short conversation that produces no edits is not a useful negative test. Equally, HTTP 200 with a text response does not prove that an optional request field reached the upstream service.

Keep a raw, access-controlled response fixture during development, with appropriate redaction and retention. Compare its structure before and after your application adapter. If the upstream result contains diagnostics but the SDK wrapper drops them, the failure is in the wrapper rather than the model.

Applications that stream tool arguments have another boundary to preserve. The fine-grained Claude tool JSON streaming article addresses incremental argument delivery; that behavior should have its own test rather than being inferred from a successful context-editing request.

Measure a whole task, including the information it fetches again

Run the same representative tasks with and without the policy. Start with tasks that have checkable answers and known evidence requirements. Examples include locating a configuration dependency, reconciling two documented policies, or explaining a code path at a fixed commit.

For each task, count completion, unsupported assertions, unnecessary retrieval, duplicate external actions, elapsed time, and total billable work. Keep the task dataset stable while changing the context policy. Otherwise, a different mix of easy and difficult questions can masquerade as an efficiency gain.

Use Claude token counting when planning request size, but keep estimation distinct from the final usage record. A smaller predicted context is an intermediate observation. The business outcome is a correct completed task at an acceptable cost and response time.

Caching can change the result. Read the official prompt caching documentation, and compare it with the existing gateway cache-hit test. Removing old material can alter the prefix that would otherwise be reused. Therefore, fewer visible input tokens should not automatically be described as lower total cost.

Report measurements as your own observations only after running them. A useful results table includes the model route, policy version, dataset revision, concurrency, and sample size. Avoid publishing a universal percentage saving from a handful of successful conversations.

Define rollback before enabling the policy broadly

Rollback should restore the previous request policy without requiring a reconstruction of lost application state. Keeping the original transcript makes that possible. Version the context policy alongside the tool schemas and task-ledger format, so an incident can be traced to a specific change.

Use a gradual rollout with observable failure conditions. If an agent repeatedly retrieves the same evidence, loses unresolved constraints, or produces answers that cannot be traced to retained records, stop expanding the policy. Raising the clearing threshold may help, but first determine which information was removed and why the agent needed it.

Do not repair conversation history by discarding unfamiliar blocks. Follow the official tool-call handling guidance, and consult the existing signed and redacted thinking replay guide when those blocks appear. Context editing is not permission to rewrite protocol state arbitrarily.

The official context window explanation is useful background when setting limits. Your application still needs its own stop conditions: maximum task duration, maximum retrieval count, and an explicit escalation path when evidence remains unresolved.

A practical first evaluation through 4SAPI

Choose one read-only workflow, one available Claude model route, and a small collection of fixed tasks. Prepare the baseline first. Then ask whether that route supports the specific native context-management feature—not merely whether it supports Claude.

If the feature is confirmed, use a development account and a narrowly scoped test credential to collect a comparable baseline and edited run. Review correctness before expanding traffic. If the feature is unavailable, keep the established history policy and record the missing capability; changing to an unrelated endpoint will not make the feature appear.

That is a concrete reason to evaluate an API relay: a team can assess whether its connection, observability, and model access fit a real application requirement. The registration is the start of a measurable integration test. The decision to use the route in production should follow evidence from that test.

Tags:Claude API context editingClaude tool result clearingClaude context management gatewayClaude long running agent API

Recommended reading

Explore more frontier insights and industry know-how.