Cited Answers, Not Just Search Results

A search result is not an answer. It is a set of places where an answer might live.

That distinction matters when an AI agent is working from a knowledge base. A ranked list of chunks can be useful, but the user often asked a direct question: "What does the policy say?", "Which setup steps are required?", "Do these documents disagree?", "What is missing?"

If the agent receives only search results, it still has to read, compare, cite, and decide whether the evidence is enough. If it does that work loosely, the final response can look confident while resting on weak or incomplete context.

Context Repo's reason flow is built for the next step after retrieval. It turns retrieved document evidence into a best-effort answer with sources and limitations it notices. It is not a replacement for Deep Search. It is a higher-cost layer on top of retrieval for moments when the user needs a grounded answer, not just a hit list.

What reason returns

At the product level, reason returns four things:

• answer: synthesized prose answering the user's question from the gathered evidence.
• citations: source chunks the answer relies on, 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: operational metadata such as how many chunks were gathered, how many proposed reference occurrences were withheld during mechanical validation, and latency.

The shape is deliberately different from deep_search. Deep Search gives an agent passages to inspect. reason gives the agent or user a composed answer plus the evidence trail needed to verify it.

{
  answer: string,
  citations: Array<{
    chunkId: string,
    documentId: string,
    documentTitle: string,
  }>,
  gaps: string[],
  meta: {
    chunksGathered: number,
    citationsDropped: number,
    latencyMs: number,
  },
}

The gaps array is non-exhaustive. An empty array does not prove that every relevant source was retrieved or that no requested fact is missing.

reason is read-only. It does not create documents, update prompts, write summaries back to the repository, or persist a reasoning trace. It operates on document content, not prompt content.

The three-stage flow

The implementation is intentionally simple to describe at the architecture level:

1. Gather evidence from the document chunk retrieval system.
2. Synthesize cited statements and limitations from that evidence in at most one server-managed model call.
3. Validate references, bind provenance, and render the public response.

That flow is what separates cited answering from ordinary retrieval. The system does not ask the model to search the whole repository by itself. Retrieval happens first. The model receives a bounded evidence set. Then the server checks the exact chunk IDs and quotes the model emits against that same admitted evidence.

Stage 1: gather evidence before answering

reason starts with the same progressive disclosure retrieval layer that powers Deep Search. The query is embedded, and the authenticated user's document chunk index is searched within the caller's scope before synthesis.

The caller can optionally restrict the answer to:

• a single document with documentId;
• a single collection's documents with collectionId;
• a caller-selected gather breadth with limit;
• a maximum evidence budget with maxTokens on the REST surface.

The important point is that the answer begins from document chunks the user is allowed to access. The retrieval layer enforces user isolation, applies document and collection scope, and returns chunks with document titles and similarity scores.

Reason uses that progressive result list directly and preserves its order. It does not enumerate extra collection members or walk document headings, ancestors, children, or siblings. A small final packet budget counts wrappers, titles, and content together, truncating only the last admitted content at a word boundary when necessary. Similarity scores stay available to the unscoped relevance guard but are not shown to the synthesis model or caller.

This matters because a synthesis model should not be asked to "remember" the user's repository. It should be asked to answer from the evidence the system has already gathered.

Stage 2: synthesize under evidence constraints

After gathering, reason builds a bounded evidence block from the retrieved chunks and sends the user's actual question with that evidence. The question matters. Without it, the model can only summarize nearby text. It cannot judge whether the retrieved chunks answer the thing the user asked.

The synthesis step produces a strict internal object:

• statements paired with one or more evidence references;
• limitations about requested facts or qualifications.

Disagreements remain ordinary cited statements. The model preserves source differences without choosing a winner unless the supplied evidence establishes one.

Each model-authored reference contains only a chunk ID and a short exact quote. The model does not author final citation objects, document metadata, scores, or structural retrieval state. The server owns those parts of the response.

The article version of that behavior is simple: the answer is supposed to be evidence-bound, not creative. If the bounded retrieved evidence does not answer the question, the correct result is a scoped gap, not a confident summary of adjacent facts.

The synthesis model is managed server-side. Each request uses at most one synthesis call with zero retries. Empty evidence always skips synthesis. Weak unscoped evidence also skips it. Nonempty explicit document or collection scope bypasses only Reason's fixed relevance gate. Callers do not choose a model, temperature, or reasoning settings for this endpoint. That keeps the public contract focused on the result: cited answers over repository documents.

Stage 3: validate references and bind provenance server-side

Citation validation is the most important reliability step.

The synthesis step emits references containing chunk IDs and quotes. Before rendering, the server requires each ID to identify an admitted chunk. It collapses whitespace runs and trims the quote and admitted chunk content, then requires the normalized quote to occur in the normalized chunk. Validation uses the post-truncation content sent to the model. The server then uses that admitted unit to bind document identity and title and generates inline citation tokens and public citation metadata from retained references.

citationsDropped counts references withheld by failed mechanical validation; retained duplicate references do not increase it. This diagnostic is not a semantic-correctness score. Exact citation validation proves source linkage, not semantic entailment. The model can still interpret an exact quotation incorrectly, so semantic correctness remains a separate evaluation concern.

This is the difference between "the model wrote a source-looking token" and "the server accepted an exact witness from admitted evidence."

How reason abstains

Good reasoning systems need a way to say "the bounded retrieved evidence does not establish that."

reason has two abstention paths.

First, empty evidence always skips synthesis and returns the scoped no-evidence gap. Weak unscoped evidence also skips synthesis. Nonempty explicit document or collection scope bypasses only Reason's fixed relevance gate, so a nonempty result can reach synthesis even when its best score is below that guard. Progressive retrieval thresholds and authorization still apply.

Second, if no statement survives mechanical validation, the server returns a scoped insufficiency answer and ensures the gap channel is not empty. Retrieval or token limits can exclude eligible context without creating a generic partial-packet warning.

That behavior is intentionally conservative. The goal is not to answer every question. The goal is to answer when the bounded retrieved evidence supports an answer and to show the missing pieces when it does not.

Why cited answers are better than a hit list

Ranked chunks are useful for exploration. They are less useful when the user wants a conclusion.

A hit list leaves four jobs for the agent:

1. Decide which chunks matter.
2. Compose the actual answer.
3. Attach sources to claims.
4. Notice missing or conflicting evidence.

reason moves those jobs into a controlled server flow. The agent receives a single answer plus a structured source list and explicit uncertainty fields. That improves the workflow in several practical ways.

The answer is easier to verify

The citations array points back to exact document chunks. A client can show the sources, inspect the chunk IDs, or route a follow-up through deep_read if it wants to display the source passage in more detail.

The output is not just "trust me." It is "here is the answer, and here are the chunks that were accepted as sources."

Missing evidence is first-class

Many retrieval systems treat missing evidence as an awkward edge case. Context Repo treats it as part of the answer shape.

The gaps array carries best-effort limitations the synthesis notices. It can name facts not established by the retrieved evidence within the requested scope and retrieval limits, but it is not an exhaustive inventory of everything the bounded retrieval may have missed.

Disagreements are not silently hidden

If two gathered sources disagree, the answer should not quietly pick one and bury the other. The synthesis can surface the disagreement as an ordinary cited statement in the answer.

That is valuable for policies, specs, internal runbooks, and evolving documentation where two sources may both exist but only one is current.

Scope is explicit

Because reason can be scoped to one document or one collection, users can ask questions inside a clear boundary. That makes it useful for project collections, client-specific documentation, or one manual where the answer should not pull from the whole repository.

Why it costs more

reason costs more than returning search results because it does more work.

Deep Search performs retrieval and returns chunks. reason performs retrieval, builds evidence, runs a synthesis pass, validates exact references, binds provenance, applies bounded gap safeguards, and formats the final response.

That extra work is worth paying for when the desired output is an answer with sources. It is not always worth paying for when the user only needs to find a document or inspect the top passages.

The product trade-off is straightforward:

The higher-cost path is not the default answer to every retrieval problem. It is the path for answer synthesis.

Where reason fits in an agent workflow

A practical agent workflow often looks like this:

1. Use find_items when the agent does not know which artifact matters.
2. Use deep_search when the agent needs candidate passages inside documents.
3. Use deep_read or deep_expand when the agent wants to inspect source context manually.
4. Use reason when the agent needs a concise, cited answer from document evidence.

Those tools are complementary. reason does not remove the need for search. It packages a common search-plus-synthesis workflow into a consistent endpoint so every client does not have to recreate it differently.

Honest boundaries

reason is only as grounded as the evidence available to it. If the relevant document has not been stored, falls outside the requested scope, or is excluded by retrieval limits, the answer cannot recover that missing context.

The response shape is designed to make those limits visible:

• empty evidence always becomes a gap without synthesis;
• weak unscoped evidence also skips synthesis;
• nonempty explicit document or collection scope bypasses only Reason's fixed relevance gate;
• limitations noticed during synthesis can be listed in gaps;
• disagreements can appear as cited prose in answer;
• public citations come only from mechanically valid admitted references;
• metadata shows how much evidence was gathered and how many proposed reference occurrences were withheld.

The gaps list is non-exhaustive, so an empty list does not prove complete coverage. That is the right standard for a context repository: the system should not pretend to know more than bounded retrieved evidence establishes.

What users can depend on

The public contract is simple:

• reason answers questions over document content only.
• It is read-only and does not persist the answer.
• It reuses Context Repo's document retrieval layer for evidence gathering.
• It can be scoped to a document or collection.
• It returns an answer, citations, gaps, and metadata.
• It validates exact model references against the admitted evidence set and binds public citation metadata server-side.
• It costs more than search because it adds synthesis and validation work.

That is why cited answers are different from search results. Search finds possible evidence. reason turns gathered evidence into an answer and leaves the source trail attached.

Where to read next

• Why Hierarchical Retrieval Finds More Than Flat RAG. Why Context Repo stores document structure for better recall.
• Semantic Search and Deep Search: Two Retrieval Layers. How catalog search and document chunk search fit together.
• How MCP Servers Connect AI Agents to Knowledge Bases. How Context Repo exposes retrieval and reasoning tools to AI clients.
• Prompt and Document Management for AI Agents. How saved documents become reusable context for agents.
• MCP Server install page. Connect your client and try Context Repo against your own documents.