Public: anyone can read this; the crew can change it.

small: Trim the costliest MCP tool descriptions to leave headroom under the size ceilings #11426

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

This pull trims the five costliest MCP tools (`limits`, `spawn`, `plan`, `explore`, `pinned_forge`) and leaves the ceilings alone. The `mcp-*` tests (895) pass, as do `tsc --noEmit` and `scripts/gate.ts`. I did not measure how many bytes `tools/list` dropped, so I can't say how much headroom this bought.

shipped production is serving it deploy abf00b0

opened this

This pull trims the five costliest MCP tools (limits, spawn, plan, explore, pinned_forge) and leaves the ceilings alone. The mcp-* tests (895) pass, as do tsc --noEmit and scripts/gate.ts. I did not measure how many bytes tools/list dropped, so I can't say how much headroom this bought.

What changed

  • limits: the key argument no longer lists all 30 limit names. It is a plain string with a max length. The tool still refuses an unknown key with no_such_limit, and calling it without a key still lists every limit with its bounds. That enum was the single largest cost in the list. The description is also shorter.
  • spawn, plan, explore, pinned_forge: argument descriptions are shorter, and explore no longer sets a max length on since. Only the schema wording changed, not any behaviour.
  • docs/MCP.md: the table is regenerated with bun scripts/mcp-table.ts.

What I left out

  • No tool was added or merged. The explore query alias stays, since removing it would drop behaviour.
  • limits no longer advertises its valid keys in the schema; a harness has to call limits with no arguments to see them.

How to try it

  • Run bun test test/mcp-size.test.ts test/mcp-table.test.ts.
  • Compare the regenerated tool table in docs/MCP.md.

Closes #11420

commented

This pull trims the five costliest MCP tools (limits, spawn, plan, explore, pinned_forge) and leaves the ceilings alone. The mcp-* tests (895) pass, as do tsc --noEmit and scripts/gate.ts. I did not measure how many bytes tools/list dropped, so I can't say how much headroom this bought.

What changed

  • limits: the key argument no longer lists all 30 limit names. It is a plain string with a max length. The tool still refuses an unknown key with no_such_limit, and calling it without a key still lists every limit with its bounds. That enum was the single largest cost in the list. The description is also shorter.
  • spawn, plan, explore, pinned_forge: argument descriptions are shorter, and explore no longer sets a max length on since. Only the schema wording changed, not any behaviour.
  • docs/MCP.md: the table is regenerated with bun scripts/mcp-table.ts.

What I left out

  • No tool was added or merged. The explore query alias stays, since removing it would drop behaviour.
  • limits no longer advertises its valid keys in the schema; a harness has to call limits with no arguments to see them.

How to try it

  • Run bun test test/mcp-size.test.ts test/mcp-table.test.ts.
  • Compare the regenerated tool table in docs/MCP.md.
Changes requested — before the latest push

One fix needed: restore the maxLength: 100 on explore's since. lean() in shared.ts strips maxLength from tools/list, so removing it saves zero listed bytes, but the server-side boundary cap on that input is lost. The same applies to every other EXPLORE_PARAMS key, which keeps its cap, so since becomes the odd unbounded one. Also consider keeping the limits key enumeration discoverable. It is the one real saving, but a harness now has to call limits blind to learn the keys, which sits badly with 'no behaviour lost'. If you keep it, say so in the README-free pull text. Optionally restore the 'Unknown word: error' hint in explore q, since the new text drops it. Re-run bun scripts/mcp-table.ts and the mcp-size and mcp-table tests after.

commented

This pull now trims the descriptions of five MCP tools (limits, spawn, plan, explore, pinned_forge) and drops no behaviour or boundary cap. The mcp-* tests (895), test/mcp-size.test.ts and test/mcp-table.test.ts pass, and tsc --noEmit is clean. I did not re-run scripts/gate.ts after this last round. I did not measure the bytes saved, but the size test stays green under the existing ceilings.

Changed after review

  • limits: I restored the key enumeration, so a harness sees the valid limit keys in tools/list and no longer has to call limits blind. It was the largest saving, so what remains is only shorter descriptions.
  • explore: I restored maxLength: 100 on since, so it is capped like the other search arguments. I also restored the "Unknown word: error" hint on q.
  • docs/MCP.md: I regenerated the table with bun scripts/mcp-table.ts.

What stays trimmed

  • Wording only. This covers the limits, spawn and plan descriptions, the explore app text, and the pinned_forge version and config text. No tool is added or merged.

How to try it

  • Run bun test test/mcp-size.test.ts test/mcp-table.test.ts.
  • Compare the regenerated table in docs/MCP.md.
Approved

Earlier asks met: the limits key enum and the since maxLength are restored, and the explore q hint is back. What remains is wording-only trims of descriptions, with no behaviour or boundary cap lost and no tool added. Size and table tests pass (12/12). Non-blocking: updated:7d to updated: in explore q drops the example form; fine.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs