Tool reference

The server exposes 51 tools (the 6 agents tools only when a model is configured in config/models.json or with AGENT_LLM_URL). Limit them with TOOLSETS (for example TOOLSETS=core,content), which helps small local models.

Group core

browser_navigate

Navigate to URL. Open a URL in the current tab and wait for the page (including its JavaScript) to load. Returns the final URL, page title and HTTP status. Call browser_snapshot next to read the page and get element refs.

changes page state, interacts with websites

browser_back

Go back. Go back to the previous page in this tab's history (like the browser back button).

changes page state, interacts with websites

No parameters.

browser_forward

Go forward. Go forward to the next page in this tab's history.

changes page state, interacts with websites

No parameters.

browser_reload

Reload page. Reload the current page.

changes page state, interacts with websites

No parameters.

browser_snapshot

Read page. Read the current page: URL, title, scroll position, the readable text, and a list of interactive elements (links, buttons, inputs…) each with a ref like "e3". Pass a ref to browser_click, browser_fill, browser_type, etc. Refs stay valid until the page navigates. Call this after navigating or whenever the page may have changed.

read-only, interacts with websites

browser_click

Click element. Click an element (link, button, checkbox, …) identified by ref (from browser_snapshot) or CSS selector. The element is scrolled into view and clicked with real mouse events; if the click navigates, the new page is loaded before returning.

changes page state, interacts with websites

browser_fill

Fill field. Replace the value of a text input, textarea, contenteditable element or <select> (identified by ref or CSS selector) with the given value. Fires focus, input and change events like a real edit. Use browser_type to append text instead, browser_check for checkboxes/radios, and browser_fill_form to fill several fields at once.

changes page state, interacts with websites

browser_type

Type text. Type text into a field like a user: focuses it and appends the text at the end of the existing value (use browser_fill to replace the value). Set submit=true to press Enter afterwards, e.g. to run a search or submit a login form; if that navigates, the new page is loaded before returning.

changes page state, interacts with websites

browser_press_key

Press key. Press a single key, optionally on an element (ref or selector) which is focused first; otherwise the key goes to the currently focused element. Supported: Enter, Tab, Shift+Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, Space, or a single printable character. Enter submits the form of a focused field (via its submit button) or activates a focused link/button, Tab/Shift+Tab move focus, Backspace/Delete edit text, PageDown/PageUp/Home/End/Space scroll the page when no text field is focused. The page's key handlers run first; if one cancels the key, the result says so. Modifier combinations (Control+A, Meta+C, Alt+…) are not supported because the browser ignores modifier keys. Use browser_type for text.

changes page state, interacts with websites

browser_select_option

Select option. Choose an option in a <select> dropdown by its value or visible text (case-insensitive). For a multi-select pass values with every option that should end up selected. For custom (non-<select>) dropdowns use browser_click.

changes page state, interacts with websites

browser_check

Check or uncheck. Check or uncheck a checkbox, or select a radio button (ref or CSS selector). Idempotent: reports when it was already in the requested state. Pass checked=false to uncheck a checkbox.

changes page state, interacts with websites

browser_scroll

Scroll. Scroll the page (direction top|bottom|up|down|left|right, default down by one viewport) or scroll an element (ref or selector) into view. Use "bottom" to trigger infinite-scroll loaders, then browser_snapshot to read the new content.

changes page state, interacts with websites

browser_wait_for

Wait for element. Wait until an element matching a CSS selector is visible (default), attached, hidden or detached. Use after an action that loads content asynchronously (search results, dialogs, lazy lists) before reading or clicking it.

read-only, interacts with websites

browser_wait_for_text

Wait for text. Wait until a piece of text is visible on the page (case-sensitive substring; runs of whitespace match any whitespace), or until it is no longer visible with gone=true. Text inside scripts or hidden elements does not count. Use to wait for a result or confirmation message, or for a "Loading…" indicator to go away.

read-only, interacts with websites

browser_wait

Wait. Pause for a number of seconds so the page can finish animations or background loading. Prefer browser_wait_for or browser_wait_for_text when you know what you are waiting for.

read-only, interacts with websites

browser_screenshot

Take screenshot. Capture a screenshot of the current viewport (or the full page, or one element) as an image. Use browser_snapshot to read text; use this to check visual layout.

read-only, interacts with websites

Group content

browser_interactive_elements

List interactive elements. List clickable and typeable elements on the current page with refs (e.g. "e3") for browser_click / browser_fill / browser_type. Use include_hidden to also list elements that are not currently visible.

read-only, interacts with websites

browser_markdown

Read page as Markdown. Return the current page (or one element) as Markdown: headings, paragraphs, lists, tables, code blocks, quotes, links and images with absolute URLs. Best for reading articles, docs and other long content; use browser_snapshot instead when you need element refs to interact.

read-only, interacts with websites

browser_links

List links. List the links on the current page, one JSON object per line: {"text","href"} with absolute, de-duplicated URLs (javascript: links are skipped). Use it to decide where to navigate next; narrow the list with internal_only or filter.

read-only, interacts with websites

browser_search

Search page text. Find a word or phrase in the page text (the same text browser_snapshot shows) and return each match with surrounding context. Use it to check that content exists or to locate a section before reading or scraping it. Each match is a JSON line {"offset","snippet"}; offset is the JavaScript string index (UTF-16 code units) of the match in that text.

read-only, interacts with websites

browser_extract

Extract structured data. Extract structured data from the page with CSS selectors and get one JSON object back. schema maps each output field to a selector: {"title": "h1"} gives the text of the first match; end the field name with [] for all matches as an array ({"prices[]": ".price"}); end the selector with @attribute to read an attribute ({"links[]": "a.result@href"}; href/src become absolute URLs, @value and @checked give the current state of form fields). Missing elements give null (or [] for arrays).

read-only, interacts with websites

browser_count

Count matching elements. Count the elements on the current page that match a CSS selector. A cheap way to check that something exists, how many results or rows a page has, or whether more items loaded.

read-only, interacts with websites

browser_get_attribute

Read element attribute. Read one attribute of an element (href, src, value, class, aria-, data-, …) identified by ref (from browser_snapshot) or CSS selector. Returns the raw attribute value as written in the HTML (relative URLs stay relative; use browser_extract with "@href" for absolute URLs). Exception: "value" of inputs, textareas and selects and "checked" of checkboxes/radios return the current state (what was typed or toggled; "true"/"false" for checked), not the HTML default.

read-only, interacts with websites

browser_get_text

Read element text. Read the text of one element identified by ref (from browser_snapshot) or CSS selector: one line per block, whitespace collapsed. For inputs, textareas and selects it returns the current value. Use browser_markdown to read a whole section with its structure.

read-only, interacts with websites

Group forms

browser_detect_forms

Detect forms. List every <form> on the page with its action, method and fields (type, name, label, current value, options for selects), each with a ref usable in browser_fill_form, browser_fill, browser_check, browser_select_option and browser_click. Use it to understand a form before filling it. Password values are masked.

read-only, interacts with websites

No parameters.

browser_fill_form

Fill form. Fill several form fields in one call, then optionally click a submit button (submit_ref or submit_selector) and wait for the resulting page. Each field is {ref or selector, value, type?}; type is inferred when omitted (checkboxes accept value "true"/"false"; for a radio button, value may name any option of its group by value or label). Per-field errors are reported; the form is not submitted if any field failed.

changes page state, interacts with websites

Group tabs

browser_tab_new

Open new tab. Open a new browser tab, optionally loading a URL, and make it the active tab (all other browser tools then act on it). All tabs share cookies. Obscura v0.2.2 limitation: a background tab may lose its in-page JavaScript state (variables, event listeners) when you work in another tab, so prefer one tab at a time and reload a page that stops reacting.

changes page state, interacts with websites

browser_tab_list

List tabs. List open tabs with their id, URL and title. The active tab (the one other tools act on) is marked with *.

read-only, local to the browser

No parameters.

browser_tab_switch

Switch tab. Make another open tab the active tab; all following browser tools act on it. Use browser_tab_list to see tab ids. Element refs from other tabs do not apply; call browser_snapshot after switching.

changes page state, local to the browser

browser_tab_close

Close tab. Close a tab (default: the active tab). If the active tab is closed, the most recently opened remaining tab becomes active.

changes page state, local to the browser

browser_close

Close all tabs. Close every tab and discard their pages, console and network logs. Cookies are kept (use browser_clear_cookies to remove them). A fresh blank tab opens automatically on the next browser tool call.

changes page state, local to the browser

No parameters.

Group state

browser_get_cookies

Get cookies. List cookies in the browser cookie jar (shared by all tabs), including HttpOnly cookies, as one JSON object per line. expires is a unix timestamp in seconds, or -1 for session cookies.

read-only, local to the browser

browser_set_cookie

Set cookie. Add or replace a cookie in the browser cookie jar (shared by all tabs), e.g. to reuse a session token instead of logging in. Give domain or url; by default the cookie is set for the current page's host.

changes page state, local to the browser

browser_clear_cookies

Clear cookies. Delete every cookie from the browser cookie jar (all domains, all tabs). Page localStorage is not affected.

changes page state, local to the browser

No parameters.

browser_storage_state

Export storage state. Export the session state as JSON: all cookies plus localStorage and sessionStorage of the active tab's origin. Save it and pass it to browser_set_storage_state later to restore a logged-in session without logging in again (cookie-based logins restore fully; Obscura keeps page storage only until the page navigates or reloads).

read-only, local to the browser

No parameters.

browser_set_storage_state

Restore storage state. Restore state exported by browser_storage_state: cookies are added to the shared cookie jar, and localStorage/sessionStorage entries are written for the origin the active tab is currently on (navigate there first; entries for other origins are reported as skipped). Obscura keeps page storage per page load, so restored storage lasts until the tab navigates or reloads; cookies persist.

changes page state, local to the browser

Group debug

browser_evaluate

Run JavaScript. Run JavaScript in the active page and return the result. Accepts an expression (document.title), an object literal ({title: document.title, links: document.links.length}), statements (the last expression is the result: const n = 2; n * 21) and top-level await (await fetch("/api").then(r => r.json())); returned promises are awaited. Objects and arrays come back as JSON (large values are shortened), DOM elements as their HTML. Thrown errors are reported as errors. Prefer browser_snapshot / browser_extract for reading pages; use this for custom checks or page APIs.

changes page state, interacts with websites

browser_console_messages

Console messages. Show console output and uncaught errors of the active tab (console.log/warn/error, script exceptions), oldest first. Messages are kept across navigations in the tab. Use level "error" to see only errors and exceptions.

read-only, local to the browser

browser_network_requests

Network requests. List the network requests of the page currently open in the active tab (document, scripts, stylesheets, images, fetch/XHR), with HTTP status, type, size and duration. The list starts over on each navigation. Note: with Obscura stealth mode on, requests made by page scripts (fetch/XHR) are not reported.

read-only, local to the browser

Group capture

browser_pdf

Save page as PDF. Print the current page to a PDF (print media, paginated) and return it as an embedded application/pdf resource. Obscura renders PDF pages as images, so the text is not selectable; use browser_snapshot or browser_markdown to read text.

read-only, local to the browser

browser_set_viewport

Set viewport size. Resize the active tab's viewport (CSS pixels), e.g. 390x844 to check a phone-width layout. The page reflows and later screenshots use this size. Only the active tab changes; new tabs start at the default size.

changes page state, local to the browser

Group agents

agent_run

Run a browser agent (agentic mode). Hand a browser task to a sub-agent. It works in its own isolated browser (own tabs and cookies; your browser is not touched), completes the TASK on its own (navigating, clicking, filling forms, reading pages, searching the web) and returns the OUTPUT you describe. Use it for multi-step jobs you do not need to drive step by step. Runs can take minutes; if the result is not ready in time you get a run_id for agent_wait.

changes page state, interacts with websites

agent_automate

Automate a browser task as a reusable script. Hand a browser task to an automation agent. It does the TASK once in its own isolated browser to learn how, then writes a reusable script that repeats it for new parameter values, verifies the script in a fresh browser, and stores it. Returns the script name, its parameters (types, meaning, examples), how to run it, the verification result, and the OUTPUT of the task itself. Run the script later with script_run — no model needed, much faster.

changes page state, interacts with websites

agent_find

Find information on the web (with sources). Give a finder agent an OBJECTIVE (a question or a specific thing to find). It searches the web in its own isolated browser, reads the pages, cross-checks the facts on several independent websites, and returns the answer with a confidence level, conflicts between sources, and the links it cited (each with the supporting quote).

read-only, interacts with websites

agent_wait

Wait for an agent run. Wait for a sub-agent run (agent_run, agent_automate, agent_find) to finish and return its result; returns "still running" again if it is not done in time.

read-only, local to the browser

agent_status

Agent run status. Show one sub-agent run (progress, or its result when finished), or list recent runs when run_id is omitted.

read-only, local to the browser

agent_cancel

Cancel an agent run. Stop a running or queued sub-agent run. Its browser is closed; a script it already saved is kept.

changes page state, local to the browser

Group scripts

script_list

List automation scripts. List the stored automation scripts (made by agent_automate) with their parameters and verification status.

read-only, local to the browser

No parameters.

script_get

Show an automation script. Show a stored script: what it does, its parameters, how to run it, verification status and (optionally) its source code.

read-only, local to the browser

script_run

Run an automation script. Run a stored automation script with parameters, without any model: it replays the recorded browser job in a fresh isolated browser and returns the script output (JSON) and its log. Parameters are validated and defaulted from the script definition (see script_get).

changes page state, interacts with websites

script_delete

Delete an automation script. Delete a stored automation script (its code and metadata files).

changes page state, local to the browser