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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: 'move' changes render order ("the order IS the render order"), 'set' values are clamped to each effect's ranges, 'add' returns the new effect's id, and an empty `resource` clears a LUT. It stops short of saying whether removals are undoable or what happens to indices after a remove.

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-loaded with the core purpose and no filler sentences — every clause carries a spec detail. However, it is a single dense run-on paragraph of semicolon-chained clauses, which makes the per-action contracts harder to scan than a short list would.

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 13-parameter, non-idempotent mutation tool with no output schema, the description covers action semantics, effect-type specs, and even the one return value ('add' returns the new effect's id). Remaining gaps are failure behavior (invalid effectId, out-of-range clamping outcome) and undo/irreversibility, which the destructiveHint alone does not fully convey.

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?

With 100% schema coverage the baseline is 3, but this description goes well past the schema by giving value ranges (temperature/tint −100..100, exposure −5..5 stops, saturation 0..300) and neutral values (lift/gamma 0, gain 1, offset 25 printer points; curve identity [0,0,1,1]). It also maps parameters to actions and explains that points are flat control points in the unit square, which the schema only hints at.

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 ("Edits a clip's effect stack") and immediately enumerates the six supported actions and the effect types they operate on. It also explicitly names the sibling it is not — set_clip_properties motionBlur — so an agent can distinguish the two without opening either schema.

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?

Each action is paired with the parameters it requires (add → type; remove → effectId; move → effectId + toIndex; toggle → effectId + enabled; set → params patch; curve → curve + points), which is actionable routing guidance. The one genuinely confusable case is called out explicitly with a when-to-use-this-instead rule: "For blur that follows the clip's own keyframed movement, use set_clip_properties motionBlur instead."

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