voices

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

Annotations already flag this as non-read-only, non-destructive, and open-world, and the description is consistent with that (search hits an external library; add mutates the account; set_default mutates state). It adds useful context beyond the annotations: that add persists a voice to the account, that name is required for it, and what to do when the plugin isn't configured. It omits error/rate-limit behavior and what a no-arg call returns.

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?

Three tightly packed sentences with no filler; the listing behavior and returned data are front-loaded, followed by mode mechanics and the setup fallback. The semicolon-chained mode syntax is dense but each clause carries distinct information, so nothing reads as waste.

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 nine-parameter, multi-mode tool with no output schema and no enums, the description covers all four modes, the setup prerequisite, and the required pairing of add with name. It is nearly complete, lacking only the default behavior of a no-argument call and any indication of result shape.

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 100%, so the per-parameter descriptions already carry the basics and a baseline of 3 applies. The description earns above baseline by explaining the mode-to-parameter wiring: that add takes an id drawn from a search result and needs name, and that the qualifier fields (gender, accent, language, age, use_case) only apply with search. That relational context is not present in the schema itself.

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 names the resource (ElevenLabs voices) and states the distinct operations it fronts: listing the account's voices/default/plan/quota, searching the library, adding a voice, and setting a default. Each mode has a concrete verb, so an agent can tell what the tool does. It does not, however, differentiate itself from sibling voice tools like design_voice, clean_voice, or change_voice.

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 per-mode triggers: use search to query the voice library (with the qualifier params), add to save a library result, and set_default to change the default. It also supplies a clear fallback for the not-set-up state ('tell the user to open Plugins › Voices'). It stops short of naming alternatives or exclusions relative to the sibling voice tools.

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