build-webmcp-tools

<!-- Copyright 2026 Google LLC SPDX-License-Identifier: Apache-2.0 -->

WebMCP Tool Development Workflow (build-webmcp-tools)

WebMCP lets a web page expose client-side capabilities as structured tools to in-browser AI agents on document.modelContext, instead of agents scraping or clicking the DOM. This skill routes a developer to the right stage of the tool lifecycle and points to the reference file that holds the detailed rules and code for that stage.

Key tenet: WebMCP runs client-side in the browser tab on document.modelContext, inside the user's authenticated session. It supports Tools only (no Resources or Prompts). It is not a backend MCP server over stdio/SSE, and tools execute application logic (state stores, APIs, client routers) directly rather than simulating typing or clicks.

How to Use This Skill

1. Match the developer's request to a row in the Router and go to that stage.
2. Read the files in the "Read first" column before responding. Paths are relative to this skill's directory. This file only summarizes them; the detailed rules, examples, and code patterns live in the references, so do not answer from this summary alone.
3. If the request refers to an artifact you were not given (transcripts, schema.json, source files), read it if it is available in the workspace; otherwise ask for it, and outline how you will apply the stage's key rules from its reference file (for audits, include the verification steps). Never invent the missing artifact.
4. Apply the Non-Negotiables to everything you produce.
5. Before finishing an audit, schema.json, or implementation, check your output against references/audit-checklist.md.

---

Non-Negotiables

• Budgets: tool and parameter names ≤ 30 chars; tool descriptions ≤ 500 chars; parameter descriptions ≤ 150 chars; output ≤ 1,500 chars (~400 tokens), paginated. → tool-design.md
• Descriptions: "What + When" (what the tool does, when to choose it); never repeat inputSchema parameters; no implementation jargon (Redux, Pinia, Express, REST, GraphQL, gRPC). → tool-design.md
• Naming & shape: action verbs; initiate_* for tools that open a form or wizard vs. book_*/create_* for immediate execution; never make the model compute values (relative dates, conversions): accept the user's phrasing and resolve it in the app, though unambiguous lookups to standard codes are fine; prefer names over opaque IDs; recommended: consolidate entities that share a lifecycle and annotations into polymorphic, batched tools, keeping trusted and user-authored content in separate tools. → tool-design.md
• Annotations: all hints default to false and are strictly opt-in (specify only when true; never declare : false); readOnlyHint: true only on pure queries; consequentialHint: true only on significant, irreversible real-world actions (payments, bookings, deletions); view navigation, tab switching, and initiate_* hand-offs must not declare readOnlyHint: true (omit it) and do not need consequentialHint, protecting unsaved work inside the tool; routine mutating tools omit annotations; untrustedContentHint: true on any output containing user- or third-party-authored text, even from your own database. → annotations.md
• Errors reach the agent: React useWebMCP throws Error (→ isError: true); native registerTool resolves { error, code, retryable } because rejections become a generic DOMException: UnknownError; declarative forms resolve structured field errors via event.respondWith. → error-handling.md
• UI sync: await state and DOM updates before a tool returns.
• Cross-origin: tools are same-origin by default (Permissions Policy tools, default self); delegate only with <iframe allow="tools"> plus registerTool(tool, { exposedTo: ['https://trusted.origin'] }); origin isolation is required (Origin-Agent-Cluster: ?0 disables WebMCP). → vanilla-patterns.md
• Design before code: every tool goes through Stages 2–4 (starting states, role-play, variations, and critique of tone, clarifying questions, and autonomous boundaries) before Stage 5–6 schemas, evals, or code; implementation simplicity is not conversational simplicity. Run Stages 2–6 in Interactive Mode (pausing after each goal's role-play for developer critique) or Autonomous Mode (working through each isolated goal's Stages 2–4, self-critique, and Stage 5–6 consolidation/code end-to-end without stops). Only skip Stages 2–4 on the Explicit Fast Path below when asked to skip design for one tool. → conversational-design.md

---

Router

The developer has / asks for	Go to	Read first	Don't yet
"Add WebMCP to this project" (local code in the workspace, no URL)	Stage 1	The project's package.json, routes, and main components; conversational-design.md	Ask what the app does; write code or schemas before Stage 1
Wants a starter toolset end-to-end without stopping ("work through the design stages autonomously", "generate starter tools")	Autonomous Mode (Stages 1–6) — inspect app, run Stages 2–4 per goal with self-critique, deliver schema + evals + code	Project files, the framework file (below), conversational-design.md, evals-format.md	Skip Stages 2–4 role-play/variations; stop early to ask questions
One specific tool idea ("a tool to search flights")	Stage 2 or 3 for that goal	conversational-design.md, use-case-template.md	Ideate an unrelated portfolio; write code
Goals already defined	Stage 2	conversational-design.md	Re-ideate goals
Goal + starting state	Stage 3	use-case-template.md, conversational-design.md	Skip the critique loop
A happy-path transcript to harden	Stage 4	conversational-design.md	—
Approved role-plays → schemas & evals	Stage 5	tool-design.md, annotations.md, evals-format.md	Invent tools for un-modeled goals
Existing schema.json → evals.json	Stage 5 (evals)	evals-format.md	Force Stages 1–4
Just finished schema.json/evals.json ("what next?")	Stage 5 eval gate	evals-format.md	Start Stage 6 without asking
Existing schema, tool spec, or named tools to implement in framework code (e.g. "write React useWebMCP tools for list_items and move_items")	Stage 6	The framework file (below), error-handling.md	Reopen conversational design
A URL or domain (e.g. example.com, https://...) to add tools to or analyze for journeys	Stage 1, after exploring the site with chrome-devtools MCP	live-site-discovery.md (not conversational-design.md first)	Ask the user to describe the site; use read_url_content or guess instead of calling chrome-devtools MCP; write frontend code
Feedback on, review, or audit of existing tools (live site or local code)	Audit	audit-checklist.md, agent-security.md, error-handling.md	Restart Stage 1 ideation
Testing, DevTools, chrome-devtools-mcp live discovery, Lighthouse, page readiness	—	testing-and-debugging.md	Scrape minified JS bundles
Concept questions	—	Budgets/naming/descriptions: tool-design.md; annotations: annotations.md; prompt injection, spotlighting: agent-security.md; errors: error-handling.md	—
Wants to skip design for one tool ("can we skip role-play and just code it?", "skip the design, give me the code")	Explicit fast path (below) — must open with 1 sentence noting the skipped design risks, then deliver schema + eval + code	tool-design.md, annotations.md, the framework file	Refuse to write code
Backend MCP (stdio/SSE server, Node/Python)	Out of scope	—	Use document.modelContext on a server

Framework files: React → react-patterns.md; Angular → angular-patterns.md; Vanilla JS, Vue, Svelte → vanilla-patterns.md; declarative HTML forms → declarative-patterns.md. All files are in references/.

Unclear entry point: ask which applies — 1) discover user goals, 2) model starting states, 3) role-play conversations, 4) harden with variations, 5) generate schema.json/evals.json, 6) implement in frontend code, or audit existing tools.

---

Explicit Fast Path

Only when the developer asks to skip design (asking "can we skip it?" counts) for a single tool. For greenfield or starter-set requests without intermediate stops, use Autonomous Mode (so Stages 1–4 still run).

1. Start the response with one or two sentences naming what is being skipped, e.g. "Skipping role-play means ambiguous requests, clarifying questions, and confirmation boundaries stay untested." Do this every time, even if the developer says they understand the risks.
2. If their reason is that the code is simple, also correct that: easy code is not an easy conversation (e.g. "a one-line state update is simple, but 'save the one I just opened' or a duplicate URL is where agents fail").
3. Deliver the tool schema, at least one evals.json case, and the framework code.
4. Still apply every Non-Negotiable (budgets, What + When, annotations, error handling). Don't argue for design again.

Stage 1: User Goals Portfolio

• Inspect the app yourself, then propose 3 prioritized candidate journeys derived from what the app actually does. For each journey, state its ideal outcome, required context, and autonomous boundary (what the agent must not do without user confirmation).
• Live site: explain that tools must be registered by code running in the page (first-party code or an extension/content script) on document.modelContext, not by headless scraping. If chrome-devtools MCP (or another browser tool) is available in your environment, call it immediately (navigate_page, take_snapshot, check /llms.txt, and check list_webmcp_tools / document.modelContext.getTools()) to inspect the rendered pages before proposing journeys—never rely on static HTTP fetchers (read_url_content, curl) or training-data assumptions. Only if no browser tool is available in your environment, recommend browsing or inspecting the site's pages and checking /llms.txt before proposing journeys.
• Offer two pacings for Stages 2–6:
  • Interactive Mode (One goal at a time, developer checkpoints): pick ONE goal to step through Stages 2–4, pausing at the User Critique Loop (tone, clarifying questions, autonomous boundaries) before moving on.
  • Autonomous Mode (End-to-end, agent self-critique): have the agent work through Stages 2–4 (starting states, role-play, variations, self-critique) per isolated goal without stopping, read the framework file, and deliver Stage 5 (schema.json, evals.json) and Stage 6 (framework code).
• Single tool idea (e.g. "a tool to search flights"): skip the portfolio. Frame that one request as a user goal (ideal outcome, required context, autonomous boundaries) and continue straight into Stage 2 or Stage 3 for it.

Stage 2: Starting States Matrix

• Model functional state for the goal: active route, loaded entities, cart/selection, session and auth, constraints.
• Prune irrelevant diagnostics (device_battery, gpu_temp, screen_dpi).

Stage 3: Turn-by-Turn Role-Play

• Document every turn with 6 elements: User utterance, Agent intent, Agent tool invocations, Tool response (structured JSON with pagination fields page_size and total_count, ≤ 1,500 chars), Site implementation & UI reaction, Agent response. Format with use-case-template.md.
• For payments, bookings, or high-stakes actions, model a human-in-the-loop UI hand-off (e.g. initiate_booking returning status: "requires_user_action" and navigating to a dedicated confirmation UI where the user clicks Confirm, rather than autonomously charging the user).
• End with the Critique Loop (evaluating agent demeanor/tone, clarifying questions, and autonomous confirmation boundaries): in Interactive Mode, pause and ask the developer to critique; in Autonomous Mode, explicitly self-critique those three dimensions for each goal and continue.

Stage 4: Variations & Graceful Failure

Stress-test the baseline: missing required parameters (ask, never guess), prerequisite violations (actionable errors), over-constrained queries (suggest relaxations), coreference ("the second one"), and human-in-the-loop hand-off for sensitive actions (return status: "requires_user_action" and open a dedicated confirmation UI the user completes; consequentialHint: true only on a tool that commits the action itself).

Stage 5: Tool Consolidation & Evals

• Consolidate only tools from approved goals (Iterative Incremental or Portfolio-First pathway); apply tool-design.md and annotations.md to every tool.
• Write schema.json and evals.json per evals-format.md.
• Then ask the user whether to run npx webmcp-evals local -t schema.json -e evals.json now or proceed to Stage 6. If they run it, check that the provider key is set in .env (GOOGLE_AI for Gemini, or OPENAI_API_KEY / ANTHROPIC_API_KEY) and suggest a fast model.

Stage 6: Application Implementation

• Read the framework file first. React: useWebMCP from use-webmcp-tool (never raw registerTool in components), schema literals hoisted or stable, and always include a Vitest + React Testing Library test that mocks document.modelContext.registerTool and calls the captured execute. Angular: provideExperimentalWebMcpTools. Vanilla: document.modelContext.registerTool with an AbortController signal. Declarative: <form toolname tooldescription>.
• Verify with testing-and-debugging.md (DevTools Application > WebMCP pane, Lighthouse "Agentic browsing") and self-check against audit-checklist.md.

Audits

1. First read references/audit-checklist.md, references/agent-security.md, and references/error-handling.md (you can request them together), and only then open the code under review. The checklist, not the Non-Negotiables summary, is the audit standard; an audit based only on this file is incomplete.
2. Collect the tools:
   • Local codebase: read the registration code (useWebMCP, registerTool, provideExperimentalWebMcpTools, <form toolname>).
   • Live site: discover tools at runtime across routes, tabs, and UI states using list_webmcp_tools (chrome-devtools-mcp with --categoryExperimentalWebmcp), await document.modelContext.getTools(), or the DevTools Application > WebMCP pane (see references/testing-and-debugging.md). If document.modelContext is undefined, WebMCP is not enabled in the browser (--enable-features=WebMCP or chrome://flags/#enable-webmcp-testing)—report that prerequisite instead of assuming no tools exist. Never fetch or scrape minified production JS bundles on a live site; only inspect live-site source when unminified or sourcemapped.
3. Report findings per checklist item, each with the affected tool and a concrete fix.
4. End with verification steps: inspect and manually execute the tools in the Chrome DevTools Application > WebMCP pane (Play icon), and run the Lighthouse "Agentic browsing" audit.
5. No tools available yet (e.g. a live site you cannot open): do not stop at asking for code. Tell the user how to collect the tools (await document.modelContext.getTools() across routes in the console, list_webmcp_tools via chrome-devtools-mcp, or the DevTools Application > WebMCP pane), list the checklist areas you will audit (budgets and jargon, annotations including navigation and UGC, error handling, security), and end your reply with the verification steps from step 4 (DevTools manual execution, Lighthouse "Agentic browsing").