Implement WebMCP in web projects — add browser-native structured tools for AI agents using imperative JS or declarative HTML APIs. Full lifecycle from setup through testing and optimization.
<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:
window.navigator.modelContext — register tools via JavaScripttoolname/tooldescription attributes on <form> elementsPrerequisites: 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>
Wait for response before proceeding. </intake>
After reading the workflow, follow it exactly. </routing>
<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:
navigator.modelContext exists (Chrome flag enabled?)Report to user:
</verification_loop>