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

Beyond the annotations (idempotent, non-destructive, non-read-only), the description discloses real behavioral traits: the ceiling caps sample peaks in dBFS, true inter-sample peaks can exceed it on dense bright material, and qa.check measures that in dBTP. It also explains that inline previews carry measured loudness while link previews do not — useful context that is not derivable from structured fields.

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?

The purpose is front-loaded in the first clause and every subsequent sentence carries distinct information (peak caveat, measurement pointer, preview caveat, return pointer). Some phrasing is terse to the point of being cryptic ("Audio edits with preview inline carry the measured loudness").

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 deferring return values to the server instructions is acceptable, and the peak/loudness caveats cover the non-obvious failure modes of mastering. Only the relationship to sibling gain tools is left unaddressed.

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 75%, so the schema already documents limit_db and the preview enum. The description still adds meaning: it clarifies gain is in dB and that the ceiling applies to sample peaks rather than true peaks, and links preview mode to loudness reporting, which the enum description does not cover.

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?

"Gain (dB) and limiter ceiling on the whole mix" gives a specific resource and scope (the master mix), which implicitly distinguishes it from the per-clip audio.set_gain sibling. It never names that sibling, so the differentiation is inferred rather than stated.

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?

Scope ("whole mix") implies when to use this over clip-level gain tools, and the qa.check mention hints at a verification workflow, but there is no explicit when-to-use / when-not-to-use statement or named alternative. The agent must infer routing from the word "master".

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