webmcp

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