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

No annotations are supplied, so the description carries the full burden and it does disclose a lot: per-second credit cost charged to the project owner, that the first take fills the timeline clip while later takes wait for select_take, and that edit mode mutates the first clip in place. It does not say whether generation is asynchronous or how progress is polled (generation.status exists as a sibling), nor anything about failures or limits, which matters for a costly mutation with zero annotation coverage.

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-loads the purpose in the first clause and every following sentence adds distinct information (model paths, edit mode, cost, take ordering). Sentences are dense and run long, so an agent must parse carefully, but there is no filler.

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 credit-costing mutation with no annotations and no output schema, the description covers cost, sequencing, side effects on the timeline clip, and model selection branches. It still leaves the return shape (take identifier) and asynchronous status handling unstated, which an agent would need in order to use it end to end.

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 0%, so the description must compensate. It effectively explains the `model` parameter by naming image_to_video and reference_to_video families and their behavioral differences, including referenceVideoMode edit, but projectId and shotId get no added meaning beyond the prose context that the shot is the target and the project owner is billed.

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 ('Generate a video take for a shot') plus the inputs it draws from (camera movement, action, cast), which clearly separates it from siblings like shot.generate_keyframe and shot.select_take.

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 explicit routing: run shot.generate_keyframe first for image_to_video models, no start frame is needed for reference_to_video models that follow referenceVideoAssetIds set via shot.update, and later takes are resolved with shot.select_take. The alternative paths and their preconditions are all named.

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