focus_on

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

No annotations are provided, so the description carries the full burden, and it does well: it discloses that scroll only ensures in-viewport presence, that focus moves keyboard focus, and that highlight 'can affect timing and may reduce stealth' — the last one is a non-obvious behavioral trait an agent must know. It omits edge-case behavior (e.g., what happens when a selector matches nothing), but the core profile is disclosed.

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 front-loaded with the behavior, followed by the negative-scope sentence, then an Args block, then a 'Tool selection' table. Every sentence carries information. It is slightly longer than strictly necessary — the Tool selection section paraphrases the opening paragraphs — but the redundancy improves navigation, so I do not penalize further.

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?

Given that the tool sits among 24 siblings that include click, type_text, hover_with_action, select_option and scroll, the description exhaustively routes the agent: it covers the primary use, the three actions' semantics, and the exclusions with alternative tool names. It also accounts for the stealth/timing implication of highlight. Nothing an agent needs in addition to the schema and sibling list is missing.

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% — the schema provides only names, a default, and an enum. The description compensates: selector is defined as 'CSS selector or SeleniumBase selector,' and the three action enum values are each explained in a sentence of behavior. It doesn't specify selector validity rules, but for the coverage gap this is strong.

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 starts with a specific verb and two resources: 'Scroll to, focus, or highlight an element.' It immediately differentiates itself from siblings (click, type_text, hover_with_action) by explicitly stating it 'does NOT click, type into, select from, hover over, or otherwise activate the element.' This gives an agent a clear discriminator without opening any other schema.

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 lists each use apart ('Bring into view' -> default, 'Focus' -> action="focus") and names the exact sibling alternatives for excluded actions ('Click -> use click', 'Type text -> use type_text', 'Hover -> use hover_with_action'). It states when to use it AND when not to, referencing the right sibling names.

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