scroll

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

Annotations already indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds minimal behavioral context beyond the action itself, such as the unit (pixels of document height), but does not disclose effects like whether it scrolls the entire page or only a scrollable element, or if there is any animation. It does not contradict annotations, and the bar is lower because annotations exist, but it adds limited extra transparency.

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 a single, focused sentence that states the action, the target, and the primary parameters. It is front-loaded with the verb and resource, and there is no extraneous information. It is efficiently concise.

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, the description is mostly complete: it names the action, the target (page), the direction (up/down), and the unit (pixels). The output schema exists and likely covers return values, so the description does not need to explain those. The openWorldHint suggests possible side effects, but the description does not mention any; however, given the simplicity of scrolling, the core usage is clear. The only gap is the lack of explicit parameter value details, but that is partially covered by the description's 'down or up' and 'pixels' hints.

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% (no descriptions in the schema), so the description must compensate. It partially does: 'amount' is implied to be pixels (from 'by pixels of document height'), and 'direction' is implied to accept 'down' or 'up'. However, it does not specify the exact valid values for direction (e.g., case sensitivity), the behavior of negative amounts, or how the default values work. This is adequate but not comprehensive.

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 uses a specific verb ('scroll') and resource ('page'), and clarifies the two possible directions (down or up) with a unit of measurement (pixels of document height). It clearly differentiates from siblings like goto (navigation), drag (pointer), and press_key (keyboard) by describing a page-level scroll action.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention when scrolling is appropriate, whether it should be used for specific scroll contexts (e.g., inside an iframe), or when other tools like drag might be more suitable. The description is purely definitional.

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