# Test and troubleshoot page tools

> A checklist to run before launch, the toolResult event, and fixes for common problems.

Try every tool the way a visitor would before you launch. While you test, turn on **Show actions** (the deployment's **Chat widget** tab → **Behavior**) so each call shows as a card.

## Checklist

1. **Each tool:** ask for it in plain words. The card reads **Completed** and the answer uses the result.
2. **Tools that ask first:** **Approve** runs the tool; **Reject** doesn't, and the card reads **Denied**.
3. **Forms:** the agent fills them in; with `toolautosubmit` the form is submitted; password fields stay empty.
4. **Reload mid-call:** start a slow tool and reload the page. The card reads **Not completed**, and the tool doesn't run twice.
5. **Stop:** start a slow tool and select **Stop**. The card reads **Not completed**, and the agent doesn't reply.
6. **A new message mid-call:** the tool stops and the agent answers the new message.
7. **Changing pages:** move to a page without a tool and ask for it again. The agent says it can't do that there.
8. **Two tabs:** open your site in two tabs and send from one. Only that tab runs the tool.
9. **Failures:** make a tool throw. The card reads **Error**, and the agent explains.
10. **Your team's view:** find the conversation in **Inbox**, and the tool in the **Tools** column of **Analytics** → **AI Model**.

Test in Chrome, Safari and Firefox, and on a phone.

## Follow every call with the `toolResult` event

```js
const chat = await HelpAI.ready();
chat.on('toolResult', ({ toolCallId, name, status, durationMs }) => {
  analytics.track('help_ai_tool', { name, status, durationMs });
});
```

| `status` | Meaning |
| --- | --- |
| `completed` | The tool returned a result |
| `failed` | The tool threw an error |
| `declined` | The visitor selected **Reject** |
| `stopped` | The visitor selected **Stop** |
| `interrupted` | A reload cut the tool short |

The event never carries the input or the result. Answering one of the agent's questions in the chat fires it too, with only `toolCallId`.

## Common problems

| What you see | Why | What to do |
| --- | --- | --- |
| The agent never uses a tool | Its description says what it does but not when, or the tool was left out | Add "Use it whenever…" to the description, and look in the browser console for a "skipped a tool" warning |
| No card in the chat | **Show actions** is off | Turn it on in the deployment's **Chat widget** tab → **Behavior** |
| A tool that asks first never runs | **Visitor approvals** is off | Turn it on in the **Chat widget** tab → **Features** |
| "This page doesn't offer that action right now." | The tool was removed, such as by a page change, or isn't registered on this page | Keep a tool registered while the agent may still use it |
| The chat waits after a tool | `execute` never finishes | Return or throw in every case, and pass on the `signal` |
| A form isn't submitted | A field needs the visitor, such as a password | Expected: the agent asks the visitor to finish it |

## When you report a problem

Include:

- The conversation id: `(await HelpAI.ready()).state.conversationId` in the browser console.
- The request body of `/pai/stream-message` (DevTools → **Network**), which lists the tools the message offered in `clientTools`.
- Any warnings in the browser console, and a screenshot of the card.

<Tip>
The full reference ships with the widget: [page tools guide](https://cdn.help.ai/sdk/js/elements/latest/docs/page-tools.md).
</Tip>