---
title: "Progressive Disclosure for Large Files"
summary: "Puts only file metadata in the prompt and gives the agent load, peek, and extract tools to pull file content into context on demand"
status: "emerging"
category: "Context & Memory"
url: "https://agentic-patterns.com/patterns/progressive-disclosure-large-files"
source: "https://lethain.com/agents-large-files/"
authors: ["Nikola Balic (@nibzard)"]
tags: ["progressive-disclosure","large-files","context-optimization","file-management","lazy-loading","file-handling","metadata"]
signals: ["Agent works with large PDFs, DOCX files, or images","Files are much bigger than the relevant text they contain","Workflows compare documents or read ticket attachments"]
anti_signals: ["Files are small enough to load in full","Extra tool round-trips are not acceptable"]
updated_at: "2026-10-13"
---

# Progressive Disclosure for Large Files

> Puts only file metadata in the prompt and gives the agent load, peek, and extract tools to pull file content into context on demand

## Use when

- Agent works with large PDFs, DOCX files, or images
- Files are much bigger than the relevant text they contain
- Workflows compare documents or read ticket attachments

## Avoid when

- Files are small enough to load in full
- Extra tool round-trips are not acceptable

## Problem

Large files (PDFs, DOCXs, images) overwhelm the context window when loaded naively. A 5-10MB PDF may contain only 10-20KB of relevant text/tables, but the entire file is often shoved into context, wasting tokens and degrading performance.

## Solution

Apply **progressive disclosure**: load file metadata first, then provide tools to load content on-demand.

**Core approach:**

1. **Always include file metadata** in the prompt (not full content):

   ```
   Files:
     - id: f_a1
       name: my_image.png
       size: 500,000
       preloaded: false
     - id: f_b3
       name: report.pdf
       size: 8500000
       preloaded: false
   ```

2. **Optionally preload first N KB** of appropriate mimetypes (configurable per-workflow, can be 0)

3. **Provide three file operations:**

   - `load_file(id)` - Load entire file into context
   - `peek_file(id, start, stop)` - Load a section of file
   - `extract_file(id)` - Transform PDF/DOCX/PPT into simplified text

4. **Include a `large_files` skill** explaining when/how to use these tools

```pseudo
# Agent workflow for document comparison
1. Prompt includes file metadata for report_2024.pdf and report_2025.pdf
2. Agent sees large PDFs, checks large_files skill
3. Agent calls: extract_file("report_2024.pdf")
4. Agent calls: extract_file("report_2025.pdf")
5. Agent compares extracted summaries using minimal context
```

```pseudo
# Agent workflow for image analysis
1. Prompt includes metadata for screenshot.png
2. Agent sees PNG type, calls: load_file("screenshot.png")
3. Image content is loaded, agent analyzes visual content
```

## How to use it

**Best for:**

- Document comparison workflows (multiple PDFs)
- Ticket systems with file attachments (images, PDFs)
- Data export analysis (large reports in various formats)
- Any workflow where agents need file content but files are large

**Implementation considerations:**

- File `id` should be a stable reference for tool calls
- `extract_file` should return simplified text (tables, text content)
- Consider making `extract_file` return a virtual `file_id` for very large extractions
- Preloading first N KB is optional - can give agent initial context without full load
- Cache extracted content to avoid re-processing; pick TTLs to match how often the underlying files change

**Tool design:**

```python
def load_file(file_id: str, format: str = "text") -> str:
    """Load entire file content into context window."""

def peek_file(file_id: str, offset: int, length: int, unit: str = "bytes") -> str:
    """Load a specific range from file. Unit options: bytes, lines, pages, tokens."""

def extract_file(file_id: str, extraction: str = "text") -> str:
    """Convert PDF/DOCX/PPT to simplified representation.
    Extraction options: text, structure, tables, summary."""
```

## Trade-offs

**Pros:**

- Enables working with files much larger than context window
- Agent has control over what/when to load
- Reusable across workflows via `large_files` skill
- Extracted text is typically far smaller than the original file (a multi-megabyte PDF may hold only kilobytes of relevant text)

**Cons:**

- Adds tool call overhead (multiple round-trips)
- Requires preloading heuristics (how much is enough?)
- Extraction from complex formats (DOCX) can be slow without native dependencies
- Agent may make poor loading decisions without proper guidance

**Trade-offs in preloading:**

- **Preloading**: Gives agent immediate context but reduces control
- **No preloading**: Maximum agent control but requires explicit load calls

## References

* [Building an internal agent: Progressive disclosure and handling large files](https://lethain.com/agents-large-files/) - Will Larson (2025), the practitioner source for the metadata-plus-load/peek/extract core described above
* Agent Skills use the same progressive-disclosure model for instructions: a `SKILL.md` with metadata loads up front and full instructions are read only on demand - https://code.claude.com/docs/en/skills
* Related: [Progressive Tool Discovery](progressive-tool-discovery.md) - the same lazy-loading idea applied to tool definitions rather than file contents
* Related: [Context-Minimization Pattern](context-minimization-pattern.md) - Complementary pattern for reducing context bloat
* LangChain - Document loaders with metadata-first approach ([github.com/langchain-ai/langchain](https://github.com/langchain-ai/langchain))