Make the execution ladder legible from every rung

[robertjamesprior]

Second half of the metadata work. #198 covered the catalog entry and the server instructions; this covers the tool descriptions, where the model actually chooses.

The gap

Main has moved since this opened. execute_playwright_code now tells the caller to check webmcp.listTools() first and prefer a structured tool when the site exposes one, so the webmcp-to-playwright half is already there. Three things still are not:

• manage_browsers creates the session every web task runs in and never says how to drive it.
• computer_action opened with "execute computer actions on a browser session", which tells a model nothing the tool name did not.
• browserSessionNextActions(), returned after create and update, named computer_action first. The most expensive rung, recommended as the immediate next step, contradicting the descriptions either side of it.

The change

Three description openings and one returned hint. Operational detail untouched.

• manage_browsers: names the four ways to drive a session once it exists, in preference order.
• computer_action: visual control for when the DOM cannot carry the step, and what to prefer above it.
• execute_playwright_code: adds computer_action below the existing WebMCP preference.
• browserSessionNextActions(): returns the same order instead of computer_action alone.

The ladder gained a rung since this opened. browser_repl sits with execute_playwright_code as DOM interaction, so all four mentions name it, matching how webmcp already lists the fallbacks.

What I did not touch

The other tools. Most open with "manage X" and describe the resource rather than the job, and several already carry a decent "when an agent needs Y" clause. Rewriting all of them is an unreviewable diff; these are the ones a model picks between during a web task.

No test pins the description prose. Asserting on it would need source matching or reaching into the SDK's private tool registry, both more brittle than what they would protect. The next_actions hint is a returned value, so that one is pinned: a new test holds it to naming webmcp before computer_action.

Testing

bun test: 1050 pass, 0 fail. tsc --noEmit clean.

🤖 Generated with Claude Code

---

Note

Low Risk
Metadata-only changes to tool descriptions and user-facing hints; no runtime behavior or API contract changes beyond guidance text.

Overview
Aligns MCP tool descriptions and post-create next_actions so models see the same browser-control preference everywhere: webmcp, then browser_repl / execute_playwright_code, then computer_action when the DOM cannot carry the step.

manage_browsers now states that sessions are the container for web work and names all four driving tools in order. computer_action is reframed as coordinate/visual control and what to try first. execute_playwright_code adds computer_action as the last rung below the existing WebMCP preference. browserSessionNextActions() returns that full ladder in the first hint instead of leading with computer_action alone.

A new test asserts the create response’s first next_actions entry mentions webmcp before computer_action and includes the session id.

^{Reviewed by Cursor Bugbot for commit b66f8a8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
mcp	Ready	Preview	Oct 16, 2026 3:11pm UTC

[masnwilliams]

This makes the tool-choice order clearer without adding implementation complexity. No blocking code-quality concerns; 604 tests passed locally. Two non-blocking copy alignments below.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b3233ae. Configure here.}