scroll_to

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

With no annotations provided, the description carries the full burden. It discloses the smooth-scroll behavior, the smooth parameter controlling smooth vs instant, and the capability to scroll large distances. However, it does not detail behavior when ref and selector conflict, or error handling if element not found.

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 very concise: a one-sentence purpose, a bullet-argument list, and a notable capability note. Every sentence adds value with no redundancy or fluff. It is front-loaded with the core purpose.

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 tool with 4 parameters, 0 required, and an output schema (assumed complete), the description covers identification, alignment, smoothness, and a key capability. It misses conflict resolution for ref/selector and error scenarios, but is otherwise adequate.

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 0%, so the description must fully explain parameters. It does so: ref is a snapshot ref from browser_snapshot, selector is a CSS alternative, block lists valid alignment options, and smooth explains the smooth vs instant behavior. This adds critical meaning beyond the schema's type-only definitions.

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 clearly states the tool's purpose: 'Smooth-scroll a specific element into viewport.' It specifies the action (scroll), target (element), and adds a distinguishing capability: works even if element is far off-screen. This sets it apart from sibling tools like 'scroll' which are more generic.

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 implies when to use (when an element needs to be scrolled into view, especially if far off-screen), but does not explicitly state when not to use or mention alternatives like 'scroll' or 'click'. It lacks guidance on preferring this over other interaction tools.

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