CONCEPT Nest tags when content has a natural hierarchy
When your content is naturally hierarchical — a set of documents, each with a source and a body — mirror
that hierarchy with nested tags. The official guidance: "Nest tags when content has a
natural hierarchy (documents inside <documents>, each inside
<document index="n">)." An outer container holds a repeated inner element, and each
inner element can carry metadata — an index attribute, a
<source>, a <title> — alongside its <document_content>.
| Level | Tag | Role |
|---|---|---|
| Container | <documents> | Wraps the whole collection. |
| Item | <document index="1"> | One document, numbered by attribute. |
| Metadata | <source> | Where the document came from. |
| Body | <document_content> | The actual text of that document. |
CONCEPT Referring back — Claude can point at the hierarchy
The payoff of nesting-with-metadata is addressability: because each piece has a name (or an
index), your instructions can point precisely at it, and Claude can cite it back. You can ask
for "the figure from <document index="2">," and Claude can attribute a claim to
document 2's <source>. Referencing tag names in the instructions (4.2) becomes far
more powerful once the tags form a hierarchy you can index into.
<document index="1"> with the forecast
in <document index="2">, and cite each by its <source>." The nested,
labelled structure makes both the request and the citation unambiguous.DIAGRAM A nested document tree
annual_report_2023.pdf"] D1 --> C1["<document_content>
…report text…"] D2 --> S2["<source>
competitor_q2.xlsx"] D2 --> C2["<document_content>
…analysis text…"] INS["<instructions>
refer back by index & source"] -.->|"points at"| D1 INS -.->|"points at"| D2 classDef container fill:#e7f0ff,stroke:#4a90d9,color:#123; classDef meta fill:#fff3cd,stroke:#e0a800,color:#665200; classDef task fill:#d4edda,stroke:#28a745,color:#155724; class DS,D1,D2 container; class S1,S2,C1,C2 meta; class INS task;
CODE Nested documents with metadata, referenced by index
Mirrors the official multi-document structure: an outer <documents>, each
<document index="n"> carrying a <source> and
<document_content> — then the instruction points back by index and asks for source
citations.
<documents>
<document index="1">
<source>annual_report_2023.pdf</source>
<document_content>
{{ANNUAL_REPORT}}
</document_content>
</document>
<document index="2">
<source>competitor_analysis_q2.xlsx</source>
<document_content>
{{COMPETITOR_ANALYSIS}}
</document_content>
</document>
</documents>
<instructions>
Using <document index="1"> and <document index="2">, identify strategic advantages
and recommend Q3 focus areas. Attribute every claim to the document's <source>.
</instructions>
TRADE-OFFS Flat list vs. nested hierarchy
✅ Nested + indexed + metadata
- Each item is addressable by index and by source
- Claude can cite claims back to a specific document
- Scales cleanly to many documents (see 4.5 long-context)
⚠️ One flat tag for everything
- Simpler for a single short document
- But: no way to say "document 2" or attribute a source
- Deep nesting on trivial content just adds ceremony
EXAM TRAPS
index/<source> metadata. → Without
it you can't reliably say "document 2" or ask Claude to cite its source; addressability is the whole
point.index must be numeric or a special attribute. → It's just
a descriptive attribute you choose; consistency matters, not a reserved name.PRACTICE
Q1 · When should you nest XML tags?
When the content has a natural hierarchy — e.g. a collection of documents, each with a source and body. Use an outer container (<documents>) with repeated indexed items (<document index="n">) carrying metadata like <source> and a <document_content> body.
Q2 · What does adding index and <source> metadata buy you?
Addressability: your instructions can point at "document 2," and Claude can refer back and cite claims to a specific document's source — impossible with one flat, unlabelled blob.
Q3 · Give an instruction that references the nested hierarchy.
"Compare the figure in <document index='1'> with the forecast in <document index='2'>, and attribute each claim to its <source>." It names both the item (by index) and the metadata tag to cite.