Skip to main content
Knowledge Bases

Tune Retrieval: Results per Question and Match Threshold

Use Results per question and Match threshold to control how much your agent finds in a knowledge base, and what to change when it misses or invents answers.

Written By voiceaiwrapper

Last updated 26 days ago

When an agent looks something up in a knowledge base, it gets back a handful of matching passages to answer from. Two settings decide what comes back: how many passages, and how close a passage has to be to the question before it counts. The defaults suit most knowledge bases. Change them when your agent misses answers it should find, or picks up things it shouldn't.

Applies to: VAW Native Pods. For Vapi, Retell AI and ElevenLabs, see Provider Knowledge Bases and Tools in VoiceAIWrapper.

Before you start

When these settings apply

Retrieval settings only matter when the agent looks things up. That happens when an agent's answering mode is Look things up when asked, or Automatic on a knowledge base that's too large to give the agent in full. The size limit is shared by all the knowledge bases attached to one agent, so an Automatic knowledge base can also be looked up because the agent's other knowledge bases already fill the limit.

If the agent is given the whole knowledge base (Give the agent everything, or Automatic on a small knowledge base), it reads every document on every call and these settings have no effect. See Attach Knowledge to Agents and Choose an Answering Mode.

Change the settings

  1. In the sidebar of your VAW Native Pod, open Knowledge Base and click the knowledge base.
  2. Open the Settings tab.
  3. Under How much to look up, drag the sliders:
    • Results per question: from 1 to 20. Default 4.
    • Match threshold: from 0% to 100%. Default 40%.
  4. Click Save. You'll see "Knowledge base updated".

Changes apply to the next call as soon as they're saved. Calls already in progress keep the settings they started with.

Knowledge Base β†’ open a knowledge base β†’ Settings tab, showing the Name and Description fields, the How much to look up heading, the Results per question (4) slider, the Match threshold (40%) slider with their help text, the blue sync note, and the Save button.

What each setting does

SettingWhat it controlsRaise it whenLower it when
Results per questionThe most passages handed to the agent for one question.Answers need facts from several places, such as comparing two plans.The agent rambles or mixes up details from unrelated passages.
Match thresholdHow close a passage has to be to the question before it counts.The agent answers with things unrelated to the question.The agent says it doesn't know, or guesses, when the answer is in your documents.

Results per question is a maximum. If only two passages qualify, the agent gets two.

Match threshold works like a minimum score. Each passage gets a match score for the question. Passages below the threshold are left out. A lower threshold finds more but risks irrelevant answers. A higher one is stricter but can miss answers worded differently from the question.

Two things can let a passage through even when its score is below the threshold:

  • A keyword match. If a distinctive word from the question, such as a product code or a name, appears in the passage, it counts.
  • A clear closest match. If nothing reaches the threshold, the best passage still counts when it's within 10 percentage points of the threshold and clearly ahead of the next one.

The Test tab shows which of these applied to each result. See Test Your Knowledge Base.

Fix common problems

Always test before and after a change, using the same questions.

The agent misses answers that are in your documents

  1. Open the Test tab and ask the question the agent missed.
  2. If the right passage appears under "Closest results, below the … floor" with the label below the floor, lower Match threshold a little (for example from 40% to 35%), save, and test again. If it appears there with a label such as matched by meaning instead, it did qualify but was cut by the Results per question limit, so raise Results per question.
  3. If the right passage doesn't appear at all, the wording is the problem, not the threshold. Add a short FAQ entry with Paste text that uses your callers' words. See Add and Edit Pasted Text.

The agent gives answers that don't fit the question

  1. Ask the question on the Test tab and look at what comes back.
  2. If unrelated passages are in the results, raise Match threshold a few points, or lower Results per question.
  3. Save and test again.

The agent answers only part of a question

Raise Results per question (for example from 4 to 6) so facts from more than one document can come back together.

Change one setting at a time, in small steps. Large jumps make it hard to tell which change helped.

Frequently asked questions

When one agent looks things up in several knowledge bases at once, the most generous settings among them are used for that agent: the highest Results per question and the lowest Match threshold. Adding a second knowledge base never makes the first one return less.

The Test tab uses the saved settings. Click Save on the Settings tab first, then run the test again.

No. At 0% almost every passage qualifies, so the agent always receives your top passages even when none of them answers the question. That's when agents start answering confidently with the wrong information.

Only if you let them. Client permissions on VAW Native workspaces control whether a client can see and change a knowledge base's settings. See Set Client Permissions on VAW Native Workspaces.