Sharpen WebMCP guidance for empty catalogs, tool_ref misuse, and outcome_unknown

[rgarcia]

Summary

Smoke tests with an MCP client agent exercising the new webmcp tool and the execute_playwright_code WebMCP helpers surfaced three places where the tool descriptions left the agent guessing:

• After outcome_unknown, the agent knew not to retry but had no stated way to resolve the ambiguity. Both descriptions now say to read page state (ariaSnapshot() / webmcp.listTools() or execute_playwright_code) to decide whether the action happened.
• When discovery returned zero tools, the agent passed a tool name as tool_ref. Both descriptions now say to pass only a tool_ref from the latest list and never a tool name.
• An empty catalog was read as WebMCP being broken in the browser. Both descriptions now say the site most likely does not support WebMCP or uses an outdated WebMCP API, and point to Playwright/computer interaction as the fallback.

Description text only; no behavior or schema changes.

Testing

• bun test src/lib/mcp/tools/webmcp.test.ts src/lib/mcp/register.test.ts passes (11 tests); the exact-match description test was updated.
• prettier --check passes on the touched files.

[vercel]

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

Project	Deployment	Actions	Updated
mcp	Ready	Preview	Sep 3, 2026 3:27pm UTC