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

Beyond the annotations (which only mark it as non-read-only, open-world, non-idempotent, non-destructive), the description discloses pricing (127 credits/second baseline), two separate billing wallets by auth method, and a quote-before-charge confirmation flow — genuinely valuable behavior. The weakness is the phrase 'Omit approval', which does not correspond to any parameter name, leaving the agent to work out that approval means omitting max_credits/max_usd.

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?

Three compact sentences: capability first, billing second, confirmation procedure last — well front-loaded with no filler. The only friction is the undefined term 'approval', which forces a reread against the schema to map onto concrete fields.

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 7-parameter mutation tool with no output schema, the description covers cost, auth branching, and input clip length well. It never says what a call returns — a job id, a quote object with cost_usd, or a finished asset — even though the quote flow depends on the agent reading cost_usd from that response, which is a meaningful gap for correct multi-step invocation.

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; the description earns slightly more by tying parameters to a workflow (quote first, then confirm max_credits or max_usd) and by supplying the per-second pricing that has no schema equivalent. It does not explain model selection or reference_image_urls beyond what the schema already says, so the added meaning is real but partial.

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?

The description uses a specific verb and resource ('Change a short video with words') and enumerates the editable dimensions (subject, outfit, setting, style, weather) while constraining behavior ('keeping the motion'). That scope implicitly separates it from siblings like change_camera_angle, copy_motion, and extend_video, but it never names an alternative, so an agent must still infer the boundary itself.

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 clearly explains the two-step usage pattern: call without approval to obtain a quote, then re-call with max_credits (OAuth) or currency USD plus max_usd (API keys) to confirm. It also branches guidance by auth type. It stops short of saying when to prefer this tool over edit_image or the other video siblings, so the routing guidance is contextual rather than explicit.

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