Your agent passes the demo, then becomes unreliable in production. It recommends the wrong next action because an account changed yesterday, applies a familiar metric with the wrong definition, or tries to act without establishing who authorized it. Another prompt rewrite will not repair those failures.

The agent needs a decision-ready view of the situation: the right identity, current state, relevant history, business meaning, permissions, and evidence. Context is what lets an agent distinguish a plausible response from one that fits the user’s actual circumstances. Your goal is not to send the model more data. It is to supply the smallest complete packet of evidence required for the decision in front of it.

Diagnose the context problem before changing the model

Teams often use four different words as if they all mean context. Separating them gives you a much faster way to locate a failure.

Component	What it supplies	Typical failure signal
Instructions	The rules for how the agent should reason, respond, and behave	The same procedural mistake appears even when the evidence is correct
Knowledge	Relatively stable domain facts and concepts	The agent does not understand a product, process, or term
Context	The current facts that make this user, entity, moment, and decision distinct	The answer looks sensible in general but is wrong for this case
Tools	The mechanisms used to retrieve information or take action	The intended decision is sound, but the lookup or execution fails

A prompt problem usually repeats under the same evidence. A context problem changes with the account, workflow state, time, or history. A tool problem appears between the intended operation and the system that must perform it. A model problem remains after you give the model an accurate, complete context packet and clear instructions.

You can test that distinction without rebuilding the agent. Freeze the model and instructions, then replay one representative task with four controlled inputs:

1. A complete, verified context packet.
2. The same packet with one decision-critical field removed.
3. The same packet with a clearly marked stale value.
4. A synthetic, isolated packet in which one decisive fact belongs to a different scope.

The output should respond to each change. It should ask for missing information, reject stale evidence when freshness matters, and refuse to cross the scope boundary. If the agent produces the same confident answer every time, either the context is not reaching the model in a usable form or the agent is not grounded strongly enough to use it.

Now compare the verified packet with the live retrieval path. Correct reasoning with the verified packet and an incorrect result with live data points to retrieval, identity resolution, transformation, or freshness. An incorrect result with both inputs points to instructions, reasoning, or the action interface. This split prevents a costly cycle of model changes that leave the actual defect untouched.

Write a context contract for each consequential action

Do not begin with a broad requirement such as giving the agent customer context. Begin with an action: recommend a next step, summarize an account, classify a request, draft a response, update a record, or initiate a workflow. Different actions require different evidence and different safeguards.

For each action class, write a context contract. It should define what must be present, where each value comes from, how fresh it must be, and what the agent must do when the requirement is not satisfied.

Context field	Question the contract must answer	Safe behavior when absent
Actor and scope	Who is making the request, and which tenant, workspace, or account may be accessed?	Stop before retrieval or action
Objective	What outcome is requested, and what would make the task complete?	Ask a focused clarification question
Current entity state	Which status, lifecycle stage, configuration, or open process controls the decision?	Retrieve the current state or abstain
Relevant history	Which sequence of events explains how the entity reached its current state?	State that the historical basis is unavailable
Business semantics	Which canonical definitions, units, and eligibility rules apply?	Do not invent or substitute a familiar definition
Authority	Which data may be read, which tools may be called, and which changes may be made?	Block the unauthorized operation
Evidence metadata	What system supplied each fact, when was it observed, and is it raw or derived?	Surface the uncertainty instead of hiding it

The contract turns an ambiguous product requirement into an interface that product, data, engineering, security, and operations can inspect. It also forces an important decision: which missing fields should trigger retrieval, clarification, abstention, or a hard block. Those behaviors should not be left to the model to improvise.

Business definitions deserve special attention. If active customer, qualified lead, resolved ticket, or at-risk account has more than one internal meaning, the agent needs the canonical definition for this workflow. A database column with a familiar name is not enough. Include the definition identifier, applicable scope, and relevant units so the model does not silently translate the term into its most common meaning.

Authority also needs to be explicit. The ability to call a tool is not permission to use it in every situation. A write operation should receive verified identity, allowed scope, action-specific authorization, and the preconditions for the change. If any of those are missing, the tool call should fail closed before the model can turn uncertainty into an action.

Keep the contract minimal. Every unnecessary field increases privacy exposure, retrieval complexity, and the chance that irrelevant information distracts from decisive evidence. The right question is not whether a data point might be useful. Ask whether changing that data point could legitimately change the agent’s decision. If not, it probably does not belong in the packet.

Build retrieval as a reliability pipeline, not a data dump

A long context window does not turn a warehouse export into good context. Raw volume can bury the one event, policy, or state transition that matters. An agent needs situational and behavioral evidence organized around the decision, not every record your systems can expose.

A dependable retrieval path should assemble context in a deliberate order:

1. Resolve the actor, tenant, entity, and requested action class.
2. Apply access controls before searching for records, so unauthorized data never enters the context window.
3. Fetch the current entity state from the canonical system for each required field.
4. Retrieve the smallest relevant sequence of events that explains the state, preserving order and timestamps.
5. Add the business definitions, policy constraints, and tool preconditions that govern the decision.
6. Label every material value with its origin, observation time, and whether it is observed or derived.
7. Transform the result into a stable, decision-oriented schema while preserving the raw identifiers needed for verification.

Filtering by identity and access after retrieval is too late. By then, out-of-scope information may already have influenced a summary or intermediate inference. Scope the query first, carry the scope identifier through every transformation, and verify it again at the tool boundary.

Freshness should be a field-level requirement, not a vague promise that the pipeline uses live data. Declare the maximum acceptable age for each decision-critical value. Stable taxonomy can usually tolerate a different caching policy from permissions, workflow status, inventory, or another mutable operational state. The appropriate limit depends on the action and the cost of being wrong; there is no honest universal freshness threshold.

For a write based on mutable state, use two checks. Retrieve the state while planning the action, then revalidate the decisive preconditions immediately before execution. If the state changed in between, cancel or re-plan. This closes the gap in which an agent makes a sound decision from information that becomes obsolete before the tool call runs.

Compression is often necessary, but the transformation must preserve the evidence required to challenge the result. Use these rules:

• Keep mutable facts explicit rather than burying them in narrative summaries.
• Separate observations from inferences. The agent should be able to tell a recorded event from a generated interpretation.
• Preserve sequence when order changes meaning. A list of events without chronology can imply the opposite causal story.
• Distinguish no matching event from event history unavailable. Those are not equivalent conclusions.
• Retain the system identifier and timestamp for every decision-critical fact.
• Remove irrelevant personal or sensitive data before it reaches the model.
• Resolve contradictions explicitly. Do not let the transformer silently choose whichever system answered first.

When two systems disagree, the context packet should name the conflict and apply a documented precedence rule if one exists. If no rule exists, the agent should abstain or request review. A fluent synthesis of contradictory records is still an unreliable answer.

Evaluate context assembly separately from agent reasoning

A single answer-quality score conceals the root cause. You need separate tests for context assembly, reasoning over a fixed packet, and execution through tools.

• Context assembly tests verify identity, scope, retrieval, freshness, definitions, ordering, and provenance before the model reasons.
• Reasoning tests provide a verified context packet and check whether the agent reaches the expected conclusion, asks for clarification, or abstains.
• Action tests verify permissions, preconditions, argument mapping, idempotency, failure handling, and the resulting system state.

Build evaluation cases by changing one contextual variable at a time. This makes the expected behavior inspectable and gives each failure a useful owner.

Test variation	Expected behavior	Failure it exposes
Same request, different tenant	Retrieve and use only the selected tenant’s records	Identity or scope leakage
Same entity before and after a state change	Change the decision when the new state is material	Stale retrieval or caching
Same wording, different permission	Allow, limit, or block the action as authorized	Permission inferred from intent
Same label, different business definition	Apply the definition assigned to the workflow	Semantic ambiguity
Required record missing	Clarify, retrieve again, or abstain as specified	Fabrication under incomplete context
Canonical and cached values conflict	Use documented precedence or surface the conflict	Uncontrolled source selection
Long irrelevant history with one decisive event	Find and use the decisive event	Poor selection or context dilution

For every evaluated run, retain the request, resolved identity and scope, retrieved record identifiers, timestamps, transformed context packet, model output, policy decision, tool arguments, tool result, and final state. Without that trace, a bad outcome collapses into the unhelpful diagnosis that the agent was wrong.

Your production dashboard should expose context health alongside outcome quality. Useful measures include:

• Required-field coverage: the share of eligible runs in which every field required by the action’s context contract was available.
• Freshness compliance: the share of decision-critical values that met their declared age requirement at decision and execution time.
• Scope integrity: whether every retrieved record matched the verified tenant, actor, and entity boundaries.
• Evidence traceability: the share of material claims that can be mapped back to an identifiable record and observation time.
• Safe fallback behavior: whether the agent clarified, abstained, or blocked when the contract was not satisfied.
• Action-precondition compliance: whether every tool execution met its identity, authority, state, and argument requirements.

Break those measures down by action class and context version. A blended score can hide a safe summarization workflow and an unsafe update workflow behind the same average. Set release thresholds according to the consequence of each action rather than adopting one global accuracy target.

Use a compact failure taxonomy in reviews: identity, freshness, semantics, relevance, permission, reasoning, or execution. Assign one primary category and any contributing categories to each failure. After a few release cycles, that classification tells you whether the next investment belongs in data contracts, retrieval, policy, prompts, models, or tool engineering.

Key takeaways and the next release decision

Autonomy should expand only after the context path survives realistic changes in identity, state, permission, and time. Use a staged release:

1. Observe: assemble the context packet and trace the evidence, but make no recommendation or change.
2. Draft: generate a recommendation or proposed action for a person to approve.
3. Execute within narrow bounds: permit low-impact, reversible actions with explicit preconditions and complete audit records.
4. Expand selectively: add action classes only after their context contracts, evaluations, monitoring, and recovery paths are ready.

Where an error could delete data, expose customer information, create a financial obligation, alter access, or make a binding customer commitment, keep a human approval gate or purpose-built deterministic control. Also require idempotency where repeat execution could duplicate an effect, and provide a tested recovery path where reversal is possible. Missing context must never broaden the agent’s authority.

Ownership should be as explicit as the data contract. Product owns the action classes, expected outcomes, and fallback experience. Data owners define canonical fields, semantics, and freshness. Engineering owns retrieval, transformations, tool preconditions, and traces. Security and privacy owners define access boundaries and data-minimization rules. Operations labels real failures and feeds them back into evaluations. A shared responsibility with no named owner becomes an unmaintained dependency.

Key takeaways

• Start with one consequential action and define the evidence it requires.
• Treat identity, current state, business meaning, authority, freshness, and provenance as separate context requirements.
• Filter by scope before retrieval, and revalidate mutable state before a write.
• Test the retrieval path and the model with separate evaluation suites.
• Measure context health in production instead of relying only on answer-quality scores.
• Make clarification, abstention, and blocking designed product behaviors, not accidental model responses.
• Increase autonomy by action class only after the context contract and recovery path have been proven.

For your next agent review, bring one failed or high-consequence action instead of a broad roadmap item. Write its context contract, build a verified packet, and replay the task through both the verified and live retrieval paths. That comparison will tell you whether the next release needs better data assembly, better reasoning, or a safer action boundary.

References

• Amplitude — Your agents are only as good as your data context

---