Analyze Voice Heard

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

With no annotations, the description carries the full burden and does it well: it discloses the hidden prerequisite that it reads the last render(stems=True), defines exactly what counts as 'the rest' (other track stems to master plus bus stems, bus counted without the voice), specifies the frame gate (within 30 dB of the voice's loudest), and names the band split. It also bounds expectations by stating no speech server or transcription is assumed.

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 question, the trigger, the data source, the computation, and the verdict arrive in a logical order with little redundancy. It is dense but nearly every clause supplies operative detail; the closing 'Built in a song and proven there' is the one line that does not directly help an agent call it.

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 verdict format need not be restated, and the description correctly stops at describing inputs and computation. The render(stems=True) prerequisite is covered. Remaining gap is edge behavior: what happens when no stems render is present, and the unstated meaning of 'project'.

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 must carry parameter meaning, and it only partly does: bars is explained as an inclusive [a, b] range, and voice is characterized as the voice's track stem. 'project' is never mentioned, and the accepted form of the voice value (track name, stem id, or path) is left ambiguous.

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 states a specific measurement: voice level versus the summed other stems, in per-band dB, ending in a masking verdict. It is clearly distinct from generic siblings like analyze_overview or cmp_bars, though it never names a competitor to sharpen the contrast. 'Is the voice heard over the mix?' front-loads the question but the actual verb+resource is only spelled out in the following sentences.

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 gives concrete trigger conditions ('a narrator under a drop, a vocal fighting a lead') and timing relative to another action ('before asking the person whether they can make out the words'). That is a clear use context. What's missing is a when-not or an explicit alternative (e.g., a generic spectrum/level tool) for cases where stems are unavailable.

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