Voice Help

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

No annotations are provided, so the description must carry the behavioral load, and it does add real substance: it discloses the specific content returned, the velocity range probed (0.2 to 1.0), and the unit and reference for level (dB against 1.0). It does not state whether the probe is expensive/slow or that the operation is read-only, which keeps it short of a 5.

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?

It is a single front-loaded sentence that leads with scope and then enumerates content, with no filler. The parenthetical about the velocity probe is dense but earns its place; the phrasing is slightly more prose-like than necessary.

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 return values need not be explained and the description's content enumeration is a bonus. However, with two undocumented parameters and no annotations, the definition leaves an agent unable to confidently supply arguments or predict whether the call performs measurement work.

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% for both parameters, so the description must compensate and does not: 'name' and 'project' are never mentioned, and 'one voice module' only loosely implies that name selects the voice. An agent must guess whether name is a voice id, preset name, or display name, and what project scopes.

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 says it returns 'everything about one voice module' and enumerates the content categories (provenance, velocity behavior, functions, parameters, level per velocity), which gives a sense of the resource. But it never states the verb precisely (does it return documentation, or measure/probe the voice?) and doesn't distinguish it from siblings like instrument_help, voices_list, or instrument_show.

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?

There is no guidance on when to call this versus instrument_help, voices_list, instrument_show, or fx_help, all of which sit in the same conceptual space. The only implied use is the closing hint about balance changes ('so a balance change is one step'), which is a benefit statement rather than a selection rule.

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