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

Annotations already declare readOnlyHint=false with destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds that the whole property surface is editable in one call, but says nothing about whether omitted properties remain untouched, whether edits are undoable, or what happens when a text property is applied to a non-text clip. For a 19-parameter mutation tool, that is a meaningful gap.

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?

A single front-loaded sentence that scales efficiently to 19 parameters; the enumeration earns its length by telling the agent the whole editable surface up front. No filler, no repetition of the title.

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?

There is no output schema, so the description could usefully say what an update returns, but does not. It also omits the partial-update contract and any preconditions (e.g. text fields requiring a text clip), which matter given 19 parameters with only clipId required and nested objects for crop, transform, filters and text.

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 description coverage is 58%, and the description compensates partly by grouping parameters into recognizable categories (timing, fades, colour filters, text content/style), which helps an agent map intent to fields. However it mostly restates parameter names and omits several parameters entirely (name, label, preset, projectId), and it does not clarify that only the fields supplied are changed.

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?

Specific verb ("Change") plus resource ("clip property") with an explicit enumeration of the mutable surface: timing, speed, volume, opacity, fit, transform, crop, filters, fades, text, track. That makes it easy to distinguish from add_clip, duplicate_clip or delete_clips. It stops short of naming near-neighbours such as update_clips (bulk), move_clip, trim_clip or slip_clip, and "move to another track" overlaps with move_clip, leaving a little ambiguity.

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?

Usage is implied rather than stated: the agent can infer this is the tool for editing an existing clip's attributes. There is no explicit when-not guidance, no pointer to update_clips for multi-clip edits, and no hint that move_clip/trim_clip are the dedicated alternatives for track moves or boundary trims.

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