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

Adds substantial context beyond the annotations: it renders immediately, spends credits at roughly one per second of audio, points to estimate_cost for the ceiling, warns that omitting reference photos makes the system invent a person, and explains that reusing idempotency_key within 24h returns the first result instead of charging again. The opt-in idempotency note complements rather than contradicts idempotentHint=false, and the credit-spend warning aligns with destructiveHint=true.

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 core capability and its constraints come first, followed by the key-wiring instructions and then the cost/idempotency caveats. It is dense but every clause carries actionable information, with no restatement of the title or the schema.

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 10-parameter, credit-spending, irreversible render with no output schema, the description covers the audio and image sourcing chain, the cost model, the idempotency escape hatch, and the failure mode of missing references. Nothing an agent needs in order to call this correctly is absent.

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 baseline is 3; the description goes further by naming where each key comes from (upload_audio, get_audio_upload_page, get_reference_upload_page) and clarifying that topic only controls look/setting while spoken words always come from the recording. It leaves product_id, video_type and aspect_ratio entirely to the schema.

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 plus the exact scope: one scene, length matched to the recording (max 60s), lip-synced in the recording's own voice and language. This clearly distinguishes it from the sibling create_video (which writes a script) without the agent needing to open either schema.

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 concrete conditions and prerequisites: pass the recording via audio_key (from upload_audio / get_audio_upload_url) or audio_upload_id (from get_audio_upload_page), and photos via reference_image_keys / reference_upload_id, with an explicit 'strongly recommended' caveat. It does not explicitly state when to prefer the sibling create_video instead (i.e. when there is no recording), which is the only missing routing cue.

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