Skip to content

feat(mcp)!: preload loop tools, trim schemas, and shorten errors - #4507

Merged
thymikee merged 13 commits into
mainfrom
t3/mcp-tool-payload
Nov 14, 2026
Merged

thymikee merged 13 commits into
mainfrom
t3/mcp-tool-payload

Conversation

@thymikee

@thymikee thymikee commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

Claude Code defers MCP tool schemas: each tool a run needs costs a tool-search turn, and a failed call to an unloaded tool gets its whole schema appended. This PR cuts both costs.

  • _meta["anthropic/alwaysLoad"] on the new 'loop' tier (part of 'core'): open, snapshot, press, fill, back, wait, scroll; screenshot stays on demand, since preloading it caused detours. Every tool gets _meta["anthropic/searchHint"] from its command text.
  • Extends feat(mcp)!: advertise only agent inputs in MCP tool schemas #4468's operator rule to debug, cost, and responseLevel. A new alias audience sends tool calls to deviceTarget instead of target.
  • Loop tool descriptions carry the command help's usage guidance. batch documents its step shape with the help batch examples.
  • MCP errors show Error (CODE, reason) and one line, then the log path when one exists. MCP open drops Session state:.
tools/list before (80075b6) after
total, 62 tools 148,296 B 114,950 B
always-loaded 27,872 B (8) 21,377 B (7)

Breaking changes for MCP clients

MCP tool calls are refused for mcpOutputFormat (removed), includeCost, responseLevel, debug, and target; AI SDK calls refuse debug and target and drop the rest. For JSON text, set AGENT_DEVICE_RESPONSE_LEVEL or AGENT_DEVICE_COST; for a form factor, use deviceTarget.

Validation

Focused unit suites, typecheck and lint pass; byte counts come from the built server over stdio. Not device-facing; CI owns full validation.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

View guided diff Turn on auto-fix

Claude Code defers MCP tool schemas, so each tool a run needs costs a tool
search turn. Mark the 'loop' framework tier (open, snapshot, press, fill,
back, wait, scroll, screenshot) with _meta "anthropic/alwaysLoad", and give
every tool an "anthropic/searchHint" from its command text.

Make the always-loaded schemas lean: debug, the MCP response controls
(cost, responseLevel), and the target alias leave every tool schema. The
controls become operator settings (AGENT_DEVICE_COST,
AGENT_DEVICE_RESPONSE_LEVEL); mcpOutputFormat is removed.

Loop tool descriptions carry their usage guidance from the command help
text, batch documents its step shape with tested examples, MCP errors put
the typed reason beside the code and drop the log path unless the recovery
step reads it, and MCP open text drops the Session state path.

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

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.27 MB 6.28 MB +3.8 kB
Package (unpacked) 6.27 MB 6.28 MB +3.8 kB
Package (download) 1.90 MB 1.90 MB +1.3 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 21.5 ms 19.1 ms -2.4 ms
CLI --help 40.8 ms 40.2 ms -0.6 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 59 files

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

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

Comment thread website/docs/docs/agent-setup.md Resolved
@apex-sentinel-staging

apex-sentinel-staging Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 1 no longer raised (1 marked fixed)

No open findings.

1 finding below minor hidden (user_settings.min_severity).

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

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

Earlier reviews

Review of 06c9d4c8 · 14.11.2026 07:47 UTC

Apex Sentinel · ✅ Approve

Since the last review: 1 new · 0 still open · 1 no longer raised (1 marked fixed)

1 finding(s): 1 minor.

🟡 Minor (1)

Where Finding
website/docs/docs/agent-setup.md:66 🆕 agent-setup.md still lists screenshot among the always-loaded loop tools

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

Review of 9c4a12c4 · 14.11.2026 07:40 UTC

Apex Sentinel · 🟠 Request changes

Since the last review: 1 new · 0 still open · 0 no longer raised

1 finding(s): 1 major.

Required fixes

  • Loop-tier pin test still expects 'screenshot', which the last commit reverted to 'core'

🟠 Major (1)

Where Finding
src/__tests__/command-descriptor-parity.test.ts:301 🆕 Loop-tier pin test still expects 'screenshot', which the last commit reverted to 'core'

2 new findings away from what changed since 3ede315 not shown. Comment @apex-sentinel-staging review for a full review.

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

Review of 3ede3159 · 13.11.2026 19:52 UTC

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 0 no longer raised

No open findings.

1 finding below minor hidden (user_settings.min_severity).

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

Review of 4d365c31 · 13.11.2026 16:17 UTC

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 0 no longer raised

No open findings.

2 findings below minor hidden (user_settings.min_severity).

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

Review of 067626d2 · 13.11.2026 15:18 UTC

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 1 no longer raised (1 marked fixed)

No open findings.

1 finding below minor hidden (user_settings.min_severity).

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

Review of 8e043474 · 13.11.2026 15:08 UTC

Apex Sentinel · 🟠 Request changes

Since the last review: 1 new · 0 still open · 1 no longer raised (1 marked fixed)

1 finding(s): 1 major.

Required fixes

  • ai-sdk default 'core' tool set now silently includes tier-less local-CLI commands

🟠 Major (1)

Where Finding
src/ai-sdk/index.ts:104 🆕 ai-sdk default 'core' tool set now silently includes tier-less local-CLI commands

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (80075b6412df).

Review of 88080f60 · 13.11.2026 14:58 UTC

Apex Sentinel · ✅ Approve

Since the last review: 1 new · 0 still open · 2 no longer raised (2 marked fixed)

1 finding(s): 1 minor.

🟡 Minor (1)

Where Finding
packages/command-surface/src/batch/index.ts:49 🆕 batch's MCP description states a 60-second budget that the policy does not encode

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (80075b6412df).

Review of 0751d1aa · 13.11.2026 14:35 UTC

Apex Sentinel · ✅ Approve

2 finding(s): 2 minor.

🟡 Minor (2)

Where Finding
packages/command-output/src/output/error.ts:66 Log path suppression compares raw hint to the default hint, not the printed Next:
packages/command-surface/src/post-action-observation-grammar.ts:32 settleQuietMs help drops the iOS 1500ms floor and bridge default

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (80075b6412df).

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Apex Sentinel: 2 new findings on 0751d1a. The verdict and the full list are in the summary comment.

…rule

- Settle fields state the diff is against the pre-action tree and keep the
  iOS 300 ms default and broad-replacement floor, tersely.
- open documents initialSnapshotError on a fresh open; customActions keeps
  its recovery routes, with the full wording in help snapshot.
- Model-facing errors keep the log path only when the code's default step
  reads the log (defaultHintReadsLog), and bound details.reason to one line.
- batch grounds its @E12 example; searchHints carry only words the tool
  text lacks, enforced by a test.

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

@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 33 files (changes from recent commits).

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

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

… is absent

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

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Apex Sentinel: 1 new finding on 88080f6. The verdict and the full list are in the summary comment.

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

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Apex Sentinel: 1 new finding on 8e04347. The verdict and the full list are in the summary comment.

Comment thread src/ai-sdk/index.ts Resolved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

At 067626d, the agent-facing MCP error text can tell the reader to check a log while omitting the log path. In packages/command-output/src/output/error.ts:128, the "Log:" line is kept only when the hint equals the default hint for the code. Two producers pass a logPath with their own hint that names the log: packages/apple-runner/src/runner-recycle-ledger.ts:101 and packages/command-runtime/src/commands/interaction/runtime/wait-polling.ts:242. For those, the MCP text keeps "Next: Check the runner log…" and drops the path, so an agent on an iOS runner recycle failure or a wait that exhausted runner restarts has no path to read. This also contradicts the new sentence in agent-setup.md. Please make the rule "the agent text keeps the log path whenever its Next step directs the reader to a log" a declared fact, for example a typed details flag set by the default-hint path and by every producer whose hint mentions a log (a grep of hints that mention a log enumerates them), or drop the agent-only suppression and always keep the line. Please add a test with a producer hint that reads the log.

Not blocking, take or leave: ai-sdk.md should say that createAgentDeviceTools calls now refuse debug and the target alias too (they go through the same executor, src/ai-sdk/index.ts:97,125), and the PR body breaking section could say so; for the agent reader, a message over 300 characters is cut with "…" and the full "Message:" line is no longer emitted (error.ts:70), so keeping it when truncated would help; the toolInputAudience comment at src/mcp/command-tools.ts:123 still says the command map is spread first, and the cost/responseLevel type checks in readClientConfig (command-tools.ts:382-405) may no longer be reachable from tool input; and the reader union in output-common.ts:45 and error.ts:36 could be one exported OutputReader type.

CI is green, 22 checks with none failing at 067626d, and I did not run the suites or rebuild the tools/list byte figures locally, so those are covered only by the CI size gates. No conflicts. The earlier review threads are resolved. The log-path fix above must land before merge.

…or text

A producer hint that sends the reader to the runner or diagnostics log lost
the path under the default-hint rule. Agent text now keeps the Log: line
whenever a log exists and the full Message: line when the summary cuts it.

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

Copy link
Copy Markdown
Member Author

Fixed in 44e7c76: the agent text now keeps the Log: line whenever the failure has a log path, so a producer hint that sends the reader to the runner or diagnostics log (runner-recycle-ledger, wait-polling, and the others that name a log) always carries the path. I dropped the default-hint rule and defaultHintReadsLog rather than flagging each producer, so a new producer cannot forget it. New test: a runner_recycle_budget_exhausted error with a "Check the runner log…" hint keeps Log: ….

Non-blocking notes: taken — a cut summary is now followed by the full Message: line for the agent reader too (tested); OutputReader is one exported type; the toolInputAudience comment matches the spread order; ai-sdk.md and the PR body say AI SDK tool calls refuse debug, cost, responseLevel, and target too; agent-setup.md describes the log line. Not changed — the cost/responseLevel checks in readClientConfig are still reachable: config defaults (user config and env) reach it through resolveMcpConfigDefaults.

@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 7 files (changes from recent commits).

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

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

Comment thread website/docs/docs/ai-sdk.md Resolved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

This PR is ready at 4d365c3. I found no new problems in the code, and the findings from the earlier review are fixed. All 22 checks pass at this commit, and no conflicts are known. I did not run the test suites or the linter. I judged the new tests from the diff, and CI is the execution evidence. No live device run is needed, because this change only affects text formatting. Nothing else must happen before merge.

Not blocking: in ai-sdk.md, cost, responseLevel and stateDir are dropped silently, not refused, so only debug and the target alias raise INVALID_ARGS. In agent-setup.md, "the text ends with its path" could say "includes its path", since the divergence report, the --debug details and "Supported on:" can follow the Log: line. You can take or leave both.

The review thread on the ai-sdk.md session and platform wording is fixed at this head, so you can resolve it: #4507 (comment). The "refused" wording for cost and responseLevel is covered by the first note above.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 13, 2026
… log path

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

Copy link
Copy Markdown
Member Author

Took both notes in 3ede315: ai-sdk.md now says debug and the target alias are refused with INVALID_ARGS while cost, responseLevel, and stateDir are dropped from the call (the PR body says the same), and agent-setup.md says the error text includes the log path. The session/platform thread is resolved.

@thymikee

Copy link
Copy Markdown
Member Author

The new head 3ede315 looks good, and the earlier clean review at 4d365c3 (#4507 (comment)) still stands. The change since then touches only two website docs files, and I found no problems in it. I read the INVALID_ARGS behavior for debug and target in the AI SDK route from the code and did not run it. All 8 remaining CI jobs are still in progress on this head, and the docs-only change cannot affect their code paths apart from the docs build. No threads are open. Once those jobs finish green, this is ready to merge.

Benchmark runs showed that a preloaded screenshot pulls agents into a
screenshot, image read and coordinate-tap detour whenever open returns
before the app is ready, so it moves back to the core tier: still in the
default AI SDK set, loaded on demand over MCP.

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

@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 2 files (changes from recent commits).

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

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

thymikee and others added 2 commits November 14, 2026 08:37
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* origin/main:
  fix(android): carry an empty text on a node labelled by its content description (#4531)
  fix(ios): restore the back swipe's pre-swipe still span (#4515)
  fix(daemon-client): type the remote daemon refusal with its dispatch fact (#4532)
  fix: prepare reinstall artifacts before removing apps (#4533)
  fix(ios): classify the keyboard dismiss refusal by what it dispatched (#4536)
  fix(ios): press the navigation bar back button and speed up the back swipe (#4508)
  refactor(gestures): one owner for the densified gesture path; drop the unproven sendevent transport (#4239)
  fix(host-kit): keep Linux process identity stable across clock steps (#4438)
  fix(ios): bound the idle wait of keyboard dismiss and keyboard enter (#4454)
  fix(device-selection): fail an ambiguous device request with only the tied devices (#4506)

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Apex Sentinel: 1 new finding on 9c4a12c. The verdict and the full list are in the summary comment.

…rmat the loop pin

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

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Apex Sentinel: 1 new finding on 06c9d4c. The verdict and the full list are in the summary comment.

Comment thread website/docs/docs/agent-setup.md Resolved
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

I found no problems in the changes since the earlier review of 3ede315 (#4507 (comment)). I reviewed 83c034c, which adds 9c4a12c, 2dc0ae1, 06c9d4c and 83c034c on top of the eight commits that did not change. The parity pin no longer lists screenshot, the loop pin matches the 7 loop descriptors, and the agent-setup doc lists the 7 loop tools and says screenshot loads on first use.

The three earlier inline threads are fixed at this commit, so you can resolve them: #4507 (comment) (parity pin lists screenshot), #4507 (comment) (loop pin format and count) and #4507 (comment) (agent-setup tool list).

All 22 checks pass at 83c034c, and there are no conflicts. I did not run the MCP server. I read the always-loaded set from the code (command-tools.ts:194) and from the loading-meta test that CI ran. I did not reproduce the benchmark claim that a preloaded screenshot causes detours, and the change does not depend on it. Nothing else stands in the way of merging.

@thymikee
thymikee merged commit d78be6c into main Nov 14, 2026
26 of 27 checks passed
@thymikee
thymikee deleted the t3/mcp-tool-payload branch November 14, 2026 10:43
thymikee added a commit that referenced this pull request Nov 14, 2026
Resolves the open summary conflict with #4507: keeps main's agent guidance
and adds the local-iOS-simulator first-screen wait, compact enough to keep
the always-loaded tools inside their 22 KB budget. Takes the review note
that other devices and backends (Android included) skip the wait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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