How to write help articles your AI agent can actually answer from
How an AI agent finds answers in your help center, and how to write articles it can use: one question per section, answer first, exact numbers, no contradictions.
On this page
- How does an AI agent find answers in your help articles?
- Nine rules for help content an AI agent can answer from
- Before and after: rewriting a returns article
- What to do with PDFs, videos and things nobody wrote down
- How to keep help content fresh
- Find the gaps from real conversations
- Score an article in two minutes
- Help content audit checklist
Key takeaways
- An AI agent doesn't read your help center from top to bottom. It searches for short passages that match the question by meaning and answers from the best few, so every section has to make sense on its own.
- Give each common question its own article or clearly titled section, and put the answer in the first sentence under the heading.
- Write exact numbers, conditions and names (60 days of delivery, unworn, a prepaid Royal Mail label) instead of pronouns, "see above" or "promptly".
- Keep each fact in one place. When two pages disagree, the agent may quote either one, so fix the content rather than hoping it picks the right page.
- Let real conversations set your writing list: questions handed off for low confidence and well-rated human replies show exactly what's missing.
You’ve pointed an AI agent at your help center and asked it something you know is covered. It handed the chat to a person, or it answered with last year’s returns window. The article was right there.
The problem is rarely the AI. Help articles are written for people, who read from the top, skim, and fill gaps from context. An AI agent does none of that. It pulls out a few short passages that seem to match the question and writes its answer from those alone. This guide explains how that works and how to write for it, with a before-and-after rewrite of a returns article and an audit checklist at the end.
How does an AI agent find answers in your help articles?
Three things follow from that, and they shape every rule in this guide.
The agent sees passages, not pages. If the answer to “who pays return postage?” is split between a paragraph at the top and a note at the bottom, the agent may only see one half. Each section has to stand on its own.
Matching is by meaning, not keywords. “Can I send back boots I’ve had out on a walk?” will find a section headed “Can I return worn boots?” even though the words differ. That’s the good news. The bad news is that a section that never says what it’s about (“It’s free for UK customers”) gives the search very little to hold on to.
The best match wins, even when it’s out of date. Retrieval doesn’t know which page is current. If an old blog post says 30 days and your returns article says 60, both can match, and the agent can only be as right as the passage it picks.
Here’s a Kettlewell Outdoor returns article as an agent sees it: six passages, each scored against the customer’s question. Pick a question to see which passage wins.
Customer asks
kettlewelloutdoor.com · Help centre
Returns and exchanges
- Passage 1 0.62
Returns and exchanges
You can return unworn items within 60 days of delivery for a full refund, and size swaps are free. Worn boots can’t be returned unless they’re faulty.
- Passage 2 0.91
Can I return worn boots?
Boots worn outdoors can’t be returned. If a pair leaks or comes apart, send us a photo within 12 months of delivery and we’ll repair, replace or refund them.
- Passage 3 0.38
How do I send a return from the UK?
Start a return from your order page and we’ll email you a prepaid Royal Mail label. Return postage from the UK is free.
- Passage 4 0.27
Who pays return postage from the EU or US?
You do. Use a tracked service, keep the receipt, and put your KW- order number inside the parcel.
- Passage 5 0.21
When will I get my refund?
Within 5 working days of your parcel reaching our Leeds warehouse, to your original payment method.
- Passage 6 0.33
Can I return a Sock Club delivery?
Yes, if the socks are unworn and within 60 days of delivery. To pause or cancel future pairs, see Managing your Sock Club.
Answer, from the best passage only
✦ Intelligence
Passage 2 scored 0.91. The opening summary came second (0.62). It says the same thing with less detail, so the specific section wins.
✦ Intelligence
Passage 4 scored 0.89. The UK section came second (0.66). If both countries shared one section, the agent could easily have told a German customer postage is free.
✦ Intelligence
Passage 5 scored 0.93. Nothing else came close. A clear heading and a number in the first sentence make for an easy match.
A returns article split into six passages. For the question about returning boots worn on a walk, the passage headed Can I return worn boots scores 0.91 and supplies the answer; for postage from Germany, the EU and US postage passage scores 0.89; for refund timing, the refund passage scores 0.93.
The winning passage isn’t the longest or the most keyword-heavy. It’s the one that asks the customer’s question in its heading and answers it straight away. That’s the structure the rest of this guide recommends.
If you haven’t set up the agent itself yet, start with our guide to setting up an AI agent for customer support. This one is about the content it answers from.
Nine rules for help content an AI agent can answer from
1. One question per article, or per clearly titled section
A long “Everything about orders” page mixes shipping, returns, address changes and gift notes. When it’s split into passages, the boundaries fall wherever the text happens to break, and a passage can end up half about one thing and half about another. Give each common question its own short article, or its own section with a heading that names it.
Headings phrased as questions work especially well because they look like what customers type. “Who pays return postage from the EU or US?” beats “Postage”, and it’s far better than “Other information”.
2. Put the answer in the first sentence
Answer first, then the conditions, then the detail. People skim this way anyway, and it protects the answer from where a passage happens to be cut: if the answer is the fifth sentence of a long section, it may land in a different passage from the heading that gives it context.
Weak: We know returns can be frustrating, so we’ve tried to make the process as simple as possible.
Strong: You can return unworn items within 60 days of delivery for a full refund.
3. Use names, not pointers
Pronouns and pointers lose their meaning when a passage is lifted out of the page. “It’s free”, “see above”, “this option”, “the form below” and “as mentioned earlier” all point at something the agent can’t see.
Repeat the noun, even when it feels clunky: “Return postage from the UK is free.” Name products, plans and pages in full: “the Sock Club”, not “your subscription”; “see Managing your Sock Club”, not “see the relevant page”.
4. State numbers and conditions exactly
Agents are good at repeating what’s written and bad at guessing what you meant. “Within a couple of months” could be 56, 60 or 62 days. “Promptly” isn’t a number at all. “In original condition” leaves the customer, and the AI, unsure whether boots worn once round the garden count.
Write the number, the unit and the condition: “within 60 days of delivery”, “within 5 working days of your parcel reaching our Leeds warehouse”, “unworn”. Put exceptions in the same section as the rule, not in a footnote three screens down, so they travel together into the same passage.
5. Call one thing by one name
If your shop says “Sock Club” on one page, “sock subscription” on another and “monthly plan” on a third, a reader works out they’re the same thing. Retrieval mostly will too, but the agent may then use all three names in one answer, or treat them as different products. Pick one name per thing and use it everywhere. Mention the words customers use once, near the top: “The Sock Club (our sock subscription) can be paused at any time.”
6. Keep each fact in one place
This rule prevents more wrong answers than any other. Delivery times tend to appear on the shipping page, the FAQ, the checkout, a few product pages and a blog post about Christmas cut-offs. Change one and the others quietly go stale, and the agent can quote any of them.
Give each fact a home (delivery times live in “Delivery and tracking”) and have other pages link to it instead of restating it. When you can’t avoid repeating a fact, keep a short list of everywhere it appears so a change reaches all of them. And keep old announcements out of the agent’s training content; they’re the most common source of confident, outdated answers.
7. Date it, and say which version it covers
Show an “Updated” date on every article and change it when the content changes. It tells customers what’s current, and it gives you an easy review rule: anything untouched for a year gets a look.
For software, say which plan or version an article applies to. Tallybook’s guide to connecting a bank account should say whether it covers Starter, Growth or Scale, because a customer on Starter asking “how do I connect my bank?” needs the answer for their plan, not the most detailed one.
8. Use tables for comparisons
Plan comparisons, shipping zones and size charts are where prose fails worst. “EU delivery takes a little longer than the UK, and the US a little longer again” is hard to answer “how long to Ohio?” from. A table isn’t:
| Destination | Delivery time |
|---|---|
| UK | 1–2 working days (free over £50) |
| EU | 3–5 working days |
| US | 5–8 working days |
Keep tables simple: one header row, one fact per cell, no merged cells. Add a plain sentence above the table that names what it shows (“Delivery times from our Leeds warehouse”), so the passage containing it has words to match as well as numbers.
9. Write in your customers’ words
Your team says “RMA”, “SKU” and “fulfilment”. Customers say “send it back”, “the waterproof one” and “when will it arrive”. Use their words in headings and first sentences, and put your internal term in brackets if your team needs it. Your inbox is the best source: search it for how people actually phrase the question before you write the heading.
Before and after: rewriting a returns article
Here’s a returns page of the kind most shops have, and the same policy rewritten for an AI agent (and, not by accident, for people).
On the left, a short returns policy with seven problems marked: a preamble, the phrases a couple of months, original condition, it's free, see above, promptly, and an unnamed link. On the right, the rewrite with a 60-day rule up front and separate sections for UK returns, EU and US postage, refund timing and the Sock Club.
What changed:
- The answer moved to the top. The old first paragraph was friendly and said nothing a customer could act on. The new one states the policy in two sentences.
- Vague words became exact ones. “A couple of months” became “60 days of delivery”, “original condition” became “unworn”, and “promptly” became “5 working days of your parcel reaching our Leeds warehouse”.
- “It’s free” and “see above” are gone. Every section names its subject, so each passage still makes sense on its own.
- UK and international returns were split. In the original they shared one sentence, which is how an agent ends up telling someone in Hamburg that postage is free.
- The link names its page. “See the relevant page” became “see Managing your Sock Club”, which a customer, and the agent, can follow.
- It has a date. Anyone reviewing the article can see when it last changed.
Most of the work is deleting padding and replacing soft words with hard ones. You can usually rewrite an article like this in fifteen minutes.
What to do with PDFs, videos and things nobody wrote down
PDFs and documents
A PDF is a fine source as long as its text can be extracted. A scan is a picture of text, so always upload the original document rather than a scan or a photo of a printout. Before you add one:
- Check it has real headings, not just bold lines, so it splits into sensible passages.
- Cut cover pages and long boilerplate if you can. They add passages that match nothing useful.
- If the same content also lives on a web page, use one or the other. Two copies drift apart.
Product manuals, care instructions and spec sheets make good PDF sources. Brochures full of marketing claims don’t, because the agent will repeat “the toughest boots in Britain” as if it were a fact.
Videos
Agents learn from video through its transcript or caption file, and speech makes looser text than writing. “So you just work the wax in like that, and then, yeah, leave it overnight” works on screen and reads poorly as a source. Check that the captions spell your product names correctly (Fellside is a likely casualty of auto-captions), and give each important video a short written article with the key steps and numbers. The video stays useful for people. The article is what the agent quotes.
Q&A pairs for what lives in people’s heads
Every team has facts that were never written down: whether you ship to PO boxes, whether the Ridgeline Rain Shell can go in the washing machine, whether you can add a gift note. They live in your team’s replies, so the agent can’t find them.
Q&A pairs are the quickest fix. Write the question the way customers ask it, then a one- or two-sentence answer:
Q: Do you ship to PO boxes?
A: Yes, within the UK. We can’t deliver to PO boxes in the EU or US.
Keep each pair to one fact. If an answer grows past a short paragraph, it wants to be an article.
How to keep help content fresh
Content goes stale quietly. A price changes, a courier changes, a plan gets renamed, and the help article keeps telling every customer who asks the old version. Three habits stop it.
Change the article the same day as the policy. Make “update the help content” part of the change itself, not a follow-up task. Search your help center and your Q&A pairs for every mention of the old fact before you call it done.
Give each article an owner and a review date. Shipping and returns belong to whoever runs fulfilment; plan comparisons to whoever owns pricing. Review your 20 most-used articles every quarter, and anything with an “Updated” date more than a year old.
Re-test after the agent re-syncs. If your agent learns from a crawl of your site, it only knows what the site said the last time it was crawled. Turn on scheduled refresh so changes are picked up, then run the questions affected by the change through your test playground and check the answers and their sources.
Find the gaps from real conversations
You can’t guess every question in advance. Your customers will tell you what’s missing, if you look in three places each week:
- Handoffs for low confidence. When the agent hands off because nothing matched well, the answer is usually missing from your content, or worded so differently that the search didn’t connect them. Group these questions, count them, and write for the most frequent first.
- Good human replies. When a teammate answers a question well and the customer rates the chat highly, that reply is a draft Q&A pair or article. Turn it into one before the next customer asks.
- Wrong answers and their sources. When the agent gets something wrong, look at the source it cited. It points you straight to the stale or contradictory page.
A knowledge gaps panel listing four unanswered questions by frequency, led by Do you ship to PO boxes with 23 asks, beside a suggested knowledge entry about pausing a Sock Club, drawn from a chat rated 5 out of 5, with an Approve button.
Score an article in two minutes
Before a full rewrite, score your most-used articles to see where to start. Give each row 0, 1 or 2 points.
| Check | 0 points | 1 point | 2 points |
|---|---|---|---|
| Focus | Several topics, no clear question | One topic, generic heading | One question, heading in the customer’s words |
| First sentence | Preamble or background | Answer somewhere in the first paragraph | The first sentence is the answer |
| Numbers and conditions | Vague (“soon”, “a month”) | Some exact, some vague | All exact, with exceptions in the same section |
| Stands alone | Relies on “it”, “this” or “see above” | A few pointers | Every section names its subject |
| Consistency | Contradicts another page | Repeats a fact that lives elsewhere | One home for each fact; other pages link here |
| Freshness | No date | Dated, over a year old | Dated and reviewed this year |
As a rough guide: 10 to 12 is ready, 6 to 9 needs a rewrite pass, and under 6 is worth rewriting before the agent relies on it. Start with the articles behind your most-asked questions, because those are the passages the agent retrieves most often. If you sell online, our guide to live chat for ecommerce covers which pre-sale and order questions usually top that list.
Help content audit checklist
AI-ready help content audit
0 of 14 done
None of this is writing for robots. Every rule here also makes articles faster for people to skim, which is why the rewrite above reads better as well as retrieving better. The agent just makes the cost of a vague article visible, because it repeats that vagueness to every customer who asks.