Provides tools for generating speech, cloning voices, transcribing audio, and manipulating audio using the ElevenLabs API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@elevenlabs-mcp Turn this speech into text and identify speakers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Get your API key from ElevenLabs. There is a free tier with 10k credits per month.
Install uv (Python package manager), install with curl -LsSf https://astral.sh/uv/install.sh | sh or see the uv repo for additional install methods.
Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:
{
"mcpServers": {
"ElevenLabs": {
"command": "uvx",
"args": ["elevenlabs-mcp"],
"env": {
"ELEVENLABS_API_KEY": "<insert-your-api-key-here>"
}
}
}
}
If you're using Windows, you will have to enable "Developer Mode" in Claude Desktop to use the MCP server. Click "Help" in the hamburger menu at the top left and select "Enable Developer Mode".
Related MCP server: ElevenLabs MCP Server
For other clients like Cursor and Windsurf, run:
pip install elevenlabs-mcp
python -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --print to get the configuration. Paste it into appropriate configuration directory specified by your MCP client.
That's it. Your MCP client can now interact with ElevenLabs through these tools:
⚠️ Warning: ElevenLabs credits are needed to use these tools.
Try asking Claude:
"Create an AI agent that speaks like a film noir detective and can answer questions about classic movies"
"Generate three voice variations for a wise, ancient dragon character, then I will choose my favorite voice to add to my voice library"
"Convert this recording of my voice to sound like a medieval knight"
"Create a soundscape of a thunderstorm in a dense jungle with animals reacting to the weather"
"Turn this speech into text, identify different speakers, then convert it back using unique voices for each person"
You can configure how the MCP server handles file outputs using these environment variables in your claude_desktop_config.json:
ELEVENLABS_MCP_BASE_PATH: Specify the base path for file operations with relative paths (default: ~/Desktop)
ELEVENLABS_MCP_OUTPUT_MODE: Control how generated files are returned (default: files)
The ELEVENLABS_MCP_OUTPUT_MODE environment variable supports three modes:
files (default): Save files to disk and return file paths
"env": {
"ELEVENLABS_API_KEY": "your-api-key",
"ELEVENLABS_MCP_OUTPUT_MODE": "files"
}resources: Return files as MCP resources; binary data is base64-encoded, text is returned as UTF-8 text
"env": {
"ELEVENLABS_API_KEY": "your-api-key",
"ELEVENLABS_MCP_OUTPUT_MODE": "resources"
}both: Save files to disk AND return as MCP resources
"env": {
"ELEVENLABS_API_KEY": "your-api-key",
"ELEVENLABS_MCP_OUTPUT_MODE": "both"
}Resource Mode Benefits:
Files are returned directly in the MCP response as base64-encoded data
No disk I/O required - useful for containerized or serverless environments
MCP clients can access file content immediately without file system access
In both mode, resources can be fetched later using the elevenlabs://filename URI pattern
Use Cases:
files: Traditional file-based workflows, local development
resources: Cloud environments, MCP clients without file system access
both: Maximum flexibility, caching, and resource sharing scenarios
You can specify the data residency region with the ELEVENLABS_API_RESIDENCY environment variable. Defaults to "us".
Note: Data residency is an enterprise only feature. See the docs for more details.
If you want to contribute or run from source:
Clone the repository:
git clone https://github.com/elevenlabs/elevenlabs-mcp
cd elevenlabs-mcpCreate a virtual environment and install dependencies using uv:
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"Copy .env.example to .env and add your ElevenLabs API key:
cp .env.example .env
# Edit .env and add your API keyRun the tests to make sure everything is working:
./scripts/test.sh
# Or with options
./scripts/test.sh --verbose --fail-fastInstall the server in Claude Desktop: mcp install elevenlabs_mcp/server.py
Debug and test locally with MCP Inspector: mcp dev elevenlabs_mcp/server.py
Logs when running with Claude Desktop can be found at:
Windows: %APPDATA%\Claude\logs\mcp-server-elevenlabs.log
macOS: ~/Library/Logs/Claude/mcp-server-elevenlabs.log
Certain ElevenLabs API operations, like voice design and audio isolation, can take a long time to resolve. When using the MCP inspector in dev mode, you might get timeout errors despite the tool completing its intended task.
This shouldn't occur when using a client like Claude.
If you encounter the error "MCP ElevenLabs: spawn uvx ENOENT", confirm its absolute path by running this command in your terminal:
which uvxOnce you obtain the absolute path (e.g., /usr/local/bin/uvx), update your configuration to use that path (e.g., "command": "/usr/local/bin/uvx"). This ensures that the correct executable is referenced.
Add a knowledge base to ElevenLabs workspace. Allowed types are epub, pdf, docx, txt, html.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
Args:
agent_id: ID of the agent to add the knowledge base to.
knowledge_base_name: Name of the knowledge base.
url: URL of the knowledge base.
input_file_path: Path to the file to add to the knowledge base.
text: Text to add to the knowledge base.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ||
| knowledge_base_name | Yes | ||
| url | No | ||
| input_file_path | No | ||
| text | No |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-destructive and open-world. Description adds cost warning and allowed file types, going beyond 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?
Description is clear and structured with a cost warning and parameter list. Slightly verbose due to Args, but effective overall.
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?
Covers purpose, usage, parameters, and file types. With output schema present, return values need not be described. Missing details on how multiple sources interact, but still complete enough.
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%, but the Args section explains each parameter clearly (agent_id, knowledge_base_name, url, file, text), providing full meaning.
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?
Clearly states 'Add a knowledge base to ElevenLabs workspace' and specifies allowed file types. Distinguishes itself from sibling tools like create_agent or speech_to_text.
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?
Includes a cost warning and explicit instruction to use only when user requests it. Does not mention when not to use or alternatives, but provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the current subscription status. Could be used to measure the usage of the API.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds the behavioral hint that the tool can measure usage, which provides some extra context but is not required. It does not contradict 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 two sentences, no filler words, and front-loads the core purpose. Every word adds 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?
Given the simplicity (no parameters, output schema present), the description fully covers what the tool does and offers a relevant use case, leaving no significant gaps.
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 (schema coverage 100%), so the baseline is 4. The description adds no parameter details, but none 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?
The description clearly states the tool checks the current subscription status, with a specific verb and resource. It also adds a practical use case ('measure the usage of the API'), distinguishing it from sibling tools which are unrelated.
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 provides a clear context for use (measuring API usage) but does not explicitly state when not to use or name alternatives. Since no sibling tools overlap in functionality, this is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a prompt to music and save the output audio file to a given directory. Directory is optional, if not provided, the output file will be saved to $HOME/Desktop.
Args:
prompt: Prompt to convert to music. Must provide either prompt or composition_plan.
output_directory: Directory to save the output audio file
composition_plan: Composition plan to use for the music. Must provide either prompt or composition_plan.
music_length_ms: Length of the generated music in milliseconds. Cannot be used if composition_plan is provided.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | ||
| output_directory | No | ||
| composition_plan | No | ||
| music_length_ms | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Contradicts annotations: description says 'save the output audio file' (write operation), but annotations have readOnlyHint=true. Also adds cost warning but does not compensate for the contradiction.
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 purpose, uses bullet-like Args section and bold cost warning. Some redundancy in 'Must provide either...' phrase but overall efficient.
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?
Covers basic usage and cost implications, but does not explain relationship with sibling 'create_composition_plan', output format, or return value despite output schema existing. Incomplete for a tool with multiple modes.
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?
Adds value beyond schema by explaining mutual exclusivity between prompt and composition_plan, default directory, and cost warning. However, does not explain the complex nested structure of composition_plan or music_length_ms constraint.
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?
Clearly states the verb 'convert' and resource 'prompt to music'/'save output audio file'. Distinguishes from siblings like text_to_speech by specifying music generation.
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 'Only use when explicitly requested by the user' due to cost. Lists required parameter combinations but does not explicitly compare with sibling 'create_composition_plan' or explain when to use prompt vs composition_plan.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a conversational AI agent with custom configuration.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
Args:
name: Name of the agent
first_message: First message the agent will say i.e. "Hi, how can I help you today?"
system_prompt: System prompt for the agent
voice_id: ID of the voice to use for the agent
language: ISO 639-1 language code for the agent
llm: LLM to use for the agent
temperature: Temperature for the agent. The lower the temperature, the more deterministic the agent's responses will be. Range is 0 to 1.
max_tokens: Maximum number of tokens to generate.
asr_quality: Quality of the ASR. `high` or `low`.
model_id: ID of the ElevenLabs model to use for the agent.
optimize_streaming_latency: Optimize streaming latency. Range is 0 to 4.
stability: Stability for the agent. Range is 0 to 1.
similarity_boost: Similarity boost for the agent. Range is 0 to 1.
turn_timeout: Timeout for the agent to respond in seconds. Defaults to 7 seconds.
max_duration_seconds: Maximum duration of a conversation in seconds. Defaults to 600 seconds (10 minutes).
record_voice: Whether to record the agent's voice.
retention_days: Number of days to retain the agent's data.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| first_message | Yes | ||
| system_prompt | Yes | ||
| voice_id | No | cgSgspJ2msm6clMCkdW9 | |
| language | No | en | |
| llm | No | gemini-2.0-flash-001 | |
| temperature | No | ||
| max_tokens | No | ||
| asr_quality | No | high | |
| model_id | No | eleven_turbo_v2 | |
| optimize_streaming_latency | No | ||
| stability | No | ||
| similarity_boost | No | ||
| turn_timeout | No | ||
| max_duration_seconds | No | ||
| record_voice | No | ||
| retention_days | No |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=false and openWorldHint=true. The description adds that it makes an API call and may incur costs, but does not elaborate on failure modes or side effects beyond creation. Adequate but not exceptional.
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 relatively long due to the parameter list, but it is well-structured with a front-loaded cost warning and a clear 'Args:' section. Every sentence adds value given the tool's complexity.
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 output schema exists, the description does not need to explain return values. It covers creation behavior, parameter constraints, and usage conditions. Missing information about error handling or validation, but overall complete for its purpose.
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 carries full burden. It provides detailed explanations for all 17 parameters, including defaults, ranges, and meanings (e.g., temperature range, stability range, turn_timeout default). This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a conversational AI agent with custom configuration', which is a specific verb + resource. It distinguishes from siblings like 'add_knowledge_base_to_agent' and 'get_agent' by focusing on creation.
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 includes a cost warning that tells the agent to only use when explicitly requested by the user, providing a clear usage condition. It does not explicitly mention alternatives, but the warning effectively guides when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a composition plan for music generation. Usage of this endpoint does not cost any credits but is subject to rate limiting depending on your tier. Composition plans can be used when generating music with the compose_music tool.
Args:
prompt: Prompt to create a composition plan for
music_length_ms: The length of the composition plan to generate in milliseconds. Must be between 10000ms and 300000ms. Optional - if not provided, the model will choose a length based on the prompt.
source_composition_plan: An optional composition plan to use as a source for the new composition plan
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| music_length_ms | No | ||
| source_composition_plan | No |
| Name | Required | Description |
|---|---|---|
| positive_global_styles | Yes | |
| negative_global_styles | Yes | |
| sections | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation 'readOnlyHint: true' directly contradicts the description's claim of creating a new plan, which is a write operation. This is a major inconsistency, undermining transparency despite additional info on cost and rate limits.
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 concise with a clear first sentence and organized Args section. The credit/rate limit sentence adds relevant context, though it could be slightly tighter. Still, it is well-structured.
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?
The description covers purpose, parameters, and relationship to sibling tools, but the annotation contradiction undermines completeness. With an output schema present, return values are not required. However, the contradiction leaves the agent uncertain about behavioral expectations.
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?
Despite 0% schema coverage, the description adds meaningful details: prompt is explained, music_length_ms includes valid range and optionality, and source_composition_plan is described as an optional source. This compensates well for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a composition plan for music generation,' specifying the verb and resource. It also distinguishes from the sibling 'compose_music' tool by explaining that plans are used with that tool.
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 explains that no credits are used and rate limits apply, giving clear context for when to use. It also mentions the relationship to 'compose_music', but does not explicitly state when not to use or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a generated voice to the voice library. Uses the voice ID from the text_to_voice tool.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
| Name | Required | Description | Default |
|---|---|---|---|
| generated_voice_id | Yes | ||
| voice_name | Yes | ||
| voice_description | Yes |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-destructive and open-world behavior. Description adds value by explicitly stating it makes an API call to ElevenLabs, which may incur costs. No contradictions with 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?
Two sentences plus a cost warning note. Front-loaded with purpose and key usage constraint. Every sentence serves a purpose.
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?
Description covers purpose, source of key parameter, and cost warning. Output schema exists to handle return value details. Minor gap: does not explain prerequisites like having a preview from `text_to_voice`.
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?
Input schema has 0% description coverage. Description adds meaning for `generated_voice_id` by linking to `text_to_voice`, but provides no guidance on `voice_name` or `voice_description`. Insufficient compensation for low schema coverage.
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?
Description clearly states the tool 'adds a generated voice to the voice library' and specifies it uses the voice ID from the `text_to_voice` tool. Verb and resource are specific, and the reference to a sibling distinguishes its purpose.
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 cost warning and instruction 'Only use when explicitly requested by the user' provide clear usage context. However, it does not explicitly list when not to use or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a specific conversational AI agent
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds minimal behavioral context beyond stating it gets details; no mention of caching, permissions, or return format details beyond what output schema provides.
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 a single 11-word sentence with no wasted words, but it could be more informative without sacrificing conciseness.
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's simplicity (1 required param, output schema exists), the description is minimal. It lacks guidance on when to use it, what details are included, or prerequisites, making it incomplete for an AI agent to use reliably.
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 schema has one required parameter 'agent_id' with 0% description coverage. The description does not explain what agent_id is or how to obtain it, failing to compensate for the schema's lack of documentation.
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 clearly states the verb 'Get details' and the resource 'specific conversational AI agent', effectively distinguishing it from siblings like list_agents (which lists all agents) and create_agent (which creates).
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?
No explicit when-to-use or alternatives are provided; the intended usage is implied by the tool's purpose (fetch details for a single agent) but lacks explicit guidance or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets conversation with transcript. Returns: conversation details and full transcript. Use when: analyzing completed agent conversations.
Args:
conversation_id: The unique identifier of the conversation to retrieve, you can get the ids from the list_conversations tool.
| Name | Required | Description | Default |
|---|---|---|---|
| conversation_id | Yes |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint (true) and openWorldHint (true). The description adds value by specifying that the tool retrieves completed conversations and returns conversation details plus full transcript, which is behavioral context beyond 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 extremely concise at three sentences, each serving a distinct purpose: stating what it does, when to use it, and describing the argument. No redundant or irrelevant 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?
Given low complexity (1 parameter, presence of output schema indicating return structure is documented elsewhere), the description adequately covers purpose, usage, parameter source, and general return content. No gaps remain for this 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?
The description explains the only parameter (conversation_id) as 'the unique identifier of the conversation to retrieve' and directs the agent to list_conversations to get IDs, adding significant meaning beyond the schema (which only provides title and type).
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 clearly states the tool 'gets a conversation with transcript', specifying the resource (conversation) and the full transcript. It distinguishes from siblings like list_conversations by referencing it for obtaining IDs, and from get_agent which targets a different resource.
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 provides explicit usage context: 'Use when: analyzing completed agent conversations.' It does not explicitly state when not to use, but implies this use case. The mention of list_conversations as a source for IDs provides a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific voice
| Name | Required | Description | Default |
|---|---|---|---|
| voice_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| category | Yes | |
| fine_tuning_status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's simple statement is consistent. No additional behavior is disclosed, but none is needed for a straightforward read operation.
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 a single concise sentence. It is efficient but could be slightly more informative without becoming verbose.
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 simple retrieval tool with one parameter and an output schema, the description is adequate. However, it lacks usage context relative to sibling tools.
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%, and the description does not explain the voice_id parameter or its format beyond the schema. The phrase 'specific voice' implies an identifier but adds no concrete meaning.
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 clearly states the tool retrieves details of a specific voice, but does not differentiate from sibling tools like search_voices or voice_clone. The verb and resource are clear.
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?
No guidance on when to use this tool versus alternatives (e.g., search_voices). The description does not mention prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Isolate audio from a file. Saves output file to directory (default: $HOME/Desktop).
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
| Name | Required | Description | Default |
|---|---|---|---|
| input_file_path | Yes | ||
| output_directory | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool makes an API call and saves a file, implying a mutation. However, the annotation readOnlyHint=true indicates a read-only operation, creating a direct contradiction. Additionally, the openWorldHint adds further confusion. Score 1 per guideline for contradiction.
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 two sentences with no redundant information. Every sentence adds value: the first defines the action, the second provides a critical usage warning. Very concise and well-front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (not shown), the description lacks details on return format, file types, or behavioral nuances. The contradiction with annotations further reduces completeness. The tool is simple but still requires more context for safe 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 0%, so the description must compensate. It adds meaning for output_directory by specifying the default ($HOME/Desktop), but input_file_path remains unexplained (relies on param type 'string'). Partial compensation leads to a score of 3.
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 clearly states 'Isolate audio from a file' which is a specific verb+resource. While it distinguishes from sibling tools like speech_to_text or compose_music, it doesn't elaborate on what 'isolate' entails (e.g., vocals from background). The action is unambiguous enough for selection.
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 includes a cost warning and explicitly states 'Only use when explicitly requested by the user', providing clear context for usage. However, it does not specify when NOT to use it or list alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available conversational AI agents
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the behavioral baseline. The description adds nothing beyond stating 'list all available', which is consistent but does not enrich the agent's understanding of traits like auth, rate limits, or interpretation of 'available'.
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 a single sentence that is clear, front-loaded, and contains no wasted words. It 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 no parameters, output schema present, and annotations already covering open-world and read-only hints, the description is adequate. One might wish for clarification on 'available' scope, but overall it is complete for this simple 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?
There are zero parameters, so the description does not need to add param information. Schema coverage is 100% trivially. The description is sufficient for a param-less tool.
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 clearly states the tool lists all available conversational AI agents, with a specific verb and resource, and it distinguishes itself from siblings like get_agent and create_agent.
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?
No guidance is provided on when to use this tool versus alternatives like get_agent or list_conversations. No exclusions or contextual hints are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists agent conversations. Returns: conversation list with metadata. Use when: asked about conversation history.
Args:
agent_id (str, optional): Filter conversations by specific agent ID
cursor (str, optional): Pagination cursor for retrieving next page of results
call_start_before_unix (int, optional): Filter conversations that started before this Unix timestamp
call_start_after_unix (int, optional): Filter conversations that started after this Unix timestamp
page_size (int, optional): Number of conversations to return per page (1-100, defaults to 30)
max_length (int, optional): Maximum character length of the response text (defaults to 10000)
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | No | ||
| cursor | No | ||
| call_start_before_unix | No | ||
| call_start_after_unix | No | ||
| page_size | No | ||
| max_length | No |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint (safe read) and openWorldHint. The description adds return type info but does not disclose pagination behavior or potential rate limits.
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?
Starts with a clear purpose, then returns and usage hint, then parameter list. No unnecessary words, though parameter descriptions could be integrated more concisely.
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?
Covers all 6 parameters with defaults and filtering logic. Output schema exists, so details on return format are not required. Pagination cursor is mentioned but behavior not elaborated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description lists each parameter with a brief functional description. These are minimal but add essential meaning beyond schema field names.
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 clearly states the tool 'Lists agent conversations' with a specific verb and resource. It distinguishes from siblings like 'get_conversation' which retrieves a single conversation.
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?
Provides a usage cue 'Use when: asked about conversation history' but lacks explicit when-not-to-use or alternatives such as 'get_conversation' for single conversations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available models
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that the tool lists 'all available' models, which is consistent. No additional behavioral context is needed beyond what annotations provide.
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 a single sentence with no unnecessary words. It is appropriately sized for the tool's simplicity.
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 zero parameters and the presence of annotations and an output schema, the description is minimally adequate. It conveys the basic purpose but could benefit from clarifying what a 'model' is in this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema description coverage, the description does not need to add parameter semantics. A baseline of 4 is appropriate as there is no gap to fill.
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 'List all available models' clearly states the action (list) and resource (models). It is specific enough, though it does not differentiate from sibling tools, which are mostly unrelated.
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?
No guidance is provided on when to use this tool versus alternatives. While there are no obvious sibling tools for listing models, the description lacks any context on prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all phone numbers associated with the ElevenLabs account
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims 'List all phone numbers' but the annotation openWorldHint=true indicates the result set may not be complete. This contradiction misleads the agent into assuming exhaustiveness. The description adds no other behavioral context beyond what annotations already provide.
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 a single sentence that immediately conveys the purpose with no extraneous words. It is front-loaded and efficient.
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?
Without considering the contradiction, the description is sufficient for a zero-parameter list tool with output schema present. However, the contradiction undermines completeness by providing false assurance of completeness. Also lacks mention of what fields are returned, though output schema may cover that.
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 are no parameters, and schema coverage is 100% (trivially). The description does not need to add parameter details. Baseline 4 applies per guidelines for zero parameters.
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 clearly states the action ('List all phone numbers') and the resource ('associated with the ElevenLabs account'), making it distinct from sibling tools like list_agents or list_conversations. The verb and resource are specific and unambiguous.
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?
No guidance on when to use this tool versus alternatives. However, given the simple nature (no parameters, clear listing), implicit usage is straightforward. A higher score would require explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make an outbound call using an ElevenLabs agent. Automatically detects provider type (Twilio or SIP trunk) and uses the appropriate API.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
Args:
agent_id: The ID of the agent that will handle the call
agent_phone_number_id: The ID of the phone number to use for the call
to_number: The phone number to call (E.164 format: +1xxxxxxxxxx)
Returns:
TextContent containing information about the call
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ||
| agent_phone_number_id | Yes | ||
| to_number | Yes |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and open-world hints. The description adds specifics: automatic provider detection and a cost warning about ElevenLabs API calls. This extends beyond annotations but does not detail all behavioral traits (e.g., call duration, error handling).
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 very concise, front-loaded with the purpose, followed by a cost warning and parameter list. No redundant sentences; every word adds value. The structure is clear and easy 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?
Given the tool's simplicity and presence of an output schema, the description adequately covers key aspects: purpose, parameters, return type, and cost implications. However, it lacks context on prerequisites (e.g., agent setup) or error scenarios, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides textual explanations for all three parameters (agent_id, agent_phone_number_id, to_number), including the expected format for to_number. This adds critical meaning beyond the schema, though descriptions are minimal and could include where to obtain IDs.
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 clearly states the tool's purpose: making an outbound call using an ElevenLabs agent. It specifies the action ('make'), resource ('ElevenLabs agent'), and includes automatic provider detection, which is a distinctive feature. The tool is unique among siblings as no other tool performs outbound calling.
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 includes a cost warning and explicitly states 'Only use when explicitly requested by the user,' providing a clear usage constraint. However, it does not mention when not to use this tool or suggest alternatives, though the sibling list implies uniqueness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play an audio file. Supports WAV and MP3 formats.
| Name | Required | Description | Default |
|---|---|---|---|
| input_file_path | Yes |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint: true, but the description does not elaborate on side effects (e.g., audio playback) or system requirements. Since annotations already cover basic behavioral intent, a moderate score is appropriate.
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 deliver the core purpose and format support with no extraneous words. Ideal brevity.
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?
Tool has one required param and an output schema, yet the description omits return behavior, required permissions, or playback context. Incomplete for an agent to fully understand usage.
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 input schema has one parameter (input_file_path) with no description, and the description does not explain it. With 0% schema coverage, the description fails to compensate.
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 clearly states the tool's function: 'Play an audio file.' It specifies supported formats (WAV and MP3), distinguishing it from sibling tools like text_to_speech or compose_music.
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?
No guidance on when to use this tool versus alternatives like speech_to_text or text_to_sound_effects. It lacks prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for a voice across the entire ElevenLabs voice library.
Args:
page: Page number to return (0-indexed)
page_size: Number of voices to return per page (1-100)
search: Search term to filter voices by
Returns:
TextContent containing information about the shared voices
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds no extra behavioral details (e.g., pagination limits, data freshness, or the implications of openWorldHint), failing to provide value beyond 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 concise, with a clear purpose sentence followed by a structured parameter list. Every sentence earns its place, and it is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and sibling tools, the description is moderately complete. It specifies return type ('TextContent about shared voices') but lacks context on open world behavior and differentiation from 'search_voices'. It is minimally adequate.
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?
Despite 0% schema description coverage, the description provides meaningful parameter semantics: explaning page indexing, page size range, and search term usage. This adds significant value over the bare schema, though more detail (e.g., search behavior) would improve it.
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 clearly states 'Search for a voice across the entire ElevenLabs voice library,' specifying the verb, resource, and scope (entire library), which distinguishes it from sibling tools like 'search_voices'.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., 'search_voices'). The description only lists parameters without contextual usage tips.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for existing voices, a voice that has already been added to the user's ElevenLabs voice library.
Searches in name, description, labels and category.
Args:
search: Search term to filter voices by. Searches in name, description, labels and category.
sort: Which field to sort by. `created_at_unix` might not be available for older voices.
sort_direction: Sort order, either ascending or descending.
Returns:
List of voices that match the search criteria.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | ||
| sort | No | name | |
| sort_direction | No | desc |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description adds value by detailing search behavior (fields searched) and a caveat about sort field 'created_at_unix' possibly missing. This is sufficient behavioral disclosure beyond 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 concise and front-loaded with the purpose. However, it redundantly states 'Searches in name, description, labels and category' both in the main description and the search param docstring. Minor redundancy, but overall well-structured.
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?
The description covers search functionality and sorting, and an output schema exists for return values. However, it lacks information on pagination, result limits, case sensitivity, or matching behavior. Given the tool's simplicity and the openWorldHint, this is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates well by explaining each parameter: 'search' describes the search fields, 'sort' notes a potential issue with older voices, and 'sort_direction' clarifies order. This adds context that the schema alone does not provide.
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 clearly states the tool searches for voices already added to the user's ElevenLabs voice library, specifying the verb 'search' and the resource 'voices in user's library'. It also lists searchable fields (name, description, labels, category), differentiating it from the sibling 'search_voice_library' which likely searches public voices.
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 provides clear context: it searches the user's own voice library across multiple fields. While it doesn't explicitly state when not to use it or compare to alternatives, the scope is well-defined, and the sibling name 'search_voice_library' implies a different usage. Minor lack of explicit exclusions prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transform audio from one voice to another using provided audio files. Saves output file to directory (default: $HOME/Desktop).
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
| Name | Required | Description | Default |
|---|---|---|---|
| input_file_path | Yes | ||
| voice_name | No | Adam | |
| output_directory | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Saves output file' indicating a write operation, but annotations include readOnlyHint: true, which suggests no side effects. This is a direct contradiction, meriting a score of 1.
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 concise with front-loaded purpose, but could benefit from structured parameter descriptions. The cost warning adds useful context without being verbose.
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 an output schema, the description does not need to explain return values. It covers basic functionality and output directory, but lacks details on output format or error handling. Adequate but could be more complete.
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%, but the description adds meaning by specifying that input_file_path should be audio files and that output_directory has a default of $HOME/Desktop. However, it does not fully explain all parameters (e.g., voice_name).
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 clearly states the tool transforms audio from one voice to another using provided audio files, which is a specific verb and resource. It implicitly distinguishes from siblings like text_to_speech or voice_clone by focusing on voice transformation.
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 warns about costs and says to use only when explicitly requested, but does not explicitly state when not to use or mention alternative tools. Usage guidance is implied but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transcribe speech from an audio file. When save_transcript_to_file=True: Saves output file to directory (default: $HOME/Desktop). When return_transcript_to_client_directly=True, always returns text directly regardless of output mode.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
Args:
file_path: Path to the audio file to transcribe
language_code: ISO 639-3 language code for transcription. If not provided, the language will be detected automatically.
diarize: Whether to diarize the audio file. If True, which speaker is currently speaking will be annotated in the transcription.
save_transcript_to_file: Whether to save the transcript to a file.
return_transcript_to_client_directly: Whether to return the transcript to the client directly.
output_directory: Directory where files should be saved (only used when saving files).
Defaults to $HOME/Desktop if not provided.
Returns:
TextContent containing the transcription or MCP resource with transcript data.
| Name | Required | Description | Default |
|---|---|---|---|
| input_file_path | Yes | ||
| language_code | No | ||
| diarize | No | ||
| save_transcript_to_file | No | ||
| return_transcript_to_client_directly | No | ||
| output_directory | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses API call and potential costs, and explains output behavior for both save and return modes. Annotations include readOnlyHint=true, which is consistent with not modifying input; description adds useful context beyond 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?
Well-structured with purpose, warning, args, and returns. Slightly lengthy but every sentence adds value. Front-loaded with core purpose.
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?
Covers all aspects: purpose, usage conditions (cost), parameters, return values, output location. With output schema present, description complements it well without redundancy.
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%, but the description thoroughly explains each parameter including defaults, the meaning of diarize, and default output directory. Adds significant value beyond the raw 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?
Description clearly states 'Transcribe speech from an audio file.' Specific verb and resource. Differentiates from sibling tools like speech_to_speech or text_to_speech.
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?
Includes cost warning and explicit instruction to use only when requested. Explains when save vs return modes apply. No explicit alternatives mentioned, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert text description of a sound effect to sound effect with a given duration. Saves output file to directory (default: $HOME/Desktop).
Duration must be between 0.5 and 5 seconds.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
Args:
text: Text description of the sound effect
duration_seconds: Duration of the sound effect in seconds
output_directory: Directory where files should be saved (only used when saving files).
Defaults to $HOME/Desktop if not provided.
loop: Whether to loop the sound effect. Defaults to False.
output_format (str, optional): Output format of the generated audio. Formatted as codec_sample_rate_bitrate. So an mp3 with 22.05kHz sample rate at 32kbs is represented as mp3_22050_32. MP3 with 192kbps bitrate requires you to be subscribed to Creator tier or above. PCM with 44.1kHz sample rate requires you to be subscribed to Pro tier or above. Note that the μ-law format (sometimes written mu-law, often approximated as u-law) is commonly used for Twilio audio inputs.
Defaults to "mp3_44100_128". Must be one of:
mp3_22050_32
mp3_44100_32
mp3_44100_64
mp3_44100_96
mp3_44100_128
mp3_44100_192
pcm_8000
pcm_16000
pcm_22050
pcm_24000
pcm_44100
ulaw_8000
alaw_8000
opus_48000_32
opus_48000_64
opus_48000_96
opus_48000_128
opus_48000_192
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| duration_seconds | No | ||
| output_directory | No | ||
| output_format | No | mp3_44100_128 | |
| loop | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool saves output files, implying a write operation, which contradicts the readOnlyHint annotation indicating the tool is read-only. This is a direct contradiction.
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 well-structured with a front-loaded summary, constraints, and cost warning. The arg list is detailed but not excessively verbose. Slightly long but efficient for the complexity.
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?
Covers parameters and warnings well, but fails to describe the output or return value (despite an output schema existing). The contradiction with annotations also reduces completeness.
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?
Despite 0% schema description coverage, the description thoroughly explains each parameter, including default values, allowed ranges, and format options (e.g., output_format details). This adds significant value 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 clearly states the tool converts text descriptions of sound effects to audio files with specified duration. It specifies default output directory and constraints. Differentiates from siblings like text_to_speech by focusing on sound effects.
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?
Provides explicit cost warning and instructs to use only when explicitly requested. However, it lacks explicit comparison to sibling tools or guidance on when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert text to speech with a given voice. Saves output file to directory (default: $HOME/Desktop).
Only one of voice_id or voice_name can be provided. If none are provided, the default voice will be used.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
Args:
text (str): The text to convert to speech.
voice_name (str, optional): The name of the voice to use.
model_id (str, optional): The model ID to use for speech synthesis. Options include:
- eleven_multilingual_v2: High quality multilingual model (29 languages)
- eleven_flash_v2_5: Fastest model with ultra-low latency (32 languages)
- eleven_turbo_v2_5: Balanced quality and speed (32 languages)
- eleven_flash_v2: Fast English-only model
- eleven_turbo_v2: Balanced English-only model
- eleven_monolingual_v1: Legacy English model
Defaults to eleven_multilingual_v2 or environment variable ELEVENLABS_MODEL_ID.
stability (float, optional): Stability of the generated audio. Determines how stable the voice is and the randomness between each generation. Lower values introduce broader emotional range for the voice. Higher values can result in a monotonous voice with limited emotion. Range is 0 to 1.
similarity_boost (float, optional): Similarity boost of the generated audio. Determines how closely the AI should adhere to the original voice when attempting to replicate it. Range is 0 to 1.
style (float, optional): Style of the generated audio. Determines the style exaggeration of the voice. This setting attempts to amplify the style of the original speaker. It does consume additional computational resources and might increase latency if set to anything other than 0. Range is 0 to 1.
use_speaker_boost (bool, optional): Use speaker boost of the generated audio. This setting boosts the similarity to the original speaker. Using this setting requires a slightly higher computational load, which in turn increases latency.
speed (float, optional): Speed of the generated audio. Controls the speed of the generated speech. Values range from 0.7 to 1.2, with 1.0 being the default speed. Lower values create slower, more deliberate speech while higher values produce faster-paced speech. Extreme values can impact the quality of the generated speech. Range is 0.7 to 1.2.
output_directory (str, optional): Directory where files should be saved (only used when saving files).
Defaults to $HOME/Desktop if not provided.
language: ISO 639-1 language code for the voice.
output_format (str, optional): Output format of the generated audio. Formatted as codec_sample_rate_bitrate. So an mp3 with 22.05kHz sample rate at 32kbs is represented as mp3_22050_32. MP3 with 192kbps bitrate requires you to be subscribed to Creator tier or above. PCM with 44.1kHz sample rate requires you to be subscribed to Pro tier or above. Note that the μ-law format (sometimes written mu-law, often approximated as u-law) is commonly used for Twilio audio inputs.
Defaults to "mp3_44100_128". Must be one of:
mp3_22050_32
mp3_44100_32
mp3_44100_64
mp3_44100_96
mp3_44100_128
mp3_44100_192
pcm_8000
pcm_16000
pcm_22050
pcm_24000
pcm_44100
ulaw_8000
alaw_8000
opus_48000_32
opus_48000_64
opus_48000_96
opus_48000_128
opus_48000_192
Returns:
Text content with file path or MCP resource with audio data, depending on output mode.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| voice_name | No | ||
| output_directory | No | ||
| voice_id | No | ||
| stability | No | ||
| similarity_boost | No | ||
| style | No | ||
| use_speaker_boost | No | ||
| speed | No | ||
| language | No | en | |
| output_format | No | mp3_44100_128 | |
| model_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotation readOnlyHint=true by stating it saves files and makes API calls, which are mutations. This is a serious inconsistency. The description itself does disclose behavioral traits (cost, file saving, API call), but the contradiction undermines trust.
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 structured into sections (Args, Returns) with a front-loaded cost warning. While verbose, it is organized and lacks redundancy. Minor room for tightening parameter descriptions without losing clarity.
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's complexity (12 params, API call, output modes, cost), the description covers purpose, parameter details, outputs, default behaviors, and warnings. It is self-contained and does not rely on external schema or annotations for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the tool description provides extensive semantics for all 12 parameters: ranges, defaults, enumerations (model_id, output_format), and explanations (e.g., stability, style, speed). This far exceeds the baseline and is critical for correct usage.
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 explicitly states 'Convert text to speech with a given voice' and specifies file saving behavior. It clearly distinguishes from sibling tools like speech_to_speech, text_to_voice, etc., by focusing on text-to-speech conversion.
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?
Includes a clear cost warning and instruction to use only when explicitly requested. Also clarifies constraint that only one of voice_id or voice_name can be provided. However, it does not explicitly compare to alternatives like text_to_voice or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create voice previews from a text prompt. Creates three previews with slight variations. Saves output file to directory (default: $HOME/Desktop).
If no text is provided, the tool will auto-generate text.
Voice preview files are saved as: voice_design_(generated_voice_id)_(timestamp).mp3
Example file name: voice_design_Ya2J5uIa5Pq14DNPsbC1_20250403_164949.mp3
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
| Name | Required | Description | Default |
|---|---|---|---|
| voice_description | Yes | ||
| text | No | ||
| output_directory | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description contradicts annotations: readOnlyHint=true but the tool makes a paid API call and saves files, implying mutation. Description adds cost warning and file creation details, but the contradiction undermines reliability.
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, includes naming convention and example. Each sentence provides useful information, though the cost warning could be integrated more succinctly.
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?
Output schema exists, so return values are not required. However, description omits what the tool returns (likely file paths) and does not explain the three previews' variations fully. Adequate but with gaps.
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 description must explain parameters. It partially explains 'text' and 'output_directory' but does not describe the required 'voice_description' parameter beyond its name.
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?
Description clearly states 'Create voice previews from a text prompt' and specifies three previews with variations. However, it does not differentiate from siblings like 'text_to_speech' or 'create_voice_from_preview'.
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 warns about cost and directs to use only when user requests. Includes context about auto-generation when no text provided, but does not mention exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an instant voice clone of a voice using provided audio files.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| files | Yes | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| type | Yes | |
| text | Yes | |
| annotations | No | |
| _meta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate openWorldHint: true, and the description adds explicit context about external API calls to ElevenLabs and potential costs. This goes beyond annotations, though some traits like file format requirements are omitted.
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 plus a warning are concise and front-loaded. The warning is clearly separated, but structure could be improved with bullet points or parameter details.
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 3 parameters and no output schema shown, the description lacks necessary details like audio format, length limits, and return value. It is insufficient for proper invocation given the complexity of voice cloning.
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%, and the description fails to explain what 'files' (paths, URLs?), 'name', or 'description' mean. No parameter details are provided, leaving critical gaps.
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 clearly states 'Create an instant voice clone of a voice using provided audio files,' specifying the verb and resource. It is distinct from sibling tools like text_to_voice or create_voice_from_preview, though it does not explicitly differentiate.
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 includes a cost warning and advises to use only when explicitly requested, but it does not provide when-not-to-use guidance or compare to alternative tools like search_voices or text_to_voice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_knowledge_base_to_agentcheck_subscriptioncompose_musiccreate_agentcreate_composition_plancreate_voice_from_previewget_agentget_conversationget_voiceisolate_audiolist_agentslist_conversationslist_modelslist_phone_numbersmake_outbound_callplay_audiosearch_voice_librarysearch_voicesspeech_to_speechspeech_to_texttext_to_sound_effectstext_to_speechtext_to_voicevoice_cloneScored across 24 tools
Most tools target distinct actions and resources, but `search_voice_library` and `search_voices` are similarly named and could cause confusion despite different scopes. Overall, tools are well-differentiated.
Tool names follow a verb_noun pattern consistently, with only minor variations like prepositions (e.g., 'add_knowledge_base_to_agent'). The pattern is predictable and readable.
24 tools cover a broad set of ElevenLabs features (TTS, STT, voice management, agents, calls, music, etc.). While on the higher side, it remains scoped to the service without excessive redundancy.
The tool set covers many core operations but lacks update and delete functionality for agents, voices, and other resources. Basic CRUD is incomplete, though major workflows are present.
Official MCP server for OmniDimension. Drive voice agents, dispatch calls, and run bulk campaigns.
Official MCP server for Lovable, the AI-powered full-stack app builder.
Official Microsoft Learn MCP Server – real-time, trusted docs & code samples for AI and LLMs.
AI voice generation: text-to-speech and voice cloning from any MCP client.
