page_tap_at

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

No annotations are provided, so the description carries full burden. It discloses the dispatched event sequence, the coordinate space alignment with screenshots, and the delta reporting (network/console/url). It also mentions the waitMs default. It doesn't specify failure behavior if touch is not enabled, but the requirement is clearly stated, so it's nearly complete.

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 long but every sentence earns its place: purpose, coordinate space, event dispatch, prerequisite and how to enable, and a usage hint. It's front-loaded with the core purpose and uses a compact structure. Slightly verbose but not wasteful.

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?

The tool is moderately complex (4 params, 2 required, no output schema). The description covers the purpose, coordinate system, event behavior, prerequisites, and the return delta. Missing details include sessionId usage and exact return format, but these are minor given the thorough coverage of the critical aspects.

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 only 25% (only waitMs has a description). The description compensates for x and y by explaining they are in CSS px in the same space as screenshots, and for waitMs by giving the default. However, sessionId is not explained anywhere, and the description doesn't elaborate on coordinate ranges or units beyond the schema. Given the low coverage, it adds value but doesn't fully compensate.

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 opens with a specific verb (Tap) and resource (raw viewport coordinate) and immediately distinguishes it from the sibling page_click_at by stating it dispatches touchstart→touchend for touch-aware games. It also names the alternative explicitly in the closing sentence, making the purpose unmistakable.

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?

It explicitly states when to use this tool: when a game ignores page_click_at, and gives the exact condition (touch emulation required) with two concrete ways to enable it (device:'mobile' or hasTouch:true via browser_launch/page_set_viewport). This is textbook usage guidance with a clear alternative and exclusion criteria.

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