What page tools are and how they work

Page tools let the AI agent do things on your website, not only answer questions. Your page lists a few actions it offers, such as opening the booking form, reading the visitor's cart or adding a product to it, along with the code that does each one. When a visitor asks for something a tool can do, the agent calls it, the widget runs your code in the visitor's browser, and the agent carries on with what your code returned.

Every page can offer different tools. On a product page the agent can add that product to the cart; on your pricing page it can open the plan comparison.

A short example#

<script>
  window.HelpAI = window.HelpAI || function () { (HelpAI.q = HelpAI.q || []).push(arguments); };
  HelpAI('registerTool', {
    name: 'open_booking',
    description: 'Open the booking form for a meeting type. Use it whenever the visitor wants to book a call.',
    inputSchema: {
      type: 'object',
      properties: { meetingType: { type: 'string', enum: ['sales', 'support'] } },
      required: ['meetingType'],
    },
    execute({ meetingType }) {
      openBookingForm(meetingType); // your own code
      return { opened: true };
    },
  });
</script>
<script
  src="https://cdn.help.ai/sdk/js/elements/1.12.0/elements.js"
  data-public-key="YOUR_PUBLIC_KEY"
  data-ai-agent-deployment-id="YOUR_DEPLOYMENT_ID"
  defer
></script>

A visitor writes "I'd like to talk to sales". The agent calls open_booking with { meetingType: 'sales' }, your booking form opens, and the agent replies that the form is open and they can pick a time.

How a call works#

1. When the visitor sends a message, the widget reads the tools your page offers at that moment and sends their names, descriptions and inputs with the message. Your code never leaves the page.
2. The AI agent decides whether a tool helps. It knows your tools as site__<name>, next to the tools you gave it in the dashboard.
3. The widget runs your execute function in the visitor's browser, with the input the agent chose.
4. What it returns, or the error it throws, goes back to the agent, which continues its reply.

Each call runs once, in the tab where the visitor sent the message: not again after a reload, not in their other tabs, and not twice when the widget's script is on the page twice.

You need widget 1.11.0 or later. Page tools work with every way of installing the widget: the script tag, the npm package, the React kit and the <web-ai-chat> element.

What the visitor sees#

• With Show actions on (the deployment's Chat widget tab → Behavior), each call shows as a card, such as Site · Open booking, that reads Running, then Completed or Error. The visitor can expand it to see the input and the result. With it off, the default, they see only the agent's reply.
• While a tool runs, the send button turns into Stop. Selecting it ends the tool, nothing goes to the agent, and the card reads Not completed. A call cut short by a reload or by a new message reads Not completed too.
• For an action with consequences, you can have the agent ask first: the visitor sees an approval card, and the tool runs only when they select Approve. See Ask before an action runs.

What your team sees#

• Inbox: the conversation shows each call as a site__<name> step with its input and its result or error, followed by the agent's reply.
• Analytics → AI Model: each model turn lists the tools it used, page tools included, in the Tools column.

Where results are stored#

A call and its result are saved in the conversation with the rest of the reply, like any tool the agent uses, and the agent can refer back to them later in the conversation. A result over 30,000 characters is cut to a preview. Your tool definitions travel with each message; your code stays on your page.

Good first tools#

• Open part of your page: a booking form, the plan comparison, a section of a long page.
• Read what the visitor sees: their cart, the product on the page, their current plan.
• Do what they could do themselves: add to cart, start a return, fill in a form.

Keep each tool to what the visitor could do on the page themselves. The agent acts as them, in their browser.