Create a TTS clip asynchronously

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

The annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) already set the safety profile. The description adds valuable context by stating the return value is a raw job record and that the render is asynchronous, which goes beyond the annotations without contradicting them.

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 with all content earning its place. The action, usage context, polling step, and return type are efficiently packed. No verbosity or repetition.

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 job-starting tool with no output schema, the description explains the async behavior, return status, and next-step polling. It lacks parameter details and potential side effects, but given the annotations and schema, it is reasonably complete. Could be improved by mentioning model/library_ids options.

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 only 50% (text and speaker_id have descriptions; model and library_ids do not). The description does not mention any parameters or compensate for the undocumented ones, leaving library_ids completely unexplained. This is a clear gap.

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 clearly states the tool starts an asynchronous TTS render and returns the clip id/status. It is distinct from synchronous generation, though it does not explicitly contrast with wellsaid_generate_speech. The verb 'start' and 'asynchronous' make the purpose specific.

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 says to use it for long or batched jobs and instructs polling with wellsaid_get_clip. This provides clear context and an alternative, though it does not explicitly say when not to use it (e.g., for short jobs), so it falls short of a full 5.

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