view_frames

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

With no annotations provided, the description carries the full burden, and it delivers richly: frames are cached by absolute timestamp, overlapping ranges reuse work, frames are never silently dropped or resampled, the interval requested is the interval returned, and requests past limits fail with numbers and alternatives. It also discloses the exact server limits (20 images, 10 MB each, 40 MB per result) and the lossless PNG behavior for start==end. This is exemplary transparency.

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 dense and front-loaded with the core purpose, then moves through key behaviors and limits. Every sentence adds information, but it is a long paragraph that could benefit from light structuring (e.g., separating the caching note from the limits note). Still, no sentence is wasted, and the most important facts come first.

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 8-parameter tool with no annotations and a single sibling, the description covers the purpose, the key parameter interactions, the failure mode, the caching behavior, and the deployment-specific limits. The output schema exists, so return-value details are already structured. An agent has everything needed to call this tool correctly and to reason about trade-offs.

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, and it does for most parameters: start/end/interval semantics, format trade-offs, max_frames default and trade-offs, and max_edge as a lever. It does not explicitly explain quality, but the schema already provides min/max/default for it, and the description's trade-off framing covers the main decision parameters. Slight gap on quality, hence 4 rather than 5.

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 and resource: 'Sample a video and return frames as images, each preceded by its timecode.' This clearly distinguishes it from the sibling video_info, which presumably returns metadata rather than frames. The timecode detail and the start==end single-moment behavior further sharpen the purpose.

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 explicit usage guidance: set start == end for a single moment, use jpeg for smaller payloads, raise max_frames only if you can trade detail, and lower max_edge or use jpeg to afford more frames. It also states that server limits are fixed by the deployer, not the agent, and that requests past a limit fail rather than being silently truncated. This is strong when-to-use and how-to-trade-off guidance.

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