imgui_scroll_window

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

With no annotations provided, the description carries the full burden of behavioral disclosure. The description is a terse one-liner that reveals nothing about side effects—does this simulate input persistently or transiently? Does the window need to be focused/hovered for scroll to work? Does it fail silently if the window is not found or not scrollable? None of these behavioral aspects are disclosed.

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 efficient sentence with no wasted words. It states the essential action clearly. It is appropriately minimal but doesn't cross into being incomplete for a tool this simple.

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?

While the tool is relatively simple (2 params, no output schema, no nested objects), the lack of any behavioral context makes it incomplete. The description doesn't explain how the scroll is delivered (synthetic vs passthrough), whether the mouse must be positioned over the window first, or what the function returns/does on success or failure. For an action tool with no output schema and no annotations, more context is warranted.

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 schema documents both parameters (window ID and delta_y with direction semantics). The description adds nothing beyond what the schema already provides—the wheel-scroll context is implicit. The schema's 'positive=up, negative=down' convention is helpful and self-explanatory, so baseline 3 is appropriate.

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 'Scroll the mouse wheel over a window' uses a specific verb (scroll) and resource (window), clearly stating the primary action. It distinguishes from siblings like imgui_click_widget and imgui_hover_widget, though it doesn't explicitly differentiate from imgui_set_mouse_pos or imgui_press_key.

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 provides no guidance on when to use this tool versus alternatives. For instance, it doesn't clarify whether this tool synthesizes a synthetic wheel event versus expecting an actual user input, nor does it state when to use delta_y versus other scroll approaches. No context about prerequisites (e.g., window must exist/be visible) is given.

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