Reasoning

The reason tool answers a natural-language question from your stored document content. It retrieves a bounded evidence set, synthesizes one answer, and returns the sources, gaps, and disagreements that shaped that answer.

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": 12,
    "maxTokens": 6000
  }'

See the REST endpoint reference for the complete wire response.

Read the response

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

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

Verify citations

The synthesis step proposes a chunk ID and exact quotation for every supported claim or disagreement alternative. Context Repo validates both against the evidence admitted to that request, then binds the document title, document ID, score, 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 incompatible source statements as alternatives with separate evidence. A disagreement stays unresolved unless the supplied evidence explicitly states a resolution. Evidence that no alternative is selected leaves the disagreement unresolved and isn't repeated as a separate claim.

If only part of the eligible evidence fits within retrieval or token limits, the server keeps any cited content that survives validation and adds a partial-evidence gap. A gap applies only to the bounded evidence packet. It doesn't prove that your entire repository lacks the fact.

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 or weak evidence skips that call. The server-managed model and its reasoning settings aren't caller-selectable.

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