list_instance_tools and the published docs still tell operators to audit external reach by filtering on connector — the proxy #584 disproved

[serge-ivo]

The auditing surface still tells an operator to use the proxy #584 proved wrong

#584 established that "names a connector" is not "reaches outside the platform", and shipped a
server-sent reach: "platform" | "machine" | "internet" field (workers/api/src/lib/tool-reach.ts,
31194df). The advice that field replaced is still published in two places.

1. The MCP tool description an operator reads. workers/mcp/src/instance-tools/base.ts:133,
final sentence of list_instance_tools:

To audit reach into EXTERNAL systems specifically, filter on connector.

2. The published docs. platform-docs/mcp.md:394:

To audit reach into external systems specifically, filter on connector.

Why this is a defect and not stale prose

connector is wrong in both directions, both measured by #584:

• Under-reports. fetch_url has no connector and takes a caller-chosen method. Filtering on
  connector hides it — which is why 10 of 34 instances were told they had no tool reaching
  outside the platform while fetch_url was allowed:true on all ten.
• Over-reports. Every supervision tool names a connector and never leaves the platform.
  Filtering on connector reports external access to a system that does not exist.

So an operator following this sentence gets a false negative on the case that matters and a false
positive on the case that does not. It is the #584 bug restated as guidance, on the one surface
whose stated purpose is auditing — list_instance_tools's own description opens by offering itself
as the way to check what an agent can reach.

The same description was corrected in the same release for the neighbouring claim: it now says
"To verify an agent is read-only … read mutates — NOT scope". This sentence is the identical
mistake one clause later, and reach is the field that answers it.

Why the guards did not catch it

platform-docs/mcp.md was rewritten today by #572 and this line survived, correctly:
scripts/docs-drift.mjs compares documented numbers and names to the code defining them, and
nothing it measures changed. #573's surface lock excludes description from its hash by design,
so a description can go stale without moving MCP_SERVER_VERSION. Both exclusions are right — this
is simply a class neither covers, and the issue does not propose extending them to prose.

Acceptance criteria

1. Both sentences name reach and state what its three values mean, replacing the connector
   advice. The tool description and platform-docs/mcp.md say the same thing.
2. reach is present on rows returned by list_instance_tools — confirm it survives
   projectToolListing, since list_instance_tools schemas:true is 433 B over the wire limit, measured but not asserted #578 (8bc0453) just changed what that projection carries.
3. A test asserts the description does not recommend connector as a reach proxy — the pairing of
   a corrected field and prose still naming the old one is the failure here, and it should not be
   able to recur silently.
4. No MCP_SERVER_VERSION bump is required (descriptions are excluded from the serverInfo.version and server.json disagree, and neither moves when the tool surface does #573 hash) —
   confirm that rather than assume it, since AC2 may add a field.

Verified vs inferred

• Verified: both sentences at the cited file:line; tool-reach.ts and commit 31194df;
  the 10-of-34 and supervision measurements from The console tells 10 of 34 instances they have "no tool that reaches outside the platform" while fetch_url is allowed on every one of them #584's live enumeration; that #573's hash
  excludes description; that docs-drift.mjs compares numbers and names only.
• Inferred: that reach currently reaches the MCP listing at all. It was added to the API's
  row shape and the console consumes it; whether projectToolListing passes it through to MCP
  was not checked, and list_instance_tools schemas:true is 433 B over the wire limit, measured but not asserted #578 altered that projection hours later. AC2 exists to settle it — if it
  does not pass through, this issue is larger than a wording fix.

[serge-ivo]

Fixed — fc5fda9. AC2 checked before the prose, and it was already satisfied

AC2 first, as the issue asks

reach crosses two projections to reach an MCP client, and #578 (8bc0453) had changed the
second one hours earlier. Both verified:

• projectToolListing (instance-tool-policy.ts) drops only jsonSchema — every other field,
  reach included, passes through.
• budgetToolListing (the list_instance_tools schemas:true is 433 B over the wire limit, measured but not asserted #578 truncation) spreads the row ({...row, description}), so it
  rewrites one field and preserves the rest.

So no field had to be added, and the prose fix is not recommending something callers cannot see.
Pinned by a test that asserts reach on a truncated row specifically — truncation is the
projection that rewrites a row, so it is the one that could drop a field, and a not-runnable row is
exactly where an auditor looks ("what could this reach if I switched it on").

AC4, confirmed rather than assumed

Because AC2 added nothing, this is description-only: conformance.test.ts still matches the
0.1.4 lock, so no MCP_SERVER_VERSION bump is due. Confirmed by running it, not by reasoning
from the exclusion rule.

AC1 and AC3

Both sentences now name reach and define all three values (platform = never leaves
ProAgentStore, machine = the owner's computer, internet = anywhere else), and both cite why the
old proxy was wrong in both directions.

AC3's guard is deliberately not "the description does not mention connector" — it is a real
field named for other reasons. What must not recur is the recommendation:

expect(d).not.toMatch(/(audit|verify|check)[^.]*(reach|external)[^.]*filter[^.]*`connector`/i)

Its three values are read out of the API's own TOOL_REACHES as text, the same drift-proof
channel the tier arm uses, since this worker cannot import from workers/api — so a fourth reach
value added over there fails here rather than quietly going undocumented. Watched failing on the old
sentence before being trusted.

On the irony you flagged

It is worth recording that this arm now sits directly beneath the one written for #563, which exists
because the same description offered scope as the read-only answer. Same file, same sentence, same
failure mode, three tickets apart: a field gets corrected and the prose that recommends the old proxy
is left behind. The two guards are now adjacent, which is at least the right place for the next one.

Both docs gates run: docs:drift clean, docs:build --strict clean. CI green on main, Deploy Host
Worker succeeded.

Closing as delivered.