<essential_principles>

WebMCP is a browser-native standard that exposes structured tools for AI agents on websites. Instead of screen-scraping, agents interact through typed JavaScript APIs and HTML annotations.

Two APIs:

• Imperative API — window.navigator.modelContext — register tools via JavaScript

• Declarative API — HTML toolname /tooldescription attributes on <form> elements

Prerequisites: Chrome 146.0.7672.0+, chrome://flags/#enable-webmcp-testing enabled.

Core principles that always apply:

Tools must be atomic and composable — one function per tool, no overlapping tools with nuanced differences. Combine similar tools into one with input parameters.

Accept raw user input — tools should accept natural strings (e.g., "11:00") not computed values (e.g., minutes-from-midnight). Minimize cognitive computing for the model.

Validate in code, not schema — schema constraints are helpful but not guaranteed. Validate within execute functions and return descriptive errors so agents can self-correct.

Update UI before returning — agents use UI state to verify execution. Ensure execute/submit logic updates visible state before resolving.

Positive, verb-first descriptions — describe what the tool does and when to use it. Avoid negations. "Creates a calendar event for a specific date" not "Do not use for weather."

</essential_principles>

• Set up WebMCP in a project (initial integration)

• Add a tool using the imperative JavaScript API

• Add a tool using the declarative HTML form API

• Debug WebMCP tools that aren't working

• Audit existing WebMCP implementation for best practices

• Test WebMCP tools

• Something else

Wait for response before proceeding.

After reading the workflow, follow it exactly.

<reference_index>

All in references/ :

APIs: imperative-api.md, declarative-api.md Design: tool-design.md Events: events-and-css.md Quality: testing.md, anti-patterns.md

</reference_index>

<workflows_index>

All in workflows/ :

Workflow Purpose

setup-webmcp.md Initial WebMCP integration into a project

add-imperative-tool.md Register tools via JavaScript API

add-declarative-tool.md Annotate HTML forms as WebMCP tools

debug-webmcp.md Diagnose and fix WebMCP issues

audit-webmcp.md Review implementation against best practices

test-webmcp.md Test tools with inspector extension and agents

</workflows_index>

<templates_index>

All in templates/ :

Template Purpose

imperative-tool.md Scaffolding for JS-registered tools

declarative-form.md Scaffolding for HTML form-based tools

</templates_index>

<verification_loop>

After every WebMCP change:

• Open Chrome DevTools console — check for JS errors

• Verify navigator.modelContext exists (Chrome flag enabled?)

• Use Model Context Tool Inspector extension to list registered tools

• Manually execute a tool from the inspector to confirm it works

• Check that UI updates are visible after tool execution

Report to user:

• "Tools registered: X imperative, Y declarative"

• "Tool [name]: executes successfully / returns error [detail]"

• "UI state: updates correctly after execution / missing update"

</verification_loop>