glass_scroll_to_element

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false) and carry little behavioral weight, so the description does the heavy lifting — and it is exceptionally thorough: it discloses the sweep-and-reverse strategy, the vertical down→up fallback when the target isn't in the tree, the anchor-on-target-row/column behavior for off-center containers, and the {matched:false} timeout failure mode. No contradiction with annotations; scrolling as a state change is consistent with readOnlyHint=false.

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 core purpose is front-loaded, but the single paragraph is dense and repeats information already captured in the schema field descriptions (defaults of 3 and 20000ms, anchoring behavior, direction-inference fallback all appear in both places). The extra behavioral detail is valuable, yet the redundancy with the 100%-coverage schema makes it longer than it needs to be.

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?

With no output schema and no required parameters, the description bears full responsibility for explaining returns and behavior — and it delivers: it spells out the exact return shape ({matched, elapsed_ms, element{id,role,name,bounds,states}, scrolled{steps,reversed,direction}}, {matched:false} failure), the error case when no a11y tree exists, and the visibility requirement linking to glass_click_element. Nothing an agent needs to call it correctly 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 coverage is 100%, so baseline sits at 3. The description adds a small layer of meaning on top: it frames 'step' as a 'calibration escape hatch' with a stepping-past warning, and motivates the x/y defaults with the top-toolbar example. Much of the parameter detail (defaults, direction inference, anchoring) duplicates the schema's own rich field descriptions, so the added value is present but modest.

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?

Opens with a specific verb+resource+goal: 'Scroll a container (any axis) until an accessibility element is on-screen, then return it.' The scope is precisely delimited (scroll-to-target and return an actionable id), and it names its downstream consumer (glass_click_element), which distinguishes it from the plain glass_scroll sibling without opening either 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?

The description gives clear context on when to use it: to bring an element on-screen so its returned id is usable with glass_click_element, and it notes the visibility requirement ('actually visible — not merely present in the a11y tree'). It does not, however, explicitly state when NOT to use it versus the alternative glass_scroll, leaving part of the selection decision to inference.

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