/user-value-chain-glossary

name: user-value-chain-glossary
description: Defines every member of MCPJam's user-value chain vocabulary — the six stages, the five stage states, the twenty-nine stage reasons, the seven failure categories, the four verdicts, the stage-analytics exclusion classes, the five friction signals and the nine suspected conditions, and the swarm findings vocabularies — plus the population rules that decide what a count means. Use when reading a `decisionSummary`, a stage chain, a trial's `frictionSignals` or `suspectedConditionVerdict`, or stage analytics returned by MCPJam's eval tools and you need to know what a wire value means or whether a number can be compared.

The user-value chain, member by member

MCPJam's eval results travel as WIRE ENUMS: `userValue`, `argumentMismatch`, `evaluatorErrorRateAboveMaximum`. That is correct on the wire and useless without definitions, and the meanings are not derivable from the spellings. This is the definition of every member.

**The story these values tell, in order:** what was decided → how much was measured → where the chain broke → the evidence supporting that → who should look next. The decision summary says what the eval decided. The user-value chain explains how far value travelled, where it stopped, what evidence supports that claim, and who should investigate next.

**Source of truth.** Every word below is copied from `sdk/src/contract/decision-labels.ts` (the label maps), `sdk/src/contract/chain.ts` (stages, states, categories), `sdk/src/contract/stage-derivation.ts` (`STAGE_REASONS`), `sdk/src/contract/stage-analytics.ts` (exclusion classes, parity) and `sdk/src/contract/friction-signals.ts` (friction signals, suspected conditions). A test in `mcp/tests/` asserts this file names every member of `DECISION_LABEL_VOCABULARIES` and quotes each label verbatim, so drift here fails the build rather than misinforming you.

The one rule that matters most

**A first failed stage is a LOCATION. A failure category is a BUCKET. Neither is a cause, and neither on its own authorizes proposing a change to the server under test.** The nearest thing to a cause is the `reason` on that stage's own row — and even that says what was observed, not what to fix.

The six stages

They run in this order, and **the order is normative**: `notReached` is derived from position — but only over a stage that decided nothing of its own. A stage AFTER the first failure that has its own evidence keeps its measured verdict; the derivation overwrites only the rows that were otherwise `notMeasured`. A case whose `selection` failed on a stray call still made the expected call and still ran its predicates, and those rows say so.

`connection` → `discovery` → `selection` → `call` → `response` → `userValue`

| Wire value | Words | The question it answers | What good looks like | | --- | --- | --- | --- | | `connection` | Connection | Could the client reach the server and initialize a session? | Session connected | | `discovery` | Discovery | Did the client receive usable primitives and metadata? | Tools and resources discovered | | `selection` | Selection | Did the model choose the right tool for the request? | Right tool selected | | `call` | Tool call | Was the call made with usable arguments? | Valid call made | | `response` | Response | Did the server return data the model could use? | Usable response returned | | `userValue` | User value | Was the user's actual request satisfied? | Request satisfied |

The five stage states

The three non-verdicts are three different facts. Collapsing them is how "we never checked" gets read as "it passed".

| Wire value | Words | What it means | | --- | --- | --- | | `passed` | passed | Measured, and the link held. | | `failed` | failed | Measured, and the link did not hold. | | `notReached` | never ran (an earlier stage failed) | Position, applied only to a stage that decided nothing of its own: the chain broke upstream and that is why nothing is known here. Not a verdict about this stage — and not applied to a later stage that WAS measured, whose own rows survive. | | `notMeasured` | not measured | The stage was reached and this run captured nothing that could decide it. **Not a pass.** | | `notApplicable` | not applicable to this case | The authored case asserts nothing this stage could decide. **Not a pass.** |

The twenty-nine stage reasons

Each completes the sentence "…because <reason>". A CLOSED vocabulary: render what arrives, never widen it.

**Nothing could be measured**

| Wire value | …because | | --- | --- | | `noSpanChannel` | this run captures no evidence channel for that stage | | `noEvidenceCaptured` | nothing eligible for that stage was captured | | `matchVerdictUnavailable` | extra tool calls were captured but the run did not report whether its match options tolerate them | | `traceAbsent` | the iteration recorded no trace | | `executorEmitsNoSpans` | the executor emitted no spans | | `blockedByPolicy` | a policy blocked the run before it could be measured | | `evaluatorError` | the evaluator itself failed, so the run says nothing about the server | | `providerError` | the model provider failed the call, so this stage was never measured | | `setupAborted` | the environment was never prepared, so the test never began | | `connectFailed` | the configured server was reached and initialize failed there | | `toolsListFailed` | initialize succeeded and listing tools failed | | `egressUnverified` | the connection failed with no evidence that our own network egress works | | `lifecycleStopped` | the run was stopped mid-flight |

A `setupAborted`, `egressUnverified`, `connectFailed` or `toolsListFailed` row may carry the producer's one-line explanation in `evidence.predicateReasons` — "rejected the stored token (invalid_token)", "MCPJam could not reach its authorization server" — the same slot judge reasons use. It explains the state; it never changes it.

**The stage does not apply**

| Wire value | …because | |