gate: cap startup/tool-schema payload including plugin disclosures

buildagent commented

2026-08-18 12:34:01 +02:00

Member

I040 measured the fixed startup tax for the first time and cut where it was safe. Nothing stops it growing back.

Measured 2026-08-18 (real `initialize` + `tools/list` off the wire)

	bytes	~tokens
`tools/list`	46,444	~11,600
`instructions`	4,298	~1,075
total per session, before one query	~50,700	~12,700

77% of that payload is English prose, not structure — 26,374 bytes of tool descriptions plus 9,370 bytes of per-parameter prose inside inputSchema.

Prior art for the ratchet

Copy has grown three times deliberately (175613a0, 25cd1698, 21c8ae66) and was pinned in place by regression tests asserting the marketing anchors. I040 retargeted those tests and added INSTRUCTIONS_MAX_BYTES = 4096 for the instructions string only. tools/list — the 90% — is still unbounded.

Ask

A test that drives a real initialize + tools/list and asserts total bytes under a ceiling, failing with a diff of the per-tool ranking so the offender is named. Set the ceiling at roughly the current value; it is a ratchet, not a target.

Second lever, untouched

9,370 bytes (20% of the payload) is per-parameter description prose inside inputSchema — search_text alone carries 1,407 B, change_impact 819 B, file_outline 788 B. Independent of the description pass; plausibly another ~2,000 B.

The rule this enforces

From I040: prose in a tool description is not a disclosure. If an agent needs it at call time it goes in the RESPONSE, where it ships with the data. A disclosure attached to the number beats one in a schema the agent read 200k tokens ago — and is cheaper, because it is only paid when the situation arises.

code-index://docs/{topic} exists now as the destination for anything that is reference rather than contract.

Runtime-plugin architecture expansion

#75 adds packages, generations, capabilities, bridges and reason-code families. None of that reference material belongs duplicated across every tool description or parameter schema.

Extend the ratchet to report bytes by category:

initialize instructions;
tool name/schema structure;
tool/parameter prose;
plugin-specific prose;
resource references.

Plugin state travels in responses only when relevant, preferably as one package dictionary plus compact row handles. Full capability, ABI and reason-code documentation lives under code-index://docs/plugins/*.

The real initialize + tools/list gate must run with the complete #80 surface enabled and fail with a per-tool/per-category size diff. Adding runtime plugins may not raise the fixed session tax without an explicitly reviewed baseline reason.

I040 measured the fixed startup tax for the first time and cut where it was safe. Nothing stops it growing back. ## Measured 2026-08-18 (real `initialize` + `tools/list` off the wire) | | bytes | ~tokens | |---|---:|---:| | `tools/list` | 46,444 | ~11,600 | | `instructions` | 4,298 | ~1,075 | | **total per session, before one query** | **~50,700** | **~12,700** | **77% of that payload is English prose, not structure** — 26,374 bytes of tool descriptions plus 9,370 bytes of per-parameter prose inside `inputSchema`. ## Prior art for the ratchet Copy has grown three times deliberately (`175613a0`, `25cd1698`, `21c8ae66`) and was *pinned in place* by regression tests asserting the marketing anchors. I040 retargeted those tests and added `INSTRUCTIONS_MAX_BYTES = 4096` for the instructions string only. `tools/list` — the 90% — is still unbounded. ## Ask A test that drives a real `initialize` + `tools/list` and asserts total bytes under a ceiling, failing with a diff of the per-tool ranking so the offender is named. Set the ceiling at roughly the current value; it is a ratchet, not a target. ## Second lever, untouched 9,370 bytes (20% of the payload) is per-parameter `description` prose inside `inputSchema` — `search_text` alone carries 1,407 B, `change_impact` 819 B, `file_outline` 788 B. Independent of the description pass; plausibly another ~2,000 B. ## The rule this enforces From I040: **prose in a tool description is not a disclosure.** If an agent needs it at call time it goes in the RESPONSE, where it ships with the data. A disclosure attached to the number beats one in a schema the agent read 200k tokens ago — and is cheaper, because it is only paid when the situation arises. `code-index://docs/{topic}` exists now as the destination for anything that is reference rather than contract. ## Runtime-plugin architecture expansion #75 adds packages, generations, capabilities, bridges and reason-code families. None of that reference material belongs duplicated across every tool description or parameter schema. Extend the ratchet to report bytes by category: - initialize instructions; - tool name/schema structure; - tool/parameter prose; - plugin-specific prose; - resource references. Plugin state travels in responses only when relevant, preferably as one package dictionary plus compact row handles. Full capability, ABI and reason-code documentation lives under code-index://docs/plugins/*. The real initialize + tools/list gate must run with the complete #80 surface enabled and fail with a per-tool/per-category size diff. Adding runtime plugins may not raise the fixed session tax without an explicitly reviewed baseline reason.

Rows
Columns

gate: cap startup/tool-schema payload including plugin disclosures #71

Measured 2026-08-18 (real initialize + tools/list off the wire)

Prior art for the ratchet

Ask

Second lever, untouched

The rule this enforces

Runtime-plugin architecture expansion

Closing: this shipped in v0.23.0. Verified first-hand.

One sub-ask genuinely unbuilt, split out

Why this close matters

Measured 2026-08-18 (real `initialize` + `tools/list` off the wire)