Scroll page

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

With no annotations, the description carries the behavioral burden and does a decent job: it reveals the operation is a relative window.scrollBy, that it mutates scroll position, and that it returns the new position. It also flags the lazy-loading caveat, though it does not describe return shape or async behavior of smooth scrolling.

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 sentences, no filler. The core action and result are front-loaded, and the lazy-loading tip is the only additional sentence, earning its place.

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 simple scroll tool without an output schema, the description covers the action, result, and a practical follow-up (get_page_snapshot). It falls slightly short only because the return value's exact shape is unspecified and there is no mention of edge cases like coordinates outside viewport boundaries or waiting for smooth scroll to settle.

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 the schema already documents x, y, behavior, and sessionId. The description adds value by framing x/y as deltas and tying the operation to window.scrollBy, making the relative semantics explicit beyond the individual parameter descriptions.

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 names a specific operation ('Scrolls the session page window'), the input mechanism ('by the given deltas'), and the result ('returns the new scroll position'). This makes it clearly distinct from read-only siblings like get_scroll_position or get_viewport_size.

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?

It provides one concrete usage pattern: for lazy-loaded content, scroll then re-run get_page_snapshot. However, it does not explicitly state when to choose this over alternatives (e.g., get_scroll_position or navigate), nor does it state exclusions or prerequisites beyond the schema-covered sessionId.

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