> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/improve-search-quality.md).

# Analyze and Improve Search Quality

Start with questions your readers actually ask and the source records that should answer them. Keep the query text and expected record IDs so you can compare configuration changes.

## Build a Small Evaluation Set

Include direct questions, paraphrases, exact names or identifiers, ambiguous questions, and questions whose answers are absent from the source data.

For example, suppose your indexed equipment articles include **Pump has low flow**, which recommends checking the inlet strainer, and **Pump will not start**, which recommends checking the power supply and resetting the overload protection. Neither article states a warranty period. Record their actual source IDs alongside the titles, then evaluate these queries:

| Query                                        | Expected Source                         | Evidence to Look For                           | Actual Result  |
| -------------------------------------------- | --------------------------------------- | ---------------------------------------------- | -------------- |
| The pump is running but barely moving water. | Pump has low flow                       | Inlet strainer inspection                      | To be measured |
| The pump makes no sound when started.        | Pump will not start                     | Power supply and overload protection           | To be measured |
| What is the pump warranty period?            | No article in this example answers this | The answer should acknowledge missing evidence | To be measured |

## Diagnose the Result

| Observation                                                                 | Check First                                                  | Possible Change                                                      |
| --------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- |
| The expected record never appears                                           | Source eligibility, readiness, and processing failures       | Fix membership or indexing before tuning ranking.                    |
| The record exists, but its useful text is absent from evidence              | Template and source fields                                   | Add relevant text or readable reference data.                        |
| Evidence ends before the answer                                             | Chunk boundaries and header size                             | Adjust template structure, chunk size, or overlap.                   |
| Exact names are difficult to find                                           | Whether names appear in rendered text and which mode is used | Include the names and compare hybrid retrieval.                      |
| Relevant results are excluded                                               | Projection values and static filters                         | Correct the field, type, or preset filter.                           |
| Relevant evidence is retrieved but ranked poorly                            | Candidate count and reranking                                | Compare Top K values and reranking using the same queries.           |
| Many results repeat one record                                              | Document grouping                                            | Enable one result per document if the task needs distinct records.   |
| The consuming AI client gives an unsupported answer despite useful evidence | Actual search result and answer instructions                 | Ask for source-linked claims and acknowledgment of missing evidence. |

Change one factor at a time. Record the configuration, generation, actual source IDs, and useful passages. Include latency if response time matters to the workflow.

A reranker can reorder candidates; it cannot add a source that retrieval missed. An embedding change cannot supply information missing from source records or the template.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/improve-search-quality.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
