Effect operations (filters, transitions, glitch, motion graphics)

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds the discovery workflow but says nothing about the consequences of a destructive run or how `overwrite` interacts with that, which would be valuable context for a destructive dispatcher.

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?

Two short clauses, fully front-loaded, with no filler. The terseness costs a little clarity in the "Required arguments: list_operations" fragment, which could be read two ways.

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?

With an output schema present and annotations covering safety, the description's main obligation is telling the agent how to resolve the opaque operation enum and params object, which it does via list_operations and describe_operation. Minor gaps remain around the overwrite flag's effect and which operation families exist.

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?

The clause "params holds its arguments" usefully signals that the payload is per-operation and must be looked up via describe_operation, which the schema's open object cannot convey. However, the phrasing "Required arguments: list_operations" is ambiguous shorthand that reads as if list_operations were an argument, and the 28-value enum gets no explanation of categories.

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?

"Run one effect operation by name" gives a specific verb plus a specific resource, and the enum of 28 effect/glitch/transition/layout operations backs that up. It does not differentiate itself from siblings like video_edit_ops or video_mograph_* beyond the generic "effect operation" framing, so it stops short of a 5.

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?

It explicitly routes the agent: use list_operations to discover required arguments and describe_operation for the full schema. That is clear, actionable chaining guidance. It does not state when to avoid this tool (for example, in favor of video_edit_ops), so it is a 4 rather than a 5.

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