generate_video

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

Adds real context beyond the annotations: the paid/business switch requirement, the clarification that budgets are local quote checks rather than backend hard caps, and an explicit retry policy. This goes meaningfully further than the provided hints (idempotentHint, destructiveHint) and helps an agent avoid unsafe retries.

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?

Three tight sentences, front-loaded with the core action, then prerequisites, then caveats. Dense but each clause carries information; the telegraphic phrasing ('paid and business switches') is slightly terse but not wasteful.

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 mutation tool with no output schema, the description covers prerequisites and retry safety but omits what a successful submission returns (e.g., a task id to poll via get_video_task/preview_video_task) and how to satisfy or verify the required 'switches'. These gaps matter given the async-looking sibling set.

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 only 33% (only request_id is documented). The description partially compensates by explaining that request_id must be stable and that budget applies 'for every quoted resource' and acts as a local quote check, but it says nothing about quote_id's origin or how the nested credits/video_units/music_credits fields are interpreted.

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?

States a specific verb and resource ('Submit one quoted video generation') and the word 'quoted' distinguishes it from the sibling estimate_video_cost, implying a quote must already exist. It does not explicitly name sibling alternatives, but the action and domain are unambiguous.

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?

Gives prerequisites (paid/business switches, quote_id, request_id, budgets) and a retry rule ('Never automatically retry uncertain submission'), which is useful operational guidance. However, it never states when to prefer this over estimate_video_cost or preview_video_task, nor the quote-then-submit workflow, so the routing is only implied.

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