> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Page Tools

> The assistant can scroll your page to a section and highlight a single element, so it can say "it's this one" instead of giving directions.

[Live Website Events](/capabilities/live-website-events) tell the assistant *where* the visitor is. Page Tools are the other half: once it knows they are on your pricing page, it can move that page to the Pro card and put a glow around it.

Without this, the best the assistant can do is give directions — *"scroll down a bit, it's under the comparison table."* That sentence is what Page Tools replace.

<Note>
  Both tools are **read-only**. They scroll and they draw. They cannot click, type, submit or navigate. If you want the assistant to act on your site, that is a [Custom Function](/capabilities/custom-functions), where you write the handler.
</Note>

## You do not have to do anything

Page Tools ship with the standard embed snippet and are on by default:

```html theme={null}
<script src="https://waterr.ai/embed/widget.js"
        data-waterr-scenario="<scenario-id>" async></script>
```

There is no handler to register and no tool to define. The assistant gets two:

| Tool | What it does |
| - | - |
| `scroll_to_page_section` | Brings a section into view, centred. |
| `highlight_page_element` | Scrolls to one element and outlines it with a glow for a few seconds, optionally with a short caption. |

## How it finds things

The assistant never writes a CSS selector. It sends the words a person would use — *"Pro plan"*, *"Enterprise"*, *"How it works"* — and the loader matches them against the **visible text** of headings, links, buttons, labels and cells on the page.

An exact match wins over a passing mention, so on a pricing page where the Enterprise card says *"everything in Pro, plus SSO"*, asking to highlight *"Pro plan"* lights the Pro card, not Enterprise. A matched heading is then widened to the card or section it belongs to, because glowing two words inside a plan looks like a bug.

If nothing matches, the assistant is told so and goes back to describing it in words. It never points at something that only shares a word with what it meant.

### Name things precisely

For anything you want matched exactly — a plan, a tier, a feature card — label it:

```html theme={null}
<section data-waterr-item="pro plan">
  <h3>Pro</h3>
  …
</section>
```

A labelled element beats anything inferred, and the label is what the assistant matches against, so it can be wording your visible copy does not use.

### Keep things out of reach

Mark anything that should never be matched:

```html theme={null}
<div data-waterr-ignore>…</div>
```

Hidden elements are already excluded — a `display:none` tab panel full of the right words is never a scroll target, because scrolling to it scrolls to nothing.

## What it looks like

The glow is drawn in the widget's own layer, over your page. Nothing of yours is restyled, no classes are added and no attributes change, so a re-render cannot leave the page in a strange state. It never takes a click, so the visitor can keep using the button it is pointing at.

It clears itself after a few seconds, on the visitor's next click or keypress, or when the assistant points at something else. Only one highlight exists at a time.

The page scrolls smoothly unless the visitor's system is set to reduced motion, in which case it jumps.

## Turning it off

Per site, on the script tag:

```html theme={null}
<script src="https://waterr.ai/embed/widget.js"
        data-waterr-scenario="<scenario-id>"
        data-waterr-page-tools="false" async></script>
```

Per scenario, in Creator Studio under the embed settings, or through the API:

```bash theme={null}
curl -X PATCH https://api.waterr.ai/scenarios/<scenario-id>/embed-config \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"page_tools_enabled": false}'
```

Either end can decline. With Page Tools off, the assistant answers in words and still knows which page the visitor is on.

## Replacing them with your own

Register a handler under the same name and yours runs instead:

```js theme={null}
Waterr.on("highlight_page_element", function (args) {
  myDesignSystem.spotlight(args.target);
  return { found: true };
});
```

This is the right move when your site already has a tour or spotlight component. Return `{ found: false, reason: "…" }` when you cannot find the target, so the assistant knows to describe it instead.

## Where it works

Page Tools need a page to act on, so they work on the **sidebar widget**:

| Surface | Page Tools |
| - | - |
| Sidebar widget (`embed/widget.js`) | ✅ |
| Button, inline and avatar-assist embeds | ✗ |
| Meeting room, phone calls, Meet/Zoom/Teams bot | ✗ (no host page) |

## Related

* [Live Website Events](/capabilities/live-website-events) — tell the assistant what the visitor is doing.
* [Custom Functions](/capabilities/custom-functions) — let the assistant act on your site, not just point at it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.