Generate video (SPENDS CREDITS)

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

Adds significant context beyond annotations: real credit spending, cost rejection mechanism, mode switching effect on prompt, warning against duplicate charges, and setting reminders. No contradiction with annotations (destructiveHint=true is consistent).

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 thorough but not overly verbose; every sentence serves a purpose. It could be slightly more streamlined, but the complexity (multiple modes, cost logic) justifies the length.

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?

Covers creation logic, cost, mode selection, duplicate handling, and directs settings elsewhere. Lacks explicit return value description, but the mention of 'Collect later with flow_collect' implies asynchronous return. No output schema exists, so this is acceptable.

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 coverage is high (88%), but the description enriches understanding by explaining how parameters interact (e.g., start_frame vs reference_media_ids switch modes and change prompt semantics), clarifies expected_max_cost role, and details no_wait usage for parallel batches. Adds meaningful value beyond schema 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 clearly states 'Generate a video clip in Flow' and distinguishes three modes (Frames-to-Video, Ingredients-to-Video, Text-to-Video) based on which parameters are attached. It also suggests composing stills first, effectively differentiating from sibling tools like flow_generate_still.

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?

Explicitly tells when to use (generating video with cost checking against expected_max_cost and budget) and when not to (avoid duplicate calls, set model tier and aspect ratio via flow_settings, not here). Recommends an alternative workflow: compose in stills first then animate.

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