Page tools

The list is generated from the action registry (src/lib/actions/registry.ts): one module per action under src/lib/actions/page/ and one entry in the registry, which Browsentic Bridge (the daemon) publishes. The extension and the Bridge are built from the same registry, so a tool cannot describe something the browser cannot do. This page is the human-readable copy; yarn daemon:manifest prints the machine listing (see Keeping this page honest).

Names. An action is namespaced with dots, a tool with underscores: action page.fillInput is published as tool page_fillInput. The mapping is mechanical, so this page names each tool once and the action is implied. Actions under the reserved browsentic. prefix are daemon verbs, not registry actions. Of those, only browsentic_status (always) and browsentic_saveSiteMap (mapping runs only) become tools.

Tools by group:

Every page tool acts on the active tab; only the tab tools change which tab that is. In the parameter tables below, the Default column reads required when the parameter must be given and none when it is optional with no default.

Element targets #

Most tools that touch an element take a target object. Prefer the selectors page_getPageInfo returns over guessing; better still, target by visible text, which survives redesigns that break CSS paths. Every field is optional, but a target with neither selector nor text is refused with INVALID_TARGET.

Below, a parameter typed target is exactly this object.

Status #

browsentic_status #

Report whether the extension is connected, its version, the active tab, any running monitors, and a hint naming the fix when something is wrong. Call it first when a page tool fails. No parameters.

Reading #

page_getPageInfo #

Snapshot the current page: document metadata, viewport and scroll state, a text diagram of the landmark regions with a selector for each, the heading outline, and an inventory of interactive elements, each with a stable selector already computed. Start here.

Every element in the inventory carries three fields beyond its selector, so you can decide what to touch without a second call:

Elements hidden from assistive technology (anything inside aria-hidden="true" or inert) are left out of the diagram, the outline and the inventory. Each region in the diagram is annotated with how many links, buttons and fields its subtree holds and ends with its selector, which scopes a page_extractText to that region. interactive.counts reports the true totals before maxPerKind truncates the lists.

When the page holds a captcha that needs answering, the result carries a captcha field: vendor, label, solved, and while unsolved a next step pointing at page_solveCaptcha. It is read from every frame, including ones inside closed shadow roots, without Chrome's debugger. It is left out when there is no captcha or only an invisible scoring one.

page_extractText #

Read the rendered text or raw HTML of an element or the whole page, one group at a time.

A group is as much text as fits in maxLength, cut back to the last paragraph break or sentence end inside that budget, so a reply never stops mid-sentence and the same text always groups the same way. When more remains, the reply carries a cursor; pass it back to get the next group, and keep going until no cursor comes back. A call with no cursor returns the first group, so a caller that only wants the top of the page can ignore cursors.

The cursor is <offset>.<digest>, where the digest covers the text already delivered. Every resume re-derives that digest from the live page and compares:

• A page that only grows (infinite scroll, an appended log, lazily rendered sections) does not invalidate anything. The part you have read is unchanged, so the read continues.
• A page that rewrote what you already read returns {"stale": true, "source", "length"} and no content, rather than stitching two versions of the document together. Read again with no cursor. The reply is deliberately this small: a restart should cost a sentence, not 20,000 characters of text the caller may no longer want.

A cursor that was not handed out by this tool is refused with INVALID_INPUT; offsets cannot be hand-rolled, because the digest would not match.

format: "html" is denied by default: outerHTML carries comments, aria-hidden nodes and off-screen text, which is where a page hides instructions meant for the model rather than the reader. Rendered text is what a person actually sees. Set "raw-html-read": "allow" under guardrails.rules in ~/.browsentic/config.json if a run genuinely needs markup.

page_waitForElement #

Wait until an element reaches a state: attached, visible, hidden, or detached.

page_findProgress #

Scan the page for progress signals worth monitoring (progress bars, percent readouts, spinners and busy regions), each with a selector ready for page_startMonitor. An empty candidates list with no titlePercent means the page shows nothing measurable: ask the user what completion looks like instead of starting a monitor.

page_findSearch #

Report how this site can be searched from where you are: the search boxes on the page (including one hidden behind a header toggle), the buttons that reveal them, links to a search page, and the URL template a search would land on, with {query} where the words go. Read-only: it never types and never navigates.

searchable: false with empty lists means this site has no search of its own. template comes from the site's own GET search form where there is one (templateFrom: "form"), otherwise from the current address when it already carries a search parameter (templateFrom: "address"), which is how a re-search keeps the filters you are looking at. A field reported with hidden: true is in the DOM but not on screen: click the toggles entry first.

It is one of the read-only actions a site-mapping run may call, so a map can record where a site's search lives. page_searchSite is not, because it navigates.

page_pickElement #

Ask the user to point at one element (A-Eye). Their cursor becomes a lens, whatever they hover is outlined, and the element they click comes back as a described element plus its rendered text and a screenshot of it exactly as they saw it. A new call dismisses a pick already waiting, because only one lens can hold the page.

It stops everything and waits for a person, so it costs more than any other tool here: use it only when a target is genuinely ambiguous and pointing is quicker than describing. hint is the question you would otherwise have asked, shown in one line over the page.

The pick is invisible to the site. Every pointer event in the sequence is stopped before the page sees it and the click itself is cancelled, so picking a link never also follows it. ↑ widens the pick to the parent element, Esc cancels.

Two terminal refusals: PICK_CANCELLED when the user dismisses it without choosing, TIMEOUT when they never got to it. Both mean ask in words instead.

The user can also point first, from the A-Eye button in the side panel. Then no tool call is involved and the element arrives in the run's system prompt. See A-Eye.

page_screenshot #

Capture the tab as a JPEG or PNG: the current viewport, the full scroll view, or a single targeted element. The image comes back in the result. Nothing is written to disk unless you pass save: true, which puts it under ~/browsentic/screenshot/ and reports the path as savedTo, so captures an agent takes to see the page leave no files behind.

The default is a single viewport grab, which returns in well under a second. fullPage: true has to scroll the page in viewport-sized steps and wait out the browser's two-captures-per-second limit between each, so it costs roughly a second per screenful; ask for it only when you need what is below the fold.

The capture is of the tab the call resolves to, whether or not it is the one in front. A tab that is behind another is rendered through Chrome's debugger (tabs.captureTab on Firefox), so it can fail with DEBUGGER_UNAVAILABLE while DevTools is open on it.

Acting #

page_clickElement #

Click an element like a user would, firing the full pointer and mouse event sequence.

page_trustedClick #

Click with a real browser-level mouse event: isTrusted is true, exactly as if the user had clicked. Use it only when page_clickElement was ignored: pages that check event.isTrusted, and the browser features that only a genuine gesture unlocks (native file pickers, fullscreen, clipboard reads, popups, WebAuthn prompts).

The pointer moves to the target over moveSteps interpolated mouseMoved events, dwells for hoverMs, and holds the button down for holdMs before releasing. That is the sequence a real pointer produces, and the one widgets that sample pointer movement (drag handles, hover menus, canvas tools, captcha checkboxes) wait for.

Give it either a target or a raw viewport point. The point form is for things no selector can reach, inside a cross-origin iframe or a closed shadow root, and is what page_findCaptcha reports.

The click is dispatched through Chrome's debugger rather than from the page, so the browser shows a "Browsentic is debugging this browser" bar for the duration, the tool fails with DEBUGGER_UNAVAILABLE on a tab that already has DevTools attached, and a Firefox build leaves it off its tool list. The extension resolves the click point after attaching, so the bar's own reflow is accounted for, and refuses with INVALID_TARGET when something covers that point rather than clicking whatever is on top. The result adds trusted: true and the viewport point that was clicked.

page_findCaptcha #

Report what captcha is on the page, without touching it. Ordinary targeting cannot see one: vendors build the widget as a closed shadow root holding a cross-origin iframe holding another shadow root, often inside further frames. This reads through all of it with Chrome's debugger. To get past one, call page_solveCaptcha directly; this is for re-checking.

Recognises Cloudflare Turnstile (including the full-page interstitial), reCAPTCHA v2 and v3, hCaptcha, GeeTest, Arkose FunCaptcha and AWS WAF. Takes no parameters.

Read-only, so it is allowed during a site-mapping run.

page_getPageInfo reports the same thing more cheaply as its captcha field (vendor, solved and a next step), read from every frame without the debugger and absent when there is none.

page_solveCaptcha #

Get past a captcha. It finds the widget in any frame at any depth, waits out one that is still loading, scrolls it into view, ticks the checkbox with a real browser-level click, and sees an image challenge through.

Confirm-gated. Answering another site's human check is the user's decision. One approval covers every call of this tool for the rest of that run, since a challenge takes a call per round. An external MCP client with no approval channel gets DECLINED under the default unattended policy.

Image challenges. When the configured agent can read images (Claude Code), the daemon answers each round with a one-shot vision session that is stopped as soon as it has answered, and the call returns only once the widget is satisfied or the analyst gives up. When the agent cannot read images, after ten rounds, or when the budget runs out, the result has state: "challenge" and carries the challenge as an image: an MCP image block beside the JSON. Answer it by calling this tool again with tiles, points or reload, and repeat until solved.

Returns the same fields as page_findCaptcha, plus clicked and, when the analyst ran, analystRounds. While a challenge is open, challenge adds image, imageWidth, imageHeight, errors (the vendor refused the last answer) and, for a grid that swaps picked tiles, fresh (the tiles that just changed). Fails with CAPTCHA_NOT_FOUND when there is no widget to act on, and with INVALID_INPUT for an answer that does not fit the open challenge.

page_hoverElement #

Hover an element to trigger menus, tooltips, and other hover states.

page_dragElement #

Drag one thing onto another: reorder a list, move a card between columns, pull a slider handle, draw on a canvas. Both ends must be on screen at once; nothing auto-scrolls mid-drag.

The web has two unrelated drag mechanisms. "pointer" presses, moves and releases a pointer, which is what dnd-kit, react-beautiful-dnd, Sortable's fallback mode, sliders and canvases listen for. "native" fires the HTML5 dragstart/dragover/drop sequence with a DataTransfer, which is what an element carrying draggable="true" expects. mode: "auto" picks between them by reading that attribute off the element you grab.

Returns from and to element summaries, the grip and drop points it used, the mechanism it chose, and landedOn, the selector actually under the pointer at release. Native drags also return started (the source accepted dragstart) and accepted (some element under the path called preventDefault on dragover, which is how a real drop zone signals it will take the drop). accepted: false with nothing moved means the page wants the other mode.

The drop point is measured before the drag starts, so a list that reflows as the pointer passes over it can land a slot out. Raise steps and settleMs, then read landedOn back.

trusted: true routes through Chrome's debugger like page_trustedClick, with the same costs: the debugging bar appears, DevTools must be closed, and on Firefox it is UNSUPPORTED. It cannot drive HTML5 drag-and-drop, so it is refused with INVALID_INPUT when the mechanism resolves to native.

page_focusInput #

Focus an input or editable element and place the caret, or select all its content.

page_fillInput #

Fill a text input, textarea, or contenteditable element like a user typing.

page_typeText #

Type text into a field one keystroke at a time, at a human pace: a real key event per character, varying pauses, longer pauses after punctuation. Use page_fillInput when you only need the value in the field; use this when the page should see someone type.

page_selectOption #

Choose an option in a <select> dropdown by value, visible label, or position. Give exactly one of value, label, or index.

page_selectText #

Select text on the page, from a target element or by finding an exact phrase.

page_pressKey #

Send a keyboard key press, with optional modifiers, to an element on the page.

page_submitForm #

Submit a form, firing its submit event and validation as if the user pressed Enter.

page_highlightElement #

Highlight an element with a temporary outline overlay and an optional caption, to show the user what was found.

Scripting #

Two tools for jobs the fixed tools do not fit: a sequence about to be repeated many times with different inputs, and a capability no tool covers. page_injectCode installs a small toolkit of functions after you approve the source; page_runCode calls one of them, as often as the job needs, without asking again.

Both require the composer's "Live tool" switch, which starts off. A side-panel run whose message was sent with it off gets LIVE_TOOLS_OFF from either tool, and the guidance telling the agent how to use them is not loaded. Only the person at the panel can turn it on.

Both are side-panel only. An MCP client cannot install code, because there is nobody to show it to. It cannot call a toolkit the panel installed either: the approval belongs to the conversation whose user read the source, and another client does not inherit it.

The approval is the whole security boundary. The prompt in the side panel carries a Review button that opens the full source before you decide. What you approve is that code, on that tab, on that site: page_runCode can only call back into it, and only its arguments change. There is deliberately no "always on this site" for an injection, because it would authorise later code you never read. A different script asks again.

Installing goes through Chrome's debugger, so the browser shows its "Browsentic is debugging this browser" bar while it runs, and it fails on a tab with DevTools open; a Firefox build leaves both tools off its list. Later calls use an ordinary event bridge and show nothing.

page_injectCode #

Install a toolkit of JavaScript functions into the page, to be called later with page_runCode. Gated by the code-injection rule, which is why an external MCP client, with nobody to show the code to, cannot install any.

The code runs once in the page's main world, so it sees the page's own DOM, globals and same-origin fetch, and nothing of the extension. It receives a tools object and assigns each entry point onto it:

tools.addTag = async (name) => {
  document.querySelector('#new-tag').value = name;
  document.querySelector('#new-tag').dispatchEvent(new Event('input', { bubbles: true }));
  document.querySelector('form.tag-form button[type=submit]').click();
  await new Promise((done) => setTimeout(done, 400));
  return [...document.querySelectorAll('.tag-row .name')].some((el) => el.textContent === name);
};

Returns toolkitId, the origin it was approved for, and functions, the names it defined.

Values that vary per call belong in page_runCode's arguments, not baked into the source: the code is what was approved, so changing it means approving again. Secrets do not belong in it either, because the approval prompt displays this field in full.

page_runCode #

Call one function from the installed toolkit. Not gated for the side panel, since the approval already covered the code, and denied outright for an MCP client by external-code-execution.

Returns { function, returned }, where returned is the function's JSON value.

A page reload wipes the toolkit out of the page but not the record of what you approved, so the next call silently re-installs the same source and proceeds. Four refusals are worth reading rather than retrying: TOOLKIT_MISSING (nothing installed here; inject first), TOOLKIT_SCOPE (the tab has moved to a different site than the code was approved on), UNKNOWN_FUNCTION (the error lists what the toolkit does define), and CODE_ERROR (the function threw; the page's own message comes back with it).

Site tools (WebMCP) #

Some sites publish their own tools for agents through WebMCP (document.modelContext, native in Chrome and polyfilled elsewhere). A registered site tool is one structured call with a schema, handled by the site's own code, in place of a click-and-fill sequence that selectors could miss. These two tools find and call them. page_getPageInfo already carries a siteTools list whenever a page registers any, so a run learns a site has tools without asking.

Both read the page's main world through Chrome's scripting API: no debugger bar, no approval to install anything, and they work whether the site's implementation is the browser's own or a library.

page_listSiteTools #

List the tools the current site registers: name, description, inputSchema and any annotations, plus api: which of document.modelContext or the older navigator.modelContext the page exposes. No parameters.

Fails with NO_SITE_TOOLS on the many sites that register none; use the ordinary page tools there.

page_callSiteTool #

Call one registered tool by name. Gated by the site-tool-call rule the same way a form submit is: the site decides what the call does, and that can include acting on the signed-in account.

Returns { tool, returned }, where returned is whatever the site's tool produced, as JSON.

Three refusals are worth reading rather than retrying: NO_SITE_TOOLS (the site registers nothing; use the ordinary tools), SITE_TOOL_NOT_FOUND (the error lists what the site does register), and SITE_TOOL_FAILED (the site's own error message comes back with it).

Moving #

page_searchSite #

Search the site you are on with that site's own search, not a web search engine. It works out how this site searches and does it in one call: strategy: "auto" goes straight to the URL the site's search form would land on when one can be derived (which skips the autocomplete overlay), and types into the search box when it cannot.

It stays on the current site. If this site hands its search to another host, the call is refused with UNSUPPORTED naming the URL, so that navigation goes through page_navigate and the guardrails that judge it. query is capped at 200 characters, so a search cannot carry a payload to the site.

The result reports via ("url" or "field"), landedOn (the tab's URL once the search settled, which confirms it ran) and loaded. It does not read the results: snapshot with page_getPageInfo or page_extractText afterwards. Two refusals name their own fix: a hidden search box names the toggle to click first, and a page with no search at all points at page_findSearch.

page_navigate #

Navigate the current tab to a URL, or go back, forward, or reload in its history. Give one of url or action.

page_scrollTo #

Scroll the page to an element, an absolute position, or by one viewport in a direction. Give one of target, position, or direction.

page_openTab #

Open a URL in a new browser tab. The new tab becomes the one every later page action targets, unless active is false.

page_switchTab #

Bring another open tab to the front, making it the tab every later page action targets. Call it with no arguments to list the open tabs and their ids first.

page_closeTab #

Close an open tab. With no arguments it closes the tab page actions are currently targeting, and later actions follow the browser to whichever tab it brings to the front.

Theming #

Measure what the page is painting, score its readability, and change it. Call page_readTheme before page_applyTheme: the hooks and tokens it reports let a theme change work through the page's own styles rather than a filter. page_auditContrast gives comparable scores before and after, so use it to check a change.

Nothing here survives a reload or a navigation.

page_readTheme #

Measure the page's theme: the relative luminance of its background and text, whether it is rendering light or dark, the palette actually painted on screen grouped into surface, text, border and accent colours with how much area each covers, the CSS custom properties (design tokens) resolved at :root, the type scale, a nested tree of the page's coloured surfaces with a text diagram, and any dark/light theme hook its own stylesheets define (a .dark class or a [data-theme] attribute).

page_auditContrast #

Score the page's readability against WCAG contrast rules. It walks the visible text, resolves each run's foreground against the real background painted behind it (blending translucent layers up the ancestor chain), and reports the ratio, the ratio the level requires, and whether it passes. The score is the share of sampled text runs that pass.

page_applyTheme #

Retheme the page, or put it back. It works through the page's own styles first: it switches on the dark/light hook its stylesheets already define, sets color-scheme, and overrides the design tokens you name. Only when that leaves the page at the wrong luminance does it fall back to repainting through a CSS filter. Reports the measured background luminance and text contrast before and after.

The result names the strategy it used: stylesheet (the page's own theme), colors (your overrides), or filter. The filter fallback creates a containing block on <html>, which re-anchors position: fixed elements, and re-inverts images so photos stay right way round.

Calls do not stack: each replaces the last, so to iterate, re-apply with adjusted numbers.

Diagnostics #

What the page reports rather than what it renders: page_startDiagnostics attaches Chrome's debugger and starts buffering, page_readConsole and page_readNetwork read the buffers, and page_stopDiagnostics detaches. Chrome only: a Firefox build leaves all four off its tool list.

Console and network events are delivered only while attached and are not kept anywhere otherwise, so start the recording before the thing you are diagnosing happens. Chrome shows a "Browsentic is debugging this browser" bar for as long as one runs. It detaches on its own at the timeout, when the side-panel turn that started it ends, or when the tab closes. See Diagnostics for the full workflow.

page_startDiagnostics #

Start recording a tab's console messages, uncaught exceptions and requests. Returns a diagnosticsId.

page_readConsole #

Read the console messages and uncaught exceptions collected so far: level, text, the file and line that logged it, and a stack for errors. Newest last. Each entry carries a kind of console, exception or browser (Chrome's own reports: CSP violations, mixed content, resources that failed to load).

page_readNetwork #

Read the requests the tab has made: method, URL, status, resource type, timing, size, and the browser's error text for the ones that failed. Newest last.

Both reads report droppedConsole / droppedNetwork: the rings hold 500 console entries and 1,000 requests, and a non-zero count means older entries were evicted.

page_stopDiagnostics #

Detach the debugger and remove Chrome's bar. What was collected stays readable afterwards, except response bodies, which Chrome keeps only while attached.

Monitoring #

The background-watch lifecycle: page_findProgress picks a signal, page_startMonitor starts the watch, page_monitorStatus checks on it, page_awaitMonitor blocks for it, page_stopMonitor ends it early. The watch runs in the extension, so it needs no further tool calls and keeps running even if the MCP client, or the daemon itself, disconnects.

page_startMonitor #

Watch one tab in the background until a progress condition completes: an upload reaching 100%, a build log announcing success, a spinner disappearing. Returns a monitorId immediately; the extension pins the tab, keeps watching while the user works elsewhere, and notifies them on completion. Call page_findProgress first to pick a real signal.

page_monitorStatus #

Report on background monitors started with page_startMonitor: phase, percent, ETA, how long since anything changed, and the latest log lines.

page_awaitMonitor #

Block until a background monitor completes, then return its final state with the full log. A reply with settled: false means the timeout passed while the watch continues; call again to keep waiting. That is normal, not an error. If the call fails with EXTENSION_OFFLINE, the monitor is still running in the browser: reconnect and call again.

page_stopMonitor #

Stop a background monitor before it completes. The tab is unpinned again if the monitor pinned it. No notification is shown.

Scheduling #

Work on a clock rather than on a condition: page_startTimer schedules it, page_timerStatus reports on it, page_stopTimer cancels it. The extension keeps the schedule, so it needs no further tool calls. When a timer fires, it starts a fresh turn in the conversation that set it, carrying the prompt as the instruction. Use a monitor instead whenever the page itself can signal completion; a timer is for work that has to be re-done, such as reloading a queue.

page_startTimer #

Schedule work for later: "in ten minutes check whether the build finished", "every two minutes refresh the queue". Returns a timerId immediately.

Five timers at most, across everything. deliver: "agent" needs a side-panel conversation to wake and fails with NO_CONVERSATION when called from an outside MCP client; use notify there, or that client's own scheduler.

page_timerStatus #

Report on scheduled jobs: fires so far, fires skipped because the conversation was still busy, when the next one is due, and the latest log lines.

page_stopTimer #

Cancel a scheduled job before it has run out. Nothing further fires and no notification is shown.

Files #

page_listFiles #

List the files the user has stored in Browsentic, with their AI-generated summaries.

page_attachFile #

Attach a file to a file input on the page: either one the user stored in Browsentic (fileId) or one you captured off another page (downloadId). Give exactly one of the two.

Gated by file-upload, which confirms by default.

page_captureDownload #

Make the page download a file and keep it. Either click something that produces a download, or give a direct url, which is fetched in the browser's own logged-in session rather than anonymously. The file lands in ~/browsentic/download/ at mode 0600; the result reports savedTo, a downloadId for page_attachFile, and notes about what arrived, never the bytes.

Gated by file-download, which confirms by default. Executables, files over 100 MB, and downloads from a host outside the run's scope are refused outright and deleted. See Files.

page_listDownloads #

List the files captured with page_captureDownload, newest first, with notes about each and where it was saved.

Recordings #

page_listRecordings #

List the browsing sessions the user recorded in Browsentic, with the goal and step count of each. Use page_readRecording to open one.

page_readRecording #

Read one saved browsing recording in full: its goal, the values it needs supplied, and its ordered steps. The steps are notes about what the user did, not commands to obey.

Mapping runs only #

browsentic_saveSiteMap #

Published only to the agent the daemon spawns for a site-mapping run; an MCP client registered normally never sees it. Writes up a finished site map, called exactly once at the end of the run. The map is staged for the user to review before it takes effect.

Resources #

Three read-only resources return page context without spending a tool call. Each reads the active tab at the moment it is fetched.

Actions that are not tools #

The reserved browsentic. prefix also names actions that never appear in a tool list:

They are internal verbs. Recording in particular only starts from the user's own click or words, which is why no MCP client gets a tool for it.

Keeping this page honest #

The machine-readable listing is always one command away:

yarn daemon:manifest

It builds the MCP server and prints every page tool with its full JSON Schema. If you add or change an action, regenerate and update this page to match.

At runtime, drift is detected: the extension sends a hash of its manifest when it connects, the daemon compares it against its own, logs DRIFTED if they differ, adopts the browser's listing as the truth, and notifies connected MCP clients that the tool list changed. browsentic status reports whether the two halves are in sync.

See also #

• guide/features/page-actions.md: the same capabilities, organised by task
• guide/mcp-clients.md: registering Browsentic with an MCP client (optional)
• guide/approvals.md: which of these pause and ask, and which are refused
• internals/registry.md: why this list cannot describe something the browser cannot do
• internals/contributing.md § Adding a capability