`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

[serge-ivo]

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

Two small, independently-shippable contract defects on the same tool. Both measured against instance bd43f4de-ef35-4051-bdec-43f8571414a1, GET /v1/instances/:id/tools, production 2026-08-15, 104 rows.

1. A third of the rows carry an undocumented tier

The tool's description (workers/mcp/src/instance-tools/base.ts:29) says:

plus tier (base = a universal facility every agent has; connector = reaches an external system)

Measured tier distribution over the 104 rows:

tier	rows	documented?
connector	49	yes
standard	30	no
base	21	yes
runtime	4	no

34 of 104 rows (32.7%) carry a value the description does not define. A caller filtering on the two documented values silently drops a third of the surface — including every runtime tool, which is the set that reaches the owner's own machine.

The vocabulary is already written down, correctly, one layer below — workers/api/src/lib/builtin-tool-policy.ts:145:

/** base = always granted · standard = creator-selectable · runtime = needs a local runner · connector = external system. */
export type ToolTier = "base" | "standard" | "runtime" | "connector";

and again on ToolDef (lib/connectors/types.ts:129). So this is a description that fell behind its own type, not a missing concept. Paste the type's gloss.

2. The default response is 117 KB / 3,563 lines for one instance

Measured, same call:

	chars (pretty-printed)	lines
default (all 104 rows)	117,273	3,563
allowed_only: true (35 rows)	37,363	—
all rows, jsonSchema stripped	60,427	—

Raw body over HTTP is 89,281 bytes. jsonSchema is 48% of the payload, and it is present on every row including the 69 the instance may not run — a schema for a tool that is allowed: false describes inputs the caller can never send.

This exceeded the calling host's response limit in the session that produced this issue, so the tool's own most useful mode — "return EVERY tool, not just the allowed ones", which the resolver's doc comment (lib/instance-tool-policy.ts:154-156) rightly defends — is the one that does not fit.

What to do

Cheapest, and it fixes both: paste the four-value tier gloss into the description, and drop jsonSchema from rows where allowed === false (60,427 chars, comfortably under any limit, with no loss of auditable information — the verdict, reason, scope, tier, connector and writeConsent all stay).

If more is wanted: add an optional schemas: boolean (default false) so the audit read is cheap and the schema read is opt-in. Do NOT make allowed_only the default — the resolver's stated design is that "what can this agent do" is only answerable if the answer includes what it can't, and defaulting it away would quietly retire that.

Alternatives considered and rejected

• Truncate the description strings. They are the substance of an audit — github_update_issue's description is where the "labels REPLACE" warning lives.
• Paginate. A tool listing is a set, and a paged audit is one a caller can stop halfway through and believe.

Acceptance criteria

• The description defines all four tier values, matching ToolTier's own gloss.
• A test asserts every value in the ToolTier union appears in the description string — so a fifth tier cannot ship undocumented.
• The default response for a 104-tool instance is under 64 KB.

Regression risk

Dropping jsonSchema from disallowed rows changes a response shape the console may read. store/console/src/lib/toolPolicy.ts mirrors the type — check it does not render schemas for the not-declared rows before removing the field, and make it optional in the type rather than removing it outright.

Related: #563 (the same description's scope gloss is wrong in a way that matters more), #561/#562 (the tools/list payload budget).

[serge-ivo]

Both defects fixed, in 50714da, then 3912475 after production showed the first fix was not enough. e19d7a3 adds the guard the gap exposed. All on main, deployed, CI green.

1. Tier vocabulary — fixed

The four-value gloss is now rendered from the vocabulary rather than typed out: TOOL_TIERS is a list of [id, gloss] pairs and the description is built from it, so prose and vocabulary cannot drift again. A test asserts every member appears in the description, and reads ToolTier out of builtin-tool-policy.ts as text to prove the two copies still agree — the MCP worker cannot import from the API worker.

Verified live: connector 49, standard 30, base 21, runtime 4, all four documented.

2. Payload — the interesting one

jsonSchema became opt-in (schemas:true), restricted to the allowed rows. allowed_only was not made the default, for the reason the resolver's own comment gives.

That took the API body to ~54,000 bytes and the guard passed. Production then measured the MCP call at 66,042 bytes — still over the 64 KiB limit this issue was filed about.

Both numbers were right, which is the part worth recording. tool-listing-budget.test.ts asserts the route's compact body; jsonText then pretty-printed it with two-space indentation on the way out, adding ~22%. Every assertion in the suite stopped one layer above the code that serialises, so the layer that made the response too big was the one nothing measured. It was only caught by calling the deployed tool.

3912475 gives jsonText a compact option and list_instance_tools uses it. Opt-in per call site rather than a size threshold inside jsonText, because a threshold would change the output format of any of the other 134 tools the moment their data grew, and none of them has been measured.

Verified live: 53,970 bytes, single line, 0 newlines — 11,566 bytes of headroom under the limit. Content unchanged: 104 rows, mutates on every row, all four tiers, 35 allowed.

Your acceptance criteria are met: all four tiers documented and asserted, and the default response for a 104-tool instance is 53,970 B < 64 KB.

One thing left open, and it needs its own issue

The same live check measured schemas:true at 65,969 B — 433 B OVER the 64 KiB limit. My guard only drove the default call and its fixture carried no schemas, so the heavy path had never been measured against the limit by anything.

e19d7a3 now drives it, asserts the rows pass through unchanged (schemas on the 35 allowed rows, none of the other 69), and prints the cost beside the default. It deliberately does not assert 64 KiB on that path, because that would be a failing test standing in for a decision nobody has made. The candidates:

• drop the not-allowed rows' description when schemas:true (they are the bulk, and the default call already carries them), or
• narrow schemas from a boolean to the tools the caller names.

Both change what the argument means, so it is a judgement call rather than a fix I should ship on my own. 433 bytes is also within noise of one more declared tool. Recommend filing this — the number and the options are recorded in the guard so whoever picks it up starts from the measurement.

Closing this issue: its own ACs are met and verified live.