Context Discipline Rules for Predictable Agent Behavior
Context discipline is the practice of structuring, trimming, and refreshing everything an agent sees so each decision is based on goal-relevant information instead of an unbounded transcript.
Most "the model got dumber mid-run" reports are context problems: noise, contradiction, or sheer volume drowning the current objective.
How to Use This List
- Apply structure rules to system policy first, then trimming rules to the running transcript.
- Pick numeric caps (tool-result size, retained turns) per product and write them down.
- Review context dumps from failing runs the same way you review stack traces.
- Revisit caps when tools start returning larger payloads (HTML, logs, files).
Structure Rules
| Rule | Default practice |
|---|---|
| Section stable policy | Role, goal, constraints, tool guidance, output format as labeled blocks |
| Keep policy append-reviewed | Every system-policy addition needs an owner and reason |
| One source of truth for prompts | No copy-pasted forks that drift per call site |
| Put dynamic facts in turn state | Dates, user ids, live records belong in the current user/turn payload |
| State hard constraints as testable lines | "Never call refund without approval_id" beats vague caution |
Trimming and Retention Rules
- Trim before the window is full. Waiting for overflow forces crude drops; proactive trim preserves signal.
- Prefer dropping superseded tool results over dropping the goal statement. Old search hits lose value faster than the success criteria.
- Leave markers when omitting history. The model should know context was reduced, not silently forget it ever happened.
- Cap retained tool results to a fixed N (or token budget). Choose N from observed runs, not from "keep everything."
- Collapse failed attempts. Keep the final successful retry, not every intermediate stack trace, unless debugging mode is on.
- Summarize long plans when entering a new phase. A three-line "current plan" beats a ten-turn argument about abandoned approaches.
- Never re-inject full files repeatedly. Cache references, hashes, or retrieved slices; do not paste the same blob every turn.
Tool-Boundary Rules
- Truncate or summarize at the tool adapter, not only in the prompt. Huge raw API responses should never reach the model whole by default.
- Normalize tool errors into short, structured messages. A 2 KB structured error beats a 50 KB HTML failure page.
- Strip secrets and PII at the boundary. Context discipline includes what must never enter the window.
- Label tool results with purpose and timestamp. Ambiguous blobs cause the model to reuse stale observations.
- Reject oversized results as first-class failures. Trigger a smaller query or summary tool instead of forcing the model to "cope."
Refresh and Consistency Rules
- Restate the active goal at phase boundaries. Long runs drift toward local tool subgoals without an explicit refresh.
- Keep output contracts stable for the same task type. Parsers and downstream steps depend on consistent shapes.
- Separate scratch reasoning from durable conclusions. Persist decisions; drop verbose intermediate monologues when the framework allows.
- Avoid contradictory instructions via accretion. Prune rules nobody can justify; contradictions look like flaky behavior.
- Budget tokens for observations vs instructions. If tools consume 90% of the window, policy and goal cannot compete.
- Version the context policy with the agent. Prompt and trim logic change together in review, not as hot silent edits.
Context Policy Cheatsheet
| Signal | Action |
|---|---|
| Tool result older than N turns and superseded | Drop + short marker |
| Single tool payload over size cap | Truncate/summarize at adapter |
| Approach approaching context limit | Summarize phase + hard trim |
| Failed then succeeded retry | Keep success only |
| Policy line with no owner | Candidate for deletion after test |
| Same file pasted 3+ times | Replace with reference + slice |
Minimal Trim Sketch
MAX_TOOL_RESULTS = 6
def trim_messages(messages: list[dict]) -> list[dict]:
"""Keep recent tool observations; mark older ones as omitted."""
tool_idxs = [i for i, m in enumerate(messages) if m.get("role") == "tool"]
if len(tool_idxs) <= MAX_TOOL_RESULTS:
return messages
keep_from = tool_idxs[-MAX_TOOL_RESULTS]
out = []
for i, m in enumerate(messages):
if i < keep_from and m.get("role") == "tool":
out.append({"role": "tool", "content": "[earlier tool result omitted]"})
else:
out.append(m)
return outThis sketch is illustrative only.
Production systems often use token budgets, summarization turns, or framework memory primitives - the rule is explicit policy, not a specific algorithm.
FAQs
Why not keep the full transcript if the model has a large context window?
Large windows still suffer attention and cost problems.
Irrelevant history competes with the current goal and multiplies token spend every turn.
Is summarization better than hard drops?
Summarization preserves gist; hard drops preserve exact recent facts.
Many systems use both: summarize old phases, keep raw recent tool results.
Where should truncation happen - model prompt or tool layer?
Prefer the tool layer so every consumer of that tool inherits the cap and logs stay honest about what the model saw.
How do I pick MAX_TOOL_RESULTS or a token budget?
Measure failing and successful runs.
Raise caps only when you can show missing older results caused wrong actions.
Does structured prompting really change behavior?
It improves reviewability and reduces self-contradiction.
Models still need clean observations; structure is not a substitute for trimming.
What should a trim marker look like?
Short, honest, and non-instructive junk: note that content was omitted for length, not a fake tool success.
How does context discipline interact with prompt caching?
Stable system policy should stay byte-stable for cache hits.
Volatile state belongs outside the cached prefix so trims do not thrash the cache.
Can too much trimming cause amnesia failures?
Yes.
If the agent re-fetches constantly or contradicts earlier commitments, raise retention or improve summaries rather than disabling discipline entirely.
Should debug mode disable trimming?
Often yes for local repro.
Never leave debug retention on in production paths.
How do multi-agent handoffs affect context rules?
Handoffs need a curated packet (goal, constraints, key facts), not a raw dump of the prior agent's full transcript.
Is "stuff more into the system prompt" a valid fix for mistakes?
Usually no.
Unreviewed accretion creates contradictions.
Fix tools, goals, or evals first.
What is the first context metric worth logging?
Tokens per turn broken down by policy, transcript, and tool results - so you can see what is crowding the window.
Related
- The Core Agent Fundamentals Rules: A Quick-Reference List - condensed context rows.
- Why Fundamentals Rules Prevent Early Agent Project Failures - why context drift becomes an incident class.
- Stopping-Condition Rules Every Agent Must Implement - finite runs that still need a clean window each turn.
- Model-Swapping Rules for Cost and Capability Flexibility - context size drives cost across model tiers.
- AI Agent Fundamentals Rules Best Practices - checklist form including context items.
Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana
@solana/web3.js+@solana/spl-token.