Course resource
Knowledge File Optimizer
How to prepare documents so a custom assistant actually finds the right passage.
How retrieval works, briefly
When you upload files to an assistant, they are split into chunks and indexed. At question time, the system finds the chunks that best match your question and puts those — not the whole document — into the model's context.
Everything below follows from that one fact. If the right chunk is not retrieved, the assistant answers as if the information does not exist, confidently.
The seven rules
1. One topic per file. A 40-page handbook covering pricing, refunds, shipping and warranties returns muddled chunks. Four files return clean ones. Split aggressively.
2. Put a summary at the top of every file.
SUMMARY: Refund policy for retail customers, effective March 2026.
Covers eligibility, timelines, exceptions, and the escalation path.
Does NOT cover wholesale or partner accounts — see wholesale-terms.md.
This chunk is often what gets matched, and it tells the model whether to keep reading. The "does NOT cover" line is what stops it answering wholesale questions from retail policy.
3. Name files descriptively.
2026-03-refund-policy-retail.md beats policy_final_v3.pdf. Filenames frequently appear in retrieval context.
4. Use headings, and make them questions where you can.
## How long does a refund take? matches a user's phrasing better than ## Processing Times. Retrieval is matching text against text.
5. Make each section self-contained. A chunk arrives without its neighbours. A section saying "as described above, this applies within 14 days" is useless in isolation. Repeat the antecedent: "Retail refunds must be requested within 14 days of delivery."
6. Prefer Markdown or plain text. PDFs lose structure; scanned PDFs lose everything unless OCR'd well. Word documents carry formatting noise. Convert before uploading.
7. Strip boilerplate. Page headers, footers, nav menus, cookie notices and repeated legal footers pollute every chunk they land in. Remove them.
Kill contradictions
The most damaging problem, and the least visible.
If two files say different things, the assistant will answer from whichever chunk was retrieved — effectively at random. It will not tell you there was a conflict.
- Search your files for the same policy stated twice
- Delete superseded versions rather than archiving them in the same folder
- Where two things are both true but in different circumstances, say so explicitly in both places
- Date anything time-sensitive inside the file
Dates belong in the content
EFFECTIVE: 1 March 2026
SUPERSEDES: the policy dated 12 August 2025
REVIEW BY: 1 March 2027
Then instruct the assistant: "Every knowledge file carries an EFFECTIVE date. If a user asks about something after your files' dates, say your information may be out of date."
Tell the instructions about the files
Uploading files is not enough. The instructions must say what they are and when to use them:
KNOWLEDGE FILES
- refund-policy-retail.md — retail refunds only
- wholesale-terms.md — partner and wholesale accounts
- shipping-zones.md — delivery times and costs by region
Always check the relevant file before answering. Quote the specific clause
you relied on. If the files do not cover the question, say so — do not
answer from general knowledge.
That last sentence is the difference between an assistant that answers from your policy and one that invents a plausible industry-standard policy.
Testing retrieval
For each file, ask three questions: one it clearly answers, one it partially answers, one it does not answer at all.
| Question | Expected | What happened | Fix |
|---|---|---|---|
The third question is the important one. If the assistant answers a question your files do not cover, retrieval is not the problem — your instructions are missing the "say so" rule.
Size
- Many small, focused files beat a few large ones.
- A file under a few hundred words may not chunk usefully — merge related short files.
- A file over ~20 pages should almost always be split.
- More files is not automatically better: irrelevant files compete for retrieval.
Preparation checklist
- Converted to Markdown or plain text
- One topic per file
- Descriptive filename with a date where relevant
- SUMMARY block at the top, including what it does not cover
- Question-shaped headings
- Sections self-contained, no dangling "as described above"
- Boilerplate stripped
- No contradictions with other files
- EFFECTIVE date inside the content
- Instructions updated to name the file and its scope
- Three-question retrieval test passed
Review cadence
Knowledge files rot silently — the assistant keeps answering, just wrongly.
| File | Last reviewed | Next review | Owner |
|---|---|---|---|