---
title: "The Docs Expert · Agentic Atlas"
description: "The Docs Expert: a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs."
canonical: "https://agentic-atlas.dev/nodes/docs-expert-agent"
last-updated: "2026-08-19"
---

# The Docs Expert · Agentic Atlas

[← the survey](https://agentic-atlas.dev/atlas)

1. example of [Heavy Agent](https://agentic-atlas.dev/nodes/heavy-agent)
   The Docs Expert
   Hook
   a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs
   Thesis
   A large reference of about 8k tokens is baked into an agent definition whose narrow job is answering questions about it accurately; the orchestrator sends one question and gets back a distilled answer, and never reads the reference into its own window.
   Laws & fences
  - The defining weight is authored, the baked-in reference, which is what makes this a heavy agent rather than a runtime sweep; the same authored weight can go stale, so when the underlying docs change the agent file must be maintained.
  - Loading the full reference inline costs the orchestrator's window about 8,000 tokens that stay and crowd the rest of the workflow; dispatching the docs expert costs about 250 tokens for the question and the distilled answer, while the 8k burns in the subagent's fresh window.
  - Dispatching again for another fact reloads the reference in a fresh sub-window, a per-dispatch fixed cost, but the orchestrator still never carries the 8k.
  - How the answer is shaped or verified on the way back is the return boundary, owned by neighboring patterns, contract-documentation among them, rather than by this pattern; the heavy agent ends at the offload.
   When to reach
  - Reach for it when an orchestrator mid-task needs one fact out of a large reference and answering from its own window would mean admitting the whole reference to reach the part that answers it.
  - Skip it when the reference outgrows a window or churns faster than you would re-author the agent file; that case is reference-data's territory rather than this pattern's, served by the librarian, a subagent composed with reference-data that fetches the relevant volume at runtime and returns the raw slice rather than a distilled answer.
   Provenance
   [docs-expert-agent/context-the-setup](https://agentic-atlas.dev/nodes/docs-expert-agent#context-the-setup) · v1.0.2
   Addresses
   atlas_cards docs-expert-agent
2. [
   Reference Data
   ](https://agentic-atlas.dev/nodes/reference-data)
3. [
   Heavy Agent
   ](https://agentic-atlas.dev/nodes/heavy-agent)
4. [
   Subagent Offload
   ](https://agentic-atlas.dev/nodes/subagent-offload)
5. [
   Parallel Audit Investigation
   ](https://agentic-atlas.dev/nodes/parallel-audit-investigation)
6. [
   The Contract
   ](https://agentic-atlas.dev/nodes/contract-documentation)
7. [
   Cost Relocation
   ](https://agentic-atlas.dev/nodes/cost-relocation)
8. field notes
  - “the travelling declared-shape contract specialization”
  - “validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied”

The card, in place · its connections drawn edges from atlas_links docs-expert-agent

On this plate

[context-the-setup](https://agentic-atlas.dev#context-the-setup)[problem-signal](https://agentic-atlas.dev#problem-signal)[choice-why-it-s-a-heavy-agent-not-just-subagent-offload](https://agentic-atlas.dev#choice-why-it-s-a-heavy-agent-not-just-subagent-offload)[before-the-reference-read-into-the-orchestrator-s-window](https://agentic-atlas.dev#before-the-reference-read-into-the-orchestrator-s-window)[implementation-the-dispatch](https://agentic-atlas.dev#implementation-the-dispatch)[result-the-economics-made-visible](https://agentic-atlas.dev#result-the-economics-made-visible)[verification-what-this-example-deliberately-leaves-out](https://agentic-atlas.dev#verification-what-this-example-deliberately-leaves-out)[lessons-the-expert-not-the-librarian](https://agentic-atlas.dev#lessons-the-expert-not-the-librarian) [relationships](https://agentic-atlas.dev#relationships)

Every section is addressable on its own. Read only the ground you need.

## Contextthe setup

[](https://agentic-atlas.dev#context-the-setup)

context-the-setup.md

Bake a large reference into an [agent definition](https://agentic-atlas.dev/glossary/agent-definition) — an API spec, a library's docs, an internal system's manual. Call it ~8k tokens of **authored weight**: endpoints, parameters, version notes, gotchas, worked snippets. The agent's job is narrow: answer questions about that reference accurately.

*(One concrete instantiation: a "Claude-API expert" agent with model IDs, pricing, params, streaming, tool use, and caching baked in. The teaching is the generic move, not the specific docs — swap in any large reference.)*

## Problem signal

[](https://agentic-atlas.dev#problem-signal)

problem-signal.md

An orchestrator is mid-task and needs one fact:

> "What's the current model ID for the top-tier model, and how do I enable prompt caching?"

One fact, out of ~8k of reference. Answered from the orchestrator's own [window](https://agentic-atlas.dev/glossary/window-context-window), the whole reference has to be admitted to reach the part that answers it.

## Choicewhy it's a \*heavy\* agent (not just subagent offload)

[](https://agentic-atlas.dev#choice-why-it-s-a-heavy-agent-not-just-subagent-offload)

choice-why-it-s-a-heavy-agent-not-just-subagent-offload.md

The defining weight here is **authored** — the baked-in reference — exactly [Heavy Agent](https://agentic-atlas.dev/nodes/heavy-agent)'s defining feature, not a runtime sweep (contrast [Parallel Audit Investigation](https://agentic-atlas.dev/nodes/parallel-audit-investigation) under [Subagent Offload](https://agentic-atlas.dev/nodes/subagent-offload)). Same offload mechanic, authored heaviness. That authored weight is also what can go stale: when the underlying docs change, the agent file must be maintained.

## Beforethe reference read into the orchestrator's window

[](https://agentic-atlas.dev#before-the-reference-read-into-the-orchestrator-s-window)

before-the-reference-read-into-the-orchestrator-s-window.md

The shape being replaced is the obvious one: the orchestrator reads the reference in. All ~8k of authored weight lands in its own window — and it *stays* there, crowding the rest of the [workflow](https://agentic-atlas.dev/glossary/workflow).

## Implementationthe dispatch

[](https://agentic-atlas.dev#implementation-the-dispatch)

implementation-the-dispatch.md

It **invokes the docs expert by type** with just that question. It does **not** read the reference into its own window.

## Resultthe economics, made visible

[](https://agentic-atlas.dev#result-the-economics-made-visible)

result-the-economics-made-visible.md

| Approach | Orchestrator window cost |
| --- | --- |
| Load the full reference inline | ~8,000 tokens — and it *stays*, crowding the rest of the workflow |
| Dispatch the docs expert | ~250 tokens — question + distilled answer |

The 8k of authored weight burns in the **[subagent](https://agentic-atlas.dev/glossary/subagent)'s** fresh window — for free from the orchestrator's side. The orchestrator's context grows only by the question and the answer. Dispatch again for another fact and the reference reloads in a fresh sub-window (per-dispatch fixed cost — Tradeoff #1), but the orchestrator *still* never carries the 8k.

## Verificationwhat this example deliberately leaves out

[](https://agentic-atlas.dev#verification-what-this-example-deliberately-leaves-out)

verification-what-this-example-deliberately-leaves-out.md

How the answer is shaped or verified on the way back. That is the **[return](https://agentic-atlas.dev/glossary/return) boundary** — owned by [The Contract](https://agentic-atlas.dev/nodes/contract-documentation) / *the travelling declared-shape contract specialization* / *validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied* neighbors, not by this pattern. Heavy agent ends at the offload.

## Lessonsthe expert, not the librarian

[](https://agentic-atlas.dev#lessons-the-expert-not-the-librarian)

lessons-the-expert-not-the-librarian.md

Two service counters answer questions about a big reference, and this example is only one of them. The **expert** has the material in their head — authored into the agent definition — and answers from it; nothing is fetched. The **librarian** has memorized nothing: they know *where everything is* and fetch you the relevant volume at runtime. In tree terms the librarian is a subagent composed with [Reference Data](https://agentic-atlas.dev/nodes/reference-data) — *pay-later* machinery running inside a *pay-elsewhere* window — and you get back the raw slice, not a distilled answer. Reach for the librarian when the reference outgrows a window, or churns faster than you'd re-author the agent file; that case is reference-data's territory (its declared too-big-to-frontload example), not this pattern's.

The relationships ledger

Evidence-bearing references

## Relationships

Every connection keeps the section where it was found. The map above orients; this ledger carries the evidence.

### Outbound references 7

1. in-slice · occurrence 1
   [Heavy Agent](https://agentic-atlas.dev/nodes/heavy-agent)
   the *authored-heavy* specialization
   Evidence: [Choice](https://agentic-atlas.dev/nodes/docs-expert-agent#choice-why-it-s-a-heavy-agent-not-just-subagent-offload) · occurrence 1
2. in-slice · occurrence 2
   [Parallel Audit Investigation](https://agentic-atlas.dev/nodes/parallel-audit-investigation)
   a full agent investigates in parallel; its working set stays elsewhere and only the verdict returns
   Evidence: [Choice](https://agentic-atlas.dev/nodes/docs-expert-agent#choice-why-it-s-a-heavy-agent-not-just-subagent-offload) · occurrence 2
3. in-slice · occurrence 3
   [Subagent Offload](https://agentic-atlas.dev/nodes/subagent-offload)
   the *dispatch-elsewhere* branch
   Evidence: [Choice](https://agentic-atlas.dev/nodes/docs-expert-agent#choice-why-it-s-a-heavy-agent-not-just-subagent-offload) · occurrence 3
4. in-slice · occurrence 1
   [The Contract](https://agentic-atlas.dev/nodes/contract-documentation)
   expectations at a seam, from informal prose to enforced structure
   Evidence: [Verification](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out) · occurrence 1
5. undisclosed · occurrence 2
   Undisclosed relationship
   the travelling declared-shape contract specialization
   Evidence: [Verification](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out) · occurrence 2
6. undisclosed · occurrence 3
   Undisclosed relationship
   validate at the return seam; re-dispatch over repair; bounded autonomy — the contract keystone, applied
   Evidence: [Verification](https://agentic-atlas.dev/nodes/docs-expert-agent#verification-what-this-example-deliberately-leaves-out) · occurrence 3
7. in-slice · occurrence 1
   [Reference Data](https://agentic-atlas.dev/nodes/reference-data)
   the *authored-heavy* specialization: disk-resident, grep-addressable — pay for the size of the answer
   Evidence: [Lessons](https://agentic-atlas.dev/nodes/docs-expert-agent#lessons-the-expert-not-the-librarian) · occurrence 1

### Inbound references 5

1. in-slice · occurrence 1
   [Cost Relocation](https://agentic-atlas.dev/nodes/cost-relocation#examples)
   a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs
   Evidence: [Examples](https://agentic-atlas.dev/nodes/cost-relocation#examples) · occurrence 1
2. in-slice · occurrence 1
   [Heavy Agent](https://agentic-atlas.dev/nodes/heavy-agent#examples)
   a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs
   Evidence: [Examples](https://agentic-atlas.dev/nodes/heavy-agent#examples) · occurrence 1
3. in-slice · occurrence 2
   [Reference Data](https://agentic-atlas.dev/nodes/reference-data#examples)
   a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs
   Evidence: [Examples](https://agentic-atlas.dev/nodes/reference-data#examples) · occurrence 2
4. in-slice · occurrence 5
   [Reference Data](https://agentic-atlas.dev/nodes/reference-data#relationships)
   a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs
   Evidence: [Relationships](https://agentic-atlas.dev/nodes/reference-data#relationships) · occurrence 5
5. in-slice · occurrence 2
   [Subagent Offload](https://agentic-atlas.dev/nodes/subagent-offload#examples)
   a large reference baked into the agent; narrow questions in, distilled answers out — the orchestrator never loads the docs
   Evidence: [Examples](https://agentic-atlas.dev/nodes/subagent-offload#examples) · occurrence 2

[↑ back to the top](https://agentic-atlas.dev#content) [← the survey](https://agentic-atlas.dev/atlas)

Node docs-expert-agent · corpus 31de4cb · Catalog revision 35263c4c415da742953d0462804fb14424e2244dae4c63efd27e468988de70ab