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

Goes well beyond the annotations: discloses that the clip's video is replaced by the new render, that the prior version survives in undo history, that it costs no Horizon Units, that unsupported options are refused by name before any change, and that it returns a job_id requiring async polling. The only reason it is not a 5 is that it never states whether the video replacement is permanent outside the undo window or how long the render/poll cycle typically takes.

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-loads the when-to-use trigger, then parameter semantics, then exclusions, then async/return behavior — a sensible order with no filler sentences. It is nonetheless a single dense block covering 18 parameters, which is heavy to parse in one pass but justified by the tool's surface area.

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 destructive, non-idempotent, 18-parameter mutation tool, the definition covers triggering, per-parameter vocabulary, exclusions, mutation side effects, cost, error behavior, and the post-call workflow (job_status, then preview_frame or get_download_link). With an output schema present it correctly avoids describing return payload shape.

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 0%, so the description carries the full burden, and it largely does: it enumerates caption_size values (small/medium/large/x-large or 10-100), caption_position, music genres plus 'off', music_volume tiers, layout modes, hook_title 'off', and ties remove_silences to min_pause_seconds with its 0.6 default. Only minor gaps remain (caption_animation is given as a truncated list, trim seconds have no stated units bound), which is acceptable for 18 parameters.

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 ('an everyday change to a clip they already have') and anchors it with concrete user-intent examples ('cut the silences', 'remove the ums', 'trim the start'). It also names the sibling tools that handle the adjacent jobs (style_clip, add_to_clip, translate_captions, find_clips), so an agent can route 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?

Explicit positive case (everyday edits to an existing clip), an explicit 'Not for:' exclusion list mapping each excluded intent to the correct alternative, and a rule of thumb ('Set only what was asked'). This is about as close to a routing table as a description gets.

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