MCP docs describe a wire format the server no longer serves, and the drift gate has no obligation to notice

[serge-ivo]

The MCP docs describe a wire format the server no longer serves

platform-docs/mcp.md was last touched by #525. #561 changed what tools/list and two
tools/call results carry, and the doc was not updated with it.

Verified stale

1. mcp.md:155 is now false.

Tools return a single text content block.

e392754 added outputSchema + structuredContent to list_agents and my_instances.
Both now return a text block and structured content. Measured live on 2026-08-15:
my_instances returns {"instances":[…]} where it previously returned a bare array. That
shape change is consumer-visible and appears in no doc.

2. Annotations are absent from the docs entirely.

$ grep -rniE 'readOnlyHint|destructiveHint|annotation|outputSchema|structuredContent' platform-docs/
(no match)

b2b0ac4 and 778c5d2 put readOnlyHint and destructiveHint on all 135 tools. The
"Auth Scopes And Safety" section teaches scopes, dry_run and confirm as the complete
safety vocabulary. It is now missing the one signal a host reads before calling anything —
which is the whole reason the annotations were added.

3. The server instructions field is undocumented. 951ef59 added it; a connecting
client now receives guidance the docs never mention.

The part worth more than the prose fix

scripts/docs-drift.mjs passed on all four #561 commits, correctly. Its header states the
checks are deliberately narrow — each compares a documented number or name to the code
defining it. Tool count still equals 135; every documented confirm value still matches a
requireConfirmation site. Nothing it measures changed.

So a capability can now reach the wire with no documentation obligation attached, while a
confirm value cannot. That asymmetry is the gap: confirm is checked because a doc naming a
wrong confirm string breaks a caller, and an annotation the docs never mention is the same
class of failure one level up — a host makes a trust decision from a signal the docs do not
explain.

Acceptance criteria

1. mcp.md:155's error/result-shape section states which tools carry structuredContent, and
   that their payload is an object ({"instances":[…]}, {"agents":[…]}), not a bare array.
2. The safety section documents readOnlyHint and destructiveHint: what they mean here, that
   they are derived from the handlers rather than hand-maintained, and that idempotentHint /
   openWorldHint are deliberately omitted because there is no honest source for them.
3. The server instructions field is documented.
4. docs-drift.mjs gains a check in the same style as its existing confirm-value check: a
   tool declaring outputSchema, or the annotation vocabulary itself, must be named in the
   docs. State the denominator in the success line, per ADR 0002 — the input set is asserted,
   not assumed.
5. The new check goes red when the documentation is removed, and that is demonstrated.
6. pnpm docs:build (zensical --strict) stays green.

Verified vs inferred

• Verified: the grep, mcp.md:155's text, the four The MCP server never publishes tool annotations or output schemas — it already classifies every tool read/write/destructive and tells no host #561 SHAs, the live my_instances
  payload shape, docs-drift.mjs's header and check list, and that mcp.md's last commit is
  list_instance_tools says "a tool absent from the allowed set cannot be invoked, by chat or by call_instance_tool" — 11 tools every agent runs in chat are absent, and 2 of them ran on the audited instance #525's 7d11035.
• Inferred: nothing load-bearing. The claim is an absence and the absence was grepped.

[serge-ivo]

Landed as 7dba743. CI green, Deploy Host Worker green, and verified live on the served page.

AC 1–3, the prose

platform-docs/mcp.md now states which tools carry structuredContent and that the payload is an object ({"instances":[…]}, {"agents":[…]}) rather than a bare array; documents readOnlyHint / destructiveHint, that they are derived from the handlers rather than hand-maintained, and that idempotentHint / openWorldHint are deliberately omitted for want of an honest source; and documents the server instructions field.

Verified on https://proagentstore.online/docs/mcp/ after deploy — where grep -rniE 'readOnlyHint|destructiveHint|annotation|outputSchema|structuredContent' platform-docs/ previously returned nothing:

token	occurrences on the served page
readOnlyHint / destructiveHint	1 / 1
idempotentHint / openWorldHint	2 / 2
structuredContent / outputSchema	4 / 2
instructions	2

AC 4–5, the part that matters — one design, not two arms

#572's check and #573's are the same shape, so they are one mechanism: scripts/lib/wire-surface.mjs, a table of wire facts. A wire fact is something a client receives + the one piece of code that defines it (the authority) + optionally the line that puts it on the wire (the binding) + every place that restates it. One loop asserts the authority's floor, checks the binding, requires each restatement to be non-empty, then reuses diffConfirm verbatim from doc-claims.mjs for missing / phantom / wrong. Adding a fourth fact is a table entry. parseConfirmTable became one call into a generic parseTableColumn rather than a near-copy.

Success lines, denominators stated per ADR 0002 G2:

✓ wire surface — advertised version: 1 version(s) from 1 code file(s) == server.json (1), store/.well-known/mcp-server.json (1), platform-docs/mcp.md (1), advertised from workers/mcp/src/index.ts
✓ wire surface — tool annotations: 4 hint(s) from 2 code file(s) == platform-docs/mcp.md (4)
✓ wire surface — structured results: 2 output schema(s) from 1 code file(s) == platform-docs/mcp.md (2)

The input set is asserted, not assumed: every authority carries a floor with the reason it is where it is, a restatement that yields no claim is a failure rather than a skip, and a listed path that does not exist is a failure rather than a skip. A fact that fails now prints no ✓ at all — the first draft printed == no restatement read beside a tick while the same fact was failing, which is exactly the tick this check exists to refuse.

AC 5, demonstrated — I reproduced it myself after rebasing, not just on report. Deleting the hint-table rows from mcp.md (copy/restore through a scratchpad; no git stash, which is repo-global here):

✗ [wire-surface] tool annotations: platform-docs/mcp.md states nothing, read via the `Hint` / `Published` table in its safety section.
  the `annotations` object on every tool in `tools/list` reaches every client whether or not this file mentions it. A deleted or
  rephrased paragraph must not read as agreement — that is the failure mode #555 shipped.

1 drift(s).

pnpm docs:drift exit 1. Plus six more red arms driven over in-memory files in scripts/lib/wire-surface.test.mjs.

AC 6: pnpm docs:build (zensical --strict) green.

Sharper than the issue

The vendored spec schema is the right authority for the annotation vocabulary, which the issue did not suggest. "Which hints exist" is read from mcp-schema-2025-11-25.json's ToolAnnotations and split by what tool-metadata.ts declares — so a fifth hint added by MCP arrives through the schema bump rather than through someone remembering to extend a hand-written list. The guard cannot fall behind the spec.