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

With no annotations, the description carries the full load and does so: auth requirement (Editor role), side effects (result added as a new video labelled '<label> (edited)' or replaces the original with replace:true), a domain event (video.updated), hard limits (10 minutes, 1920px), and the timeline convention (all times in the ORIGINAL video's timeline).

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?

Although dense, the purpose is front-loaded in the first sentence and every subsequent clause adds operational value: parameter semantics with worked examples, timeline convention, result naming, limits, and the verification step. No sentence is filler.

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 14-parameter, no-output-schema mutation tool this is complete: it explains what each mode does, what happens to the output artifact, what the reply's summary contains, the permission required, and the operational limits. Nothing an agent needs to invoke it correctly is missing.

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 and the schema already documents all 14 parameters. The description still adds real meaning beyond the schema: interval semantics ('take ranges OUT and keep everything else' vs 'keep ONLY one span and drop the rest'), 'give one to keep the shape' for width/height, and the fallback behavior implied by passing or omitting label.

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 ('Make a new version of a video in a video surface') and enumerates the operations it supports (remove, keep, format, resize, aspect, fps, speed, mute). It distinguishes itself from watch_video by assigning that tool the time-finding role, but it never explicitly contrasts with the similarly named siblings update_video or add_video, so routing against those is left to inference.

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 when/when-not and alternatives: use watch_video first to find exact start/end, use keep when you want only one span, use remove when you want to cut ranges out, and check the returned summary against the request. It also closes the loop with 'Watch the result with watch_video before telling anyone it's done.'

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