Define a page tool

A page tool is a plain JavaScript object in the shape of WebMCP, the draft web standard for tools a website offers to AI agents.

const addToCart = {
  name: 'add_to_cart',
  title: 'Add to cart',
  description: "Add this page's product to the visitor's cart. Use it when the visitor wants to buy or add it.",
  inputSchema: {
    type: 'object',
    properties: {
      quantity: { type: 'integer', minimum: 1, description: 'How many to add' },
    },
    required: ['quantity'],
  },
  async execute({ quantity }, { signal }) {
    const cart = await addProductToCart(PRODUCT_ID, quantity, { signal }); // your own code
    return { added: quantity, items: cart.items.length, total: cart.total };
  },
};

Fields#

Write names and descriptions the AI understands#

The agent chooses tools by reading their names and descriptions, so write them for that reader.

• Name the action: a verb and an object, such as open_booking, read_cart or start_return. Avoid names like action1 or handleClick.
• Say when to use it, not only what it does: "Open the booking form for a meeting type. Use it whenever the visitor wants to book a call."
• Say what it can't do: "Works only for the product on this page."
• One tool, one job. Two clear tools work better than one tool with a mode switch.
• Describe every input with description, and limit choices with enum.

Describe the input with JSON Schema#

inputSchema: {
  type: 'object',
  properties: {
    orderId: { type: 'string', description: 'The order number, such as A-1001' },
    reason: { type: 'string', enum: ['damaged', 'wrong-size', 'changed-mind'] },
    refundToCard: { type: 'boolean', description: 'Refund to the original card instead of store credit' },
    skus: { type: 'array', items: { type: 'string' }, description: 'The products to return' },
  },
  required: ['orderId', 'reason'],
},

The agent fills in the input, but treat it as you would a form submission: check it in execute before you act on it.

What execute returns#

What you return becomes the tool's result, as JSON:

Return what the agent needs to answer well, such as { opened: true } or { items: 2, total: '$48' }. Never return secrets: results are saved in the conversation, and your team reads them in Inbox.

Errors#

Throw an Error, or reject the promise, and the agent gets your message, such as "The booking form is already open", up to 1,000 characters. It tells the visitor or tries another way. For an expected miss, such as an item out of stock, return a normal result like { ok: false, reason: 'out of stock' }: it gives the agent more to work with than an error.

Reading tools and actions#

• A tool that only reads, such as the cart or the product on the page, runs straight away. You can mark it annotations: { readOnlyHint: true } for other WebMCP agents; help.ai doesn't use the hint yet.
• A tool that changes something the visitor would want to confirm, such as an order, a refund or a message to someone, should have consequentialHint: true. See Ask before an action runs.

Duplicates and mistakes#

• Same name twice: the latest registration wins. Remove it (see Add page tools to your site) and the earlier one is back.
• A broken tool: one without a name or an execute function is left out, with a warning in the browser console. Your other tools still work, and the chat never breaks because of a tool.
• A tool that's gone: if the agent calls a tool your page no longer offers, because the visitor moved to another page, the agent learns that the page doesn't offer it right now and tells the visitor.