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

Annotations declare the mutation/destructive/openWorld profile, and the description goes well beyond them: it discloses that team credits are spent, that the price is whatever get_video lists in after_steps (with a separate voiced price for voiced languages), that it is refunded on failure, and that it is a fire-and-poll async operation returning an id. That is exactly the context an agent needs before committing credits.

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?

Compact at three sentences with the action front-loaded and no filler. The prose is somewhat convoluted ('its voiced price for a voiced language'), but every sentence carries a distinct, useful fact about cost, constraints, or follow-up.

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 an async, no-output-schema tool this covers the essentials: what it returns (an id), how to track it (get_video polling), the credit/refund model, and the language constraint. The only real gap is the missing explicit differentiation from change_video.

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 100%, so the baseline is 3, but the description adds real semantics: 'credits' must equal the listed price or be refused, 'language' must be one after_steps offers, and idempotency_key makes a repeat call return the first answer without further spend. That is more than the structured fields convey on their own.

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 concrete verb and resource: 'Make one finished video again in another language, its own script and presenter, into a new video beside it.' The 'new video beside it' phrasing cleanly separates it from an in-place edit, but it never names the sibling it is closest to (change_video), so an agent must infer the boundary.

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?

It constrains the language to one 'after_steps lists for it' and explains the post-call workflow (poll get_video about once a minute until ready or failed), which is genuine operational guidance. However, it never says when to choose this over the sibling change_video, so usage selection is only implied.

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