Skip to main content
Glama
seleniumbase

SeleniumBase MCP

Official
by seleniumbase
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

find_elements

Find matching page elements and return structured data, including count, tag names, text, and optional HTML, using a CSS or convertible XPath selector.

Instructions

Find matching elements and return structured element information.

Use this tool when you need to discover how many elements match a selector, inspect their text/tag names, or inspect the HTML of multiple matches.

This tool converts matching elements into ordinary serializable dictionaries. It does not return live SeleniumBase element objects.

Args: selector: A CSS selector, or an XPath selector that SeleniumBase can convert to CSS. In sb.find_elements, SeleniumBase automatically attempts to convert XPath to CSS. Some XPath expressions, such as those using contains(...), cannot be converted to CSS and therefore aren't supported by this tool.

timeout: Maximum number of seconds to wait for at least one matching
    element to appear. If the selector is an XPath selector that
    cannot be converted into a valid CSS selector, then the wait
    might be less than the timeout.

include_html: If True, include each matching element's outer HTML.
    If False, return only tag name and text.

Returns: A dictionary containing: - count: Number of matching elements found. - matches: A list of element dictionaries containing tag_name and text, plus html when include_html=True. If there's an error during search, then "error" is added into the returned dictionary with error details.

Tool selection: - Need structured information about matching elements -> use find_elements. - Need the visible text/HTML of a page or a single element -> use get_content. - Need to click one of several matches -> use click with nth. - Need to know whether an element is present/visible -> use check_condition.

Notes: Element handles cannot be persisted across MCP calls. If you find elements and then need to act on one, resolve it again with the appropriate interaction tool.

For uncaught errors, @handle_sb_errors returns strings.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
timeoutNo
selectorYes
include_htmlNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv4.53.7
    • removedInput schema / properties / timeout / anyOf
      Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
    • changedInput schema / properties / timeout / default
      Previous value: -7New value: +0.5
    • addedInput schema / properties / timeout / type
      Added value: +"number"
  2. Changed1 schema field changedv4.53.2
    • changedInput schema / properties / timeout / anyOf
      Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]
  3. Addedv1.0.1

TDQS

A4.9/5.0
Behavior5/5

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

No annotations exist, so the description carries the full behavioral burden and does so richly: it states results are converted to ordinary serializable dicts (not live element objects), that handles cannot persist across MCP calls, that timeout may be shortened for non-convertible XPath, and that errors surface as an 'error' key. These are exactly the traits an agent needs to avoid misuse.

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

Conciseness4/5

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

Front-loaded with purpose and gated by clear section headers (Args, Returns, Tool selection, Notes), so it is navigable. It is somewhat long and the Returns block partially restates the output schema, but nearly every line adds routing or behavioral value.

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?

Complete for a discovery tool: it explains purpose, parameter behavior, return shape (even beyond the existing output schema), error behavior, and the critical cross-call handle limitation. No gap remains that would cause an incorrect invocation.

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

Parameters5/5

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

Schema description coverage is 0%, yet the Args section documents all three parameters with meaning beyond the schema: selector as CSS or SeleniumBase-convertible XPath with the contains(...) limitation called out, timeout as a wait-for-first-match bound with a fallback caveat, and include_html controlling outer HTML in output.

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?

Starts with a specific verb+resource ('Find matching elements and return structured element information') and then explicitly distinguishes itself from siblings get_content, click, and check_condition in the Tool selection section. An agent can identify the tool's role without opening any schema.

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?

Provides an explicit 'Use this tool when...' trigger list (count, text/tag inspection, HTML of multiple matches) and a Tool selection block naming the alternative for each adjacent need. When/when-not and alternatives are all covered.

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

Deploy Server

Other Tools