Give an actor a voice

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

Goes well beyond the annotations: it discloses that the call SPENDS CREDIT, requires the write scope (auth prerequisite), and returns the voice id, a preview clip and the cost. It also explains the persistence side effect that the design is kept on the character for reuse. These are exactly the behavioral facts annotations cannot convey.

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 dense sentences, front-loaded with the credit cost and scope, then the two modes, then the return shape. No filler; every clause carries a distinct fact.

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 an output schema present, return values needn't be enumerated, but the description still summarizes them. Combined with cost, auth scope and the two parameter paths, an agent has everything needed to invoke this destructive, credit-consuming tool correctly.

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 parameter documentation already exists. The description still adds meaning beyond it: consent is framed as the user's own attestation of rights (not just a flag), and description is explained as durable casting direction reused on later runs rather than a throwaway prompt.

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 a specific verb and resource ('gives an actor a voice') and immediately distinguishes the two operating modes: designing a voice from casting direction versus cloning from a sample. An agent can also tell it apart from the read-only sibling characters_list, which is named for the character identifier.

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?

The description clearly routes between the two paths ('description designs one...; sampleMediaKey clones a real voice and requires consent: true'), which is genuine when-to-use guidance. It stops short of stating when not to use the tool or naming a sibling alternative for voice work, so it is clear context but not full exclusion guidance.

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