ffmpeg__create_video_summary

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

With no annotations, the description takes on the full burden and discloses useful traits: input_paths accepts a comma/newline-separated list, output is JSON in stdout with output_path and clip_count, and all parameters have defaults. It does not mention overwrite behavior or resource implications, but it goes beyond the schema by returning format and input flexibility, which is stronger than the typical minimum.

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 tightly structured: a one-sentence purpose, then @remarks for input/output format, then @param lines for each parameter. It front-loads the key behavior and every line adds value without redundancy or fluff.

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 description covers purpose, all parameters with defaults, input format, and return value format. It does not include error behavior or examples, but with no output schema and a moderate parameter count, this is largely sufficient. The only gap is a deeper explanation of how the montage is assembled, but the parameters imply the sampling logic.

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 fully compensate. It does so with @param lines for all six parameters, adding meaning (e.g., input_paths as a comma/newline-separated list, clip_duration_sec as each sampled clip's duration, and defaults for interval_sec, clip_duration_sec, and merge_audio). This exceeds the schema's raw type/constraint information.

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 'Create a montage-style summary clip from one or more videos,' which clearly identifies the action (create), the deliverable (montage-style summary clip), and the input (one or more videos). This distinguishes it from sibling tools like concat_clips or split_video by focusing on summarization rather than concatenation or splitting.

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 purpose statement makes the tool's primary use obvious, but it does not explicitly state when to prefer this over alternatives or mention exclusions. Since the description gives a clear role, an agent can infer usage, but no alternative or when-not-to-use guidance is provided.

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