EasyVoice text to speech

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

Goes well beyond the annotations by disclosing hard account limits (3 cloned voices, 5 enrollments/day) and sample limits (10 MB, wav/mp3/m4a, 10–30s single-speaker). Critically, it explains the async contract — returns status 'enrolling' and there is no job to poll — which prevents an agent from wrongly reaching for get_job_status.

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?

Front-loads the verb and resource, then constraints, then the follow-up workflow — a logical order with no filler. It is dense and stacks several parentheticals into one paragraph, which slightly hurts scanability, but essentially every clause carries actionable information.

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 mutating, rate-limited, async tool with an output schema, the description covers prerequisites, input constraints, limits, and the post-call polling path. Return values are partly described anyway (voice_id, status 'enrolling'), leaving nothing an agent needs missing.

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 baseline is 3; the description earns a 4 by adding acceptance constraints the schema does not state, notably the 10–30 second duration window and single-speaker cleanliness, which determine whether enrollment succeeds. The oneOf XOR is restated rather than added, but the format and size guidance is genuinely new.

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 ('Enroll a custom cloned voice from an audio sample') plus the async nature in the first clause. It is unmistakable against siblings like list_voices and text_to_speech, which are named only as downstream consumers.

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?

Explicitly states the gating conditions (Pro or active 7-day pass key), the input requirement (exactly one of audio_base64 or audio_url), and the full workflow after enrollment (poll list_voices, then use in text_to_speech, create_podcast, or the REST endpoint). It effectively tells the agent when this tool applies and what to do next.

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

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

Annotations only declare the mutation profile (readOnly=false, destructive=false, idempotent=false), leaving the description to carry the rest — and it does: async job semantics, Pro-tier auth requirement, hard limits (60 segments, 30,000 combined characters), accepted voice-id provenance, and the job-id return contract.

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?

Four short sentences, each carrying distinct information: what it makes, the auth prerequisite, the hard limits, and the polling handoff. Front-loaded with the core action and free of filler.

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?

Even though an output schema exists, the description still supplies the auth requirement, quantitative limits, and the async job-id/polling contract an agent needs to drive the tool correctly. Nothing material is missing for a 4-parameter, non-nested schema.

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 75% and the description reinforces voice_a/voice_b meaning while adding a constraint absent from the schema: the 30,000-character combined text limit. The format parameter (mp3/wav, default mp3) is left unmentioned, which is the only minor 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?

States a specific verb+resource ('Create a two-host (A/B) podcast episode') plus the execution model ('as an async job'). The two-host A/B framing distinguishes it from single-voice siblings like text_to_speech and generate_long_form without needing to open their schemas.

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?

Gives a clear precondition (Pro subscription key) and an explicit follow-up action ('poll get_job_status'), which is exactly what an agent needs after calling. It does not, however, state when to prefer a sibling such as text_to_speech or generate_long_form instead.

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

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

Annotations only declare the generic write/non-idempotent profile; the description adds substantial behavior beyond them: async job semantics, job-id return, polling flow, progressive part rendering, when audio_url appears, and the auth-tier requirement. It also discloses the voice engine's rejection behavior, which no annotation covers.

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 that front-load the core purpose, scale, and async nature before prerequisites and the follow-up tool. No filler, and each clause carries decision-relevant information.

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?

An output schema exists, yet the description still surfaces the operationally critical return behavior (job id, progressive parts, audio_url on completion) that an agent needs to sequence the get_job_status call correctly. Nothing essential for a correct invocation is missing.

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 schema coverage at 67%, the description supplements the gaps where it matters most, clarifying that input can reach 500,000 characters and that voice must be a Kokoro id (ar_* and voice_* rejected, list_voices for catalog). Tone, pitch, speed, and format remain schema-only, which is acceptable given their inline 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?

States a specific verb (generate) and resource (long-form narration) with a concrete scope cap (up to 500,000 characters ≈ 9 hours), and frames it as an async job. This lets an agent separate it from text_to_speech, create_podcast, and the voice-cloning siblings without opening their schemas.

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?

Gives clear prerequisites (Pro subscription key; Kokoro voices only) and routes the agent to get_job_status for polling. The voice restriction effectively encodes a when-not condition, but it never explicitly contrasts short-form text_to_speech usage, leaving that inference to the agent.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuinely new behavioral context: the result includes an audio URL only on completion, and those links are ephemeral and should be downloaded promptly. That is exactly the kind of non-obvious trait annotations cannot express; it stops short of 5 only because polling cadence/expiry duration is not stated.

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 short sentences, front-loaded with purpose then return behavior then the actionable warning. Every sentence carries information the agent needs; nothing is boilerplate.

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?

An output schema exists, so the description is not obliged to enumerate return fields, yet it flags the one return-value caveat (ephemeral audio links) that matters operationally. For a one-parameter, read-only polling tool, nothing essential is missing.

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% and the single job_id parameter is fully documented in the schema, so the baseline is 3. The description's 'owned by this key' hints at an authorization constraint on the id but adds no format, origin, or validation detail beyond the schema.

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 (check status) and resource (job), and narrows scope to three job families — long-form, podcast, tts — plus ownership ('this key'). That scope maps cleanly onto the async siblings (generate_long_form, create_podcast, text_to_speech), so an agent can tell this is the polling counterpart without opening another schema.

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 is only implied: the phrase 'job ... owned by this key' plus the schema note 'Job id returned by an async tool' tells the agent this follows an async submission. There is no explicit when-to-call (after submit, poll until completed), no when-not-to-call, and no named alternatives or terminal-state guidance.

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

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

Annotations supply only readOnlyHint=true; the description carries the real behavioral load by disclosing free-tier pool size, midnight UTC reset, the 20 req/min rate limit, the 2-concurrent cap, and Pro fair-use throttling thresholds with the notable assurance that usage is never blocked or billed.

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?

Front-loaded with the one-line purpose, then dense supporting detail in two sentences with no filler. Some of the enumerated limits (5,000/day, 10M/30 days, 30 req/min) partly restate what the output schema already returns, so a small amount of space is not strictly earned.

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 zero parameters and an output schema covering the return shape, the description needs only to orient the agent about what the response means. It does that and then some, so nothing needed for correct invocation is missing.

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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly does not invent inputs, though it also makes no statement about how the calling key is identified (implicitly via auth).

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?

"Check this API key's plan and usage" names a specific verb (check) and resource (plan + usage) and is unambiguous against siblings like text_to_speech or clone_voice, which all perform generation rather than introspection.

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 is only implied: an agent can infer it should call this to learn quotas or plan, but the description never states when to call it, when not to, or any alternative (e.g., get_job_status for job progress). No explicit routing guidance is given.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real context: the result is a union of the global 66-voice catalog and this key's cloned voices, and it enumerates the fields carried per voice. It does not mention pagination or result limits, but for a small fixed catalog that is a minor gap.

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, no filler. The scope sentence comes first and the routing instruction second, so the most decision-relevant information is front-loaded.

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?

An output schema exists, so the description need not explain return values, and it already names the key fields. Combined with the explicit call-ordering advice, an agent has everything needed to invoke and place this 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-parameter tool is 4.

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 (list) and resource (voices), and quantifies scope: 66 catalog voices plus the key's cloned voices, with the returned fields enumerated. It is clearly distinguishable from the sibling clone_voice, which mutates rather than lists.

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?

Explicitly says to call this before text_to_speech or create_podcast in order to pick voice ids, giving clear sequencing and naming the downstream tools. It does not state any when-not condition, but for a zero-parameter lookup this is close to complete.

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

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

Goes well beyond the annotations (which only mark it non-read-only, non-idempotent, non-destructive) by disclosing character caps per voice family, automatic queuing instead of erroring, character-per-minute fair-use pacing, the up-to-20-second wait, and the exact error semantics when the wait would exceed that. It also states the return shape (hosted URL, no inline audio), which is real operational context.

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?

Front-loads the purpose in the first clause and then layers constraints in descending importance. It is dense but every clause carries operational meaning; the em-dash chain of limits makes it slightly harder to scan than a bulleted breakdown would be.

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 generation tool with an output schema, the description covers everything the caller needs: entitlement gating, per-voice length limits, overflow behavior, throttling, and failure mode. Nothing required to invoke it correctly is missing.

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 50% — `text` and `voice` are documented in-schema while `speed` and `format` are not. The description compensates by explaining the voice id families (catalog vs. voice_* clones), Arabic ar_* limits, and MP3/WAV output, but `speed` is never mentioned in either place, leaving one parameter fully unexplained.

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?

Specific verb + resource (convert text to MP3/WAV audio) plus the scope of voices available (66 neural voices or cloned voice_* ids). It clearly distinguishes itself from siblings like list_voices and get_job_status by naming the polling path for overflow jobs, so an agent can tell what this tool does without opening the schema.

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?

Explicit about eligibility (Pro or active 7-day pass; English) and about the free-tier voice subset, plus a concrete fallback instruction to poll get_job_status with the returned job_id when text exceeds limits. The one gap is that it never contrasts itself with generate_long_form, the obvious sibling for long inputs, leaving the agent to infer which one to use for large text.

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