Generate voiceover

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

Annotations only provide flags (readOnlyHint=false, etc.), which are neutral. The description goes far beyond by disclosing: cost implications ('Paid (a couple of credits by length; ≤900 characters)'), refusal behavior ('a name that engine does not have is REFUSED for free with its real list'), and the fact that some engines generate their own voice and ignore presets, with the reply indicating which voice actually spoke. This adds rich behavioral context beyond the annotations.

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?

Though the description is long, every sentence carries actionable information. It leads with the core purpose and output, then defines scope exclusions, then details parameters, then covers edge cases and cost. There is no fluff, and the structure flows naturally from what to when to how. The density is appropriate for the tool's complexity.

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?

With no output schema, the description must convey the return value, which it does ('return the served MP3 URL'). It covers parameter semantics, defaults, refusals, cost, and character limits. It also references a sibling tool (hermoso_capabilities) for authoritative voice lists. An agent has everything needed to call this tool correctly in all scenarios.

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%, meaning all parameters are described in the schema. The description adds substantial meaning: engine defaults and valid values (seed-audio default, plus others), the relationship between engine and voice presets (preset must belong to engine), and directs the agent to hermoso_capabilities for the full voice list. It also clarifies the character limit and cost model. This goes well beyond the schema's basic field descriptions.

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 clear, specific purpose: 'RAW text-to-speech from the voice-model catalog: speak a script in a chosen voice and return the served MP3 URL.' It defines the resource (voice-model catalog), the action (speak a script), and the output (MP3 URL). It also explicitly distinguishes itself from sibling tools (render_ad, generate_video, change_voice) by stating what it is NOT for, leaving no ambiguity about its role.

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?

Usage guidance is explicit: 'For a standalone voiceover / narration clip — NOT for adding audio to a video (render_ad and generate_video voice their own spots; change_voice re-voices a finished clip).' It also describes the engine choices with a default, mentions voice preset behavior, handles edge cases (engines that ignore presets and generate their own voice), and notes the character limit. This gives an agent clear conditions for when to use this tool versus alternatives.

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