{"course":{"slug":"context-engineering","title":"Context Engineering","url":"https://addaly.com/learn/context-engineering","level":"advanced","track":"build"},"lesson":{"slug":"metadata-that-earns-its-tokens","title":"The header on every chunk","url":"https://addaly.com/learn/context-engineering/metadata-that-earns-its-tokens","position":17,"of":87,"minutes":8,"answer":"A per-chunk header is paid k times on every request, so keep the fields that change what the model does (a short citation handle, a date when versions conflict.","keyIdea":"A per-chunk header is paid k times on every request, so keep the fields that change what the model does (a short citation handle, a date when versions conflict, and the section path that makes a mid-document chunk intelligible) and leave ids, scores and filter fields in the index."},"body":{"format":"markdown","text":"## Multiply before you decide\n\nA per-chunk header looks free. It is not, and the arithmetic is the whole lesson.\n\nA header carrying title, section path, date, source URL and an internal id runs about 45 tokens. At k=12 that is 540 tokens per request. At a million requests a month, on a typical hosted input price, it is a four-figure annual line item for text that is mostly not read.\n\nSo the question for each field is not \"might this be useful\" but \"what decision does the model make differently because this is here\". Fields that pass:\n\n**A citation handle.** Short. `[7]` or `S3`. It is what makes \"cite the passage you used\" work at all, and it is four tokens. This one always pays.\n\n**A date**, when passages can disagree over time. Covered in the previous lesson.\n\n**A source identity a user would recognise**: the document title, or the product area. Two purposes: the model can say where an answer came from in words a human trusts, and it can weigh a policy page above a forum post.\n\n**A section path**, when chunks come from long structured documents. `Refunds > Sale items > Exceptions` tells the model what the chunk is about even when the chunk itself uses pronouns. This is often the highest-value 8 tokens in the header.\n\nFields that usually fail:\n\n- **Internal UUIDs.** 15 to 20 tokens each, meaningless to the model, and the citation handle already does the job. Keep the mapping in your code, not in the window.\n- **The similarity score.** Tempting and quietly harmful: it invites the model to treat rank as truth, and a 0.82 next to a passage reads like a confidence claim about its content, which it is not.\n- **Ingestion timestamps, embedding model versions, chunk indices.** Debugging data. Log them; do not send them.\n- **Full URLs.** A long URL is 20 to 40 tokens. If the user needs a link, attach it in your application layer after the model has cited `[7]`, which costs nothing.\n\n## Format compactly, and consistently\n\nWithin a header, dense is better than pretty:\n\n```\n[7] Refund policy · Sale items · 2026-03-14\nCustomers may request a refund within 30 days of delivery...\n```\n\nThree things matter more than the exact style. Use the **same shape for every passage**, so the model learns the pattern within the request. Put the header **immediately before** its text with no blank line drift. And make the **boundary between passages unmistakable**: the delimiters lesson later covers why a consistent marker beats an elegant one.\n\n## The metadata that never enters the window\n\nA useful discipline: most metadata exists to be filtered on, not read. Tenant, ACL groups, language, document type, source system, permissions version. All of it belongs in the index for the pre-filter, and none of it belongs in the context.\n\nSending `tenant_id: acme-corp` to the model achieves nothing except telling a prompt-injection attempt what your tenant ids look like. Filter on it; do not print it.\n\n## Where the header earns the most\n\nOne case is worth calling out because it changes results more than the others: **chunks that do not stand alone.**\n\nA chunk from the middle of a long page begins \"This does not apply to items purchased during a promotional period.\" What is *this*? Without the section path, the model does not know, and neither would a human. With `Refund policy > Sale items` in front of it, the sentence becomes usable.\n\nThat is the same problem the chunking lesson solves by carrying context down into the chunk. A section-path header is the cheap version, applied at retrieval time and costing eight tokens; a generated contextual sentence is the expensive version, applied at ingestion. The next module covers when the expensive version is worth it.\n\n## Measure the header like anything else\n\nHeaders are a cheap experiment because they are pure assembly: no re-indexing, no re-embedding. Run your evaluation set with the full header, then with only the citation handle, then with handle plus section path.\n\nTeams commonly find that the handle and the section path carry almost all the benefit and the rest is decoration. Which is a 30-token-per-chunk saving, discovered in an hour, that nobody would have believed without the numbers."},"check":{"question":"A team includes the similarity score in each passage header, hoping the model will weight better-matching passages more heavily. What is the most likely effect?","options":[{"text":"It has no effect, since numbers in a header are ignored by the tokeniser as metadata.","correct":false,"tempting":"Assumes a distinction the model does not make; a header is ordinary text and is attended to like any other."},{"text":"It improves ordering robustness, because the model can recover the intended ranking if passages arrive out of order.","correct":false,"tempting":"Assumes the model needs the ranking recovered when position already carries it, and ignores what the number actually claims."},{"text":"The model reads the score as a confidence claim about the passage's truth, though it only measures embedding proximity.","correct":true},{"text":"It breaks prefix caching, because scores differ on every request.","correct":false,"tempting":"Names a real property of variable content, but retrieved passages are already variable and sit below any cached prefix."}]},"prev":{"slug":"freshness-and-as-of-lines","title":"Telling the model when things were true","url":"https://addaly.com/learn/context-engineering/freshness-and-as-of-lines"},"next":{"slug":"summarise-or-include","title":"The source or a summary of it","url":"https://addaly.com/learn/context-engineering/summarise-or-include"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Exam keys checked blind by a second model: 3,665 of 3,666 agreed. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'The header on every chunk', in Context Engineering. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/context-engineering/metadata-that-earns-its-tokens (Accessed: 13 October 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"The header on every chunk","courseTitle":"Context Engineering","module":{"index":2,"slug":"what-earns-a-place","title":"Selection: what earns a place"},"answer":null,"keyIdea":"A per-chunk header is paid k times on every request, so keep the fields that change what the model does (a short citation handle, a date when versions conflict, and the section path that makes a mid-document chunk intelligible) and leave ids, scores and filter fields in the index.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"multiply-before-you-decide","runs":[{"text":"Multiply before you decide"}]},{"t":"p","runs":[{"text":"A per-chunk header looks free. It is not, and the arithmetic is the whole lesson."}]},{"t":"p","runs":[{"text":"A header carrying title, section path, date, source URL and an internal id runs about 45 tokens. At k=12 that is 540 tokens per request. At a million requests a month, on a typical hosted input price, it is a four-figure annual line item for text that is mostly not read."}]},{"t":"p","runs":[{"text":"So the question for each field is not “might this be useful” but “what decision does the model make differently because this is here”. Fields that pass:"}]},{"t":"p","runs":[{"text":"A citation handle.","b":true},{"text":" Short. "},{"text":"[7]","code":true},{"text":" or "},{"text":"S3","code":true},{"text":". It is what makes “cite the passage you used” work at all, and it is four tokens. This one always pays."}]},{"t":"p","runs":[{"text":"A date","b":true},{"text":", when passages can disagree over time. Covered in the previous lesson."}]},{"t":"p","runs":[{"text":"A source identity a user would recognise","b":true},{"text":": the document title, or the product area. Two purposes: the model can say where an answer came from in words a human trusts, and it can weigh a policy page above a forum post."}]},{"t":"p","runs":[{"text":"A section path","b":true},{"text":", when chunks come from long structured documents. "},{"text":"Refunds > Sale items > Exceptions","code":true},{"text":" tells the model what the chunk is about even when the chunk itself uses pronouns. This is often the highest-value 8 tokens in the header."}]},{"t":"p","runs":[{"text":"Fields that usually fail:"}]},{"t":"ul","items":[[{"text":"Internal UUIDs.","b":true},{"text":" 15 to 20 tokens each, meaningless to the model, and the citation handle already does the job. Keep the mapping in your code, not in the window."}],[{"text":"The similarity score.","b":true},{"text":" Tempting and quietly harmful: it invites the model to treat rank as truth, and a 0.82 next to a passage reads like a confidence claim about its content, which it is not."}],[{"text":"Ingestion timestamps, embedding model versions, chunk indices.","b":true},{"text":" Debugging data. Log them; do not send them."}],[{"text":"Full URLs.","b":true},{"text":" A long URL is 20 to 40 tokens. If the user needs a link, attach it in your application layer after the model has cited "},{"text":"[7]","code":true},{"text":", which costs nothing."}]]},{"t":"h2","id":"format-compactly-and-consistently","runs":[{"text":"Format compactly, and consistently"}]},{"t":"p","runs":[{"text":"Within a header, dense is better than pretty:"}]},{"t":"code","lang":"","label":"Text","text":"[7] Refund policy · Sale items · 2026-03-14\nCustomers may request a refund within 30 days of delivery..."},{"t":"p","runs":[{"text":"Three things matter more than the exact style. Use the "},{"text":"same shape for every passage","b":true},{"text":", so the model learns the pattern within the request. Put the header "},{"text":"immediately before","b":true},{"text":" its text with no blank line drift. And make the "},{"text":"boundary between passages unmistakable","b":true},{"text":": the delimiters lesson later covers why a consistent marker beats an elegant one."}]},{"t":"h2","id":"the-metadata-that-never-enters-the-window","runs":[{"text":"The metadata that never enters the window"}]},{"t":"p","runs":[{"text":"A useful discipline: most metadata exists to be filtered on, not read. Tenant, ACL groups, language, document type, source system, permissions version. All of it belongs in the index for the pre-filter, and none of it belongs in the context."}]},{"t":"p","runs":[{"text":"Sending "},{"text":"tenant_id: acme-corp","code":true},{"text":" to the model achieves nothing except telling a prompt-injection attempt what your tenant ids look like. Filter on it; do not print it."}]},{"t":"h2","id":"where-the-header-earns-the-most","runs":[{"text":"Where the header earns the most"}]},{"t":"p","runs":[{"text":"One case is worth calling out because it changes results more than the others: "},{"text":"chunks that do not stand alone.","b":true}]},{"t":"p","runs":[{"text":"A chunk from the middle of a long page begins “This does not apply to items purchased during a promotional period.” What is "},{"text":"this","i":true},{"text":"? Without the section path, the model does not know, and neither would a human. With "},{"text":"Refund policy > Sale items","code":true},{"text":" in front of it, the sentence becomes usable."}]},{"t":"p","runs":[{"text":"That is the same problem the chunking lesson solves by carrying context down into the chunk. A section-path header is the cheap version, applied at retrieval time and costing eight tokens; a generated contextual sentence is the expensive version, applied at ingestion. The next module covers when the expensive version is worth it."}]},{"t":"h2","id":"measure-the-header-like-anything-else","runs":[{"text":"Measure the header like anything else"}]},{"t":"p","runs":[{"text":"Headers are a cheap experiment because they are pure assembly: no re-indexing, no re-embedding. Run your evaluation set with the full header, then with only the citation handle, then with handle plus section path."}]},{"t":"p","runs":[{"text":"Teams commonly find that the handle and the section path carry almost all the benefit and the rest is decoration. Which is a 30-token-per-chunk saving, discovered in an hour, that nobody would have believed without the numbers."}]}],"check":{"question":[{"text":"A team includes the similarity score in each passage header, hoping the model will weight better-matching passages more heavily. What is the most likely effect?"}],"options":[{"text":[{"text":"It has no effect, since numbers in a header are ignored by the tokeniser as metadata."}],"correct":false,"tempting":[{"text":"Assumes a distinction the model does not make; a header is ordinary text and is attended to like any other."}]},{"text":[{"text":"It improves ordering robustness, because the model can recover the intended ranking if passages arrive out of order."}],"correct":false,"tempting":[{"text":"Assumes the model needs the ranking recovered when position already carries it, and ignores what the number actually claims."}]},{"text":[{"text":"The model reads the score as a confidence claim about the passage’s truth, though it only measures embedding proximity."}],"correct":true,"tempting":null},{"text":[{"text":"It breaks prefix caching, because scores differ on every request."}],"correct":false,"tempting":[{"text":"Names a real property of variable content, but retrieved passages are already variable and sit below any cached prefix."}]}],"order":[3,2,1,0],"why":null},"prev":{"slug":"freshness-and-as-of-lines","title":"Telling the model when things were true","minutes":8},"next":{"slug":"summarise-or-include","title":"The source or a summary of it","minutes":9}}}