# Documentation is not product context.

Design the context contract that joins stable knowledge, live data, current screen, identity, permissions and eligible tools.

Version 1.0 · 2026-07-29 · 8 min

## Short answer

Documentation says how a product should work. Product context says what is happening for this user now. Keep those layers separate and join them through a typed context contract: validated identity, route, active entity, tenant or site, effective permissions, relevant knowledge, live observations and eligible tools. Retrieve and observe only after the access boundary is known. The model receives a controlled view, not authority to decide what it may see.

## Key points

- Stable knowledge and changing state need different sources and freshness rules.
- The context envelope should be typed, minimal and derived server-side.
- Security filters happen before model context assembly.

## A correct article can still produce the wrong answer

A help article may correctly explain how approval works while the current record is incomplete, the workflow has changed or the user lacks the relevant role. Retrieval quality cannot solve that mismatch because the missing information is not in the document corpus.

The architecture should therefore treat documents, live state and tools as different evidence classes. Each class has its own authority, freshness, access checks and failure modes.

## The context envelope

Build one server-owned object that describes what the assistant may know and do for the current turn.

### 1. Identity

User, organisation, tenant or site and effective role, resolved from the authenticated session.

### 2. Navigation

Validated route, module, selected entity and product version or feature state where relevant.

### 3. Access

Read and write boundaries calculated by the host application. These are data, not prompt advice.

### 4. Knowledge

Permitted stable sources with identifiers, versions and retrieval scores useful for evaluation.

### 5. Observations

Live tool results with scope, timestamp, partial or empty status and safe provenance.

### 6. Eligible tools

A reduced list of typed operations available for this role and workflow, including when not to use them.

## Examples

### Policy versus current status

A policy document defines the approval rule. A read tool reports whether the current request satisfies it.

### Navigation versus authority

The browser route suggests a record. The server resolves the record again inside the signed-in tenant before loading it.

### Knowledge versus tool

A guide explains the process. A tool confirms whether the next step is currently available.

## Common failure modes

- Combining every input into an untyped prompt string.
- Using browser-provided scope without server validation.
- Allowing retrieved text to override deterministic access rules.
- Caching live state without a freshness contract.
- Passing tool results without status, provenance or error semantics.

## Checklist

1. Context classes are named and typed.
2. Identity and scope come from the authenticated host.
3. Stable knowledge and live state have separate freshness rules.
4. Retrieval applies access filters before generation.
5. Tool results preserve empty, denied, partial and failed states.
6. Eligible tools are reduced before model selection.
7. The final envelope can be inspected in redacted traces.

## Limitations

- A context contract must be adapted to the host product’s data and access model.
- Provenance does not guarantee that the underlying source is correct.
- Some questions still require clarification because no system holds the missing fact.

## Sources

1. [Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks](https://arxiv.org/abs/2005.11401) — Lewis et al., 2020; type: research.
2. [ReAct: Synergizing Reasoning and Acting in Language Models](https://openreview.net/forum?id=WE_vluYUL-X) — Yao et al., 2023; type: research.
3. [Model Context Protocol specification](https://modelcontextprotocol.io/specification/2025-11-25) — MCP maintainers, 2025-11-25; type: standard.
4. [AgentDojo: A Dynamic Environment to Evaluate Prompt Injection Attacks](https://openreview.net/forum?id=m1YYAQjO3w) — Debenedetti et al., 2025; type: research.

## Practical questions

### Should the context envelope be shown to users?

Not in full. Show useful evidence and limits. Keep internal identifiers, policies and sensitive traces out of the interface.

### Can one context service support several assistants?

Yes, if each surface requests a purpose-specific view and retains its own identity and tool boundary.

### Is this just a richer RAG pipeline?

No. Retrieval is one stage. Product state, access, tools, action gates and traces belong to the wider control graph.

---

Canonical: https://scoperail.fokalabs.io/en/guides/documentation-is-not-product-context
Author: Ramzi Laieb, FokaLabs