Video frames

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

Goes well beyond the readOnlyHint annotation by disclosing side effects that matter: playback position and play/pause state are restored afterwards, cross-origin videos fall back to screen capture, and DRM-black frames are reported as such. These are exactly the behavioral facts an agent cannot derive from schema or annotations.

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?

Three tight sentences, front-loaded with the primary capability, then side-effect guarantees, then edge-case handling. No filler and no repetition of the 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?

No output schema exists, yet the description conveys the return shape at a high level (images) and how failure cases surface (DRM frames reported as such). It stops short of describing the response envelope or how multiple requested frames are ordered/returned, which is a minor gap for a 0-required-param 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 coverage is 100%, so all four parameters are already documented in the schema, including the default main-video selection and the 960px default width. The description adds only a restatement of the times behavior ('frames at given times') and no extra syntax, limits, or format detail, so baseline 3 applies.

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 and resource ('Returns frames of a video as images') plus the two capture modes (current frame vs. frames at given times), which clearly separates it from page-level screenshot tools. It doesn't explicitly distinguish itself from the close sibling video_storyboard, which also produces frames, so an agent must infer which one to use.

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 by the two modes described (current frame vs. specific timestamps) but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as video_storyboard, video_watch, or screenshot. The agent gets the what but not the routing logic.

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