Progressive Disclosure of Information: Designing Context for LLM Agents

Modern LLM agents face a paradox: context windows are larger than ever (Claude Opus now offers 1M tokens, enough for 350,000 lines of code), yet production agents routinely fail on tasks that should fit comfortably within these limits. The culprit isn't window size. It's how we load information.

Progressive disclosure treats context as a scarce resource, revealing information just-in-time rather than dumping everything upfront. This isn't premature optimization; it's a response to measurable degradation patterns in long-context scenarios. When a single MCP server can consume 147K tokens (86% of a 200K window) before any user interaction, as documented in OpenCode Issue #17480, the need for smarter loading strategies becomes urgent.

This guide examines progressive disclosure as a context-engineering pattern for production agents: the mechanics of metadata-first architectures, the failure modes they mitigate, and the trade-offs they introduce. We'll ground the discussion in concrete benchmarks, token economics, and real implementations from filesystem agents to MCP tool discovery systems.

Why Bigger Context Windows Didn't Solve the Problem

The Lost-in-the-Middle Effect

Long-context models exhibit systematic retrieval failures that scale with window size. In financial document retrieval tasks, F1 scores collapsed from 0.99 at 4K tokens to 0.40 at 128K tokens for single-concept queries (EmergentMind context degradation analysis, Dec 2025). This isn't a training artifact; it reflects how transformer attention mechanisms degrade across distance.

The pattern follows a U-shaped accuracy curve called the Serial Position Curve (SPC), where models retrieve information effectively from the beginning and end of context but fail dramatically in the middle. Under harder retrieval conditions, GPT-4o's accuracy dropped from 99.3% to 69.7% (CSE 5610 Fall 2025 lecture data). The NoLiMa benchmark found that 11 of 13 tested models fell below 50% of baseline performance by 32K tokens, with only 2 outlier models maintaining higher performance.

Effective vs. Advertised Context

NVIDIA's RULER benchmark reveals that most models achieve only 50-65% effective context utilization compared to advertised capacity. Even Claude Opus 4.6, representing what researchers call a "qualitative shift" in long-context handling, achieved 76% effectiveness on the MRCR v2 benchmark (8 needles in 1M tokens), impressive compared to the previous generation's 18.5%, but still far from perfect utilization.

This gap between theoretical and practical capacity matters enormously for agent design. A 200K token window doesn't give you 200K tokens of usable, equally-accessible context; it gives you perhaps 130K tokens with significant position-dependent retrieval variance.

Core Mechanics: Metadata-First Architecture

Progressive disclosure implements a three-layer loading strategy that balances discoverability with context efficiency.

Layer 1: Minimal Metadata for Discovery

The initial context contains lightweight descriptions only, approximately 100 words per capability. This provides semantic discoverability without schema overhead. In Cole Medin's Pydantic AI implementation (documented in his LinkedIn post from 6 months ago), skill descriptions live in the system prompt while full instructions remain on disk.

Token budget at Layer 1: ~100-200 tokens per tool/skill for basic metadata versus ~400-500 tokens for full schemas (observed in MCP tool definitions from the OpenCode analysis).

Layer 2: Just-in-Time Schema Loading

When the agent selects a capability, the system loads complete instructions on-demand. This might include:

Full parameter schemas and validation rules
Operational instructions and constraints
Usage examples and common patterns

Implementation pattern: Medin's system uses two core tools: load_skill() for dynamic capability loading and read_reference_document() for deep reference access. The agent discovers capabilities through metadata, then explicitly loads what it needs.

Layer 3: Deep Reference Materials

Documentation, examples, and edge-case handling load only when Layer 2 proves insufficient. This furthest layer remains outside context until specifically requested.

Progressive Tool Discovery at Scale

The MCP protocol discussion #532 proposes hierarchical tool management that extends progressive disclosure to tool discovery itself:

Category-based browsing: tools/categories lists available domains without loading schemas
Semantic discovery: tools/discover queries by category or search term
Selective loading: tools/load brings specific categories into context
Context cleanup: tools/unload removes unused tools to free budget

This approach addresses the practical scaling limit of flat tool lists. A 50-tool agent would theoretically consume 20,000-25,000 tokens for schemas alone before any work begins. With hierarchical loading, only 10-15 active tools might occupy context at any time, reducing baseline consumption by 50-75%.

Comparative Analysis: Eager vs. Lazy Loading

The OpenCode Issue #17480 documents behavior differences between eager and lazy loading strategies:

OpenCode (eager loading):

Loads full schemas immediately on connection
Single MCP server (lark-mcp-docx) added 147K tokens
Baseline consumption: ~21K tokens
With MCP enabled: ~168K tokens
Result: 86% of a 200K context window consumed before user interaction

Cursor (lazy loading):

Maintains minimal metadata in initial context
Fetches input_schema just-in-time on tool invocation
Baseline consumption remains low until capabilities are actually used
Result: Order of magnitude difference in usable context budget

The difference isn't merely efficiency; it's whether the agent can function at all. An 86% baseline consumption leaves 28K tokens for user messages, tool outputs, conversation history, and reasoning. Multi-turn agentic tasks routinely require tens of thousands of tokens for accumulated context.

History Management and Compaction Strategies

Progressive disclosure applies not just to tools and documents but to conversation history itself.

The Multi-Turn Accumulation Problem

Agent sessions with 10,000-token system prompts spanning dozens of API calls can accumulate tens of thousands of tokens in conversation history alone (Lumer et al., arXiv 2601.06007v2 prompt caching evaluation). Without compaction, every turn adds:

User message tokens
Tool call requests and responses
Model reasoning traces
Error messages and retries

A 20-turn conversation with 500 tokens per turn consumes 10K tokens, manageable individually, catastrophic when combined with eager tool loading.

Compaction Techniques

Summarization: Periodically compress conversation history into summaries. Instead of retaining 15 turns of back-and-forth about file locations, keep: "User is working in /src/components/, has identified Button.tsx as the target file."

Selective retention: Keep recent turns verbatim (recency bias works in your favor) while compacting older context. The U-shaped retrieval curve suggests this matches model capabilities.

Note-taking as state management: Some implementations maintain a separate "working memory" document that the agent updates with key facts, treating conversation history as ephemeral and notes as persistent state.

Sliding windows: Drop oldest turns when context budget is exhausted, with explicit acknowledgment: "Earlier conversation history has been archived to maintain context quality."

Token Economics: Prompt Caching and Cost-Latency Trade-offs

Progressive disclosure introduces additional round-trips: loading tools on-demand requires extra API calls. Prompt caching mitigates this cost, but with nuance.

Measured Caching Benefits

Lumer et al.'s evaluation across 500+ agent sessions found:

API cost reduction: 41-80% across providers (OpenAI, Anthropic, Google)
Time to first token (TTFT): 13-31% improvement
Statistical significance: p<0.05 for TTFT improvements
Scaling: Linear benefits from 500 to 50,000 token prompts, 3 to 50 tool calls

These benefits apply specifically to prompt caching implementations where stable content (system prompts, tool schemas) can be cached while dynamic content (user messages, tool results) remains fresh.

Optimal Caching Strategies

Pattern 1: System prompt caching

Cache stable system instructions and base tool metadata
Keep dynamic content (user messages, tool outputs) at the end
Result: Predictable cache hits, consistent cost/latency benefits

Pattern 2: Schema caching with lazy loading

Load tool schemas on-demand, but cache them once loaded
Subsequent uses of the same tool hit cache
Result: First invocation pays loading cost, subsequent invocations benefit from caching

Anti-pattern: Full-context caching

Caching everything including dynamic tool results can paradoxically increase latency
Cache invalidation on every dynamic element negates benefits
Result: Cache thrashing, worse performance than no caching

The Extra Round-Trip Calculation

Does lazy loading cost more than eager loading despite caching? The math depends on tool usage patterns:

Eager loading cost: N tools × 450 tokens/tool × $0.015/1K input tokens = baseline cost every request

Lazy loading cost:

Initial: N tools × 100 tokens metadata × $0.015/1K = 0.22× baseline
Per tool used: 450 tokens × $0.015/1K (first use) → cached rate (subsequent)

Break-even: If you use fewer than ~60% of loaded tools per session, lazy loading costs less even without caching. With caching, lazy loading wins decisively for agents that use 10-15 of 50+ available tools.

Provider-Specific Considerations

The Lumer study found meaningful differences across providers:

OpenAI: Strongest TTFT improvements (31% average)
Anthropic: Most consistent cost reduction (70-80%)
Google: Variable results, requiring provider-specific tuning

These differences stem from caching implementation details (block sizes, eviction policies, cache key strategies) that aren't fully documented in provider APIs. Production systems need provider-specific optimization.

Failure Modes and Mitigation Strategies

Progressive disclosure introduces new failure modes while mitigating others. Understanding both is critical for production deployment.

Failure Mode 1: Incomplete Retrieval

Risk: Metadata-based discovery might miss relevant capabilities if descriptions are poorly written or the agent's query doesn't match semantic embeddings.

Mitigation strategies:

Comprehensive metadata that includes synonyms and use-case examples
Fallback to broader category browsing when specific search fails
Explicit "show me all tools" capability for when discovery fails
Monitoring and logging of tool selection patterns to identify discovery gaps

Measurement: Track ratio of successful task completions to tool discovery attempts. Values below 0.85 suggest metadata quality issues.

Failure Mode 2: Cache Invalidation Cascades

Risk: Dynamic tool loading can invalidate cached prompt blocks if not carefully structured, negating performance benefits.

Mitigation strategies:

Structure prompts with stable content first, dynamic content last (documented in the Lumer caching study)
Use provider-specific cache control markers where available
Separate tool metadata (cached) from tool instances (dynamic)
Monitor cache hit rates; drops below 60% indicate structural problems

Measurement: Provider APIs expose cache hit metrics. Establish baseline hit rates (70-80% is typical for well-structured systems) and alert on degradation.

Failure Mode 3: Context Fragmentation

Risk: Loading tools across multiple turns creates fragmented context where related capabilities appear far apart, potentially triggering lost-in-the-middle effects.

Mitigation strategies:

Load related tools together in semantic groups
Position recently-loaded tools at context boundaries (beginning/end) where retrieval is strongest
Implement explicit "currently loaded tools" summaries that refresh position
Consider unloading rarely-used tools to consolidate active capabilities

Measurement: Compare task success rates for early-loaded vs. late-loaded tools. Significant differences (>15%) suggest fragmentation issues.

Evaluation and Observability

Production progressive disclosure systems require specific instrumentation:

Key Metrics

Context utilization: Track token consumption across layers

Baseline (metadata only): target <5% of window
Active working set: target 20-40% of window
Peak utilization: should stay below 70% to maintain effectiveness

Tool selection accuracy: Measure whether agents choose correct tools from metadata

Discovery success rate: >85%
First-choice accuracy: >70%
Average tools examined before selection: <5

Round-trip overhead: Count additional API calls from lazy loading

Average extra calls per task: target <3
Latency impact: should be offset by caching (net neutral or positive)

Cache efficiency: Monitor cache hit rates and invalidation patterns

Hit rate: target >70%
Invalidation rate: <15% per turn
TTFT improvement: target >15% vs. no caching

A/B Testing Framework

Progressive disclosure benefits vary by task type. Implement A/B testing:

Control group: Eager loading with full schemas
Treatment group: Progressive disclosure with caching
Stratify by: Task complexity, tool count, session length
Measure: Success rate, latency, cost, user satisfaction

The OpenCode vs. Cursor comparison (Issue #17480) provides a natural experiment template, though production validation requires controlled conditions.

Conclusion: A Promising Pattern Requiring Broader Validation

Progressive disclosure mitigates documented failure modes in long-context LLM agents: the lost-in-the-middle effect that drops F1 scores from 0.99 to 0.40 as context grows, the 86% baseline consumption documented in eager MCP loading, and the context accumulation that makes multi-turn agent sessions untenable.

The pattern shows measurable benefits in production scenarios: 41-80% cost reduction through prompt caching, 13-31% latency improvement, and order-of-magnitude increases in practical tool catalog sizes. The mechanics (metadata-first discovery, just-in-time schema loading, history compaction) align with both empirical attention degradation patterns and economic incentives.

However, current evidence comes from limited production deployments (Medin's implementation, Cursor's lazy loading, the OpenCode comparison) and controlled benchmarks. Broader validation across diverse agent architectures, task types, and scale regimes remains necessary. The failure modes (incomplete retrieval, cache invalidation cascades, context fragmentation) require systematic study to establish mitigation best practices.

For senior engineers building production agents, the actionable path forward:

Instrument first: Add context utilization, tool selection accuracy, and cache efficiency metrics to existing agents before architectural changes
Start with history compaction: Apply progressive disclosure to conversation history through summarization and sliding windows, lower risk than tool refactoring
Implement dual-mode tool loading: Support both eager and lazy loading behind feature flags, measure comparative performance on production traffic
Optimize caching strategy: Structure prompts with stable content first, dynamic content last; validate cache hit rates exceed 70%
Scale gradually: Expand tool catalogs only after discovery mechanisms prove reliable at current scale

Progressive disclosure isn't a silver bullet; it's a context-engineering pattern that trades additional round-trips and implementation complexity for improved accuracy, reduced cost, and expanded capability. The early evidence is promising, but production validation at scale will determine whether it becomes a standard pattern or a niche optimization.

The context window arms race continues: models will support 10M, then 100M tokens. But physics doesn't change: attention degrades with distance, retrieval fails in the middle, and loading everything upfront wastes scarce resources. Progressive disclosure treats context as what it is: a limited, position-sensitive resource that demands careful engineering, not just bigger buffers.