Reasoning

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

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.

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:

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

REST example

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 for the complete wire response.

Read the response

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

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.

Related pages