The mcp_decisions table: making AI decisions auditable

It is easy to say a platform is transparent. It is harder to make transparency a queryable fact. On TaskMatch, the mechanism behind that claim is a single append-only table called mcp_decisions. Every consequential decision the orchestration layer makes writes a row to it, and nothing that affects a client’s work happens off the record.

The premise is simple: if an AI system is going to make decisions on your behalf — how to interpret your brief, how to split it, which agent to trust with it — you should be able to inspect each of those decisions after the fact, not take them on faith.

What counts as a decision

We log a decision anywhere the platform exercises judgment that a reasonable person might want to question later. Concretely, that includes:

• Formatting — how a plain-language brief was turned into a structured spec, including what the model inferred versus what the client stated.
• Decomposition — how a job was split into tasks and why the dependency graph looks the way it does.
• Matching and ranking — the per-factor bid scores and the winning selection for each task.
• Validation — which checks ran, what they returned, and whether human review was invoked.

The shape of a row

Each row captures the decision type, the entity it concerns, the inputs the decision saw, the output it produced, and a rationale. Where an LLM was involved, we record the model and the prompt version so a decision can be tied to the exact behavior that produced it. A simplified schema:

CREATE TABLE mcp_decisions (
    id            BIGSERIAL PRIMARY KEY,
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    decision_type TEXT NOT NULL,          -- format | decompose | match | validate
    job_id        BIGINT,
    task_id       BIGINT,
    inputs        JSONB NOT NULL,         -- what the decision saw
    output        JSONB NOT NULL,         -- what it produced
    rationale     TEXT,                   -- human-readable explanation
    model         TEXT,                   -- null for deterministic decisions
    prompt_version TEXT
);

Deterministic and probabilistic decisions live side by side

One nuance: some decisions are deterministic (bid ranking) and some are probabilistic (reading a brief with an LLM). The table holds both, distinguished by whether the model column is populated. For deterministic rows, the inputs and the code version are enough to replay the decision exactly. For probabilistic rows, we cannot guarantee identical replay, so the rationale and the recorded output are what you inspect instead.

Keeping both in one place matters because a client tracing why their job went a certain way does not care about that internal distinction. They want the whole causal chain in one query, from how their brief was read all the way to which agent got paid.

What this unlocks

Auditability is not just a compliance nicety; it changes how the product can behave. Because the decisions are logged, the dashboard can show a client the reasoning behind their job’s execution in plain language. Support can answer “why did this happen” by reading rows instead of guessing. And when we change a prompt or a weighting, we can measure the effect on real decisions rather than reasoning in the abstract.

It also disciplines us as builders. When you know every decision your system makes is written down and inspectable, you design decisions you would be comfortable defending. The table is as much a constraint on our behavior as a window for the client’s.

Append-only on purpose

The table is append-only. Decisions are never edited or deleted; a correction is a new decision that supersedes an old one, and the old one stays visible. That is what makes the log trustworthy rather than a story we could rewrite. An audit trail you can quietly change is not an audit trail. This one you cannot.