ghost_scroll

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

With no annotations provided, the description carries the full behavioral burden and delivers detailed context: the wheel is POSTED to the target window, the pointer never moves, the window is never raised, covered and hidden-desktop windows work, and coord mode needs a foreground policy. This is substantial and actionable beyond what the schema provides.

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 dense and front-loaded, with every clause contributing information about a mode or constraint. It is appropriately sized for an 8-parameter tool, though the semicolon-heavy, run-on middle sentence is harder to parse than a more structured breakdown would be.

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?

Given the tool's complexity and the absence of an output schema, the description covers target selection, modes, defaults, and background behavior thoroughly. The main gap is that it only specifies the return value for 'until' mode ('returns found') and does not state what a normal scroll returns or how errors/edge cases surface.

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?

The description adds meaning to nearly every parameter despite only 50% schema coverage: amount is in notches with default 3, window anchors the target or falls back to the session anchor, x/y are coordinate-mode values at the real pointer, and until_name/until_role/max_scrolls define the 'until' mode semantics. This meaningfully compensates for the schema's sparse coverage.

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 names the action (Scroll) and the target resource (a window via 'window=' or the session anchor), and enumerates directions and modes. It is distinct enough to be understood, but it does not explicitly differentiate itself from sibling tools like ghost_tab_scroll, leaving some sibling comparison to inference.

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 gives concrete context for when each mode applies: background-window scrolling under the default background policy, coord mode requiring a foreground policy, and 'until' mode for repeated scrolling until an element appears. It does not explicitly state when not to use this tool or name alternatives, so the when-not guidance is implied rather than explicit.

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