ffmpeg__concat_clips

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

With no annotations, the description carries the full burden. It discloses that the tool uses the ffmpeg concat demuxer, returns JSON in stdout with output_path and clip_count, and provides defaults for reencode, video_codec, and audio_codec. However, it does not mention error behavior, file overwrite policies, or side effects on input files, which prevents a 5.

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 compact and well-structured: a one-sentence purpose, a concise @remarks line with key guidance, and clear @param blocks. Every sentence adds value without excessive length or redundancy.

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?

Despite having 6 parameters and no output schema or annotations, the description manages to cover the main purpose, input format, output format, defaults, and a key usage caveat (re-encoding). Minor omissions like error handling and explicit overwrite behavior prevent a perfect score, but the overall completeness is strong.

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?

The schema has 0% description coverage, but the description's @param annotations thoroughly explain every parameter: input format and order for input_paths, destination for output_path, the condition for reencode, default codecs, and the response mode. This fully compensates for the schema's lack of descriptions.

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 starts with 'Concatenate multiple video clips in sequence using the ffmpeg concat demuxer,' which states a specific verb, resource, and method. This clearly distinguishes it from sibling tools like ffmpeg__split_video or ffmpeg__add_fade, which have different operations.

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 provides a clear usage condition: 'Use reencode=true when clips have different codecs or parameters.' It also explains the input path format and output behavior. While it does not explicitly name alternatives or exclusions, the context makes the tool's purpose and when to use it clear, warranting a 4.

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