Writing help docs that an AI agent can retrieve

When a support agent gives a bad answer, the cause is more often the document than the model. LayBuild splits your docs at headings and paragraphs, embeds each piece with its heading path, and puts at most four passages of up to 1,000 characters each into the prompt. A doc written for a human reading top to bottom can fail in that setting even when every fact in it is correct. These are the writing rules that follow from how the system actually works.

What happens to a document when you add it

Uploaded files (PDF, Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, plain text and markdown, up to 10 MB by default) are converted to markdown. Web pages are fetched and converted from HTML to markdown. Then the markdown is split into sections at headings, packed into chunks of about 1,400 characters, and split again into smaller chunks of about 600 characters. The chunking post has the details.

URL ingestion is narrower than people expect. LayBuild fetches only the URLs you list. It does not follow links, crawl a site or read a sitemap. It strips navigation, headers, footers, sidebars, asides and cookie banners, prefers the page's <main> element when there is one, and keeps at most 50,000 characters per page. It does a plain HTTP fetch and does not run JavaScript, so a help center that renders its articles client-side can come back nearly empty. Check what was ingested before you rely on it. A URL that is already in your knowledge base is skipped when you add it again, so to refresh a changed page, delete its document and add the URL again. Plans cap the number of documents and URLs; see /pricing.

Put one question under one heading

The splitter starts a new section at every # to #### heading, and each chunk is embedded with the document title and heading path in front of it. So headings do two jobs: they set chunk boundaries, and their words get attached to every chunk underneath.

Write headings the way customers ask. "How do I cancel my subscription?" matches the question "how to cancel" in both the keyword and vector legs. "Subscription lifecycle management" matches neither. One question per section keeps the answer inside one chunk instead of spread across three.

Use real markdown headings. A bold line that looks like a heading is not one, and a PDF exported without heading styles arrives as a single long section. Headings below #### do not start new sections.

Make each section stand alone

A retrieved passage reaches the model without its neighbours. Anything that depends on context from elsewhere in the page breaks:

• "As mentioned above" and "see the previous step" point to text the model cannot see.
• Pronouns without a noun in the same section ("it renews automatically") leave the model guessing what "it" is.
• Conditions in a separate paragraph from the rule they modify can end up in a different chunk.

Repeat the noun. Name the plan, product or setting in each section even if the heading already says it. Keep a rule and its exceptions in the same paragraph. This reads slightly repetitive to a human and much better to a retriever.

Put the answer first

Each passage is cut to 1,000 characters in the prompt, and a full-size chunk is around 1,400. If the answer is the last sentence of a long section, it may not reach the model even when the right chunk is retrieved. Lead with the answer ("Yes, you can downgrade at any time; the change applies at the next billing date.") and follow with the explanation. Short sections, around a few paragraphs, fit whole. Open each document with a two or three sentence summary too: LayBuild also stores one vector for each whole document, and for a long document that vector mostly reflects the opening.

Tables, code and lists

The splitter packs paragraphs, and a paragraph is anything between blank lines. A markdown table with no blank lines inside is one paragraph. If it is too large for a chunk, it gets split at periods, which cuts rows away from their column headers. Keep tables small and topic-specific. For the facts customers ask about most, also write them as sentences ("The Pro plan includes 15 seats"), because a sentence survives splitting and a table row does not.

For error messages, paste the exact text customers see, including codes. The full-text leg matches exact tokens like E1042, and the vector leg does poorly on them. Then explain in plain words what the error means and what to do.

Lists are fine. Keep the sentence that introduces a list in the same paragraph block as the list, so a chunk never contains bullets with no subject.

Use your customers' words

Full-text search uses English stemming, so "refunds" matches "refund". It does not know that "money back" means "refund". The vector leg may bridge that gap, but don't depend on it. If your transcripts show customers say "money back", "invoice" or "bill" where your docs say "refund", "statement" or "charge", add their word to the text or the heading. Your conversation history is the best source for this vocabulary.

Q&A pairs and pinned documents: use them sparingly

Manual Q&A pairs are the most direct way to control an answer. If a customer's question matches a stored question exactly, or nearly (at least 80% of the shorter question's stemmed words appear in the longer one), LayBuild returns your stored answer without calling the model. Q&A pairs are also searched in every retrieval and rank high when they match. So keep them accurate and short. A wrong Q&A pair is served verbatim.

Pinned documents are always included in the prompt, capped at 4,000 characters per document and 12,000 in total. The ten most recently updated Q&A pairs for the agent are included in that same pinned block. That block and the retrieved passages share one 4,000-character context budget, and the pinned block is counted first. If your pinned content fills the budget, retrieved passages get little or no room. Pin only what is short and relevant to nearly every conversation, like your support hours and plan names. Everything else should be retrieved.

Write in English for now, or plan for weaker retrieval

The default embedding model is English-only and full-text search uses the English configuration. The model is told to reply in the customer's language, but retrieval quality for a question in another language against English docs is weaker, and LayBuild does no translation. If you support other languages, test those questions separately. Our multilingual post covers the options.

A monthly review that finds the bad docs

The fastest way to find weak docs is to read the conversations where the agent gave up. Find the conversations where the agent sent the fixed reply ("I do not have specific information about that in the knowledge base"). For each one, decide whether a doc should have answered it. If one should have, fix the heading, wording or structure using the rules above, then ask the question again. If no doc covers it, write one. Repeat monthly, or after every release that changes the product.

Where to go next

To understand what happens after a passage is retrieved, read how LayBuild limits made-up answers. For keeping content current as your product changes, read keeping an AI support agent's knowledge current.