How to write an AI agent knowledge base that actually gets used

Most company knowledge bases are written for a human who will skim them once during onboarding and never open them again. That reader tolerates vagueness, infers what you meant, and asks a colleague when stuck.

An AI agent has none of those abilities. It reads every word, takes each one literally, and has nobody to ask. The same document that worked fine for people will produce confident, wrong answers.

The good news is that writing for an agent is easier than writing for people. It just has different rules.

Write facts, not orientation

Human documentation spends its first paragraphs explaining context. An agent does not need to be eased in — it needs the fact.

Instead of: “Our returns process is designed to be as smooth as possible for customers, and we try to be flexible where we can.”

Write: “Returns are accepted within 30 days of delivery, in original packaging, with proof of purchase. Sale items are final.”

The second version can be quoted to a customer. The first cannot be quoted to anyone.

A useful test: read a paragraph and ask “could the agent reply with exactly this?” If not, it is orientation, and orientation is what produces improvisation.

Be explicit about the edges

The questions that cause trouble are never the middle of the policy. They are the edges: the item bought on sale and returned at day 29, the booking cancelled two hours out, the customer in a country you do not ship to.

A human reading your policy fills those gaps with judgement. An agent fills them with whatever sounds plausible — which is the failure mode you must design out.

So write the edges down, and write the ones you do not cover as explicit non-answers:

“We do not currently ship outside the EU. If a customer asks about shipping elsewhere, do not quote a price or a timeframe — escalate.”

An instruction to escalate is knowledge. It is often the most valuable line in the document.

One fact, one place

If your opening hours appear in four documents, three of them are wrong within a year. The agent will find all four and answer from whichever it happens to retrieve.

Pick one home for each fact. Everything else references it. This is the single biggest cause of an agent contradicting itself, and it is entirely self-inflicted.

Structure it the way questions arrive

Internal documents are organised by department, because that is who maintains them. Customers do not ask departmental questions.

Organise by intent instead — the same intents you would get from tagging a hundred real conversations. “Delivery times”, “returns”, “sizing”, “booking changes”, “payment methods”. Each one short enough to read whole.

If you have not done the tagging exercise, do it before you write anything. It takes an hour and it tells you exactly which twelve documents to write, in what order.

Put the exact words your customers use in the text

An agent matches on meaning, but meaning is easier to find when the vocabulary lines up. If your customers say “swap” and your policy says “exchange”, say both once:

“Exchanges (sometimes called swaps) are handled as a return followed by a new order.”

This costs one clause and removes a whole class of near-misses.

Say what you are not sure about

Documents written for humans project confidence. Documents written for agents should mark uncertainty, because an agent cannot hear your tone.

If a policy is under review, say so and say what to do meanwhile. If a price changes seasonally, say that rather than stating this season’s price as though it were permanent.

Maintain it from the failures, not the calendar

A quarterly review of the knowledge base is theatre. Nobody remembers what changed, and nothing gets removed.

The maintenance loop that works is the one driven by the agent’s own failures. Every week, look at the conversations it escalated because it did not know something, and at anything it answered that a person later corrected. Each of those is either a missing fact or an ambiguous one, and fixing it takes minutes because you know exactly which sentence to change.

That list is also the honest measure of whether the knowledge base is any good: it should get shorter.

A starting checklist

• Tag 100 recent conversations by intent; write the top 12 intents first
• One document per intent, each answerable in a paragraph
• Every fact in exactly one place
• Edge cases written down, including the ones that escalate
• Customer vocabulary included alongside internal terms
• A weekly pass over what the agent could not answer

The one rule that matters most

Whatever else you do, insist that the agent answers only from what you gave it. An agent that fills gaps is not a knowledge base problem you can write your way out of — a document cannot anticipate everything, and it should not have to. The correct behaviour at the edge of what it knows is to hand over, not to guess.

---

Fellix’s agent answers from the business info, FAQs and documents you upload — and nothing else. See how you brief it.