Build a WebMCP tool with JavaScript

Keep one implementation of the action

Try WebMCP’s native callback and visible buttons both call the same demo engine. That prevents an agent from operating a hidden copy of the cart. For a real product, reuse your existing authorized application service and commit the result to the visible state before returning success.

Describe and validate the input

A JSON Schema helps the agent choose valid arguments. Validate again inside the handler: IDs must exist, quantities must fit stock, and dates must form a valid range. Return a useful error that explains how to recover. In the commerce demo, a second oversized addition cannot silently exceed inventory.

Register for the page lifetime

The current Chrome documentation uses document.modelContext.registerTool and accepts an AbortSignal for registration cleanup. Abort that controller when the component leaves the page. Keep registration stable while ordinary application state changes; use current state inside the shared handler.

const lifetime = new AbortController();
const context = document.modelContext;

if (context?.registerTool) {
  await context.registerTool({
    name: "get_cart_total",
    description: "Read the current cart total in USD.",
    inputSchema: { type: "object", properties: {},
      additionalProperties: false },
    annotations: { readOnlyHint: true },
    execute: async () => ({ total: readCartTotal(), currency: "USD" })
  }, { signal: lifetime.signal });
}
// On disposal: lifetime.abort();
// readCartTotal must be implemented by your application.

Chrome: Imperative API · updated September 1, 2026 ↗

Stage consequential actions for review

Use names that match the effect: prepare_checkout prepares a review; it does not place an order. Try WebMCP’s confirmation lives in the page. Risk annotations communicate intent but do not replace authorization or an application-enforced confirmation rule.

Chrome: WebMCP tool security ↗