clip_trim

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

With no annotations, the description carries the full disclosure burden, and it does add meaningful behavior: it re-encodes rather than stream-copies and uses seconds as the time unit. However, it leaves critical traits undisclosed — whether the operation is destructive, whether it is synchronous or asynchronous, and the fact that re-encoding is compute-intensive.

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?

Five words with the verb front-loaded and zero filler — every token earns its place. It is efficient, though the parenthetical '(seconds)' is overburdened with conveying the time unit for all temporal parameters.

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 mutation tool with no annotations, no output schema, and 0% schema coverage, this is thin. An agent cannot tell whether the re-encode runs synchronously, what it returns, or whether the original clip is altered, and it barely glosses the meaning of the required `input` parameter.

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 must compensate, but it adds only the '(seconds)' unit hint. It never clarifies what `input` refers to (file path vs. media ID) or that `duration` defines a trim-to-length rather than an end time, even though duration is the sole required length parameter.

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 ('Trim') and resource (a clip) with a distinguishing method ('frame-accurate re-encoding'), which separates it from naive cuts and sibling operations like clip_concat, clip_speed, and clip_crop. It does not name a sibling explicitly, so it falls just short of full differentiation.

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?

No when-to-use guidance or alternatives are provided. The qualifier 'frame-accurate' weakly implies a precision-trimming use case, but there is no exclusion or context routing the agent to, say, clip_concat or a lossless-cut alternative.

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