sixfold-space/madtea

SHA256

Fork 0

schema byte-budget: ~14KB of tool-description growth crept in under stale measurements #407

New issue

Open

opened 2026-08-17 15:11:28 +00:00 by hexajon · 1 comment

hexajon commented

2026-08-17 15:11:28 +00:00

Owner

Found while landing #375 and #387.

What happened

totalToolByteBudget (internal/mcp/schema_budget_test.go) caps the serialized size of the whole tools/list payload. The cap forces verbose tool text into madt_help topics instead of the always-shipped schema. Every byte of MCP description costs tokens on every client connect.

Since the last pin (recorded at 215485), main-line description growth added up: the ssh surfaces, the loud what/why/action git messaging, and the finish/commit/whoami additions. The measured total reached ~229948 under go-sdk v1.6.1. That is ~14.4KB of growth. All of it sits inside the per-tool caps, so the guard never fired. It crept to ~52 bytes under the old 230000 cap while the recorded comment still claimed ~14.5KB of headroom.

Two small additions then tipped it over: protect_set (#375, ~196 bytes) and the go-sdk v1.7.0 always-emitted hint keys (#387, ~1.5KB). I recalibrated the budget to 240000 and refreshed the measurement comments.

The question

The guard's whole job is to keep the always-shipped surface lean, and it silently lost ~14KB. Three paths are open:

Keep the current verbosity and the 240000 budget. Treat the guard as recalibrated.
Run a description-diet pass to reclaim headroom and lower the budget back toward 230000.
Tighten guard discipline: force a measured-comment refresh on any description change, without cutting text.

Where I lean

I lean toward the diet pass plus the discipline check. The guard exists to keep the always-shipped surface lean, and it lost ~14KB with no signal. But the verbosity came from real usability work, mainly the loud git messaging, so whether it earns its token cost needs a closer look before I cut.

Related: #375, #387.

Found while landing #375 and #387. ## What happened `totalToolByteBudget` (internal/mcp/schema_budget_test.go) caps the serialized size of the whole tools/list payload. The cap forces verbose tool text into `madt_help` topics instead of the always-shipped schema. Every byte of MCP description costs tokens on every client connect. Since the last pin (recorded at 215485), main-line description growth added up: the ssh surfaces, the loud what/why/action git messaging, and the finish/commit/whoami additions. The measured total reached ~229948 under go-sdk v1.6.1. That is ~14.4KB of growth. All of it sits inside the per-tool caps, so the guard never fired. It crept to ~52 bytes under the old 230000 cap while the recorded comment still claimed ~14.5KB of headroom. Two small additions then tipped it over: protect_set (#375, ~196 bytes) and the go-sdk v1.7.0 always-emitted hint keys (#387, ~1.5KB). I recalibrated the budget to 240000 and refreshed the measurement comments. ## The question The guard's whole job is to keep the always-shipped surface lean, and it silently lost ~14KB. Three paths are open: - Keep the current verbosity and the 240000 budget. Treat the guard as recalibrated. - Run a description-diet pass to reclaim headroom and lower the budget back toward 230000. - Tighten guard discipline: force a measured-comment refresh on any description change, without cutting text. ## Where I lean I lean toward the diet pass plus the discipline check. The guard exists to keep the always-shipped surface lean, and it lost ~14KB with no signal. But the verbosity came from real usability work, mainly the loud git messaging, so whether it earns its token cost needs a closer look before I cut. Related: #375, #387.

hexajon added the

enhancement

status/needs-decision

labels

2026-08-17 15:11:28 +00:00

hexajon self-assigned this

2026-08-17 17:45:48 +00:00

hexajon commented

2026-09-08 19:54:51 +00:00

Author

Owner

Decided: diet + discipline.

Diet pass: trim genuinely redundant text across the MCP tool descriptions, keeping ADR 0023's mandated one-sentence inline WHY (not trimmable) and ADR 0001's gotcha-inline / depth-to-madt_help split. Savings come only from real redundancy.
Lower the cap back toward 230000 once the diet lands, so the always-shipped surface stops silently absorbing drift.
Add a discipline check that forces a measured-comment refresh whenever a tool description changes, so the ~14KB silent growth (from #375 and #387) cannot recur unnoticed. Today the per-tool "measured" comments in internal/mcp/schema_budget_test.go are hand-maintained with no guard.

Clearing needs-decision.

Decided: diet + discipline. 1. Diet pass: trim genuinely redundant text across the MCP tool descriptions, keeping ADR 0023's mandated one-sentence inline WHY (not trimmable) and ADR 0001's gotcha-inline / depth-to-`madt_help` split. Savings come only from real redundancy. 2. Lower the cap back toward 230000 once the diet lands, so the always-shipped surface stops silently absorbing drift. 3. Add a discipline check that forces a measured-comment refresh whenever a tool description changes, so the ~14KB silent growth (from #375 and #387) cannot recur unnoticed. Today the per-tool "measured" comments in `internal/mcp/schema_budget_test.go` are hand-maintained with no guard. Clearing needs-decision.

hexajon removed the

status/needs-decision

label

2026-09-08 19:54:52 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#407

No description provided.

Rows
Columns