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

No annotations are provided, so the description carries the burden. It does disclose the 'ANY' matching semantics, coordinate units (PHYSICAL pixels), and scroll cap (maxScrolls). However, it doesn't disclose side effects (actual UI scrolling changes visible state), failure behavior when element not found after maxScrolls (return null? error? empty?), or whether scrolling resets to top first. These gaps matter for a tool that physically manipulates the screen.

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, front-loaded with purpose and key semantics. The 'ANY of the provided locators' and 'PHYSICAL pixels' details are high-value. Slightly compact—could add a failure-mode sentence—but every existing word earns its place with no waste.

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 6-param tool with 100% schema coverage and no output schema, the description covers the essential mechanics (matching, scrolling, coordinates). But there's no output schema so the return format (e.g., {x, y} structure) is undisclosed, and failure behavior when element not found is unstated. Given the tool physically manipulates a device and has meaningful failure cases, this is a moderate gap.

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%—all six parameters have descriptions. The description adds the 'ANY' OR-matching semantics and 'PHYSICAL pixels' coordinate note, which is genuinely useful beyond the schema. But it doesn't clarify edge interactions like what happens if no locators are provided at all (only udid required), or whether direction 'up' vs 'down' resets scroll position first. Baseline 3 is appropriate given high schema 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?

Specific verb+resource: 'Scroll the screen until an element matching ANY of the provided locators appears, then return its coordinates in PHYSICAL pixels.' This clearly distinguishes from siblings like device_scroll (mere scrolling), device_find_element (no scrolling), and ios_scroll_to_element (iOS platform). Mentions the 'ANY of the provided locators' logic which differentiates it from a single-locator find.

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?

Provides clear context: scrolls until element appears, up to maxScrolls times, returns coordinates. It's implicit that this is for Android/iOS device UI automation vs web alternatives. However, it doesn't explicitly state when-not-to-use this vs device_find_element or device_wait_for_element, nor spell out that this is Android-specific (no 'Android' word, though siblings iOS have separate ios_scroll_to_element).

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