AI operations (transcription, scene detect, upscale, verdicts, quality)

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

Annotations already declare destructiveHint=true, openWorldHint=true, non-idempotent and non-read-only, so the safety burden is partly carried elsewhere; the description adds the two-step discovery protocol that is genuinely useful for a polymorphic dispatcher. It does not, however, mention that some operations mutate or delete media, nor does it warn about cost/latency or that operations are not idempotent.

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 sentences, front-loaded with the core action and with zero filler. The phrase "Required arguments: list_operations" is slightly telegraphic and could be misread as declaring list_operations a required argument rather than a tool to consult.

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 15-way polymorphic dispatcher with an output schema present, pointing at describe_operation covers argument detail reasonably well. Still missing is any statement about destructive side effects, failure modes, or how per-operation results differ, which matters given destructiveHint=true.

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 67% schema coverage and 15 enum values, the description adds real meaning: params is an untyped bag whose per-operation keys must be discovered via list_operations, and full argument schemas live in describe_operation. That is information the schema cannot convey, though it does not explain the overwrite flag's effect on destructive operations.

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: "Run one AI operation by name" with args in params, and the title enumerates the operation families (transcription, scene detect, upscale, verdicts, quality). It reads as a generic dispatcher, which separates it from concrete siblings like video_trim or video_merge, though it never explicitly contrasts itself with video_edit_ops or video_qc_ops.

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 a useful procedural directive — check list_operations for required arguments and describe_operation for the full schema — which tells the agent to research before calling. However, it offers no when-to-use/when-not-to-use guidance relative to the many sibling op-group tools, so an agent cannot tell from this text whether a given task belongs here or in video_effects_ops.

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