# context engineering

Also called: context management, context curation, context assembly

Context engineering is the work of deciding which tokens sit in a model's context window on each call: the system prompt, tool definitions, retrieved documents, conversation history and tool results. Anthropic defines it as curating and maintaining the optimal set of tokens during inference. In code it comes down to three choices: what you load up front, what the agent fetches with tools when it needs it, and what you summarise, clear or write to a file as a long session fills the window.

## What does context engineering mean in code?

Every request to a model is a list of tokens you assemble: a system prompt, tool definitions, the messages so far, documents you retrieved and the results of earlier tool calls. Context engineering is the code that decides what goes into that list and what stays out. In a single-turn chat the list is short and you write it by hand. In an agent that runs for dozens of turns, the list grows with every tool result, and something has to decide what to keep.

The word gets used two ways. In marketing it is a broad rebrand of prompt engineering, meaning roughly "give the AI the right information". In Anthropic's engineering guidance it has a narrower meaning: the strategies for curating and maintaining the optimal set of tokens across many inference turns, including everything that lands in the window outside the prompt itself. Anthropic calls it the natural progression of prompt engineering. Prompt engineering covers how you write the instructions; context engineering covers the whole payload and how it changes as the session runs.

## Why does more context not mean better answers?

A larger context window lets you send more tokens, and models still use those tokens unevenly. Liu et al. tested multi-document question answering and key-value retrieval and found that accuracy was often highest when the relevant information sat at the beginning or end of the input, and dropped significantly when it sat in the middle of a long context, even for models built for long contexts.

Anthropic's guidance names the same effect context rot: as the number of tokens grows, the model's ability to recall information from them declines. It describes the model as having an attention budget, because every token attends to every other token and those n-squared relationships get stretched thin. The working rule it gives is to find the smallest set of high-signal tokens that maximise the likelihood of the outcome you want.

## The techniques, and where each one lives

System prompt: Anthropic advises writing it at the right altitude, between two failure modes: rigid, overly specific logic that is hard to maintain, and vague guidance that assumes the model shares context it does not have.Tool set: keep it small and free of overlap. Anthropic's test is that if a human engineer cannot say which tool should be used in a given situation, the agent cannot be expected to do better.Just-in-time retrieval: keep lightweight identifiers such as file paths or queries in context and let the agent load the data with tools when it needs it. Claude Code works this way, running commands like head and tail on large files instead of loading them whole. Pre-loading with RAG is the other end of the same choice.Compaction: summarise the conversation when it nears the limit and continue from the summary. Claude Code keeps architectural decisions, unresolved bugs and implementation details, drops redundant tool output, and reloads the five most recently accessed files.Tool result clearing: replace old tool results with a placeholder once they have served their purpose. Anthropic calls it one of the safest, lightest-touch forms of compaction, and its API exposes it as a context editing strategy.Structured note-taking: the agent writes progress to a file outside the window and reads it back later, which is one form of agent memory.Subagents: a child agent explores in its own clean window and returns a condensed summary, so the parent never holds the raw search results.

## What clearing context costs you

Every edit to earlier context changes the prefix of the next request, and a prompt cache only hits on an unchanged prefix. Anthropic's context editing docs say so directly: clearing tool results invalidates the cached prefix, each clearing pays a cache write, and later requests can reuse the new prefix. The clear_at_least setting exists so that you only pay for that invalidation when the edit frees enough tokens to be worth it.

Clearing also removes information. If the agent needs a cleared result again it has to call the tool again, so list the tools whose output must survive in exclude_tools, and keep the last few tool results with keep. Measure the effect on an eval of long sessions before and after you turn clearing on.

## Clearing old tool results with Anthropic's context editing

POST /v1/messages
anthropic-version: 2023-06-01
anthropic-beta: context-management-2025-06-27

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 4096,
  "tools": [ ...file and search tools... ],
  "messages": [ ...a long agent session with many tool results... ],
  "context_management": {
    "edits": [
      {
        "type": "clear_tool_uses_20250919",
        "trigger": {"type": "input_tokens", "value": 100000},
        "keep": {"type": "tool_uses", "value": 3},
        "clear_at_least": {"type": "input_tokens", "value": 5000},
        "exclude_tools": ["web_search"]
      }
    ]
  }
}

response (excerpt):
{
  "stop_reason": "end_turn",
  "context_management": {
    "applied_edits": [
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

The request and response shapes follow Anthropic's context editing docs; the response counts are the docs' sample values. Trigger and keep are set to their documented defaults: once input passes 100,000 tokens, the API clears older tool results and keeps the three most recent tool use and result pairs. The clear_at_least floor stops it from breaking the prompt cache to free a few hundred tokens, and web_search results are never cleared. The applied_edits block in the response tells you what was removed.

## Frequently asked

Q: Is context engineering just prompt engineering with a new name?
A: Partly, in marketing. In code the scope is wider. Prompt engineering is about how you word the instructions. Context engineering also covers which tools you expose, what you retrieve, which old messages and tool results stay in the window, and how that set changes over a long agent run.

Q: Does a bigger context window make context engineering unnecessary?
A: No. A bigger window raises the limit on what you can send, and models still use long inputs unevenly: Liu et al. found accuracy dropped when the relevant information sat in the middle of a long context. Extra tokens also add cost and latency on every call, so trimming what the model does not need still pays.

Q: How is context engineering different from RAG?
A: RAG is one technique inside it. RAG retrieves documents and puts them in the prompt before the model runs. Context engineering also decides whether to pre-load at all or let the agent fetch data with tools when it needs it, and what to remove from the window later.

Q: Does clearing tool results break prompt caching?
A: It invalidates the cached prefix at the point where content was cleared, according to Anthropic's context editing docs. The next request pays a cache write, and requests after that can hit the new prefix. Set clear_at_least so that a clearing only happens when it frees enough tokens to justify the cache miss.

## Sources

- Anthropic Engineering: Effective context engineering for AI agents: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
  the definition of context engineering, context rot and the attention budget, and the techniques: system prompt altitude, minimal tool sets, just-in-time retrieval, compaction, tool result clearing, note-taking and subagents
- Claude docs: Context editing: https://platform.claude.com/docs/en/build-with-claude/context-editing
  the context-management beta header, the clear_tool_uses_20250919 strategy with trigger, keep, clear_at_least and exclude_tools and their defaults, the applied_edits response field, and the interaction with prompt caching
- Lost in the Middle: How Language Models Use Long Contexts (Liu et al., 2023): https://arxiv.org/abs/2307.03172
  shows accuracy is often highest when relevant information is at the start or end of the input and degrades when it is in the middle, even for long-context models

## Related terms

- context window: https://ai.developertools.io/context-window/index.md
- context compaction: https://ai.developertools.io/context-compaction/index.md
- prompt: https://ai.developertools.io/prompt/index.md
- RAG: https://ai.developertools.io/rag/index.md
- subagent: https://ai.developertools.io/subagent/index.md
- prompt caching: https://ai.developertools.io/prompt-caching/index.md

Canonical page: https://ai.developertools.io/context-engineering/
Edited by Derek Wonk. Last updated 2026-10-07.