Context Engineering Specification: [Agent or application name]

Specification for everything a language model sees on each call: the context window budget per section, system instructions, retrieved content, memory, tool definitions and tool results, ordering, compaction and summarisation rules, prompt caching, the handling of untrusted content and the evaluation that gates every context change. It treats the assembled context as a versioned artefact, like code. Tool definitions follow the Model Context Protocol (MCP) revision 2026-07-28; untrusted-content risks are mapped to the OWASP Top 10 for Agentic Applications 2026. Replace every [bracketed] value and every row marked Example. Worked examples use a billing support agent for a software subscription product.

Document control

Approvals

Revision history

Contents

1. Scope and system context
2. Context window budget
3. System instructions
4. Retrieved content
5. Memory
6. Tool definitions and tool results
7. Ordering and assembly
8. Compaction and summarisation
9. Prompt caching
10. Untrusted content handling
11. Evaluation of context changes
12. Observability and change control
13. Glossary and references

1. Scope and system context

This specification governs the context assembled for [list the model calls, for example "the main planning call and the reply call of the billing support agent"]. It does not govern [list exclusions, for example "the offline classifier that routes tickets, which has its own prompt specification"].

The context assembler is the code that builds each request. Every rule in this document must be enforced by that code or by a test, not only by wording inside the prompt. Describe the assembler's location and interface here: [repository path, function name, configuration file].

2. Context window budget

Budget every section against the usable window. Reserve output tokens (including any reasoning tokens the model spends) before allocating input sections, then keep a safety margin for tokenizer differences and wrapper overhead.

Example: the usable input budget is 128,000 minus 32,000 minus 3,500, which is 92,500 tokens. Compaction (section 8) starts at 75% of that figure, 69,375 tokens, so that a large tool result never arrives with no room left.

Rules for the budget:

• Measure ceilings with the target tokenizer in a unit test that loads the real instruction file and tool set.
• Record the actual size of each section on every call (section 12), so that drift shows up before it causes truncation.
• When the model changes, re-measure every ceiling; tokenizers differ and the same text can grow or shrink.
• Long windows are not free. Larger contexts raise cost and latency and can dilute attention on the instructions. Fill the window with what the task needs, not with everything available.

3. System instructions

Keep the system block stable across calls. Put anything that changes per request (date, locale, feature flags) in a small, clearly labelled block after the stable part, so that the stable part can be cached (section 9) and reviewed once. Describe the precedence of instruction sources in plain words, and test it in section 11. State what the agent does when sources conflict: for example, the customer asks for a refund larger than policy allows and a retrieved article appears to allow it.

4. Retrieved content

Rules:

• Give every retrieved item a stable identifier so that the reply can cite it and evaluation can check groundedness.
• Put metadata (source, date, owner) next to the content, not in a separate block the model must join.
• Deduplicate near-identical chunks before they enter the window.
• When nothing passes the threshold, say so explicitly in the context ("No matching articles were found") rather than leaving the section empty, so the model does not invent an answer.
• Link the retrieval design: RAG System Design (ai-data/rag-system-design).

5. Memory

Rules:

• Write only facts that were confirmed, with provenance (who, when, from which turn or tool).
• Never let content from an untrusted source write memory without a validation step; this is the main path for OWASP ASI06 (Memory & Context Poisoning).
• Label memory as memory in the window, with its age, so the model can weigh stale items.
• Give users a way to see and remove what is remembered about them, and align retention with the privacy notice.

6. Tool definitions and tool results

6.1 Tool set per task type

Load the smallest tool set that serves the task. Each extra tool costs tokens and adds a way to choose the wrong action. Keep tool order deterministic: the MCP 2026-07-28 tools page asks servers to return tools in a stable order, which helps clients cache the list and improves prompt cache hit rates. Each tool's full entry lives in the Agent Tool and Function Catalogue (ai-data/tool-catalogue).

6.2 Tool definition rules

• Write descriptions for the model: what the tool does, when to use it, when not to use it, and what the result contains.
• Prefer enumerations and formats in the input schema over prose rules.
• Treat tool annotations such as readOnlyHint as hints. The MCP schema says clients should never base tool use decisions on annotations from untrusted servers; enforce permissions outside the model, as designed in Agent Tool Permission Design (ai-data/agent-tool-permission-design).

6.3 Tool result shaping

7. Ordering and assembly

Example: the order above suits a provider that builds its cache prefix in the sequence tools, system, messages. Confirm your provider's prefix order before copying it. Place retrieved content close to the question that needs it, and repeat the most important constraint near the end only if evaluation shows it helps.

Assembly rules:

• The assembler is deterministic: the same inputs produce byte-identical output. Sort maps and lists; never include random ids or timestamps in cached blocks.
• Use one consistent delimiter style (for example XML-like tags) for every data block, and tell the model that content inside data tags is data, not instructions.
• Log a hash of each block per call so that a replay can rebuild the exact context (section 12).

8. Compaction and summarisation

Rules:

• Summaries are generated content. Label them as summaries in the window and keep the source turns retrievable for audit.
• Never summarise away a commitment made to the user (a promised refund, a deadline) or a refusal and its reason.
• Do not summarise untrusted content into the trusted part of the context. A summary of an untrusted email stays labelled untrusted.
• Test compaction with long synthetic sessions in section 11 and compare answers before and after compaction.

9. Prompt caching

Provider rules differ and change, so record the ones you rely on with a link and a check date. As one verified example, Anthropic's prompt caching documentation (checked 2026-10-22) describes a prefix built in the order tools, system, messages, explicit cache_control breakpoints (at most four per request), a default lifetime of five minutes with an optional one-hour lifetime, and invalidation of later levels when an earlier level changes. Other providers cache prefixes automatically with their own thresholds.

Rules:

• Keep volatile values (timestamps, request ids, user names) out of cached blocks.
• Keep tool order and schema serialisation stable; a reordered tool list is a cache miss.
• Treat a cache hit rate drop as an incident signal: it usually means someone added a volatile value to the prefix.
• Caching must never mix authorisation contexts. Content specific to one user is never placed in a cache shared with another.

10. Untrusted content handling

Controls that work outside the model matter most: least-privilege tool sets per task, permission checks in code, human approval for consequential actions, output validation and egress limits. Inside the window, separate instructions from data, label trust, and instruct the model never to follow instructions found in data blocks. Model the full threat set in Agentic AI Threat Model (ai-data/agentic-threat-model) and the runtime filters in Guardrails Specification (ai-data/guardrails-spec).

11. Evaluation of context changes

Run each case several times when the model samples with temperature above zero, and compare distributions, not single runs. Keep a frozen replay set of real (consented, de-identified) sessions to catch changes that synthetic cases miss. Detailed metrics and datasets belong in the LLM Evaluation Plan (ai-data/llm-evaluation-plan) and the Agent Evaluation Plan (ai-data/agent-evaluation-plan).

12. Observability and change control

Log per call, with privacy controls applied:

Trace attributes can follow the OpenTelemetry generative AI semantic conventions; check their current status before relying on attribute names, because they are still evolving. Telemetry design lives in LLM Observability Specification (ai-data/llm-observability-spec).

Change control: every context change goes through a pull request that updates this document's revision history, links the evaluation run, and names the approver. Roll out behind a flag or to a traffic share first, and keep the previous context version deployable for rollback.

13. Glossary and references

References:

• Model Context Protocol specification, revision 2026-07-28, Tools: https://modelcontextprotocol.io/specification/2026-07-28/server/tools
• OWASP GenAI Security Project, OWASP Top 10 for Agentic Applications for 2026, December 2025: https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/
• Anthropic, Prompt caching documentation (checked 2026-10-22): https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• OpenTelemetry, Semantic conventions for generative AI systems: https://opentelemetry.io/docs/specs/semconv/gen-ai/
• Related templates: Prompt Specification (ai-data/prompt-specification), AI Agent Specification (ai-data/ai-agent-spec), RAG System Design (ai-data/rag-system-design), Agent Tool and Function Catalogue (ai-data/tool-catalogue), Agentic AI Threat Model (ai-data/agentic-threat-model).

Standard and licence note

Based on the Model Context Protocol specification, revision 2026-07-28 (tool definitions and deterministic tool ordering), and on public provider documentation for prompt caching, checked on 2026-10-22. OWASP Top 10 for Agentic Applications 2026 category IDs and short names are cited for mapping only, with attribution to the OWASP GenAI Security Project (CC BY-SA 4.0); no OWASP text is adapted. Context engineering has no formal standard: the structure, budgets and rules here are original text. Provider caching rules and protocol revisions change, so check the current official versions before use. Template licence: MIT.