flow_storyboard_keyframes

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

With no annotations supplied, the description carries the whole burden and does a lot: per-unit cost, the model tiers, the default skip-existing behavior, and what redo overwrites. It also discloses the return artifact (a contact sheet image). Gaps remain on execution behavior such as runtime/async handling, failure on individual shots, and any permission or project-access constraints.

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 purpose sentence is front-loaded, followed by the single most decision-relevant fact (cost and ordering before video), then a compact Args list. No filler sentences; every line informs either selection or invocation.

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 five-parameter, no-annotation, no-output-schema tool, the definition covers purpose, cost tradeoff, all parameters with their value sets, and the return artifact. What is missing is contextual scaffolding around shot identifiers and partial-failure behavior, which matters because shots are the primary input.

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 documents all five parameters in an Args block. Crucially it supplies enum values the schema lacks entirely ('fast'/'pro'/'lite' for model, '1K'/'2K' for image_size) and clarifies that shots defaults to shots lacking a keyframe. It does not say where shot numbers come from (presumably the planning tool), leaving a small interpretive step.

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?

"Generate one still image (keyframe) per shot and return a contact sheet" is a specific verb, resource, cardinality (per shot) and return artifact. It is clearly distinguishable from single-image siblings like flow_generate_image and from the downstream flow_storyboard_render, since the description frames keyframes as the first frame of each video.

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?

It gives an explicit workflow rule: fix the look here before paying for video, because keyframes are cheap (~$0.03) and become the first frame. The default behavior (skip shots that already have a keyframe) further encodes when this is the right call. It stops short of naming a specific alternative tool for the video step, so it is clear context rather than full when/when-not routing.

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