normalize

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

With no annotations provided, the description carries the full behavioral burden. It clearly discloses that normalization can boost or reduce audio, gives a concrete dB example, and warns about potentially blowing out the audio. It could go further by stating whether the operation is destructive or undoable, but the risk warning and dB behavior are strongly transparent.

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 description is longer than average but every section earns its place: one-line function summary, a high-signal warning, actionable target-level guidelines, and parameter details. It is well-structured with bullets and labels, and the most important risk is front-loaded immediately after the summary.

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 3-parameter tool with no annotations and no output schema, the description covers operation, risks, preconditions, parameter semantics, and recommended values. It is missing only minor edge-case context such as what happens if no audio is selected or whether the change can be reverted, but it is otherwise complete for safe and correct invocation.

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_description_coverage is 0%, so the description must fully compensate for the input schema's bare type/default info. It thoroughly explains each parameter: peak_level_db with range, default, and target-selection guidance; remove_dc with its function; and stereo_independent with its purpose. This is excellent parameter documentation beyond the schema.

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 description uses a specific verb+resource pair: 'Normalize the selected audio to a target peak level.' This immediately distinguishes it from related sibling tools like effect_amplify and loudness_normalize by emphasizing peak-level normalization rather than arbitrary gain or loudness matching.

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?

The description provides explicit target-selection guidelines based on what processing comes next, and tells the agent to check current audio levels with project_get_info before normalizing. It includes a clear when-not case ('-1 dB only on already-mastered audio, never on raw audio'), though it does not name alternative sibling tools for comparison.

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