list_instance_tools schemas:true is 433 B over the wire limit, measured but not asserted

[serge-ivo]

list_instance_tools with schemas:true is over the wire limit, and the guard records it without asserting it

#569 budgeted the default response down — production measured 66,042 B before, 53,970 B after,
confirmed by calling the deployed tool. The schemas:true path was not fixed and is
65,969 B, 433 B over the 64 KiB limit the default path is now held to.

e19d7a3 measures it and records the number. It deliberately does not assert the limit,
because making it fit means changing what the argument means, and #569's agent declined to ship
that as a guess. That was the right call and it is why this is a separate issue: the measurement
exists, the decision does not.

Why this is not "just raise the cap"

This repo has ruled on that shape twice. #503 budgeted a payload down rather than raising a cap
and cost the context window less than the bug did; #569 did the same and the whole point of the
allowed_only argument is to make the caller state what they need. Raising the limit for
schemas:true restates the problem one number higher.

The honest options, none of which are free:

1. schemas:true implies allowed_only — a caller asking for full schemas almost certainly
   wants the tools the agent can actually run. Changes what the argument means; say so in the
   description.
2. Paginate it, the way instance_messages returns nextCursor and hasMore: true and has no cursor input — every message older than the first page is unreachable over MCP #566 just gave instance_messages a real cursor. Consistent with a
   fix that landed today, and the only option that scales past one instance.
3. Return schemas only for a named subset (tools: ["a","b"]). Cheapest, and matches how the
   payload is actually consumed — nobody reads 104 schemas.

Acceptance criteria

1. schemas:true on the largest real instance is under the limit, measured on the deployed
   tool, not on the API body. list_instance_tools documents 2 of the 4 tier values it returns, and its default response is 117 KB — enough to exceed a host's limit on one instance #569's first fix passed its guard at ~54 KB while production
   served 66,042 B, because jsonText pretty-printed it after the assertion — the measurement
   must happen at the layer the client receives.
2. The chosen option is stated with its cost, and the tool description matches the new behaviour.
3. The guard asserts the limit rather than recording the number, and states its denominator per
   ADR 0002.
4. Demonstrated red on the current 65,969 B payload.

Verified vs inferred

• Verified: 65,969 B and 433 B over, measured by list_instance_tools documents 2 of the 4 tier values it returns, and its default response is 117 KB — enough to exceed a host's limit on one instance #569's guard; the 66,042 → 53,970 B default
  improvement, measured on the deployed tool; that e19d7a3 records without asserting; the
  jsonText pretty-print that defeated the first list_instance_tools documents 2 of the 4 tier values it returns, and its default response is 117 KB — enough to exceed a host's limit on one instance #569 fix.
• Inferred: that no caller wants all 104 schemas. It is the premise behind options 1 and 3
  and it is not measured — mcp_audit_log could establish it, and should, before option 1
  narrows the argument for everyone.

[serge-ivo]

The premise cannot be measured from mcp_audit_log — and the payload measurement means it no longer has to be

Verdict: the blocking unknown is closed, but not the way the ticket expected. The inferred
premise ("no caller wants all 104 schemas") is unmeasurable from anything the platform records
today; the composition of the payload, measured live, makes the choice decidable without it — and
changes which option is the obvious one.

1. Why the audit log cannot answer it

• list_instance_tools is registered as a read tool (workers/mcp/src/tool-metadata.ts:146),
  and its handler (workers/mcp/src/instance-tools/base.ts:69-84) makes no audit() call —
  it resolves the token, calls the API and returns.
• requirePermission is the only automatic writer, it is never invoked for a read scope, and it
  writes a row only on denial (workers/mcp/src/safety.ts:38-58). A successful call of any
  read tool records nothing.
• Even for write tools, audit() returns early without a subject (safety.ts:96), and
  safety(provided) sets subject: undefined whenever the caller passes an explicit token
  argument (workers/mcp/src/index.ts:57). So the audit log covers denied / dry-run / completed
  writes, on OAuth-connected sessions only.
• There is no request-level fallback: no Analytics Engine binding anywhere in the repo (grep for
  writeDataPoint / ANALYTICS → 0 hits in workers/), and GET /v1/instances/:id/tools
  (workers/api/src/routes/tools.ts:110-121) logs nothing.

What it would take: a read-side counter on the API route keyed by the schemas / allowed
flags, then real traffic to accumulate. Worth a line of telemetry someday; not worth blocking this
on, because of §3.

2. The headline number is the coder shape, not the worst case

Measured on the deployed API, 2026-08-15, every one of the 34 instances on the operator account:

mode	min	max	over 64 KiB
?schemas=true	61,796 B	66,189 B	20 of 34
?schemas=true&allowed=true	17,257 B	28,111 B	0 of 34

• The worst case is 933ebec5-… (Small Business Website Lead Finder) at 66,189 B — 653 B over,
  not 433. bd43f4de-…'s 65,969 B (433 over) is the coder-repo shape and it is what list_instance_tools documents 2 of the 4 tier values it returns, and its default response is 117 KB — enough to exceed a host's limit on one instance #569's guard
  measures. A fix tuned to 433 B of headroom still ships 653 B over on the real worst case.
• allowed_only is not marginal: it lands every shape at ≤ 43 % of the limit.
• Wire == API body: the MCP response for bd43f4de-… is the same 65,969 B this route returns, so
  the deployed-tool measurement AC 1 asks for can be taken on either side now that jsonText is
  compact.

3. Where the bytes actually are — the framing is wrong

Composition of the 66,189 B worst case (104 rows), measured by re-serialising the live response:

part	bytes	share
36 allowed rows (incl. their schemas)	25,913	39 %
68 not-declared rows	40,614	61 %
— of which their description strings alone	25,074	38 %
every schema in the response	11,753	18 %

projectToolListing already withholds schemas from rows the instance cannot run, so schemas:true
differs from the default only by the allowed rows' schemas — bd43f4de-…: 53,970 → 65,969 B,
+11,999 B. The tool's own description still says schemas "are the bulk of the response"
(instance-tools/base.ts:63); on this payload they are 18 %, and prose about tools the agent
cannot run is 38 %.

4. A fourth option, which needs no premise about callers

Drop (or truncate) description on not_declared rows. Simulated against the live worst-case
response:

variant	bytes	share of 64 KiB
drop description on not-declared rows	40,442	62 %
truncate to 200 chars	54,049	82 %
truncate to 120 chars	49,604	76 %
truncate to 80 chars	47,038	72 %

Every row, its verdict, its reason, connector, mutates, scope, tier and invocableBy stay —
#525's contract ("what it can't and why") is intact, and no argument changes meaning, so nothing has
to be assumed about what a caller wants. The cost, stated: an auditor reading a not_declared
row loses the prose saying what that tool is, and has to look it up elsewhere. That is a real
loss and it is the trade to decide, not to hide. Truncation to ~120 chars keeps the first clause of
every description and still clears the limit with 24 % headroom.

Against the three options already in the ticket:

• Option 1 (schemas:true implies allowed_only) works and is measured — 28,111 B worst case —
  but it is the one option that needs the unmeasurable premise, because it takes something away
  from every caller.
• Option 2 (paginate) is the only one that scales past today's 104 rows, and it is the one that
  costs the most. Nothing here argues against it as the eventual answer.
• Option 3 (tools: [...] subset) also needs the premise: unless an unnamed schemas:true is
  capped or refused, the 66,189 B payload is still reachable, so option 3 alone does not close this.

5. Corrections for the acceptance criteria

• AC 1 says "the largest real instance" — name it: 933ebec5-… at 66,189 B.
• AC 4 says "demonstrated red on the current 65,969 B payload" — that number is bd43f4de-…;
  the red case should be the 66,189 B one, or the guard passes on a shape that is still over.
• AC 3 (assert, and state the denominator per ADR 0002) is unchanged and right.

Verified vs inferred

• Verified: every file:line; all four size tables, measured against the deployed API today,
  one request per instance; the composition figures, computed by re-serialising the live response
  with compact separators (the same encoding the wire uses); that the audit log records no
  successful read of any tool.
• Inferred: nothing about caller intent — that is the point of §1. The simulated variants in §4
  are arithmetic on the real response, not an implementation.

[serge-ivo]

Fixed as your §4 — 8bc0453. Took the option that needs no premise

Your comment was right that the framing inverts the choice, and I took the fourth option:
truncate description on rows the instance cannot run, to 120 chars at a word boundary, ending
….

Where, and why not in projectToolListing

In the MCP worker (instance-tools/base.ts), not the API route. The 64 KiB ceiling is a
property of the MCP host, not of the data — and the route's other consumer is the console's Tool
Permissions panel, which renders t.description under every row including the not-declared
ones (store/console/src/components/ToolPermissions.tsx:139). That is how an owner reads what a
tool they could switch on actually does. Truncating in the API would have degraded that panel to
save bytes nobody there is short of.

It also kept me out of instance-tool-policy.ts, which the #584 lane was editing concurrently.

Applied on both paths, not just schemas:true: the prose weighs the same either way, one row
shape is easier to reason about than two, and the default path gains the same headroom.

AC coverage

1. ✅ Measured on the deployed tool. Your correction is taken: the red case is the 66,189 B
   shape, not 65,969.
2. ✅ Option stated with its cost, in the code and below. Tool description corrected — it claimed
   schemas were "the bulk of the response"; they are 18%.
3. ✅ Asserted, not recorded, on both paths, denominator stated: 34 instances, worst case
   66,189 B, 20 over.
4. ✅ Demonstrated red — a fixture built to your measured composition (104 rows, 68 not-declared
   carrying 25,092 B of description) serialises to 73,350 B untruncated, 7,814 B over, and that
   arm fails if anyone shrinks the fixture past the defect.

Two things I found while writing the guard, both worth knowing

#569's schemas:true fixture was 22% heavier than any real instance, and unasserted at
69,520 B. Its schemas serialised to 719 B/row against the 326 B/row your measurement gives for all
36 real ones, making its allowed rows 1,256 B where production's are 720 B. So the one existing
schemas:true measurement in the suite was of a shape nobody has — and it was printed rather than
asserted, which is the defect this ticket names. Resized to the measured shape and now asserted.

#569's pretty > HOST_LIMIT regression arm can no longer fire. After the truncation, compact
serialisation is no longer the only thing holding the default path under the limit. Restoring it
would mean inflating a fixture to keep an assertion alive — the shape ADR 0002 is about. Two
stronger assertions replace it: the reply is the compact serialisation byte for byte
(size-independent, so a reverted {compact:true} is caught however much headroom exists), and even
pretty-printed it fits.

The cost, and what this is not

An auditor reading a not_declared row over MCP now gets the first clause instead of the whole
description. Every verdict field is untouched — allowed, reason, connector, scope,
mutates, reach, tier, invocableBy — so #525's contract is intact, and a test asserts that on
a truncated row.

This is not a bound. It scales with row count, so a large enough catalogue overflows again.
Your option 2 (pagination) is the only one that bounds it and remains the eventual answer — the
guard now goes red at that point, which is when to spend it.

I did not build the telemetry path; per your §1 the premise is unmeasurable and the chosen option
does not need it.

MCP_SERVER_VERSION 0.1.3 → 0.1.4 with a new appended lock entry: the schemas argument's
.describe() lands inside inputSchema, which is in #573's fingerprint even though a tool's own
description is not. The lock caught precisely that distinction.

Closing as delivered.