Voices List

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

With no annotations, the description still discloses real behavior: it is an enumeration across three scopes (project folder, configured voices folders, built-ins) covering two distinct entry types (code instruments stored as Python files vs. profiles measured from recordings). It stops short of stating that the call is side-effect free, how results are ordered, or what happens if the folders are empty, but the read-only nature is clear from 'List'.

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?

Two sentences, front-loaded with the resource definition before the source list and the follow-up action. Slightly dense with stacked parentheticals ('(code instruments kept as Python files)', '(instruments measured from recordings)'), but every clause carries information an agent needs.

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 structure needn't be explained, and the description covers what is enumerated, where from, and how to use a result. The remaining gap — what happens with an omitted `project` and whether the output mixes code voices and mimic profiles in one list — is minor for a zero-required-parameter list tool.

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% and the single `project` parameter is undocumented in the schema, so the description must compensate. The phrase 'the song's own (<project>/voices/)' does imply that project selects which project's voices folder is included, but it never states the default behavior when project is omitted (the schema default is null). Partial compensation, not full.

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 the specific verb (List) and both resources (voice modules / mimic profiles), defines each parenthetically, and enumerates the three sources scanned: the song's own <project>/voices/, the voices setting's folders, and built-ins. That is enough to separate it from sibling catalogue tools like presets_list, sound_list and voice_help without opening any schema.

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?

Gives forward guidance: the listed entry is consumed as {"type": "code", "voice": "<name>"} or via its preset, and voice_help(name) is named as the follow-up for velocity mapping, functions and parameters. It does not explicitly say when to prefer presets_list or sound_list instead, so there are no exclusions — clear context but not full when/when-not routing.

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