video

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

With only openWorldHint in annotations, the description carries the burden and does well: it discloses that seek-based capture restores playback time and paused state, that DRM-black frames are flagged rather than silently returned, that `save` writes images to <output-dir>/frames/, and that every_ms samples in real time. It stops short of stating timeouts, failure modes for missing videos, or cross-origin restrictions beyond the iframe note.

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?

Front-loaded with the purpose, then organized by action, and no sentence is filler. The telegraphic style ('play/pause/seek(time)/set(rate, muted, volume, loop)') is efficient but occasionally compresses past readability, e.g. the 'frames' sentence packs three capture modes into one clause.

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 an 18-parameter, multi-mode tool with no output schema, the description covers the return shape of `list` (explicit field list), the frame labeling convention ('frame i/n @ mm:ss.ss'), and caption formatting. Minor gaps remain around play/pause/set return values and error behavior, but an agent has enough to invoke it correctly.

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 already 94%, so the baseline is 3; the description adds real value by explaining the mutually exclusive frame-capture modes (times list vs count over start..end vs every_ms + duration_ms) and by tying captions to the start/end window. It also explains the `target` default, which the schema repeats but the description anchors to the overall selection rule.

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?

Opens with a specific verb+resource ('Watch videos on the page (all frames, incl. cross-origin iframes)') and then enumerates every action mode (list/play/pause/seek/set/frames/captions) with what each returns. The scope is unambiguous, though it never explicitly contrasts itself with the screenshot/snapshot siblings that also produce images.

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 through the action-by-action breakdown and the default target rule ('the largest visible playing video, else the largest visible one'), which tells the agent how to omit `target` safely. There is no explicit guidance on when to prefer this over `screenshot`/`snapshot` for capturing video frames, and no stated preconditions such as whether the video must be playing or the page focused.

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