flow_assemble

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

With no annotations, the description carries the full behavioral burden and does a solid job: it discloses local processing with no API cost, per-shot trim application, retention of each clip's own audio, and music looping/fade-out during mixing. It omits the side effects that matter most for a write-ish operation — where the finished film is written, whether it overwrites an existing one, and what happens if a shot has no selected take.

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?

Front-loaded: the operation, its mechanism, and its cost profile appear before any parameter detail, so an agent scanning the first line gets the essentials. The Args block is compact and every line carries meaning, though the paragraph on trims/audio/music is slightly list-like and could be tightened.

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 a six-parameter, side-effecting tool with no annotations and no output schema, the definition explains inputs and mixing behavior but never states the result — output path, file naming, return payload, or failure modes when shot media is missing. That gap matters precisely because no output schema exists to fill it.

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%, and the Args block compensates fully, covering all six parameters with defaults and meaning: shots as playback order, the boolean toggles, music_volume as 0-1 with the rationale 'default 0.25 so it sits under dialogue', clip_volume with '0 mutes it', and project_name defaulting to the active project. This adds intent that the bare schema titles do not convey.

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 first sentence gives a concrete verb and resource — 'Join the selected take of each shot into one film' — plus the distinguishing property that it runs locally via ffmpeg at no API cost. It stops short of naming a sibling such as flow_storyboard_render or flow_storyboard_plan, so an agent must infer which assembly step this is.

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 (this is the final assembly step) and the default for `shots` tells the agent it can be called with no arguments at all. There is no explicit when-to-use vs. when-not guidance, no prerequisite stating that shots must already have selected takes/renders, and no mention of when to prefer a different tool.

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