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

Discloses traits the annotations cannot: queue scope is shared across sibling tools, pause is unsupported on Windows, skip is refused when idle, clear destroys queued segments that must be re-queued, and already-written files survive on disk. Also notes it is free (no API call). It does not say what status returns in detail or whether an output payload exists beyond the failure reporting mention.

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 purpose and scope, then walks the actions efficiently. Dense but every clause carries information; it is a single run-on paragraph, so slight readability cost versus a bulleted action list.

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 one-param control tool with no output schema, the description covers shared-state implications, per-action effects, platform caveats, irreversibility of clear, and cost — nothing an agent needs to call it safely 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 0% for the single action enum, so the description carries the full burden and does it: all five enum values (status, pause, resume, skip, clear) are given concrete semantics, side effects, and failure conditions, far beyond the bare enum list.

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 resource ('the shared audio queue') and verb ('inspect and control'), and explicitly ties it to the siblings that feed that queue (speak, queue_speech, play_audio, voice design tools). An agent can tell immediately that this governs playback state rather than producing audio itself.

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?

Each of the five actions is given a when-to-use condition: status to inspect, pause to hold (with the Windows exception steering to skip/clear), skip to drop the current segment (refused when nothing plays), clear to discard the queue. The alternatives and their selection conditions are spelled out.

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 already declare destructiveHint=true and idempotentHint=true, but the description adds real substance beyond them: the id is validated before deletion so a bad id is a no-op, catalog voices are refused, the deletion is irreversible, subsequent voice requests fail, and re-designing does not restore the sound. That is precisely the consequence information an agent needs before calling a destructive tool.

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 irreversible consequence and the id semantics are front-loaded and every clause carries information an agent cannot get from structured fields. The trailing 'Free.' is a useful cost note but reads as an abrupt fragment, and the sentence is long enough that a reader must hold several conditions at once.

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 destructive, single-parameter tool with no output schema, the description covers side effects, failure modes, and irreversibility thoroughly. It does not describe what a successful call returns (confirmation payload, freed slot info), which is the one gap left given there is no output schema to fall back on.

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 parameter is already documented as 'voice_... from list_voices or save_voice', so the schema does most of the work. The description still adds value by explaining the lookup-first validation behavior tied to that id and by reinforcing the voice_ prefix convention, though it adds no format or syntax 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 and resource ('Delete one of the account's designed voices') plus the side effect ('free its slot'), which immediately separates it from siblings like rename_voice or refine_voice. The scope limit ('catalog voices cannot be deleted') further pins down exactly what object class it operates on.

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 an explicit when-to-use condition ('Use it only when the user asks to delete that voice') and names the alternative for the adjacent intent ('to change only its name, use rename_voice'). The preconditions (id must come from list_voices, catalog voices excluded) are also stated, so an agent can route without inference.

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 provide the generic mutation profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), and the description adds the material facts an agent needs: 5 credits per call with retries charged again, the result is an unsaved draft, and the line is written to a file even when play is off.

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?

Purpose and trigger are front-loaded, and the cost/draft caveats close the text. The middle guidance paragraph is dense and slightly run-on, but each sentence carries actionable content rather than 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?

With no output schema, the description still tells the agent what comes back (a draft voice, a spoken line, a saved audio file) and what the follow-up moves are. Nothing needed 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 100%, so the baseline is 3, but the description genuinely enriches the description parameter by enumerating the facets to include (age, gender, role, pitch and texture, pace, listening context, language) and supplies a worked example plus the one-language rule.

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 — making a new voice from a written description — and immediately adds the observable side effect of playing the line through the machine's speakers. This clearly separates it from list_voices, refine_voice, and save_voice.

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 trigger ('when the user wants a voice the catalog does not have') and explicit alternatives in the sibling set: refine_voice changes the draft, save_voice keeps it. It also states what to exclude (real people's names, sound effects, the spoken content).

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?

The description adds substantial behavior beyond the annotations: page and file-size limits, no inference or lookup, the return structure, credit costs, free evidence spans, and the fact that a refused schema costs nothing. It does not contradict 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?

The description is long but front-loads the core purpose and alternative. Most sentences earn their place by covering limits, return behavior, cost, and schema guidance, though the final schema-reference sentence is somewhat redundant with the schema field.

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?

Given the complex nested schema and no output schema, the description completes the picture by explaining what is returned, how nulls work, what extra outputs exist, and what the tool costs. An agent has enough context to call it 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 description coverage is 100%, so the input schema already carries the main parameter documentation, including the detailed schema dialect and the free flags. The description adds some cost context around leaf counts but does not meaningfully extend parameter semantics 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?

The description states a specific verb and resource: 'Extract typed fields from a local PDF, PNG, JPEG, or WebP document.' It distinguishes the tool from its sibling by explicitly naming ocr_document for full-text extraction.

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 explicit when-to-use and when-not-to-use guidance: use this for typed fields, and use ocr_document instead for a document's full text. It also frames the tool as built for Thai documents and fine for English ones.

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 already declare readOnly, idempotent, and non-destructive, so the safety bar is low; the description still adds real behavioral context by noting the data is read live from the API on each call (not cached) and that the call is free. It does not discuss auth failure modes or rate limiting of the endpoint itself, keeping it short of a 5.

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 tight sentences: the first front-loads what the tool returns, the second the decision rule for calling it. Every clause carries information — no restatement of the title or 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?

With no parameters and no output schema, the description carries the burden of describing the return payload, and it does so by naming the four returned properties. Combined with the usage trigger and the live-read note, an agent has everything needed to call it 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 zero parameters, so there is nothing to document beyond the input schema's empty object. Baseline 4 applies; the description correctly implies no arguments are needed.

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 ('Show') and resource (the API key's account), then enumerates exactly what is returned: credit balance, spending cap, plan, rate limits. It is clearly distinguishable from siblings like list_models, which the description explicitly assigns to per-model pricing.

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 explicit triggering conditions — before a large paid job, or after a failure due to credits or rate limits — and routes pricing questions to list_models. Both when-to-use and the alternative are stated, leaving nothing to inference.

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 past the annotations: states nothing is written to disk, that it returns an empty transcript on silence, that it waits for ongoing playback, and gives concrete cost (12.5 credits/min, silence included). It also discloses hard prerequisites (ffmpeg/sox, Node 22+, host microphone permission), which are exactly the failure modes an agent must anticipate.

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 purpose, then usage, then edge cases, cost, and prerequisites — every sentence carries information an agent needs. It is on the long side at six sentences, but no single clause is 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?

For a zero-required-parameter, side-effecting, hardware-dependent capture tool with no output schema, the description covers return shape (transcript or empty), timing semantics, cost, prerequisites, and sibling routing. An agent has everything needed to call it correctly or decide not to.

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 100% and each parameter is well documented in-schema, so the baseline is 3. The description only adds behavioral meaning for wait_seconds ('Returns an empty transcript when nobody spoke within wait_seconds'), leaving style, convention, vocabulary, language and max_seconds entirely to 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?

Opens with a specific verb+resource+scope: 'Record one spoken turn from this machine's microphone and return its transcript,' including supported languages. It also positively distinguishes itself from transcribe_audio (disk files) so an agent can route without opening 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 an explicit invocation context ('after speak when you asked the user a question and want their spoken answer') and an explicit exclusion with a named alternative ('for a recording already on disk, use transcribe_audio instead'). The sequencing constraint ('waits for any speech this server is playing to finish first') further clarifies when it is safe to call.

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 already establish that this is a read-only, idempotent, non-destructive, open-world call. The description adds useful non-annotation context: the models are free to list and the response includes limits, pricing, and supported translation languages. It does not discuss latency or pagination, but those are minor for a zero-parameter listing tool.

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 description is front-loaded with the main action and scope, then adds usage guidance and sibling routing. Every sentence earns its place, with no 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?

Given the tool has no parameters and no output schema, the description fully covers what the tool returns, when to use it, its cost, and the relevant alternative tools. 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 has zero parameters, so there are no parameter semantics to explain. Per the baseline for zero-parameter tools, a 4 is appropriate.

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 uses a specific verb and resource: 'List the available Paxa models'. It enumerates the model categories and returned data (limits, credit pricing, translate languages), making clear how this differs from list_voices and get_account.

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 explicitly says when to call it: to check a limit or price before a large job. It also routes the agent to list_voices for voices and get_account for credit balance, covering the relevant alternatives.

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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real value beyond that: no paging in a single response, the ordering of the returned groups, the fields surfaced per voice, and that the call is free. It stops short of size limits or failure modes, keeping it at 4.

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 sentences, each doing distinct work: what is returned and in what order, when to call it and what to feed the id into, then the default-voice exception and cost. Purpose is front-loaded and no clause is redundant.

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?

No output schema exists, so the description must convey return shape, and it does: recommended voices, designed voices with slots, and per-model catalog entries with ids, names, gender, language, and character notes. That is sufficient for an agent to call it, parse it, and route the id onward.

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 the schema carries nothing an agent must interpret and the baseline is 4. The description correctly notes that filtering/selection happens downstream by passing an id from the result rather than through any input argument.

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 (List) plus resource (Paxa TTS voices) with scope clarified as a single non-paged response. It further distinguishes the content from a generic list by naming the ordering: recommended, account-designed voices with slots, then catalog roster per model.

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 triggers: user asks what voices exist or wants a different one, and before save_voice to check free slots. It also closes the loop by naming what to do with the result (pass an id to speak, queue_speech, or text_to_speech) and states the negative case: the default voice needs no lookup.

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 already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: page/size limits (50 pages, 10 MiB), credit cost per page (6.5), automatic multi-language handling with no language setting, and two-column reading order. These are exactly the operational facts an agent needs before invoking a billed, open-world tool.

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 action and output format, then language behavior, then the output-mode choice, then the sibling alternative, and finally limits and cost. Dense but every sentence carries information an agent would otherwise have to guess.

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 takes on the burden of describing return values and does so (Markdown prose vs typed JSON blocks). Limits, cost, and language behavior round out a complete picture for a two-parameter tool.

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 both parameters are already documented in structured form; the description's note on output="structured" largely restates the enum description. The added meaning (two-column reading, no language setting) is behavioral rather than parameter-level, so baseline 3 is appropriate.

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 — run Paxa OCR on a local PDF/PNG/JPEG/WebP file — and names the exact return format (GitHub-flavored Markdown or structured blocks). It also explicitly distinguishes itself from the sibling extract_fields, so an agent can pick between them without opening either 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?

Names the alternative explicitly ("Use extract_fields instead for specific values (a total, a date, an ID number) checked and typed against a schema") and gives the condition that selects it. It also states when to pick output="structured" versus default markdown, leaving little to inference.

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 by disclosing ordering semantics (waits for current playback, plays ahead of queued long-form speech), blocking behavior until the file ends, early-stop mechanism, and three distinct failure conditions that cause it to fail without playing. It does not describe the return value or what a successful block/skip outcome looks like, which is a minor remaining 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?

Front-loads the action and the speaker target, then layers ordering, failure, and sibling routing. Dense but nearly waste-free; the middle sentence packs three playback-ordering claims into one clause, which costs some readability but not correctness.

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 single-parameter, non-destructive tool with no output schema, the description covers everything an agent needs: what plays where, ordering relative to other speech, blocking behavior, escape hatch, failure modes, and the explicit note that it is free (no API call).

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 format list and path resolution rules are already documented. The description nevertheless adds real constraint information not in the schema: raw pcm, mulaw, and alaw files have no header and cannot be played, which narrows the effective domain of file_path.

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 ('Play a local audio file through this machine's speakers') plus the provenance of typical inputs ('a file produced earlier by text_to_speech'). It also explicitly distinguishes itself from the sibling 'speak' for producing new speech, so an agent can route correctly 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?

Names the alternatives and the conditions that select them: use 'speak' to say new text, use 'control_playback' with skip/clear to stop early. It also warns that headerless raw pcm/mulaw/alaw cannot be played, which is a concrete when-not-to-use rule.

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?

Beyond the annotations, the description discloses queueing semantics, immediate return behavior, pricing (10 credits per 1000 characters, 12.5 for designed voices), tag billing, and that unsupported tags are refused before any charge. It also documents model-specific tag behavior and limitations, which is substantial behavioral context for a non-idempotent, open-world tool.

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 description is front-loaded with purpose, queue behavior, and alternatives, and nearly every sentence carries useful information. It is long and dense because of the tag syntax and model-specific rules, which are justified, but the structure could be easier to scan with clearer separation between tag documentation and core tool behavior.

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 complex TTS tool with no output schema, the description covers the important behavior: what is returned immediately, how queueing works, how playback is controlled, pricing, and tag handling. The annotations already provide safety metadata, and the description fills in the operational details an agent needs to invoke it 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 the baseline is 3, but the description adds meaning beyond the schema: it explains how direction tags embedded in the text parameter are interpreted, ties the voice parameter to designed-voice pricing, and notes v1 limitations. It does not fully elaborate every parameter such as speed or temperature, but the schema already does.

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 gives a precise verb and resource ('Read long content aloud') and explains the core behavior: segmentation, ahead-of-play synthesis, immediate return with segment count and estimated credits, and ordered queueing after existing items. It also distinguishes this tool from siblings by explicitly naming speak and text_to_speech as alternatives for different use cases.

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 clearly says when to use this tool versus alternatives: use speak for a short line that should play now and wait, and text_to_speech for a file without playback. It also explains the lack of a handle and points to control_playback for monitoring and controlling the whole queue.

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 non-readonly, non-destructive, non-idempotent; the description adds the material behavior: every call mints a new draft handle while prior handles retain their versions, saved voices are never altered, and each call costs 5 credits with retries charged again. That credit/versioning disclosure is exactly what an agent needs to avoid surprise costs or lost work.

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 core action, then the instruction semantics, then versioning, then alternatives and cost. Every sentence carries distinct information, but the closing sentence is dense enough that it reads as two obligations (cost plus retry billing) compressed into one, and the sibling differentiation slightly overlaps with usage guidance.

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 correctly fills the gap by stating the return value ('a new draft handle') and the state model across calls. For a 3-parameter, non-idempotent, billed mutation, nothing an agent needs in order to call it correctly and safely 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%, so the baseline is 3; the description earns above it by explaining what 'instruction' means in practice ('a little lower and slower', 'warmer, and older') and constraining it to a single quality change. The 'play its new line' phrasing also gives context for the play flag, though it doesn't restate the default or the file-saving behavior.

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 ('Change a draft voice in words and play its new line') and immediately distinguishes it from design_voice, save_voice, and rename_voice. An agent can tell this is the iterative-refinement step rather than the create/save/rename steps without opening any 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?

Gives explicit when-to-use semantics ('change one quality at a time', with example instructions) and explicit routing to alternatives: save_voice keeps the draft the user picks, rename_voice only changes a name, and refining never mutates a saved voice. Exclusions and handoffs are both named.

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?

Adds real context beyond the annotations: the id and audio are unchanged so existing references keep working (reinforcing idempotentHint), catalog voice names are refused, and the call is free. It does not describe failure behavior for an unknown or deleted id, which is the remaining gap for a mutation tool.

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 sentences, no filler, with the core action and its non-destructive guarantee front-loaded and the alternative tools demoted to the end. Every clause carries either a constraint or a routing decision.

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?

Two required string params, full schema coverage, no output schema — the description supplies the id source, name constraints, an error case, cost, and sibling routing. Nothing an agent needs to invoke this 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 100%, so the 3 baseline applies, and the description earns above it by explaining that name collisions with a catalog voice are rejected and by tying id to its origin tools. Length bounds are restated from the schema rather than expanded, so it stops short of a 5.

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 ("Rename one of the account's designed voices") plus the identifier convention (voice_ id from list_voices or save_voice). It is clearly distinguishable from sibling mutations like refine_voice, save_voice, and delete_voice, which are each named.

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 routes the agent: to change how a voice sounds, use refine + save as a new voice; to remove one, use delete_voice. It also names the source of the id and flags the catalog-voice name exclusion, so both the positive case and the alternatives are covered.

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: it explains that re-saving the same draft returns the same voice and consumes no slot (reinforcing idempotentHint), that a saved voice's sound is immutable, that voices are account-scoped, and that plan tier limits quantity. It also discloses the returned id format and which tools accept it, which 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?

Dense but front-loaded: the action, output, and downstream usage land in the first sentence, then idempotency, immutability, and quota follow. The trailing 'Free.' fragment is a stray artifact that slightly hurts polish but costs little.

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?

No output schema exists, yet the description specifies the return value (voice_... id) and its consumers, and covers quota behavior, idempotency, and immutability. Nothing an agent needs to invoke this 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 100%, so both parameters are already documented, but the description adds that the draft handle originates from design_voice/refine_voice output or the Paxa console and that the resulting voice id is consumed by speak, queue_speech, and text_to_speech on paxa-tts-flash-v2. That is meaningful cross-tool semantics 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 (save) and resource (a draft from design_voice/refine_voice), plus the output (a voice id). It explicitly names the sibling tools that produce the input, distinguishing it from design_voice and refine_voice.

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 explicit when-to-use context: save drafts produced by design_voice or refine_voice, save only the draft the user picked, and design a new voice if a different sound is wanted. It also points to list_voices for slot visibility and names the plan tiers that cap saving, so exclusions and alternatives are covered.

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 beyond the annotations by disclosing cost ('Free, no credits'), a return value ('Returns the report's id once it is filed'), and the dependency on request ids printed by other tools. It does not address what happens if the same report is filed twice, which matters given idempotentHint=false, but the rest of the behavioral picture is well covered.

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 what the tool is for, then the minimum report, then the richer case, then cost and return. Five dense sentences with no filler and no repetition of schema text.

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 mutation tool with a nested payload and no output schema, the description covers the prerequisite (request ids from prior results), the minimum acceptable call, the escalation path for wrong outputs, cost, and the return value. Nothing an agent needs in order to file a correct report 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 already 100%, so the schema alone earns a 3. The description still adds real meaning: it explains where request_ids come from ('the request ids the other tools print ("Request id: ...")'), defines the minimum viable payload ('A rating alone on at least one request id is a complete report'), and specifies how to populate the nested example object.

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 — 'Report a wrong or poor output, an API problem, or a platform issue to the Paxa Labs team' — and enumerates the report kinds. That makes it unmistakably distinct from every sibling, which are all voice/speech/media tools.

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 both directions explicitly: 'Use it when the user says an output was wrong, or asks to report a problem; do not file reports the user did not ask for.' No plausible alternative tool exists here, so the absence of a named sibling is not a gap.

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 read/write profile; the description adds the details an agent actually needs: it blocks until playback finishes, it preempts queued long-form segments, and it costs 10 credits per 1000 characters (12.5 in a designed voice). It also discloses that invalid tags are refused before any charge and that tag characters bill as text — exactly the kind of cost/failure semantics annotations cannot carry.

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 correctly — action, blocking behavior, and cost precede the long tag tutorial. The tag section is dense and occupies over half the text, but it is load-bearing information about how the required text parameter is interpreted and is not documented elsewhere. It would read better split into labeled sub-sections rather than one block.

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 6-parameter tool with no output schema, the description covers cost, latency/blocking, queue interaction, model tradeoffs, and tag syntax thoroughly. The one meaningful omission is how to interrupt or stop playback once this blocking call is running, despite control_playback being a sibling.

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, but the description adds meaning beyond the schema: the cost premium tied to a 'voice_...' designed voice, the fact that designed voices only work on v2, and the full direction-tag grammar for the text field including pause lengths and the model-specific tag support. The v1/v2 tag restriction is genuine added semantic weight not present in the model enum description.

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 ('Synthesize a short line with Paxa TTS and play it through this machine's speakers') and immediately scopes it as short-form output. It explicitly names the sibling it is not (queue_speech for long content), so an agent can route without opening either 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?

'For long content use queue_speech' gives one explicit alternative with a clear selection condition, and the queue-priority sentence ('waits for currently playing audio but jumps ahead of queued long-form segments') further informs when this tool is the right choice. It does not differentiate from text_to_speech or play_audio, nor mention control_playback for stopping, so the routing picture is clear but not exhaustive.

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 already declare write, destructive, open-world, non-idempotent behavior; the description adds substantive context: existing files are replaced, long text is split and rejoined, ffmpeg is needed for some formats, costs vary by subtitles/voice, and unsupported tags are refused before charge. These details go well beyond the structured hints and do not contradict 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?

The most important information is front-loaded: what the tool does and which siblings to use instead. However, the description is a very dense single block, with some voice-recommendation and legacy-model detail that could be trimmed or structured more clearly for fast scanning.

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 complex 11-parameter tool with no output schema, the description covers the critical missing context: output file behavior, overwrite semantics, splitting of long text, format dependencies, subtitles, pricing, and tag syntax. An agent has enough information to call the tool correctly and anticipate side effects.

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, but the description adds meaningful semantics beyond the schema: direction-tag syntax and behavior, pause tags, cost implications, output-path replacement, and subtitle generation. It does not individually restate every parameter (speed, temperature, sample_rate, language rely mainly on schema descriptions), so it is not a full 5.

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 ('Synthesize speech ... save it as an audio file without playing it') and explicitly distinguishes this file-only tool from its siblings speak, queue_speech, and play_audio. An agent can identify the exact operation 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?

Explicitly says when to use this tool ('without playing it: voiceovers, narration, audiobooks, phone prompts') and names the alternatives for hearing speech now or later. It also gives the key selection criterion: file output versus playback.

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?

Beyond annotations, it discloses that transcripts come back inline, optional files are named after the recording and never overwrite existing files, nothing is translated, speaker labeling is available, and long recordings take minutes. It also covers vocabulary pinning and exact credit costs, which are important behavioral traits for an agent.

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 description is dense and front-loads the core purpose, supported inputs, output behavior, alternative tool, vocabulary behavior, and cost. It is appropriately detailed for a complex 11-parameter tool, though the first sentence is heavily parenthetical and could be easier to scan.

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 explains the inline return and optional file outputs, including formats and file-naming behavior. For a complex transcription tool, it covers the key constraints, costs, limits, alternatives, and side effects an agent needs before invocation.

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 100%, so the schema already documents all 11 parameters well. The description adds useful operational context around file saving, overwrite behavior, vocabulary environment configuration, detection hints, and cost, but does not need to restate every parameter's semantics.

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 uses a specific verb/resource pair, 'Transcribe a local recording or video of speech', and details supported languages, code-switching, file formats, duration, and size limits. It clearly distinguishes this from live microphone use by naming the sibling tool listen.

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 explicitly routes live microphone use to listen instead and gives practical conditions for local files, including supported formats, a 60-minute limit, and 25 MiB maximum. It also notes that language can be auto-detected but should be set when detection is wrong.

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 already cover safety (readOnly, idempotent, non-destructive), and the description goes well past them: per-segment language detection, target-language segments returned unchanged, exact credit math (25/1000 chars, 2-credit minimum, alternatives double it, supporting fields at 8/1000), dropped glossary terms are never billed, and the return payload including review flag and credits used.

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 purpose, then behavior, then cost — a sensible order with no filler sentences. The one deduction is the inline list of 15 language codes, which duplicates the target enum already in the schema and lengthens the definition without adding selection value.

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 12-parameter tool with no output schema, the description still describes the response shape (numbered translations, detected source language, review flag, credits) and explains the cost model, which is the main risk an agent faces when calling it. Nothing needed to call 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 100%, so the baseline is 3, but the description adds billing semantics not present in the schema: alternatives each re-bill the text and count against the character limit, and instructions/context/examples/do_not_translate/glossary bill at 8 per 1000. That materially changes how an agent would size a request.

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?

A concrete verb and resource (translate text) with an explicit scope: 15 named languages, any direction, string or up to 200 segments. It also routes away from a sibling by naming ocr_document for PDF/image input, so an agent can identify this tool 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?

Gives real when-to guidance: pin source 'only when detection gets it wrong', send the whole glossary rather than filtering, run ocr_document first for PDFs/images, and use context/examples for conditioning rather than translating them. It stops short of contrasting with speech siblings like text_to_speech, but the translation-vs-OCR boundary is explicit.

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