How retrieval works
How a customer's question finds the right chunks of your knowledge, how to read the retrieval tester, and how to fix an agent that says it doesn't know.
Your agent never reads a whole knowledge base. For each question it searches the chunks of every knowledge base connected to it and reads only the best few. When an answer is wrong or missing, the cause is almost always in that search step, and you can see it with the Retrieval tester.
This page explains the search, the tester, and a checklist for when the agent says it doesn't know. Anyone in the workspace can use the tester, including Members.
How content becomes chunks #
Every ingested source (websites, files, text, and API responses you ingest) is split the same way:
- Into chunks of about 1,600 characters, cut at headings and sentence boundaries rather than mid-sentence.
- Each chunk repeats the last 200 characters of the one before it, so a fact that straddles a boundary isn't lost.
- Fragments under 80 characters are dropped. One source produces at most 1,500 chunks.
- Each chunk carries a short context: the heading trail it sits under (Support › Warranty › Washing machines). For files, pasted text and API responses, a one-line description of the whole document is added too. The context is used for search only. The chunk text the agent reads is your content, unchanged.
The console counts these as chunks everywhere: on each card, in the header and on each source row.
What happens to a question #
Each time a customer writes on web chat or WhatsApp, before the agent answers:
- 1
Understand follow-ups
A short follow-up such as "and for that one?" means nothing on its own. When a question is short or points back at something said earlier, it is rewritten into a standalone question using the conversation so far. The search uses both versions.
- 2
Search by meaning and by keyword
Two searches run over every connected knowledge base at once:
- Meaning search finds chunks that say the same thing in different words. "When will my order ship?" finds "orders are dispatched within 48 hours". Matches that are much weaker than the best one are dropped rather than padded in.
- Keyword search finds chunks that contain the question's rarest words exactly. This is what finds model numbers, SR numbers, part codes and product names, which meaning search can miss.
- 3
Combine the two
The two result lists are merged into one ranking. A chunk that ranks well in both rises to the top. Near-identical chunks, such as the overlap between neighbouring chunks or the same page in two knowledge bases, are collapsed into one.
- 4
Re-rank and keep the best
On chat, a ranking model re-reads the top candidates against the question and puts them in final order. The agent receives up to 10 chunks. If the ranking step is slow or unavailable, the combined order is used instead, so the answer is never held up.
The agent then answers from those chunks under its grounding policy. With the default policy, a question that nothing covers gets an honest "I don't have that" and a way to reach your team, not a guess. See Agents.
On phone calls #
Phone agents work differently, because every extra step is silence on the line:
- A fact sheet. Each connected knowledge base is condensed into a compact fact sheet the agent keeps in mind for the whole call. Common questions (hours, prices, policies) are answered from it with no search at all. It is rebuilt automatically whenever a source finishes syncing.
- A search tool for the rest. When the fact sheet doesn't cover something, the agent searches. It is the same meaning-plus-keyword search, without the re-ranking step, and it returns up to 8 chunks.
That is why a phone agent answers common questions faster than the same question takes on chat, and why a large knowledge base still answers everyday questions instantly.
Live tools are separate #
Live API sources and MCP servers aren't searched. They are tools the agent decides to call, such as check_service_request, when a question needs live data. A knowledge base made only of live tools has nothing to search, and the tester will find nothing in it. See Tools and actions.
The retrieval tester #
Every knowledge base has a Retrieval tester under Connected agents. Type a question the way a customer would and press Enter. It runs the same search a chat agent runs, on this knowledge base only, and shows the top results without involving the model at all.
The tester shows up to 6 results. Each one has:
| Badge or line | What it tells you |
|---|---|
| Title or address | Which source the chunk came from: a page title, a file name, or a text source's title. It sits to the left of the badges, and in the narrow tester panel the badges often leave it no room, so it can be cut off entirely. The Context: line usually tells you the source too. |
dense 0.76 |
How close the chunk's meaning is to the question, from 0 to 1. Higher is closer. |
keyword 6.41 |
How strongly the chunk matches the question's words. Absent when it shares no meaningful words. Higher is stronger, with no fixed maximum. |
fused #2 |
The chunk's rank after meaning and keyword results were combined. |
reranked #1 |
Its final rank after the ranking model re-read it. This is the order the agent sees. |
v2 |
The chunk format version. Chunks from sources added or re-synced recently are the current version. |
| Context: | The heading trail and description stored with the chunk to help search. |
| The text | The first lines of the chunk exactly as the agent will read it. |
If nothing qualifies, the tester says Nothing relevant found — the agent would say it doesn't know.
The tester searches one knowledge base. An agent searches all of its connected knowledge bases together, so it can find a chunk the tester on this page doesn't show. It also doesn't rewrite follow-up questions, so test the standalone form: "Is the washing machine drum covered after two years?", not "and the drum?".
Reading a result: content or instructions? #
The tester separates two failures that look identical from the outside.
| The tester shows | The problem is | Fix it in |
|---|---|---|
| Nothing, or only loosely related chunks | Content. The fact isn't in this knowledge base, or isn't written in a way that can be found. | The knowledge base: add or rewrite a source. |
| The right chunk near the top, but the agent still answered badly | Instructions. The agent found the fact and didn't use it well. | The agent's purpose, instructions and grounding policy. See Agents. |
| The right chunk, but below several wrong ones | Competition. Other chunks look more relevant. | Make the right chunk more specific, or remove the noise. See below. |
Getting good answers #
Write chunks that answer one question #
Content that retrieves well has a clear heading and a complete answer under it, in sentences.
- Tables lose their meaning when flattened. A matrix of regions against weights reads well to a person and poorly as a line of text. Rewrite the most-asked rows as a text source: "Delivery to Mumbai for orders under 5 kg takes 2 to 3 working days."
- Text inside images on a web page is not read. A price card exported as a picture on your website is invisible to the crawler. An image uploaded as a file is read.
- Content that needs a click to load may be missing. Pages are rendered like a browser, but an accordion that fetches its answer on click may still be empty when read. Check with the tester.
- One enormous page turns into many similar chunks. Split a 20,000-word policy, or add a short text source with the ten facts customers actually ask about.
Say the exceptions out loud #
Your published pages describe the policy. Your team knows the exceptions, and customers ask about the exceptions. Write a text source for each one: "Machines used commercially, in laundries, PGs or hostels, get 1 year of warranty on all parts." If no source says it, no amount of searching will find it.
Use exact words where customers do #
Keyword search rewards the words customers type. If they say "AMC" and your pages only say "annual maintenance contract", meaning search will usually bridge it, but putting both in a heading makes it certain. The same goes for model numbers and plan names: write them out the way customers do.
Keep the noise out #
Every chunk competes. A knowledge base holding your help centre answers better than the same knowledge base plus your press releases, careers pages and blog. Crawl the parts that answer questions, and keep marketing content out. The crawler reads up to 60 pages per website source and doesn't stay under a starting path, so a focused subdomain or uploaded documents give you the most control. See Website.
When the agent says it doesn't know #
Work down this list. Most cases end in the first four steps.
- 1
Is the knowledge base connected to this agent?
Open the knowledge base and check Connected agents. An agent only searches knowledge bases connected to it.
- 2
Did the source finish?
Every source that should hold the answer should show
Synced ✓with a sensible chunk count. AFailedsource, or one stuck atCrawling, holds nothing new. See Source status. - 3
Does the tester find it?
Ask the question in the Retrieval tester, in the customer's words and in standalone form. If the right chunk isn't in the results, it's a content problem. Go to the next step. If it is, skip to the last step.
- 4
Is the fact in the content at all?
Search the source yourself. For a website, open the page in a browser: is the fact written as text on the page, or in an image, a PDF behind a link, or a tab that loads on click? Was the page among the 60 the crawler read? If not, add the page's content as a text source or upload the document.
- 5
Is it buried?
If the chunk appears but low, rewrite it so it answers the question directly, give it a clear heading, and remove sources that only add noise. Then click Re-sync on a website or API source and test again.
- 6
Is it the agent, not the knowledge?
If the tester shows the right chunk at the top and the agent still answers wrongly, look at the agent's instructions and grounding policy, and test in the agent's chat. Instructions that tell it to be brief or to always redirect can stop it using a fact it found. See Agents and Testing and publishing.
Test before you connect
Connecting a knowledge base to a live agent takes effect on the next message. Run the questions your team gets most often through the tester first, then through the agent's test chat, and connect it when both look right.
Where to go next #
Build the knowledge
Knowledge bases: sources, schedules, credentials and connecting agents.
Test the whole agent
Testing and publishing: what to try before customers do.
Live data and actions
Tools and actions: when the answer needs your systems, not your documents.