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

With no annotations provided, the description carries the full burden. It discloses several behavioral traits beyond the schema: automatic page source + element capture on each recorded step, coordinate space reference to windowSize, pressButton being 'performed live on the device,' assert performing NO device gesture but recording verification logic, and assertion failures marking steps FAILED with mismatch surfaced in errorMessage. These are meaningful behavioral disclosures not present in structured fields.

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 front-loaded with the core purpose in the opening sentence, then uses a clean bulleted list for the 9 action types. Each bullet is one line or a short clause. Every sentence earns its place — the pressButton line adds platform mapping detail, the assert bullet explains replay-time verification. No filler, no repetition of schema content that wouldn't add value.

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 14-parameter, 9-action tool with no output schema and no annotations, the description is quite thorough. It covers usage context (during recording, referencing windowSize), all action types with their parameter requirements, platform differences, and assert/replay semantics. Minor gap: it doesn't explicitly document the recordingId parameter's purpose (though the schema's 'from flow_recording_start' covers it) or describe return values like step IDs. But given no output schema exists, this is a small omission.

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 baseline is 3. The description adds value on top: it clarifies which parameters apply to which actions (swipe needs toX/toY), clarifies coordinate space (video/iOS-automation referencing windowSize), explains defaults (attribute defaults to platform primary text, durationMs default 300), and elaborates on assertType semantics (exists/notExists vs textEquals/textContains comparison behavior). This exceeds what the schema alone provides.

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 precise verb+resource statement ('Perform and record one action step on the device') and explains it does both the action AND the recording with automatic page source + element capture. It clearly distinguishes itself from sibling recording tools by being the step-recording action tool, while flow_recording_start, flow_recording_replay, etc. handle other phases. The 9 enumerated action types add substantial specificity beyond the schema enum.

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 gives clear context for when to use this tool (during a recording session, referencing flow_recording_start's windowSize for coordinates). It thoroughly documents each action variant, including required parameters per action (swipe needs toX/toY) and platform differences (Android keycodes vs iOS native). However, it does not explicitly state when NOT to use this tool or mention alternatives like device_tap/device_swipe for non-recording gestures.

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