WebMCP Tools

Implement tools using the W3C WebMCP API (navigator.modelContext) so AI agents, browser assistants, and assistive technologies can call structured JavaScript functions on your page.

When to Apply

Reference these guidelines when:

Adding tools to a web page for browser AI agents
Registering callable functions via navigator.modelContext
Exposing existing page functionality to agents
Building cooperative human-in-the-loop agent workflows

Essential Rules

Priority	Rule	Description
CRITICAL	`tool-definition`	Every tool needs name, description, inputSchema, and execute
CRITICAL	`security`	Validate params, confirm destructive actions, don't leak sensitive data
HIGH	`descriptions`	Write specific descriptions — this is what the LLM reads to pick the tool
HIGH	`dynamic-registration`	Register/unregister tools as SPA state changes
MEDIUM	`user-interaction`	Use `agent.requestUserInteraction()` for purchases, deletions, and sends

Quick Reference

1. Register a Tool (CRITICAL)

navigator.modelContext.registerTool({
  name: "add-to-cart",
  description: "Add a product to the shopping cart by ID",
  inputSchema: {
    type: "object",
    properties: {
      productId: { type: "string", description: "Product ID" },
      quantity: { type: "number", description: "How many to add (1-100)" }
    },
    required: ["productId"]
  },
  execute: async ({ productId, quantity }) => {
    await cartApi.add(productId, quantity ?? 1);
    return { content: [{ type: "text", text: `Added ${quantity ?? 1} to cart` }] };
  }
});

2. Feature Detection (CRITICAL)

if ("modelContext" in navigator) {
  navigator.modelContext.registerTool({...});
}

3. Tool Descriptions (HIGH)

// Good — specific, includes what it returns
description: "Search available flights. Returns {id, airline, price, departure, arrival}. Does not book — use book-flight to complete."

// Bad — vague
description: "Search flights"

4. User Confirmation (MEDIUM)

execute: async ({ productId }, agent) => {
  const ok = await agent.requestUserInteraction(() =>
    confirm(`Buy product ${productId}?`)
  );
  if (!ok) throw new Error("Cancelled");
  await purchase(productId);
  return { content: [{ type: "text", text: "Purchased" }] };
}

5. Dynamic Registration for SPAs (HIGH)

// React — register on mount, unregister on unmount
useEffect(() => {
  if (!("modelContext" in navigator)) return;
  navigator.modelContext.registerTool({ name: "edit-doc", ... });
  return () => navigator.modelContext.unregisterTool("edit-doc");
}, [doc.id]);

How to Use

Read individual rule files for detailed explanations and code examples:

rules/tool-definition.md
rules/descriptions.md
rules/security.md
rules/dynamic-registration.md
rules/user-interaction.md

For the complete guide with all patterns expanded: AGENTS.md

webmcp

Safety Notice

Copy this and send it to your AI assistant to learn