VoiceLabs

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

Annotations already declare idempotentHint=false and destructiveHint=false, and the description adds real value on top: the specific refusal behavior (a second call with the same name), the 2–30 second audio constraint, and an ethical precondition around owner consent. It does not cover auth/permission requirements or rate limits, which keeps it out of the top band.

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?

A single dense paragraph that front-loads the action and lists inputs before the non-idempotency warning. Efficient, though it repeats a couple of schema facts (2–30 seconds, the base64-vs-URL pair) that add length without new 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 so return values need not be re-explained, and the description still flags the key returned id and its use with speak. Combined with the duplicate-name refusal, the consent rule, and the audio constraints, an agent has everything required to invoke this 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 schema already documents every parameter including the audioBase64/audioUrl exclusivity, formats, size limits, and transcript requirements. The description restates those facts (name, language, referenceText, the two audio forms) without adding syntax or semantics the schema lacks, so baseline 3 applies.

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 ('Create a cloned voice ... from a recording') and enumerates the exact inputs, so it is clearly distinguishable from the sibling list_voice_profiles and ensure_voice_profile. It even notes the return payload and the follow-on tool (speak), which pins down what the tool is for.

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 concrete when-to-use guidance and a prerequisite: check list_voice_profiles first because a duplicate name is refused, and only clone a voice whose owner has consented. It does not explicitly contrast with the closest sibling, ensure_voice_profile, so an agent may still have to guess between the two.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, but the description adds real value beyond them: the exact idempotent response shape (`created: false`), the fact that nothing is created on repeat calls, and the boundary that it cannot clone a real voice. It stops short of stating the auth scope this tool itself requires, which is the one behavioral 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 what the tool does, then idempotency semantics, then when to use it, then the boundary against clone_voice_profile. No sentence is redundant and nothing is buried.

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 need not be restated, yet the description still flags the `created` field an agent will actually branch on. Triggers, alternatives, idempotency, and the returned id handoff are all covered for a 5-param 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 description coverage is 100%, so the schema already documents name-matching, engine defaults, language, and the full builtinVoiceId list with the INVALID_REQUEST failure mode. The description adds only the framing that the name match is 'the same uniqueness key the engine enforces', so the 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 precise verb+resource ('Make sure a voice profile with the given name exists'), explains the create-if-absent behavior, and explicitly contrasts itself with clone_voice_profile. An agent can distinguish it from every sibling without opening a 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 trigger conditions ('when list_voice_profiles comes back empty, or when speak reports NOT_FOUND'), names the alternative (clone_voice_profile) and its differing scope requirement, and tells the agent what to do with the result ('pass the returned id to speak').

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, openWorldHint=true, non-idempotent, and not read-only, so the risk profile is covered structurally. The description adds the meaningful detail that execution happens in an 'isolated sandbox' and that the program must return its result, but it does not say what constraints 'short' imposes (time, memory, tool-call budget) or what happens on sandbox failure.

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 padding, with the core operation front-loaded. The closing pointer to server instructions is a necessary redirect for a tool whose full contract is large, though it does consume space without adding local 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, so return-value description is not required, and the sandbox/return contract is sketched. However, for a destructive, open-world code-execution tool the behavioral contract is deferred to 'server instructions', leaving resource limits and failure semantics unspecified in the definition itself.

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?

There is a single parameter with 100% schema description coverage, and the schema already explains that 'code' is a TypeScript body calling declared external_* functions that must return its result. The description only adds the vague 'short' qualifier, so the baseline of 3 for high coverage 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 (Run/Execute) and resource (a TypeScript program) and pins the domain: orchestrating VoiceLabs MCP tools in an isolated sandbox. It also names the sibling 'search_tools' as the discovery path, so an agent can place it relative to the other tools 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?

The description implies use for multi-tool orchestration ('orchestrates VoiceLabs MCP tools') but never states when to prefer this over calling a sibling tool directly, nor any exclusions or limits. The explicit instruction is to consult server instructions, which is an out-of-band dependency rather than guidance in the definition itself.

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, destructiveHint=false, and openWorldHint=false, so safety is covered and the trailing 'Read-only' is largely redundant. The description does add real value beyond the annotations by disclosing the state machine (generating | completed | failed) and the failure payload (human-readable error plus failureKind), which helps an agent interpret polling results.

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 tight sentences, front-loaded with the verb and purpose, followed by return semantics and a one-word safety note. No filler 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 single-parameter polling tool with full annotations and an output schema, the description covers purpose, usage context, and the meaningful state values an agent needs. Nothing required to invoke or interpret it 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 there is a single required parameter whose schema description already explains its origin ('The id returned by the speak tool'). The description adds only 'by id', so the 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 ('Look up a VoiceLabs generation by id') plus the intended purpose ('to poll its status'), which clearly distinguishes it from siblings like speak (creates a generation) and list_captures. An agent can select this tool without ambiguity.

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 phrase 'to poll its status' establishes the context of use — checking on an asynchronously created generation — and the schema ties the id to the 'speak' tool. It does not explicitly state when not to use it or name alternatives, so it falls short of a 5.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the trailing 'Read-only' is largely redundant. The description does add non-annotation behavior: result ordering (most-recent first) and the pagination contract. It says nothing about rate limits, maximum page depth, or what happens with a huge offset.

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, front-loaded sentences with no filler, and the scope/ordering comes before the pagination mechanics. The final 'Read-only' clause is redundant with the readOnlyHint annotation, so it is the one phrase that does not fully earn its place.

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 need not be described, and annotations cover safety; what remains is scope, ordering and pagination, all of which are stated. The only shortfall is the undocumented offset semantics and defaults against a 0%-covered 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 description coverage is 0%, so the description must compensate: it supplies limit's bounds (1-200) and names offset for pagination, which is real added meaning. However it omits the defaults (50 and 0) and never explains what offset actually counts, leaving one of two parameters only half-specified.

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 (VoiceLabs captures) and scope (the user's recent ones), with the content types enumerated (dictations, recordings, uploads) and the payload described (transcripts). No sibling tool overlaps this resource, so an agent can select it unambiguously.

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 implies the usage context ('the user's recent captures', 'most-recent first') and explains pagination, but never states when to reach for this tool versus another (e.g. search-style retrieval) or any exclusions. Usage is inferable but not 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 read-only, idempotent, non-destructive behavior, and the description adds meaningful context beyond that: it discloses the empty-state response and instructs the agent to relay an `emptyState` explanation rather than reporting failure. This is substantive behavioral information not present in 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 front-loaded with purpose, then briefly reinforces read-only behavior, then covers the important empty-state edge case. All content is relevant and compact for a zero-parameter listing tool.

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 simple listing complexity, rich annotations, no input parameters, and an existing output schema, the description is complete. It covers purpose, safety context, and the key edge case an agent might mishandle.

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 the schema cannot document parameter semantics and the baseline is 4. The description does not need to add parameter details, and it appropriately adds none.

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 specific verb and resource ('List the user's VoiceLabs voice profiles') and clarifies scope by naming both cloned voices and presets. It also lists returned fields (language, engine, usage counts), making it easy to distinguish from siblings like clone_voice_profile and ensure_voice_profile.

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 implied by the tool name and list purpose, and the description gives useful handling guidance for an empty account. However, it does not explicitly say when to choose this tool over alternatives such as ensure_voice_profile or clone_voice_profile, so alternative-selection guidance is absent.

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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the return format (TypeScript declarations) and the fact that results are limited to this connection's reachable tools, but it pushes the 'full contract' off to server instructions rather than disclosing behavior directly.

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, front-loaded with the discover-tools purpose, then the return format. No filler and no 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?

With an output schema present and 100% parameter coverage, the description needn't explain return values, yet it usefully states the TypeScript-declaration form and the connection-scoped result set. The only weakness is leaning on external server instructions for the calling contract.

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% — the single 'query' parameter is fully documented as a case-insensitive substring match with omit-to-return-all semantics. The description adds nothing about the parameter, so the 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: 'Find the VoiceLabs MCP tools this connection can reach.' It also says what comes back (TypeScript declarations callable from execute_typescript), which distinguishes it from the action-oriented siblings. It stops short of explicitly contrasting itself with those siblings, so not a 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?

Usage is only implied via 'to call from execute_typescript' and the connection-scoping phrase; there is no explicit 'use this when you don't know which tool to call' or when-not guidance. It defers the contract to server instructions rather than stating the selection context itself.

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=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds the crucial non-obvious behavior that the call is asynchronous, returning a generationId with status 'generating' that must be polled, which the annotations do not 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 tight sentences with no filler: the core action and the async follow-up step are front-loaded, and the optional voice-selection note comes last. Every sentence earns its place.

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 four parameters, an output schema, and simple annotations, the description covers everything an agent needs: what it produces, that it is asynchronous, and how to retrieve the audio. 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 description coverage is 100%, so the schema already documents text, language, profileId and profileName, including the note that profileId takes precedence. The description restates voice selection ('Pass profileId or profileName') without adding format, constraints, or default behavior beyond the schema, so baseline 3 applies.

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 ('Generate speech from text') and scopes it to the user's VoiceLabs voice profiles, which cleanly separates it from siblings like transcribe (the inverse direction) and clone_voice_profile (profile creation). An agent can identify this as the text-to-speech entry point 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 concrete usage context: it explains the asynchronous flow and names the follow-up tool ('poll get_generation with that id'), and tells the caller to supply profileId or profileName to pick a voice. It stops short of stating prerequisites (e.g. needing an existing profile from ensure_voice_profile) or when not to use it.

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 mark this as a non-read-only, open-world, non-idempotent call; the description goes further by disclosing refusal behavior for non-audio payloads (under 1 KiB, bare header, placeholder bytes), the 10 MiB ceiling, and the side effect that a capture is created (implied by 'the created capture id'). That is meaningful context beyond the structured safety hints.

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 progressively narrower detail (input modes, size limits, refusal cases, fallback). Every sentence carries information, though the format/size enumerations echo the property descriptions, adding mild redundancy.

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 a 3-parameter schema at full coverage, an output schema, and annotations covering safety, the description supplies everything else an agent needs: which input form to pick, format and size constraints, failure semantics, and the recovery path when the agent lacks file bytes.

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 adds rationale the schema lacks — why base64 must be real bytes (placeholder payloads are refused) and the mutual-exclusion rule restated as 'exactly one way'. The format list and size limits largely duplicate the schema, which caps the score.

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 ('Transcribe an audio file to text') plus the underlying engine, which cleanly separates it from sibling speak (synthesis) and the capture/listing tools. An agent can identify the operation without reading 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 explicit invocation conditions ('Give the audio exactly one way: audioUrl ... or audioBase64') and a concrete fallback when the bytes aren't readable (ask for a public link or upload via the studio page). It does not name a sibling alternative, so it stops short of a full when/when-not routing statement.

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