An agent that makes fifty tool calls carries fifty tool results in its conversation history, and most of them stop mattering minutes after they arrive. The directory listing from step 3 is dead weight by step 40 — but it still costs input tokens on every subsequent request and still crowds the context window. Context editing is Anthropic's server-side answer: enabled with the context-management-2025-06-27 beta header, it prunes old content from the prompt after your request arrives but before Claude processes it. Your client keeps its full, unmodified history locally and never needs to sync state; the server replaces cleared content with placeholder text on its side of the wire.
Two strategies
clear_tool_uses_20250919 clears old tool results. It is configurable along five axes: trigger (when clearing starts — by default when input exceeds 100,000 tokens, or alternatively a count of tool uses), keep (how many recent tool-use/result pairs survive; default 3), clear_at_least (a minimum amount cleared per activation), exclude_tools (tools whose results are never cleared), and clear_tool_inputs (default false — the tool call parameters stay visible, only the results go, so the transcript still shows what the agent did).
clear_thinking_20251015 manages extended-thinking blocks. Its keep parameter takes a number of thinking turns or "all". The defaults differ by model: Opus 4.5+ and Sonnet 4.6+ keep all prior thinking by default, while earlier models and all Haiku versions keep only the last turn's thinking. When you combine both strategies in one request, clear_thinking_20251015 must be listed first in the edits array.
response = client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
betas=["context-management-2025-06-27"],
context_management={"edits": [{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 60000},
"keep": {"type": "tool_uses", "value": 5},
"exclude_tools": ["memory"],
}]},
messages=long_agent_history,
tools=tools,
)You can see exactly what was removed
Context editing is not a black box. Each response reports what happened in context_management.applied_edits — which tool uses or thinking turns were cleared and how many input tokens that removed (cleared_input_tokens). In streaming responses this arrives in the final message_delta. And you can preview the effect before paying for it: the /v1/messages/count_tokens endpoint returns both original_input_tokens (before clearing) and input_tokens (after), so you can quantify the savings on your real transcripts while tuning the trigger and keep values.
Two pairings are worth knowing. First, the memory tool: when it is present, Claude receives an automatic warning as context approaches the clearing threshold, giving it a chance to save important tool results to memory files before they vanish — pruning with a safety net. Second, prompt caching: clearing content invalidates cached prompt prefixes at the cleared point, a real cost that the clear_at_least parameter exists to manage. That trade-off gets its own article in Context Editing and Prompt Caching.
exclude_tools, keep the default of preserving tool inputs, and check applied_edits in logs for the first weeks. Silent context surgery you never inspect is how agents develop mysterious amnesia.The rare feature that works on every platform
Most advanced agent features split the 3P field — the MCP connector and Agent Skills skip Bedrock and Vertex entirely. Context editing is the pleasant exception: it is available (in beta) on all five surfaces — the first-party Claude API, Claude Platform on AWS, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry. Microsoft's Foundry documentation independently confirms context editing with the same context-management-2025-06-27 header on both of its Claude hosting modes. It is also eligible for Zero Data Retention, unlike the MCP connector and Skills — a distinction that matters if ZDR is part of your data-handling requirements. For agents that must run on Bedrock or Vertex, context editing plus the memory tool is the core context-management toolkit, since the server-side alternatives aren't there.
Where to go next
Start with the context editing basics if this is new, weigh the caching trade-off in the cache-interplay deep dive, and see the complementary approaches in context compaction and the memory tool.