audio_effects

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

With no annotations, the description carries the full burden. It does disclose the WAV-only format constraint and the return shape (success flag + output_path), which is real value. However, it says nothing about what happens when output_path already exists, that overwriting is gated behind a separate flag, or how partial/effect failures are reported (all-or-nothing vs. best effort).

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 action and resource, then parameters, then return value. The Google-style Args/Returns scaffolding is slightly verbose given an output schema already exists, but no sentence is wasted.

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, so the Returns block is redundant rather than necessary. For a write-producing tool with zero annotations, the description is not quite complete: overwrite semantics, error behavior, and the concrete set of supported effect types and their parameters remain unstated, which matters because the effects array accepts arbitrary objects.

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 coverage is only 25%, so the description must compensate, and it largely does: it specifies that input_path/output_path are absolute paths and that input must be WAV, and it sketches the effects list structure with a type discriminator plus per-type extra params. The main gap is the undocumented `overwrite` parameter, which the description never mentions (only the schema covers it), and the open-ended 'additional params per effect type' leaves effect options underspecified.

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?

The first sentence gives a specific verb+resource (apply an effects chain to a WAV file) and the second clarifies the chain concept with examples (reverb, filtering, normalization). It is clearly distinguishable from neighbors such as video_normalize_audio or audio_preset, though it never names or contrasts those siblings explicitly.

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 only implied: the reader infers you use this when you want multiple audio effects applied in one pass to a WAV file. There is no statement of when NOT to use it, no mention of alternatives (e.g. video_normalize_audio for a single normalize pass), and no prerequisites such as supported sample rates or channel layouts.

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