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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the real burden and does so richly: per-1,000-character pricing with a 1-cent floor, charging gated on confirm_cents matching the quote, idempotency keyed on (token, tool, key) rather than arguments so a reused key with different args returns the first result, and refunds on failure that still consume the daily limit until midnight UTC. None of that is inferable from the schema or 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?

The Args/Returns structure is easy to scan and the monetary constraint is front-loaded, but the opening sentence packs the price rule and the action into one clause, slightly obscuring the core purpose. Density is justified here since every clause carries an operational 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?

For a paid, non-idempotent-by-arguments generation tool with no output schema, the description supplies the return shape ({ok, job_id, kind, poll_after_s, cents}), the follow-up tool (wait_for_job, with audio_url on the finished job), and the failure/refund consequence. Nothing an agent needs to call this safely is absent.

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?

With 50% schema description coverage, the description compensates by annotating all six parameters beyond the schema: text length bounds, voice sourced from list_voices, model optional plus the Premium-voice/English constraint, confirm_cents as the agreed quote with 0 for quote_only, idempotency_key uniqueness and replay semantics, and quote_only as a price-only mode. The idempotency explanation in particular adds meaning the schema does not.

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 specific action ("starts one narration of the text") on a specific resource, and the cost framing plus the list_voices/list_models prerequisites make it unambiguous that this is a paid text-to-speech render rather than an image, music, or clip generation call. It does not explicitly name a sibling it is not, so it falls just short of 5.

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 a clear operating context: voice comes from list_voices, model is optional and required for Premium voices, confirm_cents comes from tool_cost_estimate, and quote_only=true is an explicit no-purchase alternative mode. What is missing is any statement of when not to use it (e.g. unrelated text, non-English with Premium voices is only mentioned in passing under model).

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