How to Ask an AI Agent "Why Was This Order Held?" and Get the True Answer
A customer writes to support: order 58213 was held for review last Tuesday, and they want to know why. Support asks engineering. Engineering opens the rule that holds orders and reads it: hold orders over $10,000 from new customers. The order was $7,450. By that rule it should never have been held. A bug?
No. The rule changed on Thursday. Last Tuesday the limit was $5,000. Someone remembers that eventually, or finds it in a release note, and the answer reaches the customer two days later.
Now put an AI agent in the middle. Ask it "why was order 58213 held?" and give it access to the rules. It reads the same rule engineering read, and it gives the same wrong answer, only faster and with more confidence: the order doesn't meet the hold criteria, so this may be a bug. The model didn't reason badly. It reasoned from the wrong evidence. An explanation is only as true as what it's built from, and today's rule is not what decided last Tuesday's order.
The fix is to give the agent the record of the decision, not the rule. This article shows how to do that in a .NET application with Code Effects 7: the Audit library records every production evaluation, and the embedded MCP server lets an AI agent find that record, replay it and explain it.
What a true answer needs
To explain one automated decision, four facts have to come from the moment it was made:
- The rule version that ran. Rules change. The one that decided the order may not be the one that's live today.
- The values it read. Data changes too. The customer's account was 12 days old last Tuesday; today it's 18. Run today, a rule that checks account age reads a value it never saw when it decided.
- The path it took. Which conditions held, which branch ran, what it set.
- The rules it called. A reusable rule such as New customer has versions of its own.
None of that can be reconstructed afterwards with certainty. It has to be recorded when the decision is made.
Step 1: Name the business case on the source object
Rules in Code Effects are written against a source object, an ordinary C# class. One attribute tells agents which field identifies the business case:
[Source(CorrelationField = nameof(Number))]
public class Order
{
[Field(DisplayName = "Order number")]
public string Number { get; set; } = "";
[Field(DisplayName = "Order total", Min = 0)]
public decimal Total { get; set; }
[Field(DisplayName = "Account age in days", Min = 0)]
public int AccountAgeDays { get; set; }
[Field(DisplayName = "Status")]
public OrderStatus Status { get; set; } // Pending, Approved, Held
}
CorrelationField is for agents only; the rule editor ignores it. It tells an agent that a question about "order 58213" is about the evaluations recorded under the correlation ID 58213, so the person never has to explain the application's internals.
Step 2: Record every production decision
The application loads the live rules through Audit, attaches Audit to the engine once, and evaluates as usual:
public sealed class OrderRules
{
private readonly AuditRecorder audit;
private readonly AuditRuleset rules;
private readonly Evaluator<Order> evaluator;
public OrderRules(AuditRecorder audit)
{
this.audit = audit;
// The live versions, loaded through Audit so every run is recorded
this.rules = audit.GetRules(RuleQuery.BySource("Shop.Order"));
var parameters = new EvaluationParameters();
audit.Attach(parameters);
this.evaluator = new Evaluator<Order>(this.rules.Xml, parameters);
}
public void Review(Order order)
{
// The order number is the correlation ID: how the record is found again
using(this.audit.Scope(correlationId: order.Number))
{
foreach(AuditRule rule in this.rules.Rules.Where(r => !r.IsCalled))
this.evaluator.Evaluate(order, rule.Id);
}
}
}
AuditRecorder is created once for the application (a singleton in ASP.NET Core) with the Rule Repository's database provider. GetRules returns the live versions of the source object's rules, plus every reusable rule they call, as one ruleset. The loop skips the called rules (IsCalled), because they run inside the rules that call them and are recorded as part of those evaluations.
From then on, each evaluation leaves a record with:
- the rule version and source version that ran, and the version of every rule it called;
- each value the engine actually read, as it read it;
- the return of every method the rule called, and the arguments of every action;
- the result, the branch that ran and what that branch set;
- the correlation ID, the user it ran for, when it ran and how long it took.
Recording stays off the decision's path. By default a record is appended to a local journal file in microseconds and a background thread moves it into the database. If the database is down, records wait in the journal. A synchronous mode is available for decisions that must not be acted on unless they're recorded.
The record is only half of it. The other half is that the version it names still exists. Rule versions are immutable, and a version that has ever been live can't be deleted (only deleting its whole source object removes it). Six months later, version 3 is still there, exactly as it ran.
Step 3: Give the agent the record over MCP
The MCP server is one endpoint in the same application, behind its own authentication:
builder.Services
.AddCodeEffectsMcp(options =>
{
options.MapCaller = (user, http) => Callers.Map(user);
})
.WithRepository(repository => repository.DbProvider = db)
.WithAudit(audit => audit.DbProvider = db);
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapCodeEffectsMcp("/mcp").RequireAuthorization();
MapCaller is the application's own code: it turns the signed-in user into a caller with an identity and permissions. People sign in through the identity provider the application already uses, such as Microsoft Entra ID, and add https://your-app/mcp to the AI client they already use. The agent then works as that person, with that person's permissions.
Among the server's tools, four answer questions about past decisions:
evaluation_find: the recorded evaluations, filtered by rule, correlation ID, result, user or period.
evaluation_get: one record, with the versions, the values read and what was set.
evaluation_explain: one record replayed step by step.
explain_outcome: why a business case got a value, meaning which rule set it, through which branch, on which values.
explain_outcome and evaluation_explain replay the record, which counts as a test run, so they need both the Rule Repository and Audit added to the server and a person allowed to view evaluations and run tests. With Audit alone, an agent can read what was recorded but not replay it. The Rule Repository's built-in AI Assistant has the same tools, for people who'd rather ask inside the Rule Repository than in their own AI client.
Step 4: Ask
Back to order 58213. Condensed, the exchange goes like this:
- A support lead asks Claude: "Why was order 58213 held last Tuesday?"
- The agent knows from the source object that the order number is the correlation ID, and calls
explain_outcome with 58213 and the field Status.
- The answer comes from the record. The rule Hold risky orders, version 3, set Status to Held through its THEN branch. Its first condition, Order total greater than 5,000, held with a total of 7,450. Its second is the reusable rule New customer: Account age in days less than 30, held with 12. The answer also lists the other rules that ran for this order, kept apart, since they didn't set Status.
- The agent replies in plain words: "Order 58213 was held by Hold risky orders, version 3, the version live at the time. Its total, $7,450, was over that version's $5,000 limit, and the account was 12 days old, which made it a new customer. Version 4, live since Thursday, raised the limit to $10,000."
The support lead asks a follow-up: "Would it be held today?" The agent runs the current version on the recorded values with rule_try, which records nothing, and answers no.
The agent didn't work out the explanation, and that's why the answer can be trusted. It reported what happened. The replay runs the exact version from the record with the engine's tracer on. Every value the rule reads is answered from the record, and every method call returns what it returned in production. Actions are recorded, not run, so nothing happens for real: no email goes out a second time. Production never paid for the trace. It's rebuilt only when someone asks.
What to watch for
- Records are production data. They can hold personal data.
AuditSettings.ExcludedMembers keeps chosen fields out of every record, and only people allowed to view evaluations, and their agents, can read them. The server also tells agents to show the person only what they asked about.
- Only rules loaded through Audit are recorded. Rules loaded from a file or through another query run, but leave no record.
- By default only the values the rule read are recorded. That's all a replay needs, and it's cheap. To record every declared field, for a stricter audit or richer tests, set
RecordValues = AuditValues.AllFields, but not on classes with lazy-loaded or expensive properties. Agents are told that a field the rule didn't read never explains a decision.
- A cached evaluator records what it actually ran. If a new version goes live and the application hasn't reloaded its rules yet, the records name the old version. That's the honest answer, and it can explain a surprise like "the fix was approved, why are orders still held?"
Beyond one order
The same records answer bigger questions. evaluation_summarize shows how each rule fared over a period, including live rules that never ran. outcome_rates counts how often orders were held before and after version 4 went live. And when a decision should keep coming out the same way, the agent can save the evaluation as a test with test_create, so the next version of the rule is checked against a real case. It asks first, because the test keeps a copy of the recorded data.
Try it
The Rule Repository, Audit and the MCP server are part of the commercial Code Effects packages. The rule editor and engine are free for personal, community, development and research use, as the CodeEffects.Rule.Editor.Personal and CodeEffects.Rule.Engine.Personal packages on NuGet. The documentation covers each step:
How do other teams answer "why did the system decide that?" today? Logs, a decision table in the database, the engineer who remembers? Share your approach in the comments.
Date: November 16, 2026