audio_batch_process

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

Annotations already establish this is a non-read-only, non-destructive, closed-world write. The description adds real behavioral detail beyond them: same relative output names, refusal to write into the input folder without overwrite=true, and subtype validation happening before any file is written. It stops short of describing partial-failure behavior when one file in a batch fails.

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-loads the core contract (one chain, every file, output naming), then safety, then a compact example, then subtype notes. Dense but every paragraph carries information; the subtype sentence is slightly run-on but still earns its place.

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 6-param mutating tool with no output schema and no schema descriptions, the description covers the essentials: what is processed, where output lands, the overwrite safeguard, and operations format. Gaps remain around pattern/target semantics and per-file error handling, but an agent can invoke it correctly.

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 0%, so the description has to carry the load. It explains subtype (with concrete values), the overwrite safety gate, the operations chain format via example, and output_dir semantics, but leaves target (folder vs list) and pattern interpretation largely implicit, so half the params remain under-specified.

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 scope: apply one operations chain to every file in a folder or list, writing results into output_dir. The batch framing clearly distinguishes it from the sibling audio_process (single-file) and audio_batch_survey (inspection rather than processing).

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?

Makes the when-to-use condition clear through the batch framing and a concrete example (normalize a set of sound effects), and adds a critical usage constraint: it refuses to write into the input folder unless overwrite=true. It does not explicitly name audio_process as the alternative for single files, but the batch/single split is strongly implied.

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