Retrieval settings
When someone sends a message, your bot searches your data sources for the most relevant pieces of content (called documents) and reads them before it answers. These settings control that search. They are in your bot's General settings tab: the toggles for sources are under General settings, the rest under Model settings (advanced).
Settings
| Setting | What it does | Default | Range |
|---|---|---|---|
| Document relevance | How closely a document must match the message before the bot is given it. Higher = only very relevant documents; lower = more, looser matches. | 0.75 | 0.25–0.9 (0.25–0.75 on bots using a newer embedding model) |
| Max context documents | The maximum number of documents given to the bot for each message. 0 turns knowledge retrieval off. | 4 (6 for bots created from the dashboard form) | 0–12 |
| Max context size (base tokens) | The token budget for each reply's prompt, knowledge and conversation history. Documents that don't fit are left out, then the oldest messages. | 64,000 for new bots (or the model's maximum, if smaller) | 1,024 up to the model's context window |
| Enhanced knowledge retrieval | Before searching, rewrites the latest message into a standalone question using the conversation so far. Makes follow-up questions ("how much does it cost?") find the right content. Uses extra message tokens. | Off | On / off |
| Include sources for responses | Shows links to the pages an answer actually used, numbered, with matching numbers in the reply showing where each one was used. Pages that were retrieved but not used aren't listed. Only web data sources are shown. | Off | On / off |
| Document character limit | The maximum size of each document when your content is split up during syncing. | 2,000 | 1,000–4,000 |
When to change them
The bot says it doesn't know, but the answer is in your content
- Search for the question with Document Search and use Where's my page? to see why the page isn't used: not synced, no text found, below the relevance threshold, or outranked by other documents.
- Lower Document relevance a little (for example from 0.75 to 0.6). Short content, such as product feeds or one-line FAQ entries, often needs 0.5.
- Raise Max context documents to 8–10 so more content reaches the bot.
- Turn on Enhanced knowledge retrieval if it fails mainly on follow-up questions.
The bot uses irrelevant content or drifts off topic
Raise Document relevance so only close matches are used, and tighten your instructions.
Replies use too many tokens
Lower Max context documents or Max context size (base tokens). Keep Max context size above about 2,560: below that, the settings warn "This is quite low & could mean your bot won't be given any context documents."
Answers are cut off mid-topic or miss surrounding detail
Raise Document character limit so each document holds more text. The new size applies the next time your data sources sync; see keep it up to date.
Test what your bot finds
Document Search shows which documents your bot would read for a question, so you can check your knowledge is actually being found before changing anything. It's at the bottom of your bot's Data sources tab, and on each data source's View documents tab (searching only that source).
- Open Document Search and type a question the way a visitor would ask it, for example "do you sell gift cards?".
- Click Search Documents. The top 50 matches are listed by relevance, each with the page or file it came from.
- Read the list against the two lines in it:
- Max context documents: documents above this line would be given to your bot (shown in green).
- Relevance threshold: documents below this line are near misses, too far from the question to be used.
- Click a result to read it in full. Use Previous and Next (or the arrow keys) to step through the results, Open page to see the original, and As the bot sees it for the exact text your bot is given.
- Move the Document relevance and Max context documents sliders to see which documents would be used with other values, without searching again. Click Save Settings to apply them to your bot.
Where's my page?
If a page or file you expected isn't in the results, paste its URL, title or file name into Where's my page? and click Check. It tells you where that page ranks for your question and why it would or wouldn't be used:
| Result | What to do |
|---|---|
| Not in your bot's knowledge | Add the page, or check the URL or name. |
| Not synced yet, Still syncing or Failed to sync | Sync the data source, or fix the sync error. See keep it up to date. |
| No content found | The page synced but no text was found. Check it has readable text and, for websites, the scrape settings. |
| Below the relevance threshold | Lower Document relevance, or add content that answers the question more directly. |
| Ranked #N, outside the top N | It's relevant but other documents rank higher. Raise Max context documents, or check what's outranking it. |
| Would be used | The page reaches your bot. If answers are still wrong, check your instructions. |
Document Search checks the question exactly as typed. In a conversation, Enhanced knowledge retrieval may rewrite a follow-up question first, and documents can still be left out if Max context size (base tokens) runs out.
Change a setting
- Open your bot and go to the General settings tab.
- For sources, use the Include sources for responses toggle under General settings. For everything else, scroll to Model settings (advanced).
- Adjust the setting.
- Click Save changes.
- Ask the questions that were failing and check the answers. If Include sources for responses is on, check the cited pages are the right ones.
You can also change these settings from an AI assistant with the update_bot MCP tool (documentRelevance, maxContextAmount, maxContextSize, enhancedRetrieval, includeSources, documentChunkSize).
Related
- Improve your bot's answers
Fix a bot that says "I don't know", gives wrong or made-up answers, goes off-topic, rambles, forgets context or replies in the wrong language.
- Bot settings reference
Every setting on your bot's General settings tab - what it does, its default and range, and which plans include it.
- Structure your content for better answers
Split data sources sensibly, pick the right CSS selectors for your CMS, and write content your bot can find and quote accurately.
Last updated