VoiceLabs

Ensure a voice profile exists

ensure_voice_profile

Idempotent

Make sure a voice profile with the given name exists on the user's VoiceLabs account, creating it from one of VoiceLabs' built-in (preset) voices if it does not. Idempotent: calling it again with the same name returns the same profile with created: false and creates nothing. Use this when list_voice_profiles comes back empty, or when speak reports NOT_FOUND for a voice, then pass the returned id to speak. It cannot clone a real person's voice — that is clone_voice_profile, which needs the voice:clone scope and a recording.

Input Schema

Name	Required	Description
`name`	Yes	The profile name to ensure exists. Matched EXACTLY against the account's existing profiles — the same uniqueness key the engine enforces — so a differently-cased name is a different profile.
`engine`	No	Which built-in voice catalogue to draw from. Defaults to "kokoro", VoiceLabs' fast general-purpose preset engine.
`language`	No	ISO language code for the profile. Defaults to "en".
`description`	No	Optional human note stored on the profile. Ignored when the profile already exists.
`builtinVoiceId`	No	The built-in voice to use. Defaults to "af_heart", the engine's own default Kokoro voice. The ids VoiceLabs publishes (case-sensitive) — kokoro: af_alloy, af_aoede, af_bella, af_heart, af_jessica, af_kore, af_nicole, af_nova, af_river, af_sarah, af_sky, am_adam, am_echo, am_eric, am_fenrir, am_liam, am_michael, am_onyx, am_puck, am_santa, bf_alice, bf_emma, bf_isabella, bf_lily, bm_daniel, bm_fable, bm_george, bm_lewis, ef_dora, em_alex, em_santa, ff_siwis, hf_alpha, hf_beta, hm_omega, hm_psi, if_sara, im_nicola, jf_alpha, jf_gongitsune, jf_nezumi, jf_tebukuro, jm_kumo, pf_dora, pm_alex, pm_santa, zf_xiaobei, zf_xiaoni, zf_xiaoxiao, zf_xiaoyi. qwen_custom_voice: Vivian, Serena, Uncle_Fu, Dylan, Eric, Ryan, Aiden, Ono_Anna, Sohee. Any other id is refused with INVALID_REQUEST.

Output Schema

Name	Required	Description	Default
`id`	Yes
`name`	Yes
`engine`	Yes
`created`	Yes
`language`	Yes
`voiceType`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 26, 2026
- removedOutput schema / properties / engine / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / engine / type
```
Added value: +[
+  "string",
+  "null"
+]
```
First observedSep 28, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=false, but the description adds real behavioral detail: a repeat call returns the same profile with `created: false` and creates nothing, and unknown built-in ids are refused with INVALID_REQUEST. It also notes the alternative's scope requirement (voice:clone). Minor gap: no mention of account/permission requirements for this tool itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action, then idempotency semantics, then routing guidance. Every sentence adds distinct information with no repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, rich annotations, and 100% schema coverage, the description only needs the semantics structured fields cannot express — idempotency outcome, failure mode, and sibling routing — and it delivers all three.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents exact-name matching, engine/language defaults, the full builtinVoiceId catalogue and its refusal behavior. The description adds nothing parameter-specific beyond the name, so the schema carries the load and baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('make sure a voice profile ... exists'), states the create-if-missing semantics, and explicitly separates it from clone_voice_profile by name. An agent can pick between the two 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.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete trigger conditions ('when list_voice_profiles comes back empty, or when speak reports NOT_FOUND'), the downstream consumption step ('pass the returned id to speak'), and an explicit exclusion ('cannot clone a real person's voice — that is clone_voice_profile').

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

All VoiceLabs tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?