CertSafari
    Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards· Lessons

    Domain 3 · Lesson 19/39

    Progressive discovery vs. loading everything up front

    Progressive Discovery vs. Monolithic Context Loading

    18 min read
    2.63% of exam
    8 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    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?

    Sources12

    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?

    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)

    0 of 2 selected

    Sources12

    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?

    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?

    Sources345

    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.

    What each level of a Skill costs, and when it enters context
    LevelWhen loadedToken costContent
    Level 1: MetadataAlways (at startup)~100 tokens per Skillname and description from YAML frontmatter
    Level 2: InstructionsWhen Skill is triggeredUnder 5k tokensSKILL.md body with instructions and guidance
    Level 3+: ResourcesAs neededNone until accessedReference 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.

    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?

    Sources36

    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.

    Marking a tool for on-demand loadingjson
    {
      "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.

    ENABLE_TOOL_SEARCH values in the Agent SDK
    ValueBehavior
    (unset) or trueTool search on; definitions deferred and discovered on demand, with fallback to upfront loading on unsupported models
    autoDefinitions load upfront until deferrable definitions reach 10% of the context window, then tool search activates
    auto:NSame as auto with a custom percentage; auto:5 activates at 5%
    falseTool 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
    }

    Sources78

    6.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 signals and the loading strategy they point to
    Workload signalStrategyWhat it costs
    Material fits the window, task needs links across the whole thing, latency tolerantLoad it whole up frontLarge single request; context rot still applies
    Corpus larger than any window, narrow questionsgrep plus targeted file readsOne or more tool-call turns per question
    Large procedural library, one or two items per requestOne Agent Skill per item~100 tokens per Skill at startup, plus the triggered body
    Many tools, few needed per requestdefer_loading plus a tool search toolOne extra turn per lookup
    Large but fixed tool list, many requestsPrompt caching25 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.

    Sources2

    Sources

    (8)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 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. 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. 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. 4.
      “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. 5.
      “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. 6.
    7. 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. 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

    Ready to test yourself?

    Practise Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.