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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds pipeline context and that lazy loading may be triggered, but says nothing about how much is scrolled, whether repeated calls compound, or what happens if the page cannot scroll further.

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?

A single front-loaded sentence: purpose first, then the routing notes in a compact trailing clause. Dense but every clause carries information; the parenthetical about standalone setup is slightly compressed but not wasteful.

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?

Covers purpose, placement in a pipeline, and alternatives, which is most of what an agent needs for a 3-parameter action tool with full schema coverage and no output schema. The remaining gap is the contents of fields: since it is an open additionalProperties object, the description should say what a ScrollAction config looks like rather than deferring entirely to upstream documentation.

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 description coverage is 100%, so the baseline is 3. The description only says that fields carries the upstream ScrollAction configuration and does not explain which keys matter (pixels, target element, iterations), leaving the actual contract to the upstream docs.

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?

States a specific verb and resource (scroll the page) plus the reason (trigger lazy loading, reach below-the-fold content) and the operating context (inside an importio_play_action pipeline). It explicitly names what it is not — the deprecated coordinate jump importio_scroll_to and the sibling importio_action_viewport.

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?

Gives clear when-to-use guidance (before extraction, for lazy-loaded or below-the-fold content) and routes the agent to alternatives by name for two distinct cases: coordinate jumping and viewport resizing, including the standalone variant importio_viewport. No inference is required to pick between these siblings.

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