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

With no annotations supplied, the description carries the full burden and does so: it discloses the hard limit of 3 calls per video, which changes consume minutes (re-voice uses avatar minutes, custom voices use Voice Pack minutes) versus re-recording narration which does not, the length constraint from the plan, and that the operation is slow with a follow-up via check_video. These are exactly the cost and latency traits an agent cannot infer from structured fields.

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-loaded with the core action and the batching rule first, then costs, then alternatives and follow-up, which is the right order. It is dense to the point of being packed — the voice/cost paragraph could be split more cleanly — but nearly every clause carries operational information.

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 9-parameter mutation tool with no annotations and no output schema, the description covers the missing pieces: quota, minute consumption, latency, confirmation flow, sibling alternatives, and how to retrieve the result. An agent has everything needed to call it safely and correctly.

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 89%, so baseline is 3, but the description adds real meaning above it: narration is 'changed lines only' with unlisted scenes keeping their words, the plan-imposed length ceiling, why pictures_changed matters ('so a re-render is never used for nothing'), and the two-call meaning of confirm_avatar_time. It stops short of explaining voice/subtitle_style values beyond what the schema already documents.

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 ('Re-render a finished video with the user's edits') plus the exact scope of updatable elements: narration lines, voice, caption style, motion, grain, whiteboard hand, and scene pictures. It explicitly names the two sibling tools it is not (edit_podcast for podcasts, update_3d_film for 3D films), so an agent can route correctly without opening schemas.

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 batching guidance ('gather every change first and call once') tied to a concrete constraint (one of 3 re-renders per call), plus a multi-step protocol for presenter videos requiring confirm_avatar_time after the first call. It also names alternatives by case: edit_podcast for podcasts, update_3d_film for 3D films, and regenerate_scene_image/set_scene_image as the upstream tools that produce pictures_changed.

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