Progressive discovery vs monolithic context

What you’ll be able to do

• Compare monolithic and progressive context strategies on accuracy, cost, latency, cacheability and predictability
• Design progressive disclosure with short descriptions up front and detail loaded on demand
• Recognize when a monolithic, cached context is the better choice
• Mitigate the risks of progressive discovery: missed context, extra round-trips and poor descriptions

What you need to know

Two strategies

A monolithic context strategy puts everything the agent might need into every request: all tool definitions from every connected server, the full policy handbook, every instruction for every workflow. A progressive discovery strategy starts with a compact map (names and short descriptions of available capabilities and knowledge) and lets the agent pull in detail only when the task calls for it.

Neither is right in general. The architect's job is to choose per category of context, based on its size, stability and how often it's relevant.

Why monolithic context breaks down at scale

• Attention and accuracy. As context grows with material irrelevant to the current task, the model has more to sift through. Instructions get diluted and similar tools get confused. Large tool catalogues with overlapping names are a common cause of wrong tool selection.
• Cost and latency. Every token in every request costs money and time. Caching helps with repeated prefixes, but a giant prefix still has to be processed when the cache is cold, and any change to it invalidates the cache.
• Governance and maintainability. One giant prompt with every team's instructions becomes a shared file nobody owns, where an edit for one workflow quietly changes another.
• Capability bloat. Exposing every tool up front widens what the agent can call (see 3.1).

A larger context window raises the ceiling but doesn't remove these effects. "It fits" isn't the same as "it helps."

How progressive discovery works in the Claude ecosystem

• Skills. Agent Skills are a clear example of progressive disclosure. Only each skill's name and description sit in context up front. The full SKILL.md instructions load when the model decides the skill is relevant, and bundled reference files or scripts load only if those instructions call for them. Many skills can be installed while each costs very little context until used.
• Tool discovery. Instead of loading hundreds of tool definitions, an agent can search or browse for the tools it needs and load their definitions on demand. Anthropic's platform documentation describes on-demand tool loading for large tool libraries. Check the current docs for the mechanism available to you.
• Retrieval and file exploration. RAG, or letting an agent navigate files with search and read tools (as Claude Code does in a codebase), is progressive discovery for knowledge: an index or directory structure up front, content on demand.
• Scoped instructions. Path- or task-specific instructions (for example, Claude Code rules that load for matching files) keep workflow-specific guidance out of unrelated sessions.
• Subagents. Delegating exploration to a subagent with its own context, and returning a condensed result, keeps the orchestrator's context small.

When monolithic is the better choice

Progressive discovery isn't free. Each discovery step can add a model turn and a tool call. The model can fail to load something it needed, because it didn't realise the relevant skill or document existed or the description didn't match the task. And behaviour is less predictable, because what's in context varies by request. Monolithic context wins when the material is:

• Small enough not to crowd the task,
• Stable, so it sits in a cacheable prefix and costs little after the first request,
• Always relevant, like core safety rules, the output contract, or a handful of tools used on nearly every request,
• Mandatory: rules that must apply to every turn shouldn't depend on the model choosing to load them.

The usual production answer is a hybrid: a stable, cached core (identity, non-negotiable rules, the most common tools) plus progressive access to the long tail of tools, procedures and knowledge.

Making discovery reliable

• Descriptions are routing logic. The model decides what to load from names and descriptions alone. Write them to say what the capability does and when to use it, with distinguishing terms, so similar capabilities don't blur together.
• Keep the map complete. The agent can't load what it doesn't know exists. Make sure the index of skills, tools or documents is always present even when the content isn't.
• Measure misses. In evaluation, check whether the agent loaded the right capability for each task, and trace discovery steps in production (see 3.4). Missed loads look like the model not knowing something it "should" know.
• Never make hard rules optional. Anything mandatory goes in the always-loaded core or is enforced in code, not in a skill the model might skip.

Key concept

Keep a small, stable, always-relevant core in a cached prefix, and expose everything else through short descriptions the agent uses to load detail on demand. Bigger windows don’t change that trade-off.

Questions describe an agent that degraded or became expensive as tools and documents were added, or a team that wants to put everything into one prompt because "it fits." The strong answer moves the long tail to progressive discovery and keeps the core cached. Watch for the reverse case too, where tiny, mandatory context was wrongly made optional.

Practice scenario

Build exercise — Split a monolithic context

Advanced · 50 min

What you’ll learn

• Classifying context by size, stability, relevance and whether it’s mandatory
• Moving long-tail content to progressive discovery with descriptions that work
• Measuring discovery misses alongside cost and accuracy

1. Take an existing system prompt and tool set. Label every section and tool as always-relevant or long-tail, stable or frequently changing, and mandatory or optional.

   • Why: The labels decide placement. Mandatory, stable, always-relevant content stays in the cached core. Long-tail content moves out.
   • You should see: A small core and a much larger long tail, often with frequently edited content that’s breaking the cache.

2. Move the long-tail content into skills, retrieval or on-demand tools, writing a one- or two-sentence description for each that says what it covers and when to use it.

   • Why: The descriptions are the only thing the model sees when it decides what to load.
   • You should see: A compact index in context that names every capability, with detail loaded only on use.

3. Run your evaluation tasks against both versions and record task accuracy, discovery misses (needed capability not loaded), turns per task, cache hit rate and cost per request.

   • Why: Progressive discovery trades fewer tokens for extra turns and possible misses. You need both sides to justify it.
   • You should see: Lower cost and better tool selection, plus a short list of descriptions to sharpen where misses occurred.

Exam traps

Loading every tool definition, document and instruction into every request by default

Irrelevant context dilutes attention, confuses tool selection and costs tokens on every call. Load the long tail on demand.

Assuming a bigger context window removes the need for context selection

A larger window raises the ceiling but doesn’t fix dilution, cost or cache churn. “It fits” isn’t “it helps.”

Writing vague capability descriptions that the model can’t use to decide what to load

In progressive discovery, descriptions are the routing logic. Vague ones cause missed or wrong loads.

Using progressive discovery for small, always-needed context that would cache well

That adds round-trips and miss risk for no benefit. Keep small, stable, always-relevant content in the cached core.

Forgetting that discovery adds round-trips and can miss content the model never thinks to load

Discovery has costs. Keep the index complete, measure misses, and keep mandatory rules always loaded or enforced in code.

Sources

• Claude Developer Platform Docs
• Anthropic
• Anthropic, Claude Certified Architect – Professional Exam Guide v1.0 (July 2026)