Structured and unstructured context for AI agents: why documents aren't enough

The contract stated the rule. Nothing checked whether it applied.

A manufacturer uses an AI application to calculate annual supplier rebates. One agreement pays 5% when net eligible purchases exceed $10 million, provided there's no active compliance hold at payment time.

The application retrieves the agreement and amendments. A model correctly extracts the percentage, the threshold and the hold condition. A warehouse query returns $11.2 million in gross purchases. The model calculates a $560,000 rebate and produces a valid payment proposal.

The deciding facts were elsewhere. A feature that computes net eligible purchases after returns and exclusions shows $9.7 million. The vendor master shows a compliance hold placed that morning. A policy rule bars payment while a hold is active. An event records when and why the hold was created.

None of it reached the decision. The payment went for approval as though the agreement and a gross total were the full picture.

The extraction was correct. The gross figure was correct. The arithmetic was correct. The proposal satisfied its schema. The failure was treating the document store as the system of record for a decision that depended on a ledger, a feature, a hold and a policy.

Why can't AI agent decisions live in documents alone?

Because documents explain obligations, while other systems establish whether those obligations are currently met: ledgers hold state, features calculate derived facts, policy constrains action and events record change. A decision needs both kinds of source, joined without losing type, time or authority.

"Enterprise context" hides very different kinds of information. A clause, a balance, a calculated exposure, a policy decision and an event are all context, but they don't carry the same meaning or weight.

A robust design keeps these distinctions. Pasting every value into prose and asking a model to infer the relationships throws them away.

A fact is more than a field and a value

The same number can mean gross purchases, net eligible purchases, an annual cap, a forecast or a model estimate. A field name and a value don't tell you which.

Which source owns each fact?

Declare, fact by fact, which system is authoritative, which only supports it, and how disagreements resolve. A source can be highly relevant without being the one allowed to establish the fact you need.

Several systems often hold values that look like the same thing. Don't force everything into one database. Write down what each source may establish:

Join sources by identity, not by label

Joining a clause, a transaction set, a feature, a policy fact and an event is a question of meaning, not plumbing. You have to show they refer to the same resource, period, units, legal entity and purpose. A join on supplier name or amount can look fine while connecting the wrong entity or year.

• Bind every item to stable tenant, legal entity, resource, contract, case and period IDs.
• Declare mappings between document concepts, fields, feature definitions, events and policy facts.
• Check units, basis and enum meaning before values become interchangeable.
• Carry scope and ownership through every transformation instead of rebuilding them later.

For the wider pipeline these joins sit in, see context assembly beyond RAG.

Should you turn database results into prompt text?

Only as an explanation layer, never as the sole form of facts a decision acts on. Flattening rows into prose erases types, units, nulls, ownership and time, and invites the model to recalculate values or settle conflicts that rules should handle.

Not every fact belongs in the prompt at all. One governed context package can give each consumer the view it needs:

One source of truth, several views. That avoids both extremes: one giant prompt, or several unrelated versions of the same case.

Fix the decision time before you combine anything

Sources rarely share a clock. A contract is effective for years. A feature was calculated at yesterday's close. An event happened seconds ago. A policy is published today but effective next week. A record may change while the case waits for approval.

Declare the decision time and what each source's time means: when it took effect, when it was observed, which historical state you're evaluating, which record revision, when it expires and what forces a refresh. Bundle the compatible facts into one snapshot for that decision time. That doesn't mean copying every source into one store; it means binding the IDs, values, versions and time meanings needed to explain the decision. For long-running cases, keep the original snapshot as evidence, and recheck current authority, state and policy right before any change.

Is a missing value the same as false or zero?

No. Missing can mean not found, not authorized, stale, unavailable, not applicable or unknown, and each needs a different response. Collapsing them into null, false or zero turns uncertainty into a convenient default.

In the rebate case, "no hold found" because the vendor master timed out is not the same as "no hold." Treating it that way pays a supplier you're not allowed to pay.

Conflicts are a governed state, not a model's choice

Sources legitimately disagree. An amendment conflicts with the master agreement. A warehouse snapshot lags the ledger. An event says a transition happened while the record still shows the old revision. A model extraction differs from a parser.

Don't let prompt order or a similarity score decide. Check conflicts against declared ownership, precedence, time, scope and materiality, and return a typed result: consistent, precedence applied (with the displaced item kept in lineage), time mismatch, scope mismatch, meaning mismatch, needs review, or no owning source declared. Record which sources were compared and which rule or person resolved it.

Features, events and documents each carry their own weight

Features shape behavior. Exposure, prior-event counts or eligibility flags can be as consequential as any retrieved document. Keep the definition version, window, units and lineage with the value. Change the definition and the application's behavior changes, even if no workflow step or document did. More on that in feature stores for agent decisions.

Events describe what happened; operational state says what's still true. A hold-placed event doesn't prove the hold is still active. A payment-requested event isn't a payment receipt. A document-uploaded event isn't proof it passed validation.

Documents inform judgment but never become authority. Contracts, emails and web pages can contain text that reads like an instruction, and OWASP ranks prompt injection as the top LLM risk. A document can support an interpretation; it can't create policy or grant a tool permission.

Common anti-patterns

Ten rules for combining structured and unstructured context

1. Treat documents, operational facts, features, policy, events and human input as distinct kinds of context.
2. Declare which source owns each fact.
3. Give every consequential value its meaning, unit, time, status, scope and lineage.
4. Join by stable IDs and declared mappings, never by matching labels.
5. Fix the decision time and each source's time meaning.
6. Keep false, zero, missing, denied, stale and unknown distinct.
7. Resolve conflicts by declared rules and record the resolution.
8. Version feature definitions, transformations and event meanings.
9. Give each consumer its own view of one shared source of truth.
10. Recheck current state and authority right before any change.

The result: rules and facts meet in one decision

Documents explain. Operational systems establish state. Features calculate. Policies constrain. A database row can tell you the current state without explaining what it means contractually, and a contract can explain the meaning without telling you the state. Enterprise decisions need both.

The answer isn't one storage engine or one enormous prompt. It's making each source's role explicit and joining them by identity, time, ownership and policy inside the same workflow. The complexity doesn't go away. It becomes inspectable, testable and governable.