> ## Documentation index
> Fetch the complete documentation index at: https://contextrepo.com/docs/llms.txt
> Use it to find every page before exploring further.

# Reasoning

> Ask questions over your stored documents and get best-effort answers with inline citations and non-exhaustive limitations.

The `reason` tool answers a natural-language question from your stored document content. It retrieves a bounded evidence set, synthesizes one best-effort answer, and returns sources plus limitations it notices. The `gaps` array is non-exhaustive; an empty array doesn't prove complete coverage.

Use Reasoning when you need a conclusion rather than a list of search results.

## Choose the right retrieval tool

| Your goal                                      | Use                                           |
| ---------------------------------------------- | --------------------------------------------- |
| Find a prompt, document, or collection         | `find_items`                                  |
| Inspect and navigate passages inside documents | `deep_search`, `deep_read`, and `deep_expand` |
| Get one cited answer across document evidence  | `reason`                                      |

Reasoning works with document content only. It doesn't search prompt content.

## Ask a question

You can call `reason` through the MCP Server or send `POST /v1/reason` through the REST API.

| Parameter      | MCP         | REST     | Description                                                                                                       |
| -------------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `query`        | Required    | Required | The question to answer. It must contain at least one non-whitespace character; the REST endpoint trims its edges. |
| `limit`        | Optional    | Optional | Maximum evidence chunks in the synthesis packet. Defaults to 50 and is clamped to 1–50.                           |
| `documentId`   | Optional    | Optional | Restrict the evidence to one document                                                                             |
| `collectionId` | Optional    | Optional | Restrict the evidence to documents in one collection                                                              |
| `maxTokens`    | Not exposed | Optional | Evidence token budget. The REST default is 8000; finite values are truncated and negative values become zero.     |

When you provide both `documentId` and `collectionId`, the document must belong
to that collection. A valid but inaccessible or out-of-scope selection returns
a scoped no-evidence answer rather than searching elsewhere. Omit unused scope
fields rather than sending empty or null values; nonempty malformed IDs fail
request validation.

### MCP example

Ask your connected assistant:

> Use `reason` to compare the REST and GraphQL requirements in my API Decisions collection. Preserve any disagreement and cite both sources.

The assistant can call:

```json
{
  "query": "Which interface is required, REST or GraphQL?",
  "collectionId": "j97abc123collection",
  "limit": 12
}
```

### REST example

```bash
curl -X POST "https://api.contextrepo.com/v1/reason" \
  -H "Authorization: API-Key gm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Which interface is required, REST or GraphQL?",
    "collectionId": "j97abc123collection",
    "limit": 50,
    "maxTokens": 8000
  }'
```

See the [REST endpoint reference](https://contextrepo.com/docs/api/endpoints#synthesize-an-answer) for the complete wire response.

## Read the response

The REST response and MCP structured response contain the same four fields
under `data`:

| Field       | What it tells you                                                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `answer`    | Synthesized prose with server-generated `[[chunkId]]` citation tokens                                                                                  |
| `citations` | The cited chunks, each with `chunkId`, `documentId`, and `documentTitle`                                                                               |
| `gaps`      | Best-effort limitations noticed in this run, including facts not established by the retrieved evidence within the requested scope and retrieval limits |
| `meta`      | `chunksGathered`, `citationsDropped`, and `latencyMs`                                                                                                  |

MCP preserves these fields under `structuredContent.data`. Its readable text
always includes **Answer** and **Meta**, then adds **Sources** and
**Limitations** when those arrays aren't empty.

## Verify citations

The synthesis step returns `statements` and `limitations`. Every statement has
one or more references containing a chunk ID and quotation. Context Repo
requires each quotation to occur in the admitted chunk after collapsing
whitespace runs and trimming both values, then binds the document title,
document ID, and inline citation token on the server.

Exact citation validation proves source linkage, not semantic entailment. Check the cited chunk when a decision depends on the model's interpretation.

`citationsDropped` counts references withheld by failed mechanical validation. Retained duplicate references don't increase it, and the value is not a semantic-correctness score.

## Interpret disagreements and gaps

Reasoning represents disagreements as ordinary cited statements in the answer. It preserves the supplied source differences without choosing a winner unless the evidence establishes one.

The `gaps` array contains best-effort limitations the synthesis notices, not an
exhaustive coverage report. Retrieval and token limits can exclude context
without adding a generic partial-evidence warning. An empty array doesn't prove
that every relevant source was retrieved or that no requested fact is missing.

When no sufficiently relevant evidence is available, Reasoning skips synthesis and returns:

> No sufficiently relevant evidence was retrieved for this question within the requested scope and retrieval limits.

## Know the execution boundaries

When evidence passes the relevance gate, the request uses one synthesis call
with zero retries. Empty evidence always skips that call. Weak unscoped
evidence also skips it, while a nonempty result from an explicit `documentId`
or `collectionId` scope reaches synthesis even when its best score is below
Reasoning's fixed relevance guard. Progressive search still applies its own
ranking and adaptive retrieval threshold. The server-managed model and its
reasoning settings aren't caller-selectable.

Reasoning uses the progressive-search results directly and preserves their
order. It does not enumerate extra collection members or walk document
ancestors, children, or headings. A final packet budget includes XML wrappers,
document titles, and content; the last admitted chunk can be truncated at a
word boundary. Similarity scores remain internal to the unscoped guard and
never appear in provider evidence or public citations.

Reasoning is read-only and does not persist an answer, reasoning trace, or citation record. It never creates, updates, or deletes your stored content.

> **Note:** If a provider or strict-output error occurs, the request fails instead of silently converting that failure into a claim that your evidence is missing.

## Related pages

- [MCP Tools Reference](https://contextrepo.com/docs/mcp/tools-reference#reason): Review the MCP parameters and formatted response.
- [REST Endpoints](https://contextrepo.com/docs/api/endpoints#synthesize-an-answer): Review the HTTP request, response, authentication, and metadata.