Audio operations (mix, synthesize, presets, sound pipeline, QC)

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is known. The description adds nothing about what those destructive operations touch, what the overwrite flag replaces, whether per-operation risk differs, or whether any operation is safe to retry — for a 17-operation destructive dispatcher 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?

Two short sentences with the core verb front-loaded and zero padding. However, "Required arguments: list_operations" is ambiguously phrased — it can be misread as list_operations being an argument of this tool rather than a tool to call first, which forces the reader to re-parse a very short string.

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?

An output schema exists and the 17 operations are enumerated in the schema, so return values and operation names need not be repeated. What is missing is behavioral differentiation across operations and any hint that describe_operation should be consulted per operation before a destructive call; the pointer is there but the description does not establish the workflow as mandatory.

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, the description's main contribution is explaining that params carries the chosen operation's arguments and routing the agent to describe_operation for the real shape — useful for an open-ended catch-all object. It says nothing about the overwrite flag's effect or about which operations require which params, so it neither compensates fully nor is redundant.

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 audio operation by name" gives a specific verb and resource, and the definition makes clear this is a name-dispatched multiplexer rather than a single fixed action. It does not summarize what the 17 enumerated operations actually do, but an agent can distinguish it from list_operations and describe_operation, which are cited for discovery.

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 implies a two-step workflow by pointing to list_operations for required arguments and describe_operation for the full schema, which is genuine procedural guidance. It gives no guidance on when to prefer this dispatcher over siblings such as video_add_audio, video_qc_ops, or platform_ops, and no exclusions or preconditions.

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