safari_scroll_to_element

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

With no annotations, the description carries full burden. It reveals that text mode scrolls down until text appears, but does not describe error behavior, scrolling direction, or timeout handling. The timeout parameter is mentioned only in the schema, not in the description.

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?

Two concise sentences front-load the core purpose and a special case. Every sentence is informative without redundancy.

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?

For a straightforward scroll tool, the description covers the key behavioral differences. However, it omits details on priority when both selector and text are provided, and does not clarify if selector mode also waits for the element. Overall adequate but not exhaustive.

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 is 3. The description adds minimal value beyond the schema: it restates the text parameter's behavior and consolidates the two strategies. It does not provide new semantic insights for selector, block, or timeout parameters.

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 explicitly states the tool scrolls to an element via CSS selector or text, which is a specific verb+resource. It distinguishes between two modes, clearly differentiating it from siblings like safari_scroll and safari_scroll_to.

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 provides clear context for when to use text mode (virtual DOM/lazy loading), but does not explicitly exclude other scenarios or compare with alternative scrolling tools. It offers helpful guidance but lacks comprehensive when-not-to-use advice.

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