Skip to main content
The most common retrieval question: “I know this document has the answer — why isn’t the Agent finding it?” The Diagnostics tool walks the pipeline in reverse to find where things went wrong.

​
Opening Diagnostics

Two entry points:
  • From a Trace — click “Diagnose retrieval” on any retrieval step. Loads the exact query and preset used.
  • From a document — right-click any chunk in your knowledge, “Test retrievability”. Simulates queries that should find it.

​
What Diagnostics shows

For a given query and expected chunk, Diagnostics answers:
  1. Is the chunk in the index? — Sanity check. If not, look at the pipeline (was it filtered out during Clean? Chunker skipped it?).
  2. Do filters exclude it? — Shows the filter set and whether the chunk passes.
  3. What’s the vector score? — Cosine similarity between query and chunk. Low scores (< 0.2) mean semantic mismatch — the chunk doesn’t “mean” what the query means.
  4. What’s the keyword score? — BM25 score. Low scores mean the query has no words in the chunk (maybe worth a synonym).
  5. What’s the fused position? — Where the chunk ranked in the top 50.
  6. Did reranker drop it? — If reranking was on and it fell out of the top K.
  7. Did grounding drop it? — If grounding was on and the chunk conflicted with the graph.

​
Common failures and fixes

​
Fixing at scale

If diagnostics keeps pointing to the same root cause across many queries, that’s a Signal. The Improvement flow (see Optimization) can turn a recurring retrieval miss into a proposal for a new tag, a preset change, or a chunker adjustment.

​
Retrievability tests

Save a set of “expected” chunk-for-query pairs as a Retrievability test. Runs in CI (or manually). Fails when your top-K stops including a chunk it used to include. Good pattern: every time you fix a “why can’t I find X” issue, add a retrievability test so the fix doesn’t regress.