What you will be able to do
- Explain why everything placed in a request competes for the same context window, and why a larger window does not by itself mean better answers
- Identify the workloads where loading a whole document up front is the right call: it fits the window, cross-references matter and latency is tolerant
- Choose among on-demand file reads, Agent Skills and the tool search tool for a workload whose material is too large or too broad to preload
- Configure deferred tool loading correctly with defer_loading and ENABLE_TOOL_SEARCH
Key concept
Progressive discovery — A loading strategy where Claude starts with a lightweight index of what exists (tool names, skill descriptions, a file tree) and pulls in full content only when the task calls for it. Monolithic loading does the opposite and puts all the material into context before the first turn.
1.Two ways to give Claude what it needs
Every agent design makes a loading decision, whether or not anyone writes it down. Claude can get its material in one of two ways. The whole thing can go into the request before the first turn, which is monolithic loading. Or Claude can start from a small index and fetch pieces as the task shows which ones it needs, which is progressive discovery. The right choice depends on how large the material is, how much of it a single request actually uses, and how long a user will wait.
Both strategies draw on the same budget. The system prompt, every message, tool results, documents and tool definitions all count against one context window, and so does Claude's own output for the turn. A 55k-token block of tool schemas is 55k tokens that conversation history and file contents can no longer use. For the token-accounting side of this budget, see context composition and token economics.
Space is only half the cost. As token count grows, accuracy and recall degrade, which is called context rot. Loading everything therefore has two risks. You can run out of room, and the material that matters can also get lost among the material that doesn't.
Progressive discovery has a cost too, and it is paid in latency. Each lookup is a tool call: a search for a tool, a read of a file, a cat of a skill's instructions. Each one adds a turn before Claude can act. The tool search tool's documentation states the trade plainly: one extra turn per lookup in exchange for a much smaller baseline context. The choice between the strategies comes down to which of these two costs the workload can afford.
Checkpoint 1 of 9· Check yourself
An agent currently loads about 50 tool schemas into every request before the first turn. The team switches to progressive discovery, where Claude starts from a small index and looks up tools as the task needs them. What cost does the team take on in exchange for the smaller baseline context?
Progressive discovery pays in latency: each lookup is a tool call that adds a turn before Claude can act. Context rot gets worse as token count grows, so loading less helps recall rather than hurting it.
“This trades a small amount of latency (one extra turn to look up a tool) for a large reduction in baseline context usage.”Source: platform.claude.com
2.When loading everything up front is the right call
Monolithic loading wins when three conditions hold together. The material fits in the window. The task needs connections between parts that are far apart. And nobody is waiting on the answer. A one-off contract review fits all three. A clause on page 40 that depends on a definition on page 3 and a schedule at the end can be checked in a single pass, so Claude never has to guess which section to open next. If the review ran on demand instead, every cross-reference would need another read turn. Overnight, nobody notices those turns, but they still add work and still require Claude to predict which sections matter.
Fitting in the window is a hard requirement, not a preference. Models with a 1M-token window, such as Claude Opus 5.5 and Claude Sonnet 5.5, can take very long documents in one request. Other models stop at 200k tokens. One request can also carry at most 600 images or PDF pages, or 100 on a 200k-token model, so a scanned document can hit the request size limit before it hits the token limit.
A long prompt does not guarantee thorough reading. Context rot still applies, so a long prompt makes every clause visible but does not promise that every clause gets equal attention. Write the up-front case on what it really buys: all the cross-references are in view, there are no extra tool-call turns, and latency doesn't matter for this job.
Prompt caching often comes up as a way to make large up-front loads cheaper. It is useful for stable content reused across many requests, but it changes price, not size. Cached tokens still count toward the window, and a cache only reduces what you pay for those tokens on later requests. Caching does nothing for a one-off review, and it never frees up context. Breakpoint placement is covered under cache breakpoints and reusable packaging.
Checkpoint 2 of 9· Check yourself
A team loads a 700k-token document set whole into each request on Claude Opus 5.5. A colleague proposes adding a cache breakpoint after the documents, saying it will leave more of the 1M-token window free for conversation history. What does the cache breakpoint actually change?
Caching changes price, not size. Cached tokens still fill the window on every request, so a cache breakpoint lowers the cost of repeated content but never frees up context.
“Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”Source: platform.claude.com
Checkpoint 3 of 9· Exam question
A legal-tech team will run a one-off overnight review of a single long contract. Reviewers need clauses cross-referenced against definitions and schedules anywhere in the document, and nobody is waiting on a live response. The document fits in the model's context window. Which two considerations support loading the whole document up front? Choose two.(Select 2)
Correct answers: A, B — Cross-references between distant clauses and definitions are visible in one pass, so Claude need not guess which sections to open.; Because nobody is waiting, one large request avoids the extra tool-call turns on-demand reading would add, and latency is not the constraint.
- A. Correct. When the content fits and relationships span the whole document, seeing everything at once supports the cross-referencing the task demands without relying on Claude to choose what to open.
- B. Correct. With no latency pressure and a document that fits, one request is simpler and avoids the extra turns progressive discovery would add; the cost trade-off is acceptable for a one-off job.
- C. Incorrect. Long-context attention is not uniform, and no loading strategy guarantees complete coverage; claiming otherwise overstates what the docs support.
- D. Incorrect. Discovery over a single document does not require nightly re-embedding; a read tool over the file works without any index, so infeasibility is not the real argument.
- E. Incorrect. Prompt caching applies to any sufficiently long static prefix including a document; the claim that it is unavailable is false and is not the reason to load up front.
3.Corpora larger than the window: search, then read
If the material can't fit in the window, monolithic loading is off the table. A monorepo far larger than any context window can't be packed into one prompt. Users asking narrow questions, such as where the retry policy is configured, need a few lines from one or two files. For this workload, give the agent search and read tools: grep to find candidate files, then reads of just the relevant line ranges. Agent SDK agents can use Claude Code's built-in Read, Grep and Glob tools for this loop instead of custom file-access code.
Each read has a cost you can see. In Claude Code's context-window walkthrough, reading src/api/auth.ts adds about 2,400 tokens and a search for refreshToken adds 600. The agent pays only for what it opens. A question that takes a grep and two targeted reads stays small, however large the repository is. The several seconds of extra turns are acceptable here because users have said they will wait that long.
The alternatives fail in specific ways. Preloading generated module summaries and disabling file reads leaves the agent with paraphrases, and a paraphrase rarely contains the one config line the question is about. Handing the agent top-ranked embedding chunks with no file tools means that when the right chunk isn't in the top results, the agent has no way to go and look for it. Comparing retrieval designs in general is the subject of retrieval architecture selection. The point for loading strategy is narrower: when the corpus is too large to load, the agent needs tools to discover the content it needs.
If the exploration itself would fill the main context, delegate it. A subagent that does the research in its own context window keeps those large file reads out of the main conversation, and only its summary comes back. Splitting work this way is covered in orchestrator and subagent decomposition.
Checkpoint 4 of 9· Check yourself
Users of an internal assistant ask narrow questions about a monorepo many times larger than any context window, such as where the retry policy is configured. They have said they will wait several seconds for an answer. Which loading design fits this workload?
The corpus can't fit in the window, so the agent needs tools to find content and pays only for what it opens. The users accept the extra turns. Summaries leave out the exact config line, top-k chunks give the agent no way to look further when the right chunk is missing, and caching lowers price without making the repository fit.
“On-demand file access: Claude reads only the files each task needs.”Source: platform.claude.com
Checkpoint 5 of 9· Exam question
An Agent SDK coding agent works in a monorepo far larger than any context window. Users ask narrow questions such as where a retry policy is configured, and they tolerate several seconds per answer. Which approach should the architect choose?
Correct answer: A — Give the agent grep and file-read tools, and let it find matching files and open the relevant line ranges for each question it receives.
- A. Correct. The codebase is too large to preload, and the questions are targeted lookups. Letting the agent search and read files on demand finds the relevant code, and the extra turns fit the latency users accept.
- B. Incorrect. The repository is larger than any available context window, so it cannot be packed into one prompt. Any truncated version could omit the file that holds the setting.
- C. Incorrect. With no file tools the agent can only see the chunks retrieval returns. A retry setting is often defined in one file and overridden or consumed in others, and the agent cannot follow those references to check. Users accept several seconds per answer, so the speed of precomputed retrieval is not needed.
- D. Incorrect. Module summaries describe what code does at a high level and rarely record specific configuration values or locations. With file reads disabled, the agent has no way to verify where the retry policy is set.
4.Agent Skills: metadata first, instructions on trigger
Agent Skills apply progressive discovery to procedural knowledge. A Skill is a directory with a SKILL.md file, plus optional reference files and scripts. Its YAML frontmatter, a name and a description, loads into the system prompt at startup. Until the Skill is triggered, that frontmatter is the only part of it in context. The body loads only when a request matches the description, and bundled files load only when the instructions point Claude to them.
| Level | When loaded | Token cost | Content |
|---|---|---|---|
| Level 1: Metadata | Always (at startup) | ~100 tokens per Skill | name and description from YAML frontmatter |
| Level 2: Instructions | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| Level 3+: Resources | As needed | None until accessed | Reference files load when read; scripts run through bash and only their output enters context |
This layout fits a library of playbooks where each request needs only one or two. Make each release procedure, incident runbook or compliance checklist its own Skill. Forty playbooks then cost about forty short descriptions at startup, and only the triggered playbook's instructions load in full. Putting the whole library in a cached system prompt keeps every playbook in the window on every request. Caching lowers the price of those tokens but leaves them all in context. Having the application inject top-ranked chunks moves the choice of material away from Claude and can break a procedure into fragments. Skills let Claude pick, and they load the whole procedure at once.
Triggering depends on the description. Claude compares each request against the description to decide whether to open a Skill. A description like 'Helps with documents' won't trigger reliably. A description should state what the Skill does and when to use it, for example: 'Use when the user asks for help writing commit messages.'
A triggered body costs real tokens, so how you structure it matters. Keep SKILL.md under 500 lines and move detail into separate files that it links to. Keep references one level deep, because Claude may only preview files it reaches through nested links. Organize multi-domain content by domain. A question about sales metrics should load reference/sales.md and nothing about finance. A Skill can bundle dozens of reference files, and every file Claude doesn't read costs zero tokens. In Claude Code, custom Skills go in ~/.claude/skills/ for personal Skills or .claude/skills/ for project Skills.
Checkpoint 6 of 9· Match them up
Match each part of an Agent Skill to when it enters Claude's context and what it costs there.
Tap a term, then the definition that fits it.
Skills load in stages. Only the metadata is always present. The body loads on trigger, reference files load when read, and scripts add only their output. That is why installing many Skills costs only their short descriptions at startup.
“Reference files load into context when read. Scripts run through bash, and only their output enters context.”Source: platform.claude.com
Checkpoint 7 of 9· Exam question
You are the architect for an internal Claude Agent SDK assistant whose team maintains a large library of procedural playbooks (release steps, incident runbooks, compliance checklists). Any single request needs only one or two playbooks, and the full library would consume a large share of the context window. Which loading strategy best fits this workload?
Correct answer: A — Package each playbook as an Agent Skill folder, so only its name and description sit in the prompt until Claude opens the full instructions.
- A. Correct. Agent Skills use progressive disclosure: only each skill's name and description are loaded at the start, and the full instructions are read when a task calls for them. Context cost therefore follows the one or two playbooks used, not the size of the library.
- B. Incorrect. A cache breakpoint lowers the price of re-reading the prompt, but the library still occupies a large share of the context window on each request. Only one or two playbooks are needed, so window capacity and attention are spent on irrelevant text.
- C. Incorrect. Here the application decides what to inject before Claude reads the request, so Claude cannot open a complete playbook when it needs one. Chunk-level retrieval can return fragments of an ordered procedure and drop steps from release or compliance checklists.
- D. Incorrect. Procedures baked into weights cannot be updated by editing a playbook file, and exact checklist steps are not reliably reproduced from training. It also gives up on-demand loading of a library that the team keeps maintaining, which is what the workload needs.
5.Tool search: deferring tool definitions
Tool definitions are the third kind of material that can be loaded all at once or discovered as needed. A typical multi-server setup with GitHub, Slack, Sentry, Grafana and Splunk can use about 55k tokens in definitions before Claude does any work. Selection also suffers: tool selection accuracy drops once more than 30 to 50 tools are loaded at once. With the tool search tool, Claude starts with only the search tool and any non-deferred tools. It searches the catalog by tool name, description and argument names and descriptions. The API returns matches as tool_reference blocks, five by default, and expands them into full definitions.
{
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
},
"required": ["location"]
},
"defer_loading": true
}Two configuration rules prevent common mistakes. Never set defer_loading on the tool search tool itself, and keep at least one tool non-deferred. Also keep your three to five most-used tools loaded up front, so the commonest requests don't pay for a search turn. Two search variants exist: tool_search_tool_regex_20251119, where Claude writes regex patterns, and tool_search_tool_bm25_20251119, where it uses natural-language queries. Claude Opus 4.1 and earlier don't support either.
In the Agent SDK, tool search is on by default for Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 and later. The ENABLE_TOOL_SEARCH environment variable controls when deferral starts. The catalog limit is 10,000 tools.
| Value | Behavior |
|---|---|
| (unset) or true | Tool search on; definitions deferred and discovered on demand, with fallback to upfront loading on unsupported models |
| auto | Definitions load upfront until deferrable definitions reach 10% of the context window, then tool search activates |
| auto:N | Same as auto with a custom percentage; auto:5 activates at 5% |
| false | Tool search off; all definitions load into context on every turn |
The auto modes are for agents whose tool count varies. A deployment with a handful of tools loads them all and pays no search turn. Once connected MCP servers push definitions past the threshold, deferral turns on and can stay on for the rest of the conversation. A reasonable rule of thumb from the context-management guidance: add tool search once you have 10 or more tools, or once baseline context usage becomes noticeable.
Checkpoint 8 of 9· Fill the gap
You want get_weather to stay out of Claude's context until the tool search tool finds it, but its full definition still goes in the tools array on every request. Which field completes this definition?
{
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
},
"required": ["location"]
},
" ? ": true
}Setting defer_loading to true keeps a tool out of the context window until Claude finds it through search. The definition is still sent with every request. cache_control only lowers the price of repeated tokens and does not take them out of context, and strict constrains tool-call output to match the schema.
Source: platform.claude.com6.Matching the strategy to the workload
Three questions about a workload settle the choice: whether the material fits in the window, what fraction of it a typical request uses, and whether a user is waiting. Each source of context pressure has its own fix, so identify where the tokens are going before choosing a mechanism.
| Workload signal | Strategy | What it costs |
|---|---|---|
| Material fits the window, task needs links across the whole thing, latency tolerant | Load it whole up front | Large single request; context rot still applies |
| Corpus larger than any window, narrow questions | grep plus targeted file reads | One or more tool-call turns per question |
| Large procedural library, one or two items per request | One Agent Skill per item | ~100 tokens per Skill at startup, plus the triggered body |
| Many tools, few needed per request | defer_loading plus a tool search tool | One extra turn per lookup |
| Large but fixed tool list, many requests | Prompt caching | 25 percent write markup; tokens still occupy context |
These strategies can be combined. A long-running agent can defer most tools with tool search, cache the definitions that remain loaded, and use Skills for its procedures, all at once. Each mechanism handles a different source of tokens, so using one doesn't rule out another.
Checkpoint 9 of 9· Match them up
Five agent workloads each put pressure on the context window from a different source. Pair each workload with the loading strategy whose costs it can best afford.
Tap a term, then the definition that fits it.
Each mechanism deals with a different source of tokens. Up-front loading suits material that fits and needs cross-references, and search-then-read suits corpora that can't fit. Skills defer procedure bodies, tool search defers tool definitions, and caching only lowers the cost of stable content without freeing any context.
“Each approach targets a different source of context pressure. Pick the one that matches where your tokens are going.”Source: platform.claude.com
Sources2
Sources
(8)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Everything in the request counts toward the context window”
↩︎ Two ways to give Claude what it needs“As token count grows, accuracy and recall degrade, a phenomenon known as context rot.”
↩︎ Two ways to give Claude what it needs“A larger context window allows the model to handle more complex and lengthy prompts”
↩︎ When loading everything up front is the right call“A single request can include up to 600 images or PDF pages (100 for models with a 200k-token context window).”
↩︎ When loading everything up front is the right call“As token count grows, accuracy and recall degrade, a phenomenon known as context rot.”
↩︎ Exam trap 2 - 2.
“This trades a small amount of latency (one extra turn to look up a tool) for a large reduction in baseline context usage.”
↩︎ Two ways to give Claude what it needs“it reduces what you pay for them on subsequent requests”
↩︎ When loading everything up front is the right call“Pick the one that matches where your tokens are going.”
↩︎ Matching the strategy to the workload“Add tool search once you have 10 or more tools or your baseline context usage becomes noticeable.”
↩︎ Matching the strategy to the workload“it reduces what you pay for them on subsequent requests”
↩︎ Exam trap 1“Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”
↩︎ Checkpoint“Each approach targets a different source of context pressure. Pick the one that matches where your tokens are going.”
↩︎ Checkpoint - 3.
“On-demand file access: Claude reads only the files each task needs.”
↩︎ Corpora larger than the window: search, then read“until a Skill is triggered, only its name and description occupy context.”
↩︎ Agent Skills: metadata first, instructions on trigger“The description is what Claude matches your request against when determining whether to trigger the Skill”
↩︎ Agent Skills: metadata first, instructions on trigger“Claude loads information in stages as needed, rather than consuming context upfront.”
↩︎ Key concept“until a Skill is triggered, only its name and description occupy context.”
↩︎ Exam trap 4“Reference files load into context when read. Scripts run through bash, and only their output enters context.”
↩︎ Checkpoint - 4.https://code.claude.com/docs/en/context-windowOfficial docs
“each file read adds to context”
↩︎ Corpora larger than the window: search, then read“a subagent handles the research in its own separate context window, so the large file reads stay out of yours.”
↩︎ Corpora larger than the window: search, then read - 5.https://platform.claude.com/cookbook/claude-agent-sdk-06-the-vulnerability-detection-agentSecondary source
“Drive an agentic find loop with built-in Read/Grep/Glob tools instead of hand-rolled file access”
↩︎ Corpora larger than the window: search, then read - 6.
“Keep the SKILL.md body under 500 lines for optimal performance.”
↩︎ Agent Skills: metadata first, instructions on trigger“Keep references one level deep from SKILL.md.”
↩︎ Agent Skills: metadata first, instructions on trigger - 7.
“can consume ~55k tokens in definitions before Claude does any work”
↩︎ Tool search: deferring tool definitions“Never set defer_loading: true on the tool search tool itself.”
↩︎ Tool search: deferring tool definitions“defer_loading controls what enters the context window, not what you send in the request”
↩︎ Exam trap 3“defer_loading controls what enters the context window, not what you send in the request”
↩︎ Prediction - 8.
“Tool selection accuracy degrades with more than 30-50 tools loaded at once.”
↩︎ Tool search: deferring tool definitions“Tool search is off. All tool definitions are loaded into context on every turn.”
↩︎ Tool search: deferring tool definitions