find_elements

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

With no annotations, the description carries the full behavioral burden, and it does so well. It discloses that element handles resolve immediately into JSON-like dictionaries, that live SeleniumBase element objects are not returned, and that handles cannot be persisted across MCP calls. It also explains the include_html behavior and timeout semantics, which are important operational traits not visible elsewhere.

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

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

The description is organized into clear labeled sections: purpose, args, returns, tool selection, and a persistence note. Each section earns its place, and the most decision-relevant information is front-loaded. Nothing is redundant with the schema.

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

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

The description is complete for a read-only query tool with three parameters and no annotations. It covers what the tool returns, how arguments affect behavior, when to choose alternatives, and the critical non-persistence limitation. Even with an output schema present, the narrative return details add needed context.

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

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

Schema description coverage is 0%, so the description fully compensates. It adds concrete meaning to every parameter: selector gets CSS and SeleniumBase text-matching examples, timeout gets units and default, and include_html gets exact output behavior. This is far beyond what the schema titles alone provide.

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

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

The description opens with a specific verb-resource pair ('Find matching elements') and clearly states what kind of result is returned: structured element information with count, tag names, text, and optional HTML. It also differentiates from siblings by framing the tool as the one for structured multi-match inspection, not content extraction or interaction.

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

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

A dedicated 'Tool selection' section explicitly names alternative tools and the conditions that favor each: get_content for page/single-element text, click with nth for clicking a match, and check_for_condition for presence/visibility checks. This gives an agent concrete routing guidance beyond vague 'use when' phrasing.

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