get_frame_burst

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description does not contradict these. It adds useful behavioral context beyond annotations, such as platform requirements (yt-dlp for certain sources), the default count, and the note that native frames are context-expensive.

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 well-structured with a clear lead sentence, use-case paragraph, example, supported formats list, and Args section. It is slightly long but each section earns its place; the example effectively clarifies the even distribution behavior.

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 has no output schema, and the description explains the return (N images, either file paths or base64 via returnBase64). It covers the supported source types, the motion-analysis context, and the maxWidth tradeoff. Sufficient for a 6-parameter tool with rich annotations.

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 schema already documents all parameters thoroughly. The description's Args section repeats url/from/to/count but omits maxWidth and returnBase64, though the schema descriptions for those are rich (e.g., context cost warning). The description adds minimal value beyond the schema.

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 'Extract multiple frames evenly distributed across a time range,' which is a specific verb+resource+scope. It also differentiates from siblings by positioning itself for motion and vibration analysis, distinguishing it from get_frame_at (single frame) and scene-change-based tools.

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 clearly states the intended use case — motion and vibration analysis where scene-change detection fails — and provides concrete 'Works for' examples like shaking, flickering, and animations. It lacks explicit exclusions or named alternatives, but the context is strong enough to guide an agent.

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