swipe_screen

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

No annotations are supplied, so the description carries the full burden. It does add real behavioral detail beyond the schema: scroll_to_text performs repeated automatic scrolling until a matching element appears, and return_ui_after is discouraged during continuous swipes for performance. However it omits critical behavior for a looping tool — any iteration cap, timeout, or what happens when the target text never appears — and says nothing about failure modes or that swiping mutates screen state.

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 the purpose followed by the three modes in ascending order of sophistication. Minor waste remains: '智能' (intelligent/smart) is unsubstantiated marketing framing, and the exclamation mark adds no information, though the text is otherwise tight for a 9-parameter tool.

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?

An output schema exists, so return values need not be explained, and the description covers the three invocation modes adequately. The gap is behavioral completeness for the most complex mode: scroll_to_text can run unbounded, and nothing is said about termination, failure, or how much it scrolls before giving up — information an agent needs to decide whether to call it or to use find_elements instead.

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%, so the baseline is 3, but the description genuinely adds meaning the schema cannot: it groups x1/y1/x2/y2 into a 'custom drag' mode, direction into 'four-direction swipe', and scroll_to_text as a distinct auto-scroll mode, making the mode selection legible. The return_ui_after sentence also explains the tradeoff behind a parameter whose schema text only gives the default.

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 first line names a specific verb+resource pair (swipe/scroll the screen) and then enumerates the three operating modes: four-direction swipe, custom coordinate drag, or scroll_to_text search. An agent can tell what it does without opening the schema. It does not name a sibling (e.g. perform_gesture) as the alternative, so it stops short of full sibling differentiation.

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?

Usage is implied rather than stated: the agent infers 'use this when you need to scroll or drag on screen', and the description hints that scroll_to_text is the right choice for finding an element by text. There is no explicit when-not guidance, no mention of how this differs from perform_gesture, batch_ui_actions, or find_elements + tap_element, which are the obvious neighbors.

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