Telling a refusal you configured from a gap in your material

A visitor asks something your documentation covers and gets a refusal instead of an answer.

In rough order of how often each one turns out to be the answer. Work down rather than across: each carries a way to tell whether it is yours before you change anything.

• 1

  Nothing on that subject is indexed

  Why

  The gate fires when there are no hits at all, or when the best one scores far below the threshold. Nothing reaches the model, so nothing about the wording of the answer or the settings of the model can affect the outcome.

  How to confirm it is this one

  Insights tab, Unanswered questions. Every question refused by the gate appears there with a count, when it was last asked, and a best match percentage. A best match near zero means nothing resembling that subject is in the knowledge base.

  Fix

  Add the material. The unanswered list is ordered by how often each question was asked, so the top of it is the shortest route from where you are to an assistant that answers.

• 2

  It is indexed, but worded nothing like the question

  Why

  Retrieval matches on meaning as well as words, and it is good rather than magic. A page headed Service Level Commitments does answer a question about how fast somebody gets a reply, but it does so at a distance, and the score reflects that distance. Below the threshold the gate fires exactly as if the page were not there.

  How to confirm it is this one

  Same list, different number. A best match in the middle, below your threshold but nowhere near zero, means something on the subject is indexed and the wording is not close enough. Compare the percentage against your setting: Cautious refuses below 50, Balanced below 35, Willing below 22.

  Fix

  Put the visitor's phrasing into the page. A heading worded as the question, with the answer directly under it, moves the score more than any amount of extra prose, because the question is what gets matched against.

• 3

  The caution setting is stricter than the material supports

  Why

  The threshold is the single control deciding whether an assistant would rather stay quiet or have a go. Cautious answers only on a strong match and is wrong less often. Willing answers from weaker matches, with fewer refusals and more thin answers. Balanced sits in between and is the default.

  How to confirm it is this one

  Behaviour tab, the choice under How sure it should be, and the Match threshold number underneath it. Read that number against the best match percentages in the unanswered list. Refusals clustered just below your threshold are the setting, not the material.

  Fix

  Move it one step down and watch the same list for a week. Do not jump straight to Willing on an assistant with thin material, because what you get is not more answers, it is answers built from weak matches.

• 4

  The source has not finished indexing

  Why

  Until a source finishes, its documents are not searchable, so every question gets the fallback. This is the ordinary state for the first minute after adding a site and it looks exactly like a permanent failure.

  How to confirm it is this one

  Knowledge tab: the source badge reads Queued or Indexing rather than Ready, or its document count is zero. The Test tab is explicit about it and says the assistant is still reading your files instead of showing the widget at all.

  Fix

  Wait for the badge. If it settles on Failed or Partial, the error line under the source name says what happened, and that is a different problem from this one.

• 5

  The gate passed and the model refused on its own

  Why

  The model is told to answer only from the supplied material and to say it does not have the information, suggesting the team is contacted, when the material does not cover the question. A question whose answer is spread across several pages can pass the gate on one strong match and still not be covered by what was actually shown.

  How to confirm it is this one

  Read the reply against your own fallback message. A gate refusal is that message word for word, and the question appears in the unanswered list. A model refusal is in the model's own words and does not appear there at all, because only gate refusals are recorded as unanswered.

  Fix

  Raise Passages it reads on the Behaviour tab, which defaults to 6 and accepts 2 to 12, so more of the material is put in front of it. Better still, put the whole answer in one place: an answer assembled out of four pages is fragile no matter how many passages you allow.

If a question is refused in the widget but answered on the Test tab, or the other way round, check nothing about retrieval and look at which assistant is answering. They are separate assistants with separate material, separate thresholds and separate fallback messages, and a site with the wrong key installed produces exactly this. The unanswered list belongs to one assistant too, so a question asked of one will never appear under the other.

Does a refusal get cached and repeated?

No. Only answers that cited a source are cached, precisely so a refusal cannot be frozen in place. Add the missing document and the next person to ask gets the real answer rather than yesterday's apology.

What is the best match percentage actually measuring?

How well the strongest retrieved passage matched the question, on the same scale as the threshold behind your caution setting. That is what makes it useful: it is not a general quality score, it is the number the gate compared against.

Should I just set it to Willing and be done?

Only if you would rather have a thin answer than a refusal, which is a real position on a shop and a bad one anywhere being wrong costs money. The honest version is to fix the top three questions in the unanswered list first, then decide.