Skip to content

feat(mcp)!: advertise only agent inputs in MCP tool schemas - #4468

Merged
thymikee merged 3 commits into
mainfrom
mcp-input-schema-diet
Nov 12, 2026
Merged

thymikee merged 3 commits into
mainfrom
mcp-input-schema-diet

Conversation

@thymikee

@thymikee thymikee commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Summary

tools/list cost ~268 KB. Clients that defer tool schemas then call tools without them, and clients that compact schemas above ~5 KB drop their structure. This cuts the advertised input schemas at their owners (common input fields, MCP control fields, flag inputDescriptions); no per-tool schemas.

  • Breaking (MCP and AI SDK tools): tenant, runId, leaseId, androidDeviceAllowlist become operator-owned. Explicit input is refused with the operator path. Env/config defaults still reach the route (test added).
  • Trimmed repeated property descriptions (device selectors, MCP controls, proxy lease spec, settleQuietMs, open waitMs/metroPort).
  • Server instructions: one sentence to load a deferred tool's schema before its first call.
  • Gate: every input schema ≤ 5 KB, and no declared operator key is advertised, both derived from listCommandTools().
tools/list (62 tools) before after
total 268,371 B 216,362 B
input schemas 168,497 B 116,488 B
largest input schema 7,109 B (open) 4,757 B (open)
repeated common props 115,537 B 71,066 B
output schemas (untouched) 75,699 B 75,699 B

12 files. The proxy lease device spec stays advertised (#3864 decided it is agent-visible); only its descriptions shrank.

Validation

validation: CI. At 5d4ac57: focused vitest --project unit-core on src/mcp, src/ai-sdk, packages/command-surface, packages/command-registry, packages/contracts passed (192 files, 1408 tests); pnpm typecheck and oxlint clean. Bytes measured from the built server over stdio.

🤖 Generated with Claude Code

thymikee and others added 2 commits November 12, 2026 11:11
The tool list cost about 268 KB, and clients that defer or compact large
tool schemas then call tools without their arguments. Tenant, run, lease,
and Android device-allowlist scope become operator-owned: MCP refuses them
with the operator path, and their env and config defaults still apply.
Repeated property descriptions shrink, every input schema fits under 5 KB,
and the server instructions tell agents to load a deferred schema first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Derives both checks from listCommandTools() and the declared audiences, so a
new oversized schema or an advertised operator-owned key fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.22 MB 6.22 MB -2.4 kB
Package (unpacked) 6.22 MB 6.22 MB -2.4 kB
Package (download) 1.89 MB 1.89 MB -562 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 24.6 ms 21.2 ms -3.4 ms
CLI --help 52.7 ms 47.7 ms -5.0 ms

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 12 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread src/mcp/tool-control-fields.ts Resolved
Comment thread src/mcp/tool-control-fields.ts Resolved
Comment thread website/docs/docs/agent-setup.md Resolved
Restores the facts the shortened descriptions dropped: the result-size
effect of the MCP output controls, the waitMs range, the snapshot-bridge
settle default and its non-empty-screen floor, and what physical: false
selects. The config-loader audience moves beside the other MCP audiences
so the schema gate reads the same declarations as admission.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel

Verdict: approve

No findings.

1 finding below minor not shown (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (9cbbae2c857d).

Feedback goes in the review comment threads, as a reply under the inline comment of a finding:

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Comment @apex-sentinel-staging review on this conversation to run a full review.

@thymikee

Copy link
Copy Markdown
Member Author

This PR is ready at 5d4ac57. I found no problems in the code, and all 22 checks pass. There are no conflicts. The only step left before merge is for a maintainer to accept the MCP and AI SDK break. All 9 earlier review threads are resolved, and the head diff addresses each one. Not blocking, and you can take or leave these: the "no MCP tool advertises an operator-owned input" test in command-tools-schema-budget.test.ts rebuilds the audience list inline and overlaps the operator-inputs test, so a new audience source could slip past it (folding it into command-tools-operator-inputs.test.ts, or asserting against one exported union, would keep both on the same list); and the MCP sentence in agent-setup.md omits androidDeviceAllowlist and does not say these keys also left the AI SDK tool input. I did not re-measure the byte totals in the PR body. Only the 5 KB per-schema bound is covered by the test that CI runs.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 12, 2026
@thymikee
thymikee merged commit 53cb341 into main Nov 12, 2026
22 checks passed
@thymikee
thymikee deleted the mcp-input-schema-diet branch November 12, 2026 11:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant