# Codebook: write-outcome signals in MCP server source

Version 1.1, 15 Nov 2026. Version 1.0 was written by the second coder before any server was re-coded and before the first coder's per-server table was opened. Version 1.1 adds the fixes made during adjudication (F11, F12, section 5) and the worst-path rule for wrapper losses (section 4); the extension was coded under 1.1. Applies to `recode-44.csv`, `extension.csv` and the adjudicated combined sample.

## 0. Unit, evidence and procedure

- **Unit.** One packaged MCP server (npm or PyPI package) at the census version (`sample-order.csv`, column `version`).
- **Source.** npm: `npm pack <pkg>@<ver> --ignore-scripts`. PyPI: `pip download --no-deps --only-binary=:all:` (a wheel); if no wheel exists, the sdist is fetched by its PyPI URL and unpacked, never built, because `pip download` of an sdist runs the package's build code. GitHub only when the package ships a native binary or no readable source. Each package is unpacked into its own empty folder and deleted after coding. No downloaded code is run, imported or built.
- **What is read.** For each server: the registration of the census write tools, 1 to 3 write handlers (preferring update/delete/create over local side effects), and every shared wrapper they pass through (result builder, error handler, HTTP client). Where tools differ, the code describes the server's *best* write handler for C1 to C6 (a server "has" a signal if any read write tool returns it) and its *worst* for C7 (a server has failures without `isError` if any read write path returns one). This asymmetry is deliberate and stated in the write-up.
- **Evidence.** Every code of 1, and every judgment call, cites `file:line` (or a unique code string for minified bundles).
- **Unreadable.** A server whose write path cannot be traced (only a native binary, or a minified bundle where the handler cannot be found) is coded `unreadable` and excluded like a server with no source.

## 1. Eligibility

**E. Real write.** `1` if at least one census write-class tool, on reading, changes state outside the call: a remote service, a file, a database, a process or device, an application document. `0` if every census write tool only reads, computes, or changes state private to the call (a scratch buffer discarded on return, a cache, a log of its own). Servers coded `0` are recorded and excluded from every denominator.

- Decision rule: running a check, a scan or a linter is not a write, unless the tool has a mode that rewrites files (a `--fix`), in which case it is.
- Starting, stopping or navigating a browser or app *is* a write (it changes a process's state that later calls observe).
- A write gated behind a non-default flag counts if the code is in the package.

## 2. Result shape (descriptive)

**S. Success shape**, from the read write handlers:
- `P`: prose only (text content not parseable as a JSON object, or a JSON-looking string assembled for humans);
- `JT`: a JSON object serialised into a text block, no `structuredContent`;
- `SC`: `structuredContent` returned (by the handler or by the framework from a typed return, e.g. FastMCP with an output schema).

## 3. Signals (each 0/1 unless stated)

**C1. Any machine-readable success/failure flag.** `1` if a write result (success or error path) carries a member whose value states whether the write took effect, in a JSON object the client can parse: a boolean (`ok`, `success`, `applied`, `updated`, `created`, `deleted`) or an enum (`status`/`state`/`kind`/`outcome` with values like `applied`, `failed`, `not_applied`).

- Counts in `structuredContent` or in a JSON object serialised as the whole text block.
- Does **not** count: `isError` alone (every protocol-conformant error has it; the question is about content); a success word in prose; a resource echo with no outcome member (`{"id": 5, "name": …}`) even though its presence implies success; an HTTP status number alone (that is coded under W1).
- An echoed backend body counts only if the server's own code reads, builds or documents the flag (e.g. it checks `res.success` and forwards it). An opaque echo counts 0 unless the flag is visible in the server's code or its bundled types.
- **C1sc**: same, restricted to `structuredContent`.

**C2. Distinguishes "unknown" from "failed".** `1` if the write's own result can carry a machine-readable value that itself means the outcome is not known or may have applied: `unknown`, `indeterminate`, `maybe_applied`, `outcome_unknown`, `submission_uncertain`, `paid: null` with state `unknown`. (Version 1.1, after adjudication, fix F11. Version 1.0 also counted a timeout status or kind kept distinct from definite failures whose documentation or naming says the write may have happened; under 1.1 such a code with a prose hint is C2p.)

- A thrown `TimeoutError` whose name ends up only in message text is `0`.
- A generic error enum where timeouts share a value with refusals is `0`.
- A later call that reports an earlier attempt as unknown does not make the earlier call's own result C2 = 1.
- **C2p** (descriptive): `1` if C2 is 1 or the server says "unknown / may still be running / may have been applied / partly applied" in prose.

**C3. Safe-to-repeat or replay signal.** `1` if a write result carries a machine-readable member that tells the caller whether repeating the call is safe, or that this result is a replay: `retryable`/`should_retry`/`safe_to_retry`, `replayed`/`idempotent_replay`, or the idempotency key or dedupe receipt returned on a failure or unknown path so the caller can repeat it safely.

- A rate-limit `retry_after` member counts only if it is structured and attached to a refusal (a 429 was not applied, so it says the repeat is safe).
- An idempotency key that the caller supplies and the server merely forwards does **not** by itself count (coded under C6).
- An idempotency key or receipt returned *only on success* does not count (it says nothing about repeating a failed call).

**C4. Structured conflict with current state or version.** `1` if, when a write is refused because the target changed (version/etag mismatch, conditional-check failure, 409/412), the result carries in machine-readable form (a) that it was a conflict and (b) the current version, etag, sha or current state of the target.

- **C4a** (descriptive): (a) without (b), i.e. a structured conflict code or kept 409/412 with no current state.
- An opaque echo of a backend body counts only if the code or its comments show the backend body carries the current state (e.g. DynamoDB `ConditionalCheckFailed` with `ReturnValuesOnConditionCheckFailure`).
- Git merge conflicts, geometry conflicts and name collisions with no version semantics count 0 for C4 and C4a.

**C5. Per-item results.** Applies only where a read write tool is bulk (writes several objects) or multi-step (sends several dependent writes); `B = 1` for those, otherwise C5 is `NA`. `C5 = 1` if the result reports each item's or step's outcome in machine-readable form, including on the error path.

- A partial failure that raises a single error and loses the successful items is `0`.

**C6. Accepts an idempotency key.** `1` if a write tool takes an idempotency key, request id or dedupe token that the server uses (forwards to the backend or checks itself).

**B9. Full B-9 set.** `1` if C1sc = 1 and C2 = 1 and C3 = 1, all carried in `structuredContent`. **B9+** (descriptive): B9 and C4.

**C7. Failures returned without `isError`.** `1` if on any read write path a definite failure of the requested write (caught exception, backend refusal or error status, `success:false`, input refusal) is returned as an ordinary result without `isError: true`.

- Python FastMCP/low-level tools that `return "Error: …"` or return an error dict instead of raising count `1`.
- A result that says "failed" in prose but is not flagged is `1`.
- A tool that returns the backend's body unchecked, so that a 4xx body comes back as a normal result, is `1`.

## 4. HTTP wrappers

**H. Wraps a remote HTTP API.** `1` if the read write handlers send HTTP(S) requests (directly or through the vendor's SDK) to a service that is not part of the package. `0` for local tools (files, editors, browsers, CLIs, desktop apps over a local socket or bridge) and for database wire protocols (SQL, Redis, Bolt, ClickHouse native or its HTTP interface used through a DB driver). A server talking to a localhost daemon of the same product (e.g. a desktop app's local API) is `0`.

For H = 1 only. W1 and L1 to L5 describe losses, so they are coded on the **worst** read write path: a loss present on any read write path counts. (Rule added during coding at server 35, before any comparison with the first coder; the one earlier wrapper it changed, order 13, was re-coded under it.)

**W1. Status or code.** `K` (kept): the backend's HTTP status or the API's own error code is returned as a machine-readable member on the error path. `P` (prose): it appears only in message text. `D` (dropped): it does not reach the caller at all.

**L1 to L5, the five loss patterns** (each `1` = pattern present, `0` = absent, `NA` = not applicable):

- **L1. Status turned into prose or discarded.** `1` if W1 is `P` or `D`.
- **L2. Refusal returned as a non-error or success.** `1` if a backend refusal (4xx, or an API-level `ok:false`/`errors` body) can come back without `isError` (subset of C7 restricted to backend refusals).
- **L3. Conflict check switched off.** Applicable when a read write targets an API resource that offers a version/precondition check (etag/If-Match, `sha`, `resourceVersion`, `version`, `overwrite` flag defaulting to refuse). `1` if the wrapper hard-codes force/overwrite, fetches the current version itself and sends it, or omits a precondition the API requires or offers, with no way for the caller to supply it. `0` if the caller can pass the version and the API's refusal reaches the caller. `NA` if no such check is visible in the code or known for the API.
- **L4. No answer collapsed into "failed".** `1` if a timeout or connection loss after sending is returned as a definite failure (`isError` or `success:false`) with no unknown marker (i.e. H = 1 and C2 = 0). `0` if C2 = 1. L4 is coded at server level, an exception to the worst-path rule above: on the worst path nearly every wrapper has one write whose lost answer becomes a failure, which would make the code uninformative.
- **L5. Idempotency not passed through or not given back.** Applicable when the read write's API accepts an idempotency key (visible in the SDK/client code, or a documented key on a well-known API such as Stripe). `1` if the wrapper does not let the caller pass one, or generates one and does not return it on failure. `NA` otherwise.

## 5. Fixes to the first study's definitions

Each fix was made before re-coding, because the first study's wording admits more than one reading.

| # | First study | Ambiguity | Fix in this codebook |
|---|---|---|---|
| F1 | "any machine-readable applied/failed flag (`ok`, `success`, `kind`, `state`), text JSON included" | Whether `isError` alone, a resource echo, or an opaque backend echo counts | None of the three counts (C1 rules). |
| F2 | "distinguishes unknown from failed in a machine-readable form" | Whether a distinct timeout error type counts | Counts only if kept distinct from definite failures *and* its meaning is "may have applied"; an exception name in message text does not (C2). |
| F3 | "safe-to-repeat or replay signal (`retryable`, `replayed`, dedupe receipt)" | Whether accepting a key, or returning a key only on success, counts | Neither counts; those go to C6 (C3 rules). |
| F4 | "structured conflict carrying current state or version" | Whether JSON text counts, whether 409 alone counts | JSON text counts (as in C1); a conflict without current state is C4a, not C4. |
| F5 | "the whole B-9 set (outcome + unknown + repeat), in `structuredContent`" | Whether conflict is part of the set | Kept as outcome + unknown + repeat in `structuredContent` (B9), for comparability; B9+ adds conflict. |
| F6 | "some failures returned without `isError`" | Best vs worst handler | C7 is coded on the worst read path; C1 to C6 on the best. |
| F7 | "wraps a remote HTTP API" | Database clients, local daemons | Excluded from H (section 4). |
| F8 | Status "kept" Y/P/N | "P" undefined | `K`/`P`/`D` defined in W1. |
| F9 | Five loss patterns described in prose only | No per-server rule | L1 to L5 with applicability (section 4). |
| F10 | "real writes" | Check/lint tools that can fix, gated writes | Rules under E. |

### Fixes made during adjudication (after the comparison with the first coder)

These two rules were tightened after the agreement statistics were computed and before the extension was coded. The pre-adjudication agreement figures were computed under the version-1.0 wording; every adjudicated code and every extension code uses the fixed wording.

| # | Rule as first written | Problem found | Fix |
|---|---|---|---|
| F11 | C2 counted "a status/kind for timeout or connection loss after the request was sent … whose documentation or naming says the write may have happened" | Under that wording any server that passes an HTTP 504 through, or names a timeout code and adds a prose hint, would count as saying "unknown". It made C2 depend on prose. | C2 = 1 only when the write's own result carries a value that itself means unknown or uncertain (`unknown`, `outcome_unknown`, `submission_uncertain`, `paid: null` with state `unknown`). A timeout code with a prose hint is C2p. |
| F12 | C7 silent on batches | A batch tool that returns per-item results without `isError` even when every item failed | Counts as C7 = 1 (and L2 = 1 for a wrapper): the requested write failed and the result is not flagged. A batch with some items applied and some failed is not by itself C7. |

## 6. Examples (illustrative; constructed, not from sampled servers)

| Snippet | Codes |
|---|---|
| `return {content:[{type:'text',text:'Updated issue #4'}]}` | S=P, C1=0 |
| `return {content:[{type:'text',text:JSON.stringify({success:true,id})}]}` | S=JT, C1=1, C1sc=0 |
| `except Exception as e: return f"Error: {e}"` (FastMCP) | C7=1 |
| `catch(e){ return {isError:true, content:[…], structuredContent:{ok:false, status:e.response?.status}} }` | C1=1, C1sc=1, W1=K, L1=0 |
| `{outcome:'unknown', reason:'timeout after send', retry:{same_key:true}}` in `structuredContent` | C2=1, C3=1 |
| `if (res.status===409) return {isError:true, structuredContent:{code:'conflict', current_etag: res.headers.etag}}` | C4=1 |
| `axios.put(url, body, {params:{overwrite:true}})` with no caller version | L3=1 |
| `const key = crypto.randomUUID(); …; return ok({key})` only on success | C6=1 (if caller can also pass one) else 0; L5=1; C3=0 |
