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

Annotations declare the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false) but say nothing about latency or cost; the description supplies both — the call returns a Job ID immediately with background generation, and it costs roughly 27 credits/second standard and 42 credits/second pro (399 credits for a 15s trend). It also states the 3–30s video constraint, which is behavioral context beyond the annotations.

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?

One dense paragraph, front-loaded with what the tool does before moving to constraints, workflow, and cost. Every sentence carries information, though the workflow/cost tail is long enough that an agent must read to the end for the credit and wait_for_jobs details.

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?

No output schema exists, so the description must explain the return path — and it does: an immediate Job ID, background generation, and retrieval of the Asset ID via wait_for_jobs for patch_film. Combined with input constraints, credit cost, and the long-video workaround, an agent has everything needed to invoke and follow through.

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 100%, so the schema already documents every parameter, including the asset:ID#t= syntax for 'person' and the null semantics for prompt/keepSound/projectId. The description reinforces a few of these (quality tradeoff, trimming for long videos) but adds little the schema does not already say, so the baseline 3 applies.

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 precise verb+resource ('make the person in a picture do what the person in a video does') and immediately scopes the output ('the new video shows the person and the setting of the picture... for the video's whole length'). This is clearly distinguishable from siblings like generate_video, replace_person, or apply_effect.

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 real context: best-case input conditions (one person, full or upper body in view), how to handle longer source videos (download_asset link plus import_asset_url with startSeconds/endSeconds), and the async workflow (start all generations, then wait_for_jobs, then patch_film). It stops short of explicitly naming which sibling to use instead when the source is not a video or when the subject isn't a person, so it isn't a full when/when-not routing guide.

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