← All posts

API & helpers

AI Helper page-inspection tools — query_page and list_structure

17 May 2026 · by JustZix Team

An AI assistant is only as good as what it can see. AI Helper does not work from a vague description of the page — it has tools to look at the real DOM and at your existing JustZix library. This post covers the two inspection tools: query_page and list_structure.

The starting context

Every message you send already carries the page URL, the title, and an HTML fragment. That is enough for simple requests. But a fragment is a fragment — for a precise selector the model often needs to look closer at a specific part of the page. That is what the inspection tools are for.

query_page — look at the live DOM

The model passes a CSS selector; the tool runs it against the current page and returns the match count plus the HTML of the matches.

@@JZ_TOOL@@ {"tool": "query_page", "args": {"selector": "header .nav"}} @@END@@

result:
  matches: 1
  html: "<nav class=\"nav\"> ... </nav>"

This turns guessing into checking. Instead of writing CSS for a structure it imagines, the model can confirm what is actually there: does .nav exist, is there one or five of them, what classes do the children carry, is the button inside a wrapper. With that, the selector it writes targets the real page.

How the model uses it

• Confirm an element exists — query the selector, check the count is not zero.
• Narrow down a selector — start broad, read the returned HTML, then query something more specific.
• Check uniqueness — a count of 1 means the selector is specific; a count of 30 means it is too broad for a targeted fix.
• Read the structure — see parent/child relationships before writing a :has() or descendant selector.

Across an agentic turn the model may call query_page several times, refining as it learns — all inside the 8-step budget.

list_structure — read your existing rules

The second tool looks not at the page but at your JustZix library. list_structure returns your folders, groups and rules together with their ids.

@@JZ_TOOL@@ {"tool": "list_structure", "args": {}} @@END@@

result:
  folders:
    - id: f_12  "News sites"
      groups:
        - id: g_3  "Layout fixes"
          rules:
            - id: r_88  "Hide sidebar ads"
            - id: r_90  "Wider article column"

Why the model needs this:

• Avoid duplicates — if a similar rule already exists, the model can point you to it instead of making another.
• Place new things sensibly — a new rule for a news site can go into your existing "News sites" folder rather than scattering loose rules.
• Use real ids — create_group and create_rule need a parent id; list_structure is where those ids come from.

It is read-only. Seeing your structure is not the same as changing it — creating a folder, group or rule still needs the create tools and your explicit confirmation.

Why on-demand inspection beats dumping the whole page

An obvious alternative would be to send the model the entire page HTML up front. AI Helper deliberately does not. On-demand inspection wins for real reasons:

A modern web app can be hundreds of kilobytes of HTML. Stuffing all of it into context is slow, expensive, and often counterproductive — signal gets buried in noise. A focused query_page for .cookie-banner gives the model exactly the few lines it needs.

Freshness matters too

Pages are not static. Menus open, modals appear, content loads late. Because query_page runs at the moment it is called, the model reads the DOM as it is right now — including elements that did not exist when you first opened the chat. A one-time page dump cannot do that.

Inspection feeds the workflow

These tools are step one of the larger agentic workflow: inspect with query_page and list_structure, test in a TEMP pane, ask you to verify, then persist. Good inspection is what makes the later steps accurate — the selector is right because the model actually looked.

See also

• The full agentic tool-calling workflow
• Meet AI Helper — the overview
• Build a rule with AI Helper, step by step

On-demand inspection is what keeps AI Helper precise and cheap. Download JustZix, add a key, and ask it to look at a tricky element.