Tools Reference

OverviewCopy Anchor Link

browserTools(session) returns all 33 tools. You can filter by module or create tools with the module and per-tool factories.

import { browserTools } from '@cogitator-ai/browser';

const allTools = browserTools(session);

const subset = browserTools(session, {
  modules: ['navigation', 'extraction'],
});

Tools from browserTools() call session.ensureStarted() before every execution, so the browser launches on the first tool call (and relaunches if it was closed or crashed). An unknown module name throws, listing the available ones. Every tool has category: 'web' and the tags ['browser', <module>].

Typed FactoriesCopy Anchor Link

Each module has a factory — createNavigationTools, createInteractionTools, createExtractionTools, createVisionTools, createNetworkTools — that returns a typed tuple built with toolset(). Destructuring keeps each tool's parameter and result types, which is handy when you call tools from your own code:

import {
  BrowserSession,
  createNavigationTools,
  createExtractionTools,
} from '@cogitator-ai/browser';

const session = new BrowserSession();
await session.start();

const [navigate] = createNavigationTools(session);
const [getText, , , getLinks] = createExtractionTools(session);

const ctx = { agentId: 'script', runId: 'manual', signal: AbortSignal.timeout(30_000) };

const page = await navigate.execute({ url: 'https://example.com' }, ctx); // { url, title, status }
const { text } = await getText.execute({ selector: 'main' }, ctx);
const { links } = await getLinks.execute({ baseUrl: page.url }, ctx);

Tuple order matches the order of the tools on this page. Factory-made tools do not auto-start the session — call session.start() first. Every tool also has its own factory (createNavigateTool, createClickTool, …), and the Zod schemas (navigateSchema, clickSchema, …) and input types (NavigateInput, ClickInput, …) are exported.

NavigationCopy Anchor Link

7 tools for page navigation and waiting.

browser_navigateCopy Anchor Link

Navigate to a URL. Returns { url, title, status } — the final URL, page title, and HTTP status (0 when there is no response, e.g. about:blank).

browser_go_backCopy Anchor Link

Go back to the previous page in browser history. No parameters. Returns { navigated, url, title }; navigated is false when there was no history entry.

browser_go_forwardCopy Anchor Link

Go forward to the next page in browser history. No parameters. Returns { navigated, url, title }.

browser_reloadCopy Anchor Link

Reload the current page. Returns { url, title }.

browser_wait_for_navigationCopy Anchor Link

Wait for the page URL to match a glob pattern. Returns { url, title }.

browser_get_current_urlCopy Anchor Link

Get the current page URL and title. No parameters. Returns { url, title }.

browser_wait_for_selectorCopy Anchor Link

Wait for a CSS selector to reach a state. Returns { found: true }, or { found: false } on timeout.

InteractionCopy Anchor Link

9 tools for clicking, typing, and form manipulation. With stealth humanLikeMouse, click, hover and scroll use human-like mouse movement; with humanLikeTyping, typing is keystroke by keystroke (see Stealth).

browser_clickCopy Anchor Link

Click an element by CSS selector. Returns { clicked: true }.

browser_typeCopy Anchor Link

Type text into an input element. Uses fill() for instant input (replacing the value), or keystrokes when delay is set (appending unless clearFirst). With stealth humanLikeTyping, the field is cleared and typed key by key with human-like delays, so the result matches fill(). Returns { typed: true }.

browser_select_optionCopy Anchor Link

Select an option from a <select> element. At least one of value, label or index is required. Returns { selected } — the selected option values.

browser_hoverCopy Anchor Link

Hover over an element. Returns { hovered: true }.

browser_scrollCopy Anchor Link

Scroll the page or a specific element. Returns { scrolled: true }.

browser_press_keyCopy Anchor Link

Press a keyboard key with optional modifiers (sent as a combo such as Control+a). Returns { pressed: true }.

browser_drag_and_dropCopy Anchor Link

Drag an element and drop it onto another. Returns { dropped: true }.

browser_fill_formCopy Anchor Link

Smart form filler. For each key it tries, in order: input[name], input[placeholder], input[aria-label], textarea[name], select[name], then an input / textarea / select inside a <label> containing the text, and fills the first match.

String values are typed into inputs, booleans check or uncheck checkboxes, and string arrays select options. When stealth is enabled, typing uses human-like delays. Returns { filled, skipped, errors }: the keys that were filled, the keys with no matching field or that failed, and { field, error } for failures.

// the agent calls this tool with:
{
  "fields": {
    "Email": "user@example.com",
    "Password": "secret",
    "Remember me": true,
    "Country": ["US"]
  }
}

browser_upload_fileCopy Anchor Link

Upload files to a file input element. Paths are resolved against the working directory and must exist, otherwise the tool throws Upload file not found. Returns { uploaded: true }.

ExtractionCopy Anchor Link

7 tools for reading page content.

browser_get_textCopy Anchor Link

Extract rendered text (innerText) from the page or the first element matching the selector. Hidden elements, scripts and styles are excluded. Returns { text }.

browser_get_htmlCopy Anchor Link

Get HTML content. Without a selector returns the full document; with one, the element's inner HTML, or its outer HTML when outer is set. Returns { html }.

browser_get_attributeCopy Anchor Link

Get the value of an attribute on a DOM element. Returns { value } (null when the attribute is missing).

browser_get_linksCopy Anchor Link

Extract all links from the page or the first element matching selector. Returns { links } with text, href and title for each link; href is the raw attribute unless baseUrl is given.

browser_query_selector_allCopy Anchor Link

Query all elements matching a CSS selector. Returns { elements } with tag, text (first 200 characters), attributes and visible for each.

browser_extract_tableCopy Anchor Link

Extract structured data from an HTML table as { headers, rows }. Headers come from the last <thead> row, or from the first row when there is no <thead>. Uses the table's own rows and cells, so nested tables do not leak extra rows. If the selector matches a wrapper element, the first table inside it is used; when nothing matches, both arrays are empty.

browser_extract_structuredCopy Anchor Link

Extract the rendered text of the page or a scoped element without cloning the DOM (no side effects on the page). Scripts, styles, and non-visible elements are excluded and runs of blank lines collapsed. Returns { instruction, text, url, title } so the agent can pull the requested data out of the text itself.

VisionCopy Anchor Link

4 tools for visual interaction. See the dedicated Vision page for details.

browser_screenshotCopy Anchor Link

Take a screenshot of the page or element (first match). Returns { image, mimeType, width, height } with base64-encoded image data. fullPage only applies to page screenshots.

browser_screenshot_elementCopy Anchor Link

Screenshot a specific element (first match) as PNG. Returns { image, boundingBox }.

browser_find_by_descriptionCopy Anchor Link

Find elements matching a natural language description using the accessibility tree. Returns { elements, total } (up to 50 elements with role, name, description).

browser_click_by_descriptionCopy Anchor Link

Find an element by description and click it. Tries button, link, text, label, and placeholder strategies. Returns { clicked, element }.

NetworkCopy Anchor Link

6 tools for request interception and traffic monitoring. See the dedicated Network page for details.

browser_intercept_requestCopy Anchor Link

Intercept HTTP requests matching a URL pattern in every tab. Returns { interceptorId }.

browser_remove_interceptorCopy Anchor Link

Remove an interceptor created by browser_intercept_request or browser_block_resources. Returns { removed } — the removed ids.

browser_wait_for_responseCopy Anchor Link

Wait for an HTTP response matching a URL pattern. Returns { url, status, headers, body }.

browser_block_resourcesCopy Anchor Link

Block specific resource types from loading. Returns { blocking: true, interceptorId, types }.

browser_capture_harCopy Anchor Link

Start or stop capturing HTTP traffic of all tabs. Stop returns { capturing: false, entries, truncated, har, path? }.

browser_get_api_callsCopy Anchor Link

Get captured XHR/fetch API calls with optional filtering. Returns { calls }.