phone_swipe

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

With no annotations, the description carries the full burden and does real work: it flags the tool as EXPERIMENTAL and discloses host dependencies (iPhone Mirroring, pyobjc) plus the fact that it emulates a mouse drag rather than a native touch. It does not say what happens on failure, whether the call blocks for the duration, or what the return value is, which keeps it below 5.

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 tight sentence, front-loaded with the EXPERIMENTAL warning and prerequisites before the operational detail. No redundant restatement of the name or title.

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 3-parameter mutation tool with no annotations and no output schema, the description covers prerequisites, purpose, parameters, and sibling routing. The remaining gaps — coordinate semantics, default duration, and error/return behavior — are real but secondary for a fire-and-forget gesture tool.

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 0%, so the description must compensate; it does name all three parameters — 'from [x,y] to [x,y]' and 'optional duration in ms' — which is more than the bare schema provides. It omits coordinate-space details (screen vs device points, array length/ordering) and the default value for ms, so it is not fully self-sufficient.

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+resource: swipe (mouse drag) from an [x,y] point to another over an optional duration, with the target use case (Home Screen paging) named. It also explicitly distinguishes itself from phone_scroll for list movement, so an agent can separate it from the nearest sibling without opening the schema.

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 the use case ('gestures such as Home Screen paging') and an explicit exclusion routing to phone_scroll 'to move a list'. It also states prerequisites up front (iPhone Mirroring, python3 with pyobjc), which is exactly the when-can-I-use-this information an agent needs.

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