Repository navigation
fix(mcp): add tool titles, effect hints, and descriptive help - #4480
Conversation
|
Apex Sentinel could not review commit Apex Sentinel hit an internal error and could not finish this review. This is a problem on Sentinel's side, not with the change; if it keeps happening, tell whoever runs Sentinel for this repository. Push a new commit or comment |
Size Report
Startup median (7 runs, lower is better):
|
There was a problem hiding this comment.
All reported issues were addressed across 26 files
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
|
The change looks good overall at 6baf06a, with one problem to fix: src/mcp/command-tools.ts:152 sets destructiveHint to !readOnlyHint, so snapshot, get, is, wait, screenshot, doctor and find are advertised as destructive. MCP defines destructiveHint as destructive versus additive updates, so hosts that confirm destructive tools will gate pure observations. Could each command declare its destructive effect directly, so only uninstall, reinstall, shutdown, clipboard write, settings and similar commands carry it? Could CommandMetadata (or the registry descriptor next to recordingEffect) own a title and an effect of read, write or destructive, with listCommandTools deriving the annotations from it? That would replace the parallel table in src/mcp/tool-metadata.ts and fix the inversion in one place. First decide whether MCP read-only means "observes the app" (a registry trait) or "writes no artifacts and does not foreground"; if the latter, the registry needs a declared trait for that rather than an MCP-side override. Not blocking: no tool advertises idempotentHint (devices, apps and help are idempotent, and fill replaces text), so either derive it from the same effect declaration or note in the PR body that it stays at the default; you can take or leave this. On the open inline threads: these still apply and are wording or hint fixes: #4480 (comment) (destructiveHint inversion, the finding above), #4480 (comment) (error overlay wording), #4480 (comment) (platform identifier wording), #4480 (comment) (alert timeout sentence). These do not apply and can be resolved: #4480 (comment) (snapshot refs text is unchanged base claim), #4480 (comment) (doctor simulator text is unchanged base), #4480 (comment) (longpress help scope expansion), #4480 (comment) (target_still_moving text is byte-identical to base), #4480 (comment) (the type already makes the table exhaustive; a check against the registry recordingEffect is the better test), #4480 (comment) (pose text unchanged base). All 21 build and test checks pass. The only non-passing check is an external review check that runs no build or test lane, so it looks unrelated. There are no conflicts. I read the diff and the PR body but did not run the tests or the stdio smoke, did not confirm the advertised tool count (62 or 63 with help), and did not trace the iOS runner to confirm that get, is, snapshot and wait can foreground the app. Before merge, replace the destructiveHint inversion with a declared per-command effect and answer the four open wording threads. |
|
This branch now conflicts with main at 6baf06a. Please rebase, and while rebasing address the earlier review: derive the MCP annotations from one per-command effect declaration so read-only tools are not advertised as destructive. |
6baf06a to
cf0a96a
Compare
Apex Sentinel · ✅ ApproveSince the last review: 1 new · 0 still open · 2 no longer raised (1 marked fixed) 1 finding(s): 1 minor. 🟡 Minor (1)
Reviewed with this repository's own Sentinel configuration ( 💬 Talking to SentinelIn a finding's thread, reply with:
On this conversation, comment Earlier reviewsReview of
|
| Where | Finding |
|---|---|
packages/command-surface/src/interaction/index.ts:584 |
🆕 get/is/wait/snapshot advertised non-read-only though their text says they change nothing |
packages/command-surface/src/metro/index.ts:131 |
🆕 metro reload marked destructive but cannot replace data; inconsistent with hardware button press |
1 finding below minor not shown (user_settings.min_severity).
Reviewed with this repository's own Sentinel configuration (b7ded9cfb269).
Review of cf0a96af · 13.11.2026 00:22 UTC
Apex Sentinel
Verdict: approve
No findings.
Reviewed with this repository's own Sentinel configuration (b7ded9cfb269).
cf0a96a to
a18f192
Compare
|
Addressed in
The rebase preserves main’s newer wait-text, snapshot, and verified iOS back-swipe contracts. A fresh merge-tree check is clean. Validation at the published head: affected gate passed with |
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Apex Sentinel: 2 new findings on a18f192. The verdict and the full list are in the summary comment.
|
Thanks for the update. The conflict from the earlier review (#4480 (comment)) is gone and no conflicts remain, but one defect remains at a18f192.
Please declare Not blocking: the read check in router-tool-metadata.test.ts:27 can also require On the open inline threads: two review threads do not apply, so please resolve them. The Smoke Tests (ios) fails at I did not run the router test or the stdio smoke. I confirmed the Android boot path for |
|
This branch now conflicts with main after today's merges. The finding from the review at a18f192 still applies (#4480 (comment)): |
a18f192 to
7824e99
Compare
|
Addressed the latest review and conflicts together in
The rebase preserves main’s relaunch, orientation, and verification guidance. A fresh merge-tree check was clean. Exact-head affected gate: passed ( The requested iOS smoke rerun passed on unchanged |
There was a problem hiding this comment.
Apex Sentinel: 1 new finding on 7824e99. The verdict and the full list are in the summary comment.
| export const logsCommandFacet = defineCommandFacet({ | ||
| name: LOGS_COMMAND_NAME, | ||
| effect: 'destructive', | ||
| text: { | ||
| summary: 'Manage session app logs', | ||
| }, |
There was a problem hiding this comment.
🆕 🟡 Minor · logs marked destructive though it is an observation tool; only read/delete-free subcommands
logs is published with destructiveHint: true, so a client gating on that hint refuses plain log reads via logs path, logs doctor, and logs mark—all read-only/diagnostic subcommands. The sibling evidence tools in the same file use write/read effects, and the PR's own rule in agent-setup.md limits destructive to tools that "replace or delete existing data, or dispatch arbitrary app actions." The new router-tool-metadata test does not cover logs, so nothing pins either choice.
Suggested change
Either mark logs as 'write' like the other evidence tools, or justify the destructive classification in agent-setup.md and add 'logs' to the expected-annotations list in router-tool-metadata.test.ts.
export const logsCommandFacet = defineCommandFacet({
name: LOGS_COMMAND_NAME,
effect: 'write',
text: {
summary: 'Manage session app logs',
Details
Also raised here
Also raised at this location by persona javascript: logs, a log/evidence tool, advertises destructiveHint: true, contradicting the new doc contract — A client that gates destructive calls asks the user to approve logs ("Session app log info, start/stop streaming, diagnostics, and markers"), i.e. reading the session app log, while network, perf, record and trace — the same evidence class — do not. The facet declares effect: 'destructive', which listCommandTools projects to destructiveHint: true. This contradicts both the PR description ("Observation/evidence tools are non-destructive writes") and the sentence this PR adds to website/docs/docs/agent-setup.md: "Observation and evidence tools that can cause these changes declare a write effect without a destructive hint." Either the effect is wrong for logs, or the doc's rule needs the logs exception stated.
persona: senior-developer, javascript
Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.
Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.
|
No code blockers found at 7824e99: The open logs thread does not apply: |
Summary
Address the MCPVetter report with titles and separate read-only/destructive hints for all 62 tools.
Command facets own required effects; titles reuse existing summaries. Read changes no device, app, session, or host state: no boot, foreground change, or artifact write.
appsandappstateare writes because their runtime declarations include readiness operations. Arbitrary app actions and forced script replacement remain destructive. Idempotence stays at MCP’s default.Example
tools/listentry:{"name":"apps","title":"List installed apps or deferred provider app assets","annotations":{"readOnlyHint":false,"destructiveHint":false}}Descriptions state behavior rather than workflows. 36 files; declarations, MCP projection, shared help, docs, and tests only. No linked GitHub issue. Rebase preserves main’s relaunch, orientation, and verification guidance.
Validation
Head:
7824e9914398e76814e0550de61bd0b985553444; base:efe6bb9eece4794e4cc7f4e62ea22f3e75569b56.pnpm check:affected --run --head HEAD: passed,exactCommit=true,checkoutChanged=false. Unit: 19,705 passed, 3 skipped. Related: 372 passed. Readiness regression: prior heada18f192512plus test → 2 failures; current head → 2 passes.Read-only guards inspect required/preferred/conditional runtime uses for readiness/boot operations and reject recorded app mutations. Focused tests: 551 passed. Stdio smoke: both protocols/output modes.
iOS smoke rerun passed at prior head
a18f192512. Current-head hosted CI remains separate and owns provider/platform/coverage lanes. No device execution changes.