Problem
Agents currently have to grep/read their way through a document to locate a section. On a long contract (e.g. a 60-page MSA) that burns context window and raises the risk of acting on the wrong clause — the agent has no lightweight map of where things are before it starts reading bodies of text.
We already expose read_file and grep, but neither gives structural awareness. The agent has to reconstruct the document’s shape from raw text matches.
Proposal
Add a get_document_outline MCP tool that traverses the DOM and returns a compact structural map instead of full text:
- Headings (by heading style / outline level), section breaks, and optionally table/figure anchors
- The stable paragraph id for each entry, so the agent can follow up with a targeted
read_file / replace_text scoped to that region
- JSON (and/or Markdown) output, on the order of hundreds of tokens for a long document
Flow: agent reads the outline (cheap) → sees §4.2 holds the indemnity clause → reads only the paragraphs under §4.2. Map first, then targeted read.
Notes / leverage
docx-core already has the DOM traversal and heading-style detection needed; this is mostly a projection layer over existing primitives plus a tool_catalog.ts entry.- Paragraph ids should reuse whatever stable id scheme
read/replace_text already key on, so outline entries are directly actionable.
- Open question: how to represent unstyled-but-clearly-structural headings (manual bold/centered runs that aren’t Heading N). Start with style-based detection; treat heuristic detection as a follow-up.
Out of scope
- Full text extraction (that’s
read_file)
- Semantic classification of clauses (that’s the agent’s job)
Problem
Agents currently have to
grep/readtheir way through a document to locate a section. On a long contract (e.g. a 60-page MSA) that burns context window and raises the risk of acting on the wrong clause — the agent has no lightweight map of where things are before it starts reading bodies of text.We already expose
read_fileandgrep, but neither gives structural awareness. The agent has to reconstruct the document’s shape from raw text matches.Proposal
Add a
get_document_outlineMCP tool that traverses the DOM and returns a compact structural map instead of full text:read_file/replace_textscoped to that regionFlow: agent reads the outline (cheap) → sees §4.2 holds the indemnity clause → reads only the paragraphs under §4.2. Map first, then targeted read.
Notes / leverage
docx-corealready has the DOM traversal and heading-style detection needed; this is mostly a projection layer over existing primitives plus atool_catalog.tsentry.read/replace_textalready key on, so outline entries are directly actionable.Out of scope
read_file)