Make the execution ladder legible from every rung - #201
Open
robertjamesprior wants to merge 1 commit into
Open
robertjamesprior wants to merge 1 commit into
robertjamesprior wants to merge 1 commit into
Conversation
webmcp already tells a caller to fall back to execute_playwright_code or computer_action when a site offers no tools of its own. The other three say nothing about each other, so a model picking between them has to already know the order. manage_browsers now names the three ways to drive a session it creates. execute_playwright_code says when to prefer it over webmcp and when to drop to computer_action. computer_action says it is the last resort rather than describing itself as executing computer actions. Operational detail in all three is unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
masnwilliams
approved these changes
Sep 22, 2026
masnwilliams
left a comment
masnwilliams
left a comment
Collaborator
There was a problem hiding this comment.
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.
| server.tool( | ||
| "execute_playwright_code", | ||
| "Execute Playwright/TypeScript automation or browser-wide WebMCP helpers against an existing Kernel browser session. Does not create or delete browsers -- use manage_browsers to manage session lifecycle.", | ||
| "Drive a page through the DOM, using Playwright/TypeScript automation or browser-wide WebMCP helpers, against an existing Kernel browser session. Use this when a site exposes no WebMCP tools of its own, and fall back to computer_action only when the DOM cannot drive the page. Does not create or delete browsers -- use manage_browsers to manage session lifecycle.", |
Collaborator
There was a problem hiding this comment.
non-blocking: “Use this when a site exposes no WebMCP tools” is narrower than the actual per-step rule. A site can expose tools and still need Playwright for navigation, inspection, or submitting a non-autosubmit WebMCP form. Could this say to prefer a relevant site tool for the current step, then use Playwright when that tool is unavailable or insufficient?
| server.tool( | ||
| "manage_browsers", | ||
| 'Manage browser sessions and their archived telemetry. Use "list" to choose an existing session, "create" before browser control, "update" to change supported session settings, "get" for full details, "get_telemetry" to diagnose active or deleted sessions, and "delete" when finished. Live sessions can be addressed by ID or by the name given at creation or set on update; deleted sessions only by ID. get_telemetry compacts events by default; set compact=false with explicit categories and a limit of at most 5 when raw headers, request data, response bodies, or other omitted fields are needed.', | ||
| 'Create and manage the browser sessions that every web task runs in, and read their archived telemetry. Once a session exists, drive it with webmcp, execute_playwright_code, or computer_action, in that order of preference. Use "list" to choose an existing session, "create" before browser control, "update" to change supported session settings, "get" for full details, "get_telemetry" to diagnose active or deleted sessions, and "delete" when finished. Live sessions can be addressed by ID or by the name given at creation or set on update; deleted sessions only by ID. get_telemetry compacts events by default; set compact=false with explicit categories and a limit of at most 5 when raw headers, request data, response bodies, or other omitted fields are needed.', |
Collaborator
There was a problem hiding this comment.
non-blocking: the new preference order conflicts with browserSessionNextActions(), which still recommends computer_action first after create/update. Worth aligning that returned hint with this description so the immediate next action does not steer agents to the last resort.
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
webmcpalready handles this well. Its description tells the caller what to do when a site offers no tools of its own: "use execute_playwright_code or computer_action instead of invoking."The other three rungs say nothing about each other.
manage_browserscreates the session every web task runs in and never mentions how to drive it.execute_playwright_codepoints atmanage_browsersfor lifecycle but not at the layers either side of it.computer_actionopened with "Execute computer actions on a browser session", which tells a model nothing it did not already know from the tool name.So a model choosing between them has to already know the order, which is exactly what we cannot assume.
The change
Three opening sentences. Operational detail in all three is untouched.
computer_actiononly when the DOM cannot drive the page.webmcpis unchanged. It was already right.What I did not touch
The other 23 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 a real piece of work and an unreviewable diff; these four are the ones a model picks between during an actual web task, so they are where the ordering matters.
No test pins this. Asserting on description prose would need either source-text matching or reaching into the SDK's private registry, and both are more brittle than the thing they would protect.
Testing
bun test: 604 pass, 0 fail.🤖 Generated with Claude Code
Note
Low Risk
Documentation-only changes to MCP tool description strings; no runtime, API, or auth behavior changes.
Overview
Updates the opening sentences of three MCP tool descriptions so models see the same web execution order at choice time: webmcp → execute_playwright_code → computer_action, with manage_browsers for session lifecycle.
manage_browsersnow states that sessions underpin every web task and names the three ways to drive a live session, in preference order.execute_playwright_codeis framed as DOM/Playwright (and browser-wide WebMCP helpers) when the site has no own WebMCP tools, withcomputer_actiononly when the DOM cannot drive the page.computer_actionis framed as coordinate/visual control as a last resort, explicitly below site WebMCP and Playwright.Operational detail in each description is unchanged;
webmcpand the other tools are not modified in this diff.Reviewed by Cursor Bugbot for commit de860ca. Bugbot is set up for automated code reviews on this repo. Configure here.