seleniumbase-mcp

Overview Schema Source Related Servers Discussions Admin

Find Elements

find_elements

Read-onlyIdempotent

Find matching elements via CSS or XPath selectors and get structured data: count, tag names, text, and optional outer HTML. Useful for verifying element presence and inspecting multiple matches.

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_element with nth. - Need to know whether an element is present/visible -> use check_if_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

Name	Required	Description	Default
`timeout`	No
`selector`	Yes
`include_html`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 15, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context beyond those: it clarifies the tool returns serializable dictionaries rather than live SeleniumBase objects, explains XPath conversion limitations that may reduce timeout effectiveness, and details error handling via @handle_sb_errors returning strings. No contradictions; this is complementary and rich.

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?

The description is well-structured with clear sections (purpose, args, returns, tool selection, notes). It front-loads the core purpose and usage, then provides details. A few sentences could be tightened (e.g., the XPath explanation is slightly verbose), but overall every part earns its place. The length is justified by the need to cover alternatives and caveats.

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?

Given the tool's moderate complexity (3 parameters, 1 required, 1 optional boolean, 1 optional numeric) and the presence of an output schema (mentioned via return structure), the description covers all essentials: return format, error cases, usage boundaries, and operational constraints like handle persistence. An agent can call this tool correctly without further research.

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 coverage is 0%, so the description carries full responsibility for parameter meaning. It explains selector (CSS or XPath, with conversion caveats), timeout (max wait, behavior when XPath can't be converted), and include_html (what True/False returns). Each parameter gets concrete semantics that the schema itself lacks, fully compensating for the missing descriptions.

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 opens with a clear verb and resource: 'Find matching elements and return structured element information.' It goes on to list concrete uses (count matches, inspect text/tag names, inspect HTML) and explicitly distinguishes itself from sibling tools by naming alternatives like get_content, click_element, and check_if_condition. This leaves no ambiguity about what the tool does and how it differs.

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?

The 'Tool selection' section gives explicit when-to-use guidance for this tool versus get_content, click_element, and check_if_condition, with conditions for each. It also adds a critical usage note that element handles cannot be persisted across MCP calls, telling the agent to re-resolve elements. This is exemplary routing guidance.

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