Bring the Plans MCP tool reference in line with the server - #40

What changed and why

plans/install/index.mdx is the canonical list of tools the Ref Plans MCP server exposes, and it was missing three that the server registers. The consequential one is view_media: Read hands back image markdown as raw ref-media:// URIs that are not fetchable directly, and rich-content.mdx already promises agents can view the pixels — so an agent built from the published list could read a plan full of images with no documented way to see any of them. Rename and AwaitReview were also absent, Create has gained kind and initiative, and two review capabilities are registered for only some kinds of session, which plans/collaboration/reviews.mdx described with no caveat.

Verified

All in ref-tools/ref:

• view_media exists in both modes — registered in plan-app/server/src/routes/mcpPlanServer.ts and mcpGeneralServer.ts. Behaviour read from the handler, plan-app/server/src/utils/mcpViewMediaToolHandler.ts: size defaults to standard and accepts thumb / standard / original; format defaults to url and returns a signed link with an expiresAt; format: "image" downloads the object and returns a base64 MCP image block. ref-media:// non-fetchability and the "call view_media" instruction are in the Read tool description in plan-app/server/src/routes/mcpToolDefinitions.ts.
• Rename exists in both modes — registered in both server factories; the schema is title (plus planId in general mode) and the description says it sets the plan's title (mcpToolDefinitions.ts).
• AwaitReview exists in both modes, user-driven sessions only — both factories register it inside an if (userDriven) guard. The 50-second hold is AWAIT_REVIEW_WINDOW_MS = 50_000 in plan-app/shared/reviewWaitTiming.ts, consumed as the default window by runAwaitReview in plan-app/server/src/utils/awaitReviewTool.ts, which returns a pending result telling the model to call again when the window expires.
• Create parameters — mcpToolDefinitions.ts: title, initial_content, kind (plan | explanation | receipt, default plan), initiative. PLAN_CREATED_INITIATIVES is ['user', 'agent'] in plan-app/shared/types.ts. mcpGeneralServer.ts strips initiative from the schema for non-user-driven sessions and drops it at write time.
• The session split — isUserDrivenSession in plan-app/server/src/utils/mcpAudience.ts is true only for API-key auth with no agent id, no internal flag, and a non-in-process connection. The signals are assembled in plan-app/server/src/routes/mcp.ts; Ref's own agent runner sets internal: 'true' (plus an agentId) when it builds the plan MCP URL in plan-app/cli/src/commands/agent-thread-config.ts. commentActionsFor omits request_review from the orchestrated action enum, and the orchestrated redirect copy says such an agent's work is reviewed in the app on the plan it was launched on.
• Agent-requested reviews go to the API-key owner — plan-app/server/src/utils/mcpRequestReviewHandler.ts always uses the authenticated owner's email as the reviewer; the email parameter in commentsInputSchema is explicitly ignored. The email-based path in the app is requestReview(planId, email) from plan-app/client/src/components/SharePanel.tsx, which matches the flow already documented on the page.
• request_media_upload is still registered as a deprecated alias alongside upload_media in both factories, so the existing sentence stays accurate.

Unverified / omitted

• "remains as a deprecated alias for one release" — pre-existing sentence, left untouched. The alias is definitely still registered and described as deprecated, but nothing in the product repo pins the removal to a specific release. A stated deprecation window would unblock making that precise.
• Signed-link lifetime for view_media — the handler uses a fixed TTL, but the page says "temporary link" rather than a duration, since the number is an internal constant that could move without notice.
• Pixel dimensions of thumb / standard — omitted; derivative max-edge sizes are internal constants and not part of any stated contract.
• Whether agents launched onto external harnesses (Cursor, Devin, Warp OZ, Conductor) reach the plan MCP as orchestrated sessions — the in-house agent runner demonstrably does, so the note is phrased as "agents that Ref launches and runs for you". I could not confirm the MCP wiring for every external harness, so no per-harness claim is made.
• Manual topic list differences between session kinds — orchestrated sessions also get a smaller topic enum, but the page does not enumerate Manual topics today and adding that list would be a restructure, so it is left out.

Conflicts

None expected — docs.json is untouched. Only plans/install/index.mdx and plans/collaboration/reviews.mdx changed.

Generated by Claude Code