Auto-Browser

browser.find_elements

Locate page elements by CSS selector or text/regex query, returning text, href, value, bounding box, and visibility for scraping or clicking.

Instructions

Find elements either by CSS selector or by a text/regex query across the page's text content. selector mode returns matching elements' text, href, value, bounding box, and visibility -- useful before clicking or scraping multiple items. query mode (set query, optionally regex and context) returns the matched text plus surrounding context for each hit -- a cheap way to locate a specific string on the page without a full observe.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Most matches to return.
`query`	No	Text or regex to search for across the page's text content, as an alternative to selector. Matching is case-insensitive in both modes. Returns matched elements plus surrounding text.
`regex`	No	Treat query as a regular expression (JavaScript syntax, 'gi' flags) instead of a plain-text substring match.
`context`	No	Characters of surrounding text to include around each match when query is used.
`selector`	No	CSS or Playwright selector. Give this or query.
`session_id`	No	Target session id, from browser.create_session or browser.list_sessions. Optional when exactly one session is live; observe and act tools create one when none is.

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv1.8.1Sep 26, 2026

addedInput schema / properties / context

Added value: +{
+  "default": 0,
+  "description": "Characters of surrounding text to include around each match when query is used.",
+  "maximum": 500,
+  "minimum": 0,
+  "title": "Context",
+  "type": "integer"
+}

addedInput schema / properties / limit / description
```
Added value: +"Most matches to return."
```

addedInput schema / properties / query

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 500,
+      "minLength": 1,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Text or regex to search for across the page's text content, as an alternative to selector. Matching is case-insensitive in both modes. Returns matched elements plus surrounding text.",
+  "title": "Query"
+}

addedInput schema / properties / regex

Added value: +{
+  "default": false,
+  "description": "Treat query as a regular expression (JavaScript syntax, 'gi' flags) instead of a plain-text substring match.",
+  "title": "Regex",
+  "type": "boolean"
+}

addedInput schema / properties / selector / anyOf

Added value: +[
+  {
+    "maxLength": 2000,
+    "minLength": 1,
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / selector / default
```
Added value: +null
```

addedInput schema / properties / selector / description

Added value: +"CSS or Playwright selector. Give this or query."

removedInput schema / properties / selector / maxLength
```
Removed value: -2000
```
removedInput schema / properties / selector / minLength
```
Removed value: -1
```
removedInput schema / properties / selector / type
```
Removed value: -"string"
```

addedInput schema / properties / session_id / anyOf

Added value: +[
+  {
+    "maxLength": 120,
+    "minLength": 1,
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / session_id / default
```
Added value: +null
```

changedInput schema / properties / session_id / description

Previous value: -"ID of the target browser session, as returned by browser.create_session or listed by browser.list_sessions."New value: +"Target session id, from browser.create_session or browser.list_sessions. Optional when exactly one session is live; observe and act tools create one when none is."

removedInput schema / properties / session_id / maxLength
```
Removed value: -120
```
removedInput schema / properties / session_id / minLength
```
Removed value: -1
```
removedInput schema / properties / session_id / type
```
Removed value: -"string"
```

removedInput schema / required

Removed value: -[
-  "session_id",
-  "selector"
-]

Addedv1.4.2Jul 25, 2026
Removedv1.4.2Jul 25, 2026
Changed3 schema fields changedv1.0.3May 5, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
- addedInput schema / properties / session_id / maxLength
```
Added value: +120
```
- addedInput schema / properties / session_id / minLength
```
Added value: +1
```
First observedv0.5.0Mar 26, 2026

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations say little beyond abstract hints, so the description carries much of the behavioral burden. It discloses what each mode returns: element text/href/value/bounding box/visibility for selector mode, and matched text with surrounding context for query mode. It does not discuss side effects or navigation behavior, but for a find-style tool the output disclosure is the most important behavioral trait.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact—three sentences—with the core purpose in the first clause. Each subsequent clause earns its place by describing a specific return mode, use case, or sibling alternative; there is no repetitive filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by specifying return fields for both modes and their practical use cases. The input schema already documents all six parameters, including constraints and defaults, so nothing needed for correct invocation is left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by organizing the otherwise flat parameter list into the two modes and tying 'context' and 'regex' to query mode and 'selector' to the element-attribute return path. This helps the agent assemble valid parameter combinations beyond what individual schema descriptions already provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ('Find elements') and immediately distinguishes the two operating modes: CSS selector and text/regex query. It also identifies distinct outputs for each mode, and the note about not needing a 'full observe' separates it from the browser.observe sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete usage context for both modes: selector mode is 'useful before clicking or scraping multiple items,' and query mode is positioned as a 'cheap way to locate a specific string on the page without a full observe.' This explicitly names the observe sibling as an alternative and the condition for choosing the query path.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

browser.find_elements

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools