The connection

Your client launches hailbrowser-mcp over stdio. That process listens on 127.0.0.1:12306 and the extension dials in. Tools are grouped below by what they do, in the order a run usually uses them.

Read, then act

# every call needs a tab. Start here.
tabs_context()

# then read before you act
read_page({ viewportOnly: true })
find({ query: "sign in" })
click({ ref: "ref_12" })

Two rules that prevent most mistakes

Call tabs_context before anything else, and call read_page again after any navigation. A ref describes one element on one version of the page; once the page changes, it is gone.

Refs, coordinates and text

read_page returns an indexed list: [ref_12] button "Continue". Pass that ref to click, type, select_option, hover or scroll. Refs are cheap and survive layout changes better than pixels.

A screenshot returns the visible part of the tab. Coordinates in that image are accepted by click, scroll and hover, which is the fallback for canvas and image maps. Coordinates are relative to the screenshot you were given, not to the full page.

For prose rather than controls, use get_page_text. It returns the main content first and caps at 20,000 characters by default, which is usually enough for one article and cheaper than a screenshot.

What a call returns

Every tool returns text that says what happened, and the result is written for a model rather than a log file. Three examples of the shape:

Tool	Returns
`click`	Whether the click was dispatched, the element it hit, and whether the page changed or opened a tab.
`type`	Whether the value landed, or that the field rejected it and now holds something else. Also reports the field it used when no ref was passed.
`scroll`	Which box moved, how far, and Nothing scrolled when the page was already at the end.
`navigate`	The final URL, title and whether the load was blocked by Chrome.
`run_task`	A summary of the goal, the step log, and the reason it stopped: done, blocked, or waiting for a person.

Failures and timeouts

Unknown tab. The tab was closed or the id is stale. Call tabs_context again.
Stale ref. Re-read the page. Do not reuse a ref across a navigation.
Blocked page. chrome:// pages, the Chrome Web Store and the extension's own pages cannot be driven. Chrome enforces this.
A frozen tab. A confirm, alert or "leave site?" dialog blocks the page until handle_dialog answers it. Plain alerts close on their own and are reported in the next result.
Timeouts do not finish late. If a call is cancelled or times out, the action in flight is stopped rather than completed afterwards.

Tabs and navigation

`tabs_context`

List open tabs with id, title and url, and show which tab the tools act on by default. Call this first.

No parameters. It acts on the current agent tab.

`tabs_create`

Open a new background tab without stealing focus and make it the current agent tab.

Parameter	Required	Notes
`url`	No	default about:blank
`activate`	No	bring to front, default false

`tabs_select`

Make an existing tab the current agent tab. Set activate only when the person wants to watch.

Parameter	Required	Notes
`tabId`	Yes	—
`activate`	No	—

`tabs_close`

Close a tab you opened.

Parameter	Required	Notes
`tabId`	Yes	—

`navigate`

Load a URL in the tab and wait for it. Also accepts back, forward or reload.

Parameter	Required	Notes
`url`	Yes	—
`tabId`	No	—

Reading the page

`read_page`

The page as an indexed list of interactive elements ([ref_N] role "name" value=...) plus the visible text. Cheaper and more precise than a screenshot.

Parameter	Required	Notes
`tabId`	No	—
`viewportOnly`	No	only elements on screen
`maxElements`	No	default 300
`compact`	No	on-screen only, max 150, less text

`find`

Find interactive elements whose role, name, value or placeholder contains the query. Returns refs.

Parameter	Required	Notes
`query`	Yes	—
`tabId`	No	—

`get_page_text`

Readable text of the page, main content first. Use it for articles, results and anything you need to quote.

Parameter	Required	Notes
`tabId`	No	—
`maxChars`	No	default 20000

`screenshot`

Capture the visible part of the tab as an image. Coordinates in the image can be passed to click, scroll and hover.

Parameter	Required	Notes
`tabId`	No	—

Acting on the page

These go through chrome.debugger, so the page receives real, trusted mouse and keyboard events. Sites that ignore synthetic events still respond.

`click`

Click by ref (preferred) or at screenshot coordinates. Real, trusted mouse events through CDP.

Parameter	Required	Notes
`ref`	No	e.g. ref_12
`x`	No	—
`y`	No	—
`tabId`	No	—
`button`	No	left, right, middle
`clickCount`	No	2 for double click
`modifiers`	No	ctrl, shift, alt, meta

`type`

Focus a field and replace its content (clear=false appends), then report whether the page changed or rejected the value. Without a ref it types into the focused element and says which one.

Parameter	Required	Notes
`text`	Yes	—
`ref`	No	—
`tabId`	No	—
`clear`	No	—
`submit`	No	press Enter afterwards

`press_key`

Press keys or chords, space separated: Enter, Tab Tab, ctrl+a Backspace, Escape, ArrowDown.

Parameter	Required	Notes
`keys`	Yes	—
`tabId`	No	—
`repeat`	No	—

`scroll`

Scroll the box under a ref or point, or the page when neither is given. Says "Nothing scrolled" when it is already at the end.

Parameter	Required	Notes
`direction`	Yes	up, down, left, right
`amount`	No	wheel ticks of about 120px, default 5
`ref`	No	—
`x`	No	—
`y`	No	—
`tabId`	No	—

`select_option`

Choose an option of a native select by value or visible label. For multi-selects, option adds one choice and options sets the full list.

Parameter	Required	Notes
`ref`	Yes	—
`option`	No	—
`options`	No	full list for multi-selects
`tabId`	No	—

`hover`

Move the pointer over an element or point to reveal menus and tooltips.

Parameter	Required	Notes
`ref`	No	—
`x`	No	—
`y`	No	—
`tabId`	No	—

`handle_dialog`

Close a confirm, prompt or "leave site?" dialog that is freezing the page. Plain alerts close automatically and are reported in the next result.

Parameter	Required	Notes
`accept`	No	true = OK / Leave, default true
`text`	No	answer for prompt()
`tabId`	No	—

`wait`

Wait for results to load. Ten seconds maximum.

Parameter	Required	Notes
`seconds`	Yes	—

Scripting

`javascript`

Evaluate an expression in the page and return its JSON result. Top-level await works. For inspection and extraction; prefer click and type for interaction.

This is the one tool that can be switched off in Settings → Safety. Prefer click and type for interaction; use this for inspection and extraction.

Parameter	Required	Notes
`code`	Yes	—
`tabId`	No	—

Hand over a goal

run_task is different from every other tool: your agent stops driving and HailBrowser's own agent takes over, using the models configured in the extension. That is how a coding agent gets browser work done without a frontier model on every click.

`run_task`

Hand a whole goal to HailBrowser’s own agent with the models configured in the extension. ultrafast is one decision request per step; normal is the full tool-calling agent. Returns a summary and the step log.

Parameter	Required	Notes
`goal`	Yes	include every value the agent needs
`mode`	No	normal or ultrafast
`url`	No	start URL
`values`	No	field name to text, e.g. From: Zurich
`tabId`	No	—

`stop_task`

Stop the run_task an agent started. Tasks the person started in the side panel can only be stopped there.

No parameters. It stops the run_task your agent started.

Ultrafast is one request per step

In ultrafast mode the decision model returns one operation and one element index. It never returns selectors, coordinates or code. The executor re-reads the page before each input, so a moved button costs another decision, not a misclick.

How the modes differ