Retell AI MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation5/5
Each tool targets a distinct resource type (phone numbers, agents, calls, LLMs, knowledge bases, conversation flows, chat agents, chats, batch, concurrency, MCP tools) with clear operations. Potential overlaps like retell_create_phone_call vs retell_create_web_call are differentiated by channel, and retell_list_agents vs retell_list_chat_agents are separated by chat/voice context.
Naming Consistency5/5
All tools follow the retell_verb_noun pattern with consistent verbs (list, get, create, update, delete). Exceptions like retell_add_knowledge_base_sources and retell_publish_agent are conventional and still follow the pattern. No mixing of conventions or ambiguous verbs.
Tool Count3/5
60 tools is well above the typical 3-15 range, but the server covers a broad platform API with many resource types. Each tool maps to a distinct operation, making the count justifiable. However, the sheer number may overwhelm agents, so it is not ideal.
Completeness4/5
The tool set provides comprehensive CRUD for all major resources, including lifecycle management for agents (versions, publish) and calls (list, get, create, update, delete, register). Minor gaps exist, such as no direct update for knowledge base metadata and no delete chat session, but these are not critical dead ends.
Average 3.7/5 across 60 of 60 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It only states the mutation action without explaining permissions, merge/replace semantics, effects of changing data_storage_setting, or response format. This is similar to the under-specified update_drive example.
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?
The description is a single sentence that is front-loaded with the action ('Update') and contains no filler or redundant words. It is appropriately brief and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four parameters including a nested object, no output schema, and no annotations, this description is too sparse. It omits a major capability (override_dynamic_variables), provides no usage context or alternatives, and does not address behavioral details, leaving the agent under-informed for correct invocation.
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?
The input schema already describes all four parameters with 100% coverage, so the baseline is 3. The description redundantly mentions metadata and data_storage_setting but adds no extra meaning beyond the schema, and it does not mention override_dynamic_variables.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' with the resource 'ongoing chat session' and mentions specific fields (metadata, data storage settings). It distinguishes from sibling tools like retell_update_chat_agent, but omits the override_dynamic_variables capability, making the scope incomplete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as retell_update_chat_agent or retell_update_call. The phrase 'ongoing chat session' only implies a context but does not provide explicit when/when-not decision criteria or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses no behavioral details such as side effects, return values, permissions, or whether the session is persistent. With no annotations provided to compensate, the agent has no information about what happens after starting a session.
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?
The description is a single concise sentence with no redundant wording. It is appropriately front-loaded and avoids unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not explain the return value or session lifecycle. Given that the tool creates a chat session, an agent would need to know what the session object looks like, any prerequisites, or how to reference it later. The schema covers parameters but not the tool's overall context.
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?
All four parameters are described in the input schema with 100% coverage, so the baseline is 3. The description does not add additional meaning to the parameters; the schema is sufficient for understanding them.
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?
The description uses a specific verb ('Start') and resource ('chat session'), clearly stating the tool's action. It is distinct from sibling tools like retell_create_chat_completion and retell_create_sms_chat, which involve different operations on chat or sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as create_chat_completion, create_sms_chat, or create_web_call. The description only states the action, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Release (delete)', which merely restates the tool's name and implies mutation. It does not mention irreversibility, required permissions, side effects, or any consequences, which is a significant gap for a destructive operation.
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?
The description is a single sentence, front-loaded with the verb 'Release', and contains no superfluous words. It is appropriately sized for a tool with a single parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations or output schema, the description is under-specified. It does not explain what happens on success/failure, whether deletion is permanent, or any conditions that must be met. The low complexity and complete schema do not fully compensate for the lack of behavioral context.
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% for the single parameter 'phone_number', which includes a description and example. The tool description adds no additional parameter information, but with high schema coverage, the baseline of 3 is appropriate.
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?
The description uses a specific verb 'Release (delete)' paired with the resource 'phone number from your Retell AI account', clearly distinguishing it from sibling tools like retell_create_phone_number or retell_list_phone_numbers. It unambiguously states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives or any exclusions (e.g., cannot delete a number that is assigned to an agent). The description simply restates the action without providing decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits, but it only says 'Update metadata or data storage settings.' It does not clarify whether metadata is merged or replaced, whether the data_storage_setting override is permanent, or any side effects or permission requirements. This leaves significant ambiguity for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and scope. Every word earns its place, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the schema covering parameter descriptions, the overall description is insufficient for a tool with no annotations and no output schema. It does not explain update semantics (merge vs replace), behavior when only some fields are provided, or any response expectations. An agent would need more context to invoke this correctly beyond just reading the schema.
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 description coverage is 100%, with each parameter (call_id, metadata, data_storage_setting) having a clear description. The tool description adds nothing beyond the schema, so the baseline score of 3 is appropriate.
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?
The description clearly states the action ('Update') and the resource ('existing call'), along with the specific scope ('metadata or data storage settings'). This distinguishes it from sibling tools like retell_get_call or retell_delete_call, which have different verbs and purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. While 'existing call' implies it is for post-creation updates, there is no mention of scenarios, exclusions, or relationships to related tools like retell_create_phone_call or retell_update_agent. The usage context is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It only says 'update configuration,' which is generic and does not explain whether the update is partial or full, what fields are affected, or what the response includes. Side effects and requirements are not disclosed.
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?
The description is a single, grammatically compact sentence that immediately states the tool's purpose. It contains no redundant or overly technical language and is easy to parse at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With seven parameters, no annotations, and no output schema, a one-line description is insufficient. It does not explain update semantics (merge vs. replace), the effect of omitting optional parameters, or expected return value. This leaves significant gaps for an agent invoking the tool correctly.
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?
The schema already provides descriptions for all seven parameters, achieving 100% schema description coverage. The tool description adds no additional parameter-level context, so it neither helps nor hurts beyond the schema. A baseline of 3 is appropriate given the coverage.
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?
The description clearly states the action ('Update') and the specific resource ('existing chat agent'), and the qualifier 'configuration' distinguishes it from create/delete operations. Sibling tools include both retell_update_agent and retell_update_chat_agent, so naming 'chat agent' explicitly eliminates ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as retell_update_agent or retell_update_call. No usage scenarios, prerequisites, or exclusions are mentioned, leaving the agent to infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'Update,' implying mutation, but provides no details about whether the update overwrites the entire flow, whether omitted fields are preserved, what data structure nodes must follow, or any side effects or prerequisites. This is a significant gap for a mutation tool with a complex schema.
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?
The description is a single, front-loaded sentence with no filler words. It immediately states the action and resource, making it efficiently scannable. Every word contributes to the core message, though the content could be richer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, nested-object mutation tool with no annotations and no output schema, a one-sentence description is inadequate. It does not explain update semantics (full vs partial), return values, or operational context. The schema provides param-level details but not the behavioral context needed to use the tool correctly.
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 description coverage is 100%, so each parameter is documented in the schema. The description adds little beyond listing a few updatable fields (nodes, model, prompt, tools) but omits others and introduces 'edges' without a corresponding parameter. It does not clarify parameter relationships or required combinations, so it neither adds significant value nor detracts from the already sufficient schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' and identifies the resource as an 'existing Conversation Flow,' clearly distinguishing it from create and delete siblings. It lists updatable aspects (nodes, edges, model, prompt, tools), though it omits some schema parameters (start_node_id, start_speaker, knowledge_base_ids, default_dynamic_variables) and includes 'edges' which is not an explicit parameter, causing slight ambiguity. Still, the core purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing Conversation Flow' implies the tool is for flows that already exist, providing basic usage context. However, it does not name alternatives such as create_conversation_flow for new flows or update_conversation_flow_component for component-level updates, nor does it state when not to use it. Guidance is only implied by the name and resource type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only restates the create operation and lists fields; it does not mention whether the created config is immediately usable, what response is returned, or any side effects/permissions needed.
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?
The description is a single, well-ordered sentence that front-loads the verb and resource and lists the main fields. It contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema fully documents parameters and the description conveys the core purpose, but with no annotations or output schema the description leaves out return behavior and usage context. It is adequate but not rich enough for a tool in a large sibling set.
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%, so the baseline is 3. The description loosely maps 'system prompt, model, begin message, and tools' to schema properties but omits knowledge_base_ids and adds no meaning beyond the schema's per-property descriptions.
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?
The description uses a specific verb and resource ('Create a new Retell LLM configuration') and adds the purpose 'to attach to agents.' This clearly distinguishes it from sibling tools like retell_create_agent and retell_create_chat_agent, which create different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool instead of alternatives, such as using retell_update_llm for an existing configuration or creating an agent afterward. The only contextual hint is 'to attach to agents,' which implies but does not specify workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Start an outbound SMS chat conversation' without revealing side effects (e.g., whether an SMS is immediately sent), error conditions, idempotency, or required preconditions. The one constraint it does mention ('using a phone number with SMS capability') is useful but insufficient for understanding operational behavior.
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?
The description is a single, well-structured sentence that front-loads the verb and object. It contains no filler, repetition, or unnecessary detail. Every word contributes to the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema, the description provides only the minimal purpose. It doesn't clarify what the returned conversation object looks like, whether the chat is immediately active, or how it relates to sibling chat tools. For a simple 'create' operation this may be acceptable, but the lack of an output schema and annotations leaves gaps for an agent.
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?
The input schema covers 100% of parameters, so the description is not required to add details. However, the description adds zero extra context about parameters (e.g., that 'from_number' must be a Retell-owned number or that 'to_number' is the customer). The baseline of 3 is appropriate because the schema already communicates the essentials.
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?
The description clearly states the action ('Start') and the resource ('outbound SMS chat conversation'), and specifies the requirement of 'a phone number with SMS capability'. This distinguishes it from sibling tools like retell_create_phone_call and retell_create_web_call, which handle different communication channels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool or how it compares to alternatives. It doesn't state prerequisites (e.g., need an SMS-capable number already configured) or situations where another tool would be more appropriate. This leaves the agent without clear selection criteria beyond the literal channel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it offers no extra context beyond the name. It does not mention whether deletion is permanent, whether associated data (e.g., transcripts, recordings) is affected, or any permission requirements.
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?
The description is a single, clear sentence with no filler words. It is appropriately sized for the simplicity of the tool and maximizes conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and full schema coverage, the description is adequate but not fully complete. It lacks an explicit statement about irreversibility or effects on related data, which is a clear gap for a delete tool.
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?
The input schema fully documents the only parameter, call_id, with a clear description ('The unique ID of the call to delete'). The tool description adds no additional parameter semantics, so it meets the baseline for high schema coverage.
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?
The description clearly states the tool deletes a call record, with a specific verb and resource. It distinguishes from sibling delete tools (e.g., retell_delete_phone_number, retell_delete_agent) by explicitly targeting 'call record'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like retell_get_call or retell_update_call. The description merely states the action without any context on appropriate usage scenarios or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It merely states the action without disclosing whether deletion is permanent, whether it cascades to sources, or any potential error states. This lack of consequence disclosure is a transparency gap.
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?
The description is a single, front-loaded sentence with no filler. Every word earns its place, and it is appropriately sized for a simple deletion operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is nearly complete operationally. It lacks any mention of return values, permanence, or side effects, which leaves some context gaps but is not severely incomplete.
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?
The input schema covers the single parameter 'knowledge_base_id' with a clear description. Since schema coverage is 100%, the baseline is 3. The description adds no additional semantic meaning beyond the schema.
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?
The description uses the specific verb 'Delete' with the resource 'knowledge base' and clarifies scope ('from your Retell AI account'). This clearly distinguishes it from sibling tools like retell_delete_knowledge_base_source or retell_delete_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, such as retell_delete_knowledge_base_source. There are no preconditions, exclusions, or context about choosing the entire knowledge base deletion over deleting individual sources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the destructive nature implicitly but does not mention that deletion is permanent, whether related resources are affected, or any permission requirements. This is minimal coverage for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that directly states the purpose. It is front-loaded and contains zero wasted words, making it easily scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one well-documented parameter, but the lack of annotations and output schema means the description should disclose more about side effects (e.g., permanent deletion) or expected outcomes. It is minimally viable but leaves gaps for an agent that needs to understand irreversible consequences.
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?
The schema already fully describes the only parameter (llm_id) with 100% coverage, so the description adds little beyond 'by its ID', which is redundant. The baseline of 3 applies because the schema carries the semantic weight.
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?
The description uses a specific verb ('Delete') and a specific resource ('Retell LLM configuration'), with an explicit identifier ('by its ID'). This clearly distinguishes it from sibling delete tools like retell_delete_agent or retell_delete_phone_number.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, whether this is preferred over updating an LLM, or any conditions under which deletion should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not explain the consequences of ending a chat (e.g., irreversibility, whether the chat is archived or deleted), nor any required state (e.g., chat must be active).
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?
The description is a single, front-loaded sentence with no filler words. It efficiently communicates the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema and no annotations, the description gives the minimal information. However, it lacks insight into the effects of ending a chat and any prerequisites, leaving some context incomplete.
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?
The input schema already fully describes the only parameter chat_id with 100% coverage. The description adds no additional parameter meaning, so baseline 3 is appropriate.
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?
The description uses the specific verb 'End' and clearly identifies the resource as 'an ongoing chat session,' which distinguishes it from sibling chat tools like retell_create_chat, retell_get_chat, and retell_update_chat (which do not include an 'end' operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description only states the action without specifying when to use it, prerequisites (e.g., chat must be ongoing), or alternatives (e.g., is this different from deleting a chat?).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Get details' without specifying whether the agent object is returned in full, what happens if the ID doesn't exist, or any permissions or limits. It adds minimal context beyond the basic 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no filler words. It front-loads the verb and resource, making it immediately actionable. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is minimally viable but leaves gaps. It doesn't specify what 'details' includes, whether the response is the full object, or how it differs from 'retell_get_chat_agent_versions'. It could be more complete by naming the return type or expected behavior.
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 description coverage is 100% — the 'agent_id' property is described as 'The unique ID of the chat agent.' The description's 'by its ID' reinforces the parameter's purpose but doesn't add meaningful syntax or format details beyond what the schema already provides. Baseline 3 is appropriate for full schema coverage.
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?
The description clearly states the action ('Get details'), the resource ('chat agent'), and the lookup scope ('by its ID'). This unambiguously distinguishes it from listing, creating, updating, or deleting chat agents, and also from the sibling 'retell_get_agent' for regular agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that you should first retrieve an agent ID via 'retell_list_chat_agents', nor does it note exclusions (e.g., not for getting versions). The usage context is only implied by the tool's name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Get all published versions,' but does not explain whether the response is paginated, what fields are returned, or what happens if the agent has no versions. The term 'published' adds a small qualifier but fails to describe other relevant behaviors.
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?
The description is a single, concise sentence that contains no filler or redundancy. It is front-loaded with the action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one required parameter, no output schema, no nested objects), the minimal description might be sufficient for a simple read operation. However, it omits details like pagination or version count, which could matter when listing versions. It is adequate but not rich.
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?
The input schema already provides a 100% description coverage for the single parameter 'agent_id.' The description does not add additional parameter-level meaning, so the baseline of 3 is appropriate.
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?
The description clearly states the verb 'Get' and the resource 'published versions of a chat agent,' which is specific and distinct from sibling tools like retell_get_agent_versions (for regular agents). It unambiguously conveys the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention that this is for chat agents specifically or contrast it with retell_get_agent_versions or retell_publish_chat_agent. There is no 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits on its own. It only states the immediate action and response, but does not mention that sending a message mutates the chat state, potential side effects, permissions, error behavior, or response format. This is a significant gap for a tool that modifies a session.
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?
The description is a single, efficient sentence that front-loads the action verb and clearly states the expected outcome. There is no filler or redundancy; every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple signature, but there is no output schema and no annotations. The description does not cover prerequisites (e.g., how to obtain chat_id), the exact structure of the response, or side effects. The information provided is insufficient for an agent to fully understand the tool's behavior and context.
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 description coverage is 100%, with both parameters already described ('chat_id' and 'content'). The description adds no additional meaning or detail beyond what the schema already provides, so the baseline score of 3 is appropriate.
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?
The description uses a specific verb ('send') and names the resource ('user message to an ongoing chat session'), clearly indicating the action and what is returned ('get the agent's response'). This distinguishes it from sibling tools like retell_create_chat (which creates a session) or retell_update_chat (which updates settings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'ongoing chat session' implies the tool requires an existing chat_id, providing some usage context, but it does not explicitly state when to use this tool versus alternatives or mention exclusions. The guidance is implied rather than clearly articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits on its own. It only states that a call is initiated and requires a purchased from_number; it does not describe whether the call is asynchronous, what the return value is, billing/side effects, or error behavior. This is insufficient for a side-effectful action.
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?
Two sentences, immediately states the core action, no filler. The second sentence covers prerequisites. Very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a well-covered schema, the tool has no output schema and no annotations, and it performs a side-effectful action (placing a call). The description is too brief to convey what happens after initiation, whether it returns a call object, or how it differs from related tools. It leaves significant operational context unexplained.
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?
All five parameters are documented in the schema with descriptions (100% coverage), so the description does not need to repeat parameter detail. The description adds minimal reinforcement that from_number must be purchased, which is already stated in the schema. Baseline 3 is appropriate.
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?
The description uses a specific verb ('Initiate') and resource ('outbound phone call via a Retell AI agent'), clearly conveying the action and distinguishing it from sibling tools like web calls and batch calls. It also identifies key prerequisites (purchased from_number, destination to_number).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context implies usage when the agent needs to make an outbound call with a purchased number, but it does not explicitly state when to use this instead of alternatives like create_web_call, create_batch_call, or register_phone_call, nor does it mention exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It merely restates the listing action without disclosing behavioral traits like pagination, authentication requirements, rate limits, or what 'all' entails. It adds no value beyond the tool name.
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?
The description is a single, clear sentence with no wasted words. It is appropriately sized for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain what the tool returns. It doesn't mention the return format or any side effects. For an agent selecting this tool, the lack of return information is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description doesn't need to explain parameter semantics. The baseline of 4 applies since no parameter details are required.
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?
The description uses a specific verb ('List') and specifies the resource ('knowledge bases') with clear scope ('in your Retell AI account'). This distinguishes it from other list tools like retell_list_phone_numbers and retell_list_agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It only states the action without any context such as prerequisites, exclusions, or alternative tools like retell_get_knowledge_base for retrieving a single knowledge base.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It mentions the ability to switch response engine types, but does not disclose whether the update is partial or full, potential side effects, authentication needs, or required relationships among parameters. For a mutation tool, this is a significant transparency gap.
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?
The description is a single, focused sentence that front-loads the core purpose and the key differentiator. Every word earns its place, providing high clarity without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 12 parameters, no annotations, and no output schema. The description does not explain update behavior (e.g., partial vs full replacement), mutual exclusivity of engine parameters, or return values. It leaves many critical operational details unaddressed, making it incomplete for safe autonomous invocation.
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?
The input schema has 100% parameter description coverage, so the schema already documents each parameter. The description adds minimal value by grouping engine-related parameters into a conceptual 'response engine type' switch, but does not explain inter-parameter constraints or provide deeper semantics beyond what the schema offers.
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?
The description clearly states the verb 'Update' and the resource 'existing Retell AI agent's configuration', and highlights a specific capability (switching response engine types) that distinguishes this tool from siblings like retell_create_agent or retell_delete_agent. It is 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for existing agents via the word 'existing', but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It is clear enough to infer the tool is for updates, but lacks direct usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry full behavioral disclosure. It fails to mention whether the update is a partial patch or full replacement, what happens to unset fields like start_node_id, or any permissions or side effects. The mention of 'existing' implies it fails if the component does not exist, but this is not explicit.
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?
The description is a single, focused sentence that front-loads the action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is insufficient for an update operation. It does not specify whether the response is the updated component, whether fields not mentioned are preserved or reset, or how to handle the start_node_id parameter. The moderate complexity of five parameters is not fully addressed.
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 already describes all five parameters with 100% coverage, so the description adds little beyond naming three fields (name, nodes, tools). It omits start_node_id, but the schema covers it. 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?
The description clearly states the action (update), the resource (shared Conversation Flow Component), and the specific attributes (name, nodes, or tools). It distinguishes from sibling tools like retell_update_conversation_flow by explicitly naming the component resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 such as retell_create_conversation_flow_component or retell_update_conversation_flow. The usage is implied by the name but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It says 'update' which implies mutation, but it doesn't mention potential side effects, reversibility, permission requirements, or what happens when unsetting agent IDs. The behavior of passing empty strings is left to the schema, not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and resource, and it conveys the core purpose without unnecessary words. It could be slightly more detailed, but it is concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple update tool with 4 well-documented parameters and no output schema. The description is sufficient for basic understanding, but given no annotations and no output schema, it would benefit from a mention of return behavior or success/failure indicators. It is minimally complete but has gaps.
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 description coverage is 100%, so the schema fully explains each parameter. The description itself adds no additional parameter semantics beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
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?
The description clearly states the tool updates agent binding or settings for an existing phone number, using the specific verb 'update' and identifying the resource ('existing phone number'). It distinguishes from sibling tools like retell_create_phone_number and retell_delete_phone_number by focusing on modifying existing numbers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when updating an existing phone number's settings), but it does not explicitly state alternatives or exclusions. For example, it doesn't mention that creating a phone number should use retell_create_phone_number. Usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the action ('Schedule a batch of outbound phone calls') but does not disclose side effects, permissions needed, scheduling behavior (e.g., immediate vs. delayed), or the fact that calls will actually be placed. This is a significant gap for a mutation/scheduling tool.
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?
The description is two concise sentences with no waste. It front-loads the primary purpose and immediately covers key task details. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no output schema. The description gives a general overview of batching and per-call options, but it does not mention the trigger_timestamp behavior (scheduling delay vs. immediate), what the response returns, or other important context like required agent setup. Given the schema covers parameter details, the description is minimally adequate but not fully complete for a batch scheduling tool.
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 description coverage is 100%, so the schema already documents all parameters. The description adds a brief note that tasks specify a destination number and may include overrides/dynamic variables, which somewhat overlaps with the schema. This provides marginal value beyond the schema, so the baseline of 3 is appropriate.
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?
The description clearly states 'Schedule a batch of outbound phone calls', which uses a specific verb and resource. The word 'batch' distinguishes it from single-call siblings like retell_create_phone_call and retell_create_web_call, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for scheduling multiple calls at once, but it does not explicitly mention when to choose this tool over alternatives like retell_create_phone_call or retell_create_batch_test. There are no exclusions or alternative references, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. It adds useful domain context (node types, edges, dialogue control) but does not disclose behavioral traits like validation rules, return values, or side effects beyond the obvious 'create' mutation. The information is accurate but skeletal.
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?
Two sentences, front-loaded with purpose and followed by a clear definition. Every word earns its place; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (8 params, nested objects) and there is no output schema, so more context would help. The description defines the core concept but omits expected return value, validation behaviors, and relationship to conversation flow components. Still, the schema compensates heavily for parameter details.
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%, so the baseline is 3. The description adds a bit of meaning by mentioning node types and edges, which complements the nodes parameter definition, but it adds little beyond what the schema already states.
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?
The description states 'Create a new Conversation Flow' with a specific verb and resource, and clarifies what a Conversation Flow is (a node-graph controlling agent dialogue). This clearly distinguishes it from other create tools for agents, LLMs, phone numbers, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 update_conversation_flow, delete_conversation_flow, or create_conversation_flow_component. There are no mentions of prerequisites (e.g., needing an LLM or knowledge base) or workflows such as attaching the created flow to an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the core action. It does not mention billing/financial implications, side effects, irreversibility, or what happens if area_code is omitted. The word 'purchase' hints at cost but is not explicit.
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?
A single, front-loaded sentence captures the essential purpose and key optional behavior with zero unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with complete schema documentation, but the description omits important contextual details for a purchase action, such as cost implications, default area code behavior, or return value. It is adequate but not thorough.
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?
The input schema has 100% description coverage, with each parameter clearly documented. The description adds a minor context about binding to an agent, but it does not go beyond what the schema already provides, so it earns the baseline 3.
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?
The description clearly states the action (purchase) and resource (new US phone number), with an optional binding to an agent. It distinguishes itself from sibling tools like retell_list_phone_numbers and retell_delete_phone_number by focusing on creating a new number.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use it (when you need to purchase a new number) but provides no explicit guidance on alternatives or exclusions, such as using retell_import_phone_number for existing numbers. The context is implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits on its own. It merely restates the operation name ('Get details') without explaining return format, error handling, authentication needs, or what 'details' actually includes. This leaves significant transparency gaps for the agent.
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?
The description is a single, directly worded sentence with no filler. 'Get details about a specific knowledge base' immediately conveys the action and object, and the front-loaded structure makes it highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, so the description must carry the burden of explaining what is returned. However, it does not specify the shape or content of the 'details,' nor any error conditions. It is minimally adequate for a straightforward read operation but lacks full contextual completeness.
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?
The description does not discuss the parameter, but the input schema fully describes knowledge_base_id as 'The unique ID of the knowledge base.' Since schema description coverage is 100%, the baseline of 3 applies. The description adds no additional semantic value beyond the schema.
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?
The description clearly states the action ('Get') and the resource ('knowledge base'), with the modifier 'specific' indicating a single entity. This distinguishes it from sibling tools like list_knowledge_bases (plural), create, and delete, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the agent has a knowledge_base_id and needs details, but it does not explicitly state when to choose this over list_knowledge_bases or mention alternatives. No exclusions or comparative guidance is given, so the usage context is only implied by the terminology.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action 'Update' without detailing side effects, partial update semantics, permissions, or return behavior, which is no more than what the tool name already implies.
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?
The description is a single, front-loaded sentence with no fluff. Every word contributes to stating the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update call, the description is adequate but incomplete: it lacks mention of whether the update is partial or replaces all fields, and it doesn't describe what the response contains since no output schema exists.
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?
All five parameters are described in the input schema (100% coverage), so the baseline is 3. The description's mention of 'prompt, model, or tools' loosely maps to some parameters but adds no detail beyond the schema's descriptions.
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?
The description uses a specific verb ('Update') and names the resource ('existing Retell LLM configuration'), and it lists the updatable aspects ('prompt, model, or tools'), which distinguishes it from sibling tools like retell_create_llm or retell_delete_llm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for updating an existing LLM configuration, but it provides no guidance on when to choose this over alternatives or when not to use it. No exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects, resource usage, and outcome, but it only states the action. It does not mention that this creates a batch run, potentially consumes concurrency, whether it is asynchronous, or how results are retrieved. The reserved_concurrency parameter hints at resource impact, but the description itself omits this.
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?
The description is a single clear sentence with no redundant words. It immediately states the action and the subject, making it highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must explain what happens after invocation, but it does not. It is unclear whether the batch test runs synchronously, how results are accessed, or whether concurrency reservation is required. This is a significant gap for a resource-intensive operation.
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?
The schema provides 100% coverage with descriptive text for all three parameters, including allowed structures for response_engine. The description adds no additional parameter detail, but the schema is sufficient, so 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?
The description uses a specific verb phrase ('Run a batch of automated test cases') and clearly specifies the target resources ('Retell LLM or Conversation Flow response engine'). No sibling tool fulfills this testing role, so it is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: when you need to run automated tests against an LLM or Conversation Flow. It does not explicitly state exclusions or alternative tools, but no competing testing tool exists in the sibling list, so the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It is very thin: it does not disclose that this is a write/mutation operation, whether it creates a new phone number resource, any permissions or prerequisites (e.g., SIP trunk authentication), idempotency, or the response format. The optional agent binding is mentioned but side effects are otherwise opaque.
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?
The description is a single sentence that front-loads the core purpose and includes the key optional capability. Every word earns its place; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and no annotations, the one-sentence description is insufficient. It doesn't cover prerequisites, what happens after import, or how it differs from retell_create_phone_number. An agent would need more context to select and invoke this tool confidently.
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 description coverage is 100%, so all parameters have meaning. The description adds minimal context by framing them under 'custom telephony (SIP trunk)' and 'optionally bind agents,' but it doesn't explain parameter relationships or anything beyond the schema. Baseline 3 is appropriate.
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?
The description clearly states the tool imports a phone number from the user's own custom telephony (SIP trunk) and optionally binds agents. The verb 'Import' is specific and the resource 'phone number' is identified, distinguishing it from sibling tools like retell_create_phone_number by specifying the source as a custom SIP trunk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when importing a number from a custom SIP trunk. It doesn't explicitly name alternatives or exclusions, but the phrasing implies this is for existing custom telephony setups. It could be stronger with an explicit contrast to retell_create_phone_number for Retell-provisioned numbers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description only states the basic create action and the component's purpose; it does not mention any side effects, required permissions, idempotency, return value, or error conditions. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences. It contains no redundant information or filler, immediately delivering the core purpose and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with a well-documented schema, the description provides essential context about the tool's purpose. However, the absence of an output schema means the agent has no information about the return value, and the lack of behavioral notes (e.g., duplicate handling, permission requirements) leaves some gaps. It is adequate but not thorough.
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 description coverage is 100%, so the schema fully documents all four parameters. The description adds general context about the nature of components (reusable sub-flows) but does not provide additional specifics about parameter syntax or semantics beyond what the schema already offers.
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?
The description clearly states the action ('Create a new shared Conversation Flow Component') and defines what a component is ('reusable sub-flows that can be embedded across multiple Conversation Flows'). This distinguishes it from sibling tools like create_conversation_flow, which creates a full flow rather than a reusable component.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by explaining that components are reusable sub-flows embedded across multiple Conversation Flows, implying when to use this tool. However, it does not explicitly mention when not to use it or name alternative tools, but the context is sufficient for an agent to infer the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It merely states 'Remove' without disclosing whether the action is permanent, whether there are side effects, or any error conditions. The agent cannot infer whether this is a safe read-like operation or a destructive one with consequences.
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?
The description is a single, well-structured sentence that is concise and front-loaded. It includes the verb, object, and scope without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 parameters, no output schema, no annotations), so the description is adequate for basic invocation. However, it lacks important safety context (e.g., irreversibility, behavior on missing source) and doesn't explain what the response will look like, leaving some gaps for a deletion operation.
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 description coverage is 100% - both parameters have descriptions. The tool description does not add extra meaning beyond what the schema already provides, so the baseline score of 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?
The description clearly states the action ('Remove'), the specific resource ('a specific source from an existing knowledge base'), and the method ('by its source ID'). This distinguishes it from siblings like retell_delete_knowledge_base (removes entire KB) and retell_add_knowledge_base_sources (adds sources).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: removing a specific source from an existing knowledge base by source ID. It implies this is for single-source removal, but does not explicitly mention alternatives or exclusions. The sibling list helps infer when to use it, but no direct 'use instead of X' guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It conveys a read-only operation via 'Get' and adds 'detailed information' as context, but it does not mention error scenarios (e.g., missing agent), permission requirements, or the exact structure of the returned data. This is adequate but not fully transparent.
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?
The description is a single, front-loaded sentence that captures the essential purpose and parameter without any wasted words. It is appropriately concise and well-structured for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is minimal but serviceable. It fails to specify what fields 'detailed information' includes or how it differs from other get-type tools like retell_get_agent_versions. Given the simplicity, a 3 reflects a complete-but-basic offering.
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?
The input schema already documents agent_id with 100% coverage, and the description only repeats that retrieval is 'by its ID'. No additional semantic detail about the parameter or its expected format is provided, so the description adds nothing beyond the schema.
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?
The description clearly states the action ('Get'), the resource ('detailed information about a specific Retell AI agent'), and the scope ('by its ID'). This effectively distinguishes it from siblings like retell_list_agents (which lists many agents) and retell_get_agent_versions (which retrieves version history).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied: use this tool when you have an agent_id and need detailed information. However, it does not explicitly state when to use it over alternatives (e.g., 'use list_agents to find IDs') or exclude related tools like retell_get_agent_versions, leaving the guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It clearly indicates a read-only operation that returns all chat agents, but it does not disclose pagination, response format, or whether only active agents are included. The scope is clarified, yet operational details are missing for a tool with no other behavioral metadata.
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?
The description is a single, concise sentence that clearly states the action and resource. It is front-loaded and contains no filler or redundant information, making it a model of brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (no parameters, no output schema), and the description communicates the core scope. However, it does not specify the return payload structure or any handling of large result sets. While adequate for a trivial list operation, it leaves the agent to infer the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema is empty. The baseline is 4, and the description correctly remains silent on parameters. No additional semantic value is needed since no inputs exist.
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?
The description uses the specific verb 'List' and the resource 'chat (text/messaging) agents' with a clear scope ('in your Retell AI account'). It explicitly distinguishes this tool from sibling tools like retell_list_agents or retell_list_phone_numbers by specifying the agent type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as retell_list_agents. It does not mention whether retell_list_agents covers voice agents or when to prefer this specific listing. No exclusions or alternative suggestions are provided, leaving the agent to rely on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the action, without disclosing side effects, prerequisites (e.g., KB must exist), potential errors, or idempotency. A more transparent description would mention that sources are appended and whether duplicates are checked.
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?
A single, front-loaded sentence with no waste. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple add tool with well-defined schema, the description is sufficient for selection. It lacks return-value details, but the absence of an output schema makes this less critical. The context is adequately complete for its simplicity.
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%, with each parameter described. The description's mention of 'text or URL sources' aligns with the schema but doesn't add meaningful new semantics beyond what the parameter descriptions already provide.
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?
The description clearly states the action and resource: 'Add new text or URL sources to an existing knowledge base.' It distinguishes from sibling tools like create_knowledge_base and delete_knowledge_base_source by specifying the operation (add) and the target (existing KB).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use this tool to add sources to an existing KB, as opposed to creating a KB. It doesn't explicitly mention alternatives, but the context is clear enough for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the permanent, destructive nature of the operation ('permanently delete'), which is critical. However, it does not mention side effects, whether associated objects are removed, or error behavior if the agent does not exist.
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?
The description is a single concise sentence with zero wasted words. It states the action, resource, permanence, and required identifier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple unary delete tool, the description is complete enough: it states what it does and the permanence. It lacks return value or error details, but given the tool's simplicity and poor output schema absence, this is acceptable.
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?
The input schema provides 100% coverage for the single parameter, agent_id, with a clear description. The tool description adds only 'by its ID', which is redundant with the schema. Baseline score of 3 is appropriate since the schema does the heavy lifting.
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?
The description uses a specific verb 'delete' and resource 'Retell AI agent' with the scope 'by its ID', making it distinct from sibling delete tools targeting other resources (e.g., retell_delete_call, retell_delete_llm). Fully clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to permanently delete an agent), but it does not explicitly mention alternatives or exclusions. It lacks guidance such as 'use retell_update_agent to modify instead' or 'use retell_get_agent to verify before deletion'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It does state the operation is permanent, which is a crucial destructive trait. However, it does not mention permissions, side effects, or error behavior, which are relevant for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and object. It contains no unnecessary words or redundancy, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter delete operation, the description is complete enough: it identifies the resource, specifies permanent deletion, and the parameter is well-documented. The absence of an output schema makes return value details less critical, though a note on result or error could elevate completeness.
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% with a single parameter, agent_id, fully described in the schema as 'The unique ID of the chat agent to delete.' The description adds no extra parameter semantics beyond confirming the ID's role.
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?
The description uses a specific verb ('Permanently delete') and resource ('chat agent') with a clear method ('by its ID'). This distinguishes it from sibling delete tools like retell_delete_agent and retell_delete_phone_number, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage based on the resource type 'chat agent' but does not explicitly state when to use this tool versus alternatives like retell_delete_agent. No exclusions or alternative pointers are provided, leaving the guidelines somewhat implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that the tool returns transcript, recording URL, latency, and cost, which is useful behavioral context. However, it does not mention any potential side effects (unlikely for a get), permissions, or error behavior, so transparency is adequate but not rich.
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?
The description is a single, focused sentence that leads with the core action and then lists valuable specifics. Every word earns its place; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with one parameter and no output schema, the description is fairly complete. It states the tool's purpose and enumerates the main return fields, which is sufficient for an agent to know what to expect. It does not explain error cases or authentication, but these are less critical for a read-only get operation.
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?
The schema already provides 100% coverage for call_id, and the tool description does not add significant meaning beyond the schema. The description's mention of 'specific call' reinforces the parameter's purpose, but no extra detail is added. Baseline 3 is appropriate given high schema coverage.
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?
The description uses a specific verb ('Get'), names the resource ('a specific call'), and enumerates key details ('transcript, recording URL, latency, and cost'). This clearly distinguishes it from sibling tools like retell_list_calls, which lists calls, and retell_delete_call, which deletes one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: you need a specific call_id and want full details. However, it does not explicitly mention when to use it versus alternatives (e.g., 'use retell_list_calls to find call IDs') or any exclusion criteria. The guidance is implicit and minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavior disclosure. The verb 'Get' implies read-only, but it does not explicitly state 'read-only' or describe what the transcript contains (e.g., messages, timestamps). It also does not mention error behavior for invalid chat_ids. The description adds some context (details and transcript) but lacks depth.
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?
The description is a single sentence, front-loaded with the verb 'Get,' and contains no unnecessary words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is nearly complete. It states what the tool returns (details and transcript) and the target (specific chat session). It could mention that the chat_id is required or that the tool only works for existing chats, but these are minor gaps given the simplicity.
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 description coverage is 100%, so the baseline is 3. The description only says 'specific chat session,' which aligns with the chat_id parameter's schema description ('The unique ID of the chat session.') without adding extra meaning or format details beyond the schema.
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?
The description clearly states the verb 'Get' and the resource 'details and transcript of a specific chat session.' It distinguishes from sibling tools like retell_list_chats (which lists all chats) and retell_get_chat_agent (which retrieves agent configuration), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this when you have a chat_id and want the details/transcript of that specific session. However, it does not explicitly provide when-to-use vs alternatives, such as 'to find a chat_id, use list_chats first.' No exclusions are mentioned, but the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It simply says 'Get full details' without mentioning response format, error behavior, permissions, rate limits, or side effects. While 'Get' implies a read-only operation, the description does not add any meaningful behavioral context beyond what the name and schema already suggest.
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?
The description is a single, concise sentence that front-loads the core action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one parameter and no output schema, the description is almost complete. It clearly states the purpose and implies usage, but it does not explicitly describe the return value or any error conditions. Nonetheless, the simplicity of the tool limits the need for more detail.
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?
The input schema has 100% coverage, with the only parameter 'conversation_flow_component_id' described as 'The unique ID of the Conversation Flow Component to retrieve.' The description adds no additional parameter semantics, so the baseline of 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?
The description clearly states the tool retrieves full details of a specific shared Conversation Flow Component, using the specific verb 'Get' and resource. It distinguishes well from sibling tools like retell_get_conversation_flow (which gets a conversation flow, not a component) and retell_list_conversation_flow_components (which lists components).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: when you have a specific component ID and need its full details. It does not explicitly name alternatives or exclusions, but the context is clear given the tool name and the presence of a single required ID parameter. Since there is no explicit exclusion or alternative mention, it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden for behavioral disclosure. 'Get' implies a read-only operation, but the description does not explicitly state safety, error behaviors, or what exactly is returned. It adds minimal context beyond the tool name.
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?
The description is a single, focused sentence that immediately states the tool's purpose. It uses no unnecessary words and is well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description is adequate. It communicates that the result is 'details' of the configuration, though it could be more explicit about the return format or that it is a read-only operation. Overall, it is complete enough for a simple retrieval tool.
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 description coverage is 100% with llm_id well-defined as 'The unique ID of the LLM to retrieve.' The description does not add additional meaning to the parameter, but the schema already provides sufficient clarity, so baseline 3 is appropriate.
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?
The description clearly states the tool retrieves details of a specific Retell LLM configuration, using the verb 'Get' and specifying the resource. This distinguishes it from sibling tools like retell_list_llms (which lists all) and retell_create_llm/update/delete (which mutate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific LLM ID, but provides no explicit guidance on when to choose this over alternatives like retell_list_llms. It does not state exclusions or mention that this is for a single item vs. listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It indicates the tool returns details and the associated agent, but it does not explicitly state that it is read-only or describe error behavior. The 'get' verb implies safety, so this is adequate but not rich.
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?
The description is a single, direct sentence that is front-loaded with the action and resource. Every word is useful, with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get operation with one well-documented parameter and no output schema, the description sufficiently conveys the purpose and key expected content (details and associated agent). It could be more explicit about what 'details' means, but it is complete enough for this complexity.
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?
The schema provides 100% coverage with a clear description of the phone_number parameter. The tool description does not add additional semantic detail beyond what the schema already offers, so the baseline of 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?
The description clearly states the action ('Get details') and the specific resource ('a specific phone number'), distinguishing it from sibling tools like list or delete phone numbers. The additional mention of 'including its associated agent' further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for retrieving a single, specific phone number, but it does not explicitly state when to use it over alternatives like list_phone_numbers or provide any exclusions. Usage context is somewhat clear from the singular reference, but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description relies on 'List' to signal a read-only operation, which is a weak but acceptable disclosure. It does not explicitly confirm non-destructive behavior, auth needs, or rate limits, but it does mention account scoping and supported features.
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?
The description is two sentences: the first states the core purpose, and the second lists key capabilities. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation, the description covers the primary function, filters, and pagination in a concise way. Since there is no output schema, it could have briefly described the return format, but that's a minor gap given the tool's simplicity. Overall, it provides a solid baseline for an agent to select and use the tool.
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%, so the parameters are already fully documented. The description's mention of filtering by agent ID, status, and date range adds no new meaning beyond the schema; pagination_key is also already described in the schema.
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?
The description opens with 'List calls in your Retell AI account' — a specific verb and resource. This clearly distinguishes it from siblings like retell_get_call (which retrieves a single call) and other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions supported filters and pagination, which implies when to use the tool, but it does not explicitly contrast with alternatives or state exclusions. There is no reference to when a different tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the operation is a list, which implies read-only, but does not disclose return format, pagination, or what fields are included. There is no mention of whether components are returned with configuration metadata or any statement about non-mutating behavior beyond the verb 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?
Two tight sentences: the first declares the action and scope, the second explains the concept. No unnecessary words, and the tool's purpose is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the scope of the operation for a param-less list: it says 'all' and defines the resource. However, it does not describe the response shape or any filtering indicators, nor does it mention that a `get_conversation_flow_component` exists for single-item retrieval. For a simple list, this is adequate but could be slightly more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema description coverage is effectively 100%. Baseline for 0 params is 4; the description correctly omits parameter talk since there are none, and no additional meaning is needed.
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?
The description uses a specific verb ('List') and resource ('shared Conversation Flow Components in your account'), clearly distinguishing it from sibling get/create/update/delete operations. It also defines what components are, which reinforces the resource identity and adds clarity beyond the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like `retell_get_conversation_flow_component` for a single component. The purpose is implied by the list action, but no exclusions or alternative tool mentions are provided; a sentence mentioning the singular getter would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the basic action and inputs but does not disclose any side effects or operational details, such as whether URL crawling is asynchronous, whether duplicates are handled, or what the returned object looks like. For a create tool, this is adequate but not rich.
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?
The description is a single sentence, front-loaded with the essential action and resource. Every word adds value, and it is immediately scannable. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three simple, well-described parameters and no output schema, this description is largely complete. It explains the purpose and the two input modes. It lacks guidance on follow-up actions or return value, but given the simplicity and high schema coverage, the gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explicitly stating that you can provide plain-text sources, URLs, or both, which clarifies the relationship between knowledge_base_texts and knowledge_base_urls—something not apparent from the schema alone. This slightly exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and the resource (knowledge base for RAG), and it mentions that you can provide plain-text sources, URLs, or both, which gives a good sense of what the tool does. It doesn't explicitly distinguish from retell_add_knowledge_base_sources, but the verb 'create' and the mention of 'new' make the primary purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when you need to create a new knowledge base with initial sources. It does not provide explicit alternatives or exclusions, but the context is clear enough for an agent to select it over sibling tools like add/delete/list. A mention of adding sources later would have made it a 5, but as-is it's solid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the content returned (nodes, edges, tools) and the verb 'Get' implies read-only, but it does not explicitly confirm side-effect-free behavior or describe error responses for non-existent flows.
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?
A single sentence that is front-loaded with the action and resource, concise and without unnecessary words.
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?
For a simple getter with one well-documented parameter and no output schema, the description adequately specifies what is returned and identifies the resource. It is complete given the low complexity and presence of sibling tools.
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?
The input schema fully documents the single parameter conversation_flow_id with 100% coverage. The description merely references a 'specific Conversation Flow' without adding meaning beyond the schema.
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?
The description uses the specific verb 'Get' and identifies the resource as 'a specific Conversation Flow', further clarifying the scope with 'nodes, edges, and tools'. This distinguishes it from sibling tools like list_conversation_flows and get_conversation_flow_component.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use this to retrieve full details of a specific conversation flow. However, it does not explicitly state when to use this over listing flows or getting individual components, nor does it provide exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states the return fields (IDs, names, voice settings, configuration), which is helpful, but it does not mention whether results are paginated, any rate limits, or explicitly confirm this is a read-only operation (though 'list' implies it). No contradictions.
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?
Two sentences, no filler. Every word adds value, and the key purpose is front-loaded with the return information in the second sentence.
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?
For a simple list tool with no parameters and no output schema, the description provides a clear statement of action and return values. It is sufficient for an agent to understand the tool's scope and output, despite the large sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (0 parameters), so the baseline is 4. The description adds no parameter details, but there are none to describe, so it meets the baseline without needing further elaboration.
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?
The description uses the specific verb 'List' with the resource 'all Retell AI voice agents in your account', clearly distinguishing it from sibling tools like retell_list_phone_numbers and retell_list_voices. It also enumerates the return data (agent IDs, names, voice settings, configuration), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as retell_get_agent for individual agents or retell_list_phone_numbers for phone numbers. There are no exclusions or contextual cues beyond the name and generic list semantics, so the agent gets no explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the transparency burden. It discloses the outcome (returns call_id and access_token) and hints at the audio websocket connection, which is a behavioral trait. However, it does not explain what happens after registration (e.g., that the agent must connect to the websocket and whether there are any prerequisites or side effects). This is a moderate level of disclosure, sufficient for understanding the core action but lacking operational depth.
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?
The description is a single, front-loaded sentence that states the action, context, and key return values without filler. Every clause adds useful information, and it is appropriately sized for a tool with a clearly named purpose and well-documented schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, nested objects, no output schema, and no annotations. The description names the returns but does not outline the required follow-up steps (e.g., using the access_token for the audio websocket) or any post-registration behavior. While the purpose is clear, an agent might benefit from knowing that this is part of a two-step flow. The description is adequate but leaves operational context to be inferred.
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?
The input schema has 100% description coverage for all six parameters, including nested objects and enums. The description itself does not add parameter-level details beyond what the schema already states. Since the schema is fully self-explanatory, a baseline score of 3 is appropriate; there is no gap for the description to compensate for.
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?
The description uses a specific verb 'Register' and identifies the resource 'phone call' with the key qualifier 'for custom telephony (bring-your-own telephony)'. This clearly distinguishes it from siblings like retell_create_phone_call (which likely uses Retell's infrastructure). It also states the return values (call_id and access_token), leaving no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'bring-your-own telephony' provides a clear use case: when a caller has their own telephony setup rather than using Retell's phone numbers. While it doesn't explicitly name alternative tools, the sibling context (e.g., retell_create_phone_call, retell_create_web_call) makes it evident when this tool applies. No exclusions or when-not guidance, but the context is specific enough for an agent to select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action 'Create' and parameter requirements but does not mention permissions, side effects, idempotency, return value, or error behavior. For a mutation tool without annotations, this is a significant transparency gap.
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?
The description is two sentences and front-loads the core purpose. Every clause adds meaningful information: the action, the resource, and the critical prerequisites. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is rich and covers all 11 parameters, and the description adds the essential requirement of choosing one response engine. However, the description does not mention what happens after creation (e.g., return object, how to verify via list/get) or any prerequisites like listing voices, though the schema fills some gaps. Given the good schema coverage, the description is adequate but not fully complete on behavioral outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents each parameter. The description adds value by clarifying the mutual exclusivity of the three response engine parameters, stating that exactly one is required. This semantic constraint is not fully apparent from the schema alone.
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?
The description uses the specific verb 'Create' and names the resource 'Retell AI voice agent', clearly distinguishing it from sibling tools that list, get, update, or delete agents as well as create other resource types. It also highlights essential requirements, leaving no ambiguity about the tool's primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by stating that creating an agent requires a voice_id and exactly one response engine among llm_id, llm_websocket_url, or conversation_flow_id. However, it does not explicitly compare against alternatives like retell_create_chat_agent or when not to use this tool, leaving some room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only mentions a prerequisite, not the mutation side effects, permissions, response format, or error behavior. For a create operation, the description adds minimal behavioral context beyond the name and parameter requirement.
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?
Two sentences, front-loaded with the core purpose and a key requirement. No filler or repetition of schema descriptions. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 6 parameters and no output schema, the description is fairly complete: it states the purpose and the critical requirement. It could mention the return value or error conditions, but given the simplicity and good schema coverage, it meets most needs. It is not as rich as the TDQS 4.3 example, but above the mid-range.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by grouping llm_id, llm_websocket_url, and conversation_flow_id as alternative response_engine options and indicating that one is required, even though the schema marks all parameters optional. This clarifies mutual exclusivity and a validation rule not present in the schema.
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?
The description clearly states the verb (create), resource (chat agent), and disambiguates from voice agents with 'text/messaging'. It also distinguishes from sibling tools like retell_create_agent by specifying the chat domain. The additional mention of the response_engine requirement further clarifies the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the context (text/messaging) and a key prerequisite (requires response_engine). It implicitly tells the agent when to use this tool over retell_create_agent (for voice) or retell_create_chat (for sessions). However, it does not explicitly state alternatives or exclusion criteria, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful information by stating that the call returns an access_token for the Retell Web SDK, which is a behavioral outcome. However, it omits details like permissions, side effects, or failure modes, so it's only partially transparent.
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?
The description is a single, compact sentence that is front-loaded with the action and resource. It includes the essential return value without any fluff, making it concise and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description appropriately notes the return value (access_token), which is critical for the agent to know what to expect. It also covers the main purpose and differentiates from phone calls. Gaps remain around prerequisites or call lifecycle, but the description is reasonably complete for a simple create operation.
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%; all three parameters (agent_id, metadata, retell_llm_dynamic_variables) have descriptions in the schema. The description itself adds no parameter-specific detail beyond the schema, so it meets the baseline of 3.
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?
The description clearly states the action ('Create'), the resource ('browser-based web call'), and the key outcome ('Returns an access_token'). It also distinguishes from siblings like retell_create_phone_call by specifying 'browser-based', making the purpose unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by emphasizing 'browser-based web call', which clearly separates it from the phone-call sibling tools. However, it doesn't explicitly state exclusions or when to prefer alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly discloses irreversible deletion ('permanently') and the cascading effect on versions ('all its versions'), which is critical behavioral context. It does not mention auth or error behavior, but the key destructive traits are covered.
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?
A single, concise sentence that front-loads the action and effect. Every word is useful; no wasted text or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete tool, the description provides essential context: the operation is permanent and affects all versions. While it lacks details on return values or error states, the simplicity of the operation makes this sufficient. No output schema exists, but the description adequately explains the tool's primary effect.
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% with a clear parameter description ('The unique ID of the Conversation Flow to delete'). The tool description adds context about deleting versions, but adds no extra meaning specifically about the parameter itself. Baseline 3 is appropriate.
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?
The description clearly states the action ('delete'), the resource ('Conversation Flow'), and the scope ('all its versions'). This distinguishes it from sibling delete tools like 'delete_conversation_flow_component' by explicitly focusing on the flow itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting a Conversation Flow, but it does not explicitly mention when to use this tool over alternatives (e.g., delete_conversation_flow_component) or any prerequisites. The scope is understandable from context but lacks explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it reveals a significant side effect: 'local copies are automatically created in all Conversation Flows that use it.' This goes beyond a simple delete statement and helps the agent understand the impact. It does not mention permissions or reversibility, but the disclosed side effect is a critical behavioral trait.
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?
The description is two concise sentences, with the action front-loaded in the first sentence and the key consequence in the second. There is no redundant or filler content, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and no output schema, the description covers the primary action and the most important consequence (local copy creation). It does not explain return value or error handling, but those are less critical given the tool's low complexity and the presence of related sibling tools that add context.
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 description coverage is 100%, as the parameter 'conversation_flow_component_id' already has a description in the schema. The tool description does not add additional semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
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?
The description clearly states the action ('Delete') and the specific resource ('shared Conversation Flow Component'), which distinguishes it from sibling delete tools like 'retell_delete_conversation_flow' and 'retell_delete_agent'. The second sentence adds a key behavior that further defines the purpose by explaining what happens when the component is deleted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context that this tool is for deleting shared components, but it does not explicitly advise when to use it versus alternatives or mention any exclusions. The sibling list includes related operations (create/update/list components), so the usage intent is implied but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds a meaningful distinction by stating 'published versions', implying that unpublished/draft versions are excluded. However, it does not disclose other behavioral traits such as read-only nature, ordering, pagination, or error behavior. For a simple retrieval tool, this is adequate but not rich.
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?
The description is a single sentence that is front-loaded with the verb and resource. Every word serves a purpose, and there is no redundant or filler content. It is effectively concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one well-documented parameter and no output schema. The description sufficiently explains what the tool does, and the parameter is fully covered by the schema. While it does not describe the return format, the name and description imply a list of versions, which is adequate for such a straightforward getter.
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?
The schema already provides 100% coverage for the single parameter (agent_id) with a clear description. The tool description does not add any additional parameter context, but since the schema fully documents the parameter, the baseline score of 3 is appropriate.
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?
The description uses a specific verb ('Get') and clearly identifies the resource ('all published versions of a Retell AI voice agent'). It distinguishes from siblings like retell_get_agent (gets a single agent) and retell_publish_agent (publishes a version). The action and scope are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when the agent needs to retrieve the published version history of a voice agent. It does not explicitly list alternatives or exclusions, but the purpose is straightforward and the sibling tools such as retell_get_agent or retell_publish_agent are obviously different. For a simple getter, this provides sufficient context without needing explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It indicates a read-only operation ('Get') and that data is 'current live,' which implies real-time status. However, it does not disclose potential side effects, permissions, or output format, though these are minimal for a simple getter. It adds some context beyond the name but could be more explicit about safety or data scope.
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?
The description is a single, well-structured sentence that front-loads the verb and object. It contains no filler or redundant information, earning its place perfectly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool, the description is nearly complete. It specifies what data is returned (live concurrency and limits). Without an output schema, more detail on the exact response structure could be useful, but the simplicity of the operation makes the description sufficient. It covers all essential aspects for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per rubric. No parameter descriptions are needed, and the description correctly focuses on the result rather than inputs. Schema coverage is 100% (empty schema), so there is nothing to compensate for.
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?
The description uses a specific verb ('Get') and resource ('current live call concurrency and concurrency limits') clearly distinguishing this tool from all sibling tools, none of which address concurrency. It fully explains what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for monitoring concurrency but provides no explicit guidance on when to use it versus alternatives, or any exclusions. Since no other concurrency tool exists, alternatives are not mentioned, but context like 'for your Retell organization' gives some scoping. The use case is clear but implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It conveys a read-only operation via 'Get' but does not add any further context such as prerequisites, return format, or potential side effects. It is not misleading, but also not rich.
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?
The description is a single, front-loaded sentence with no filler or redundant information. Every word contributes to clarifying the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list-retrieval tool with no output schema, the description adequately explains the action and required context. It could mention that the agent must have MCP configured, but the overall necessity is clear enough.
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 description coverage is 100%, so all three parameters (agent_id, mcp_id, version) are already documented in the schema. The description adds no additional parameter detail, so the baseline score of 3 is appropriate.
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?
The description clearly states the action ('Get the list'), the resource ('MCP tools'), and the scope ('from a specific MCP server configured on a Retell agent'). This distinctly separates it from all sibling tools, none of which focus on MCP tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context by mentioning the need for a specific MCP server and Retell agent, but it does not explicitly discuss when to use this tool versus alternatives or provide any exclusions. That 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It states the tool lists configurations, which clearly indicates a read-only operation, but it does not disclose potential details like pagination, ordering, or whether the list includes full configuration data or summaries. Given the simplicity of a list operation, this is minimal but not misleading.
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?
The description is a single concise sentence with no filler or redundant information. It front-loads the action and resource, earning a perfect score for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description adequately states what it does and the scope. However, since there is no output schema, it would be helpful to mention what information is returned (e.g., configuration names and IDs, or full details). Still, the description is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is empty. No parameter explanations are needed, and the baseline for zero-parameter tools is 4. The description adds no parameter information, but that is unnecessary here.
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?
The description is specific: 'List all Retell LLM configurations in your account.' It clearly states the verb (List), the resource (Retell LLM configurations), and scope (in your account), which distinguishes it from related tools like retell_get_llm (single LLM) or retell_create_llm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need an overview of all LLM configurations, but it does not explicitly mention alternatives or when not to use it. For example, it does not point to retell_get_llm for retrieving a single configuration or to create/update for modifications. The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It discloses that publishing creates a new immutable version, which is a key behavioral trait. However, it does not mention permissions, prerequisites (e.g., existence of a draft), or how this interacts with existing published versions beyond implying immutability.
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?
One sentence of 12 words, every word earns its place; front-loaded with the primary action and concise outcome. No redundancy or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers the core action and result. Minor omissions: it doesn't state whether a draft must exist or what the response looks like, but these are not critical for invocation. Overall adequate for a simple publication operation.
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?
The single parameter agent_id is fully described in the schema (100% coverage), and the tool description does not add any additional semantic meaning to the parameter itself. Baseline of 3 applies because the schema already documents the parameter adequately.
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?
The description uses a specific verb ('Publish') and resource ('chat agent') with additional scoping ('latest draft') and outcome ('creating a new immutable version'), clearly distinguishing it from sibling tools like retell_publish_agent (for non-chat agents) and retell_get_chat_agent_versions (for listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear that this tool is for publishing chat agents, providing clear context for use. However, it does not explicitly contrast with alternatives such as retell_publish_agent or state when not to use this tool, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implicitly indicates a read-only listing operation, but it does not disclose details such as pagination, response format, rate limits, or whether deleted chats are included. For a simple list tool, this is minimal but acceptable.
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?
The description is a single, direct sentence with no filler. It is front-loaded and every word contributes to meaning. This is an appropriate size given the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should arguably explain more about what 'list' returns (e.g., an array of chat objects). It states the action clearly but does not describe the structure or any constraints. It is minimally complete for a zero-parameter list tool, but lacks depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and a fully covered empty schema. The baseline for 0 params is 4, and the description correctly does not invent any parameter semantics. Nothing more is needed.
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?
The description uses a specific verb ('List') and resource ('chat sessions') with clear scope ('in your Retell AI account'). It distinguishes this tool from sibling list tools by the resource type (chats vs. calls, phone numbers, voices, etc.), so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this when you need to list all chat sessions. It does not explicitly mention alternatives like retell_get_chat for a single chat, but it is evident from the sibling names and the simple listing action. There are no exclusions or special conditions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the scope (all phone numbers in the account) but does not explicitly state it is read-only, mention pagination, or describe the return format. The word 'list' implies a safe read operation, though some behavioral details remain implicit.
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?
The description is a single, front-loaded sentence with no wasted words: 'List all phone numbers in your Retell AI account.' It efficiently conveys the tool's purpose without redundancy.
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?
For a simple list tool with no parameters, no output schema, and no annotations, the description is sufficient. It fully covers the tool's primary function and scope; additional detail about return values is unnecessary since 'list' implies a list of phone numbers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with zero parameters, so there are no parameter semantics to explain. The description does not need to add parameter information; the baseline for zero parameters is 4.
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?
The description clearly states the verb 'List' and the resource 'all phone numbers in your Retell AI account', which distinctly separates it from sibling tools like get_phone_number (for a single number) and create/update/delete phone numbers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (list all phone numbers) but does not explicitly mention when to choose this over alternatives like get_phone_number or list_voices. There is no when-not or alternative guidance, though the simple list operation makes intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key side effects: creating an immutable version and starting a fresh draft, which are critical for understanding the tool's impact. However, it does not mention irreversibility, permission requirements, or other potential side effects like whether the previous version remains accessible.
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?
The description is a single, well-structured sentence that is front-loaded with the primary action and includes the essential behavioral outcomes. No unnecessary words or repetition.
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?
For a tool with one parameter and no output schema, the description sufficiently explains the tool's purpose and effects. It covers what the tool does and the resulting state changes, making it complete for its simplicity.
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?
The input schema provides full coverage for agent_id with its own description. The tool description does not add additional meaning to the parameter, so the baseline 3 applies given 100% schema coverage.
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?
The description clearly states the tool's function: publish the latest draft of a voice agent, creating a new immutable version and starting a fresh draft. It uses a specific verb ('Publish'), identifies the resource ('voice agent'), and distinguishes it from similar tools like retell_publish_chat_agent by specifying voice agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying it applies to voice agents, but it does not explicitly state when to use this tool versus alternatives or mention prerequisites. The presence of retell_publish_chat_agent in sibling tools hints at differentiation but without explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the read-only nature implicitly via 'List' and explains what Conversation Flows are, but it does not disclose pagination, result size, or that full details may be obtained via get_conversation_flow. It is honest but minimal.
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?
Two sentences, both earning their place. The first states the action and scope; the second defines the entity type. No fluff, front-loaded, and easily scannable.
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?
For a parameterless list tool, the description is complete. It names the resource, scope, and provides a definition of Conversation Flows. No output schema exists, but the return value (a list of flows) is implied sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema is empty (100% coverage). Per the baseline for 0 parameters, a score of 4 is appropriate. The description does not need to add parameter details since none exist.
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?
The description clearly states the tool lists all Conversation Flows in the Retell AI account, using a specific verb and resource. It differentiates from sibling tools like get_conversation_flow or create_conversation_flow by emphasizing 'all' flows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to list all flows), but it does not explicitly mention alternatives for listing vs. retrieving a single flow. The 'all' scope and sibling tool names make the usage obvious, but explicit exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. The verb 'List' clearly indicates a read-only, non-destructive operation, and the description discloses the type of data returned (provider, gender, accent, preview URLs). No contradictions exist. It lacks explicit statements about pagination or auth, but such details are not critical for this simple list tool.
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?
The description is a single, information-dense sentence. Every word earns its place, stating what the tool does and what data it returns without any fluff or repetition.
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?
Given the tool's simplicity (no parameters, no output schema), the description is complete. It specifies the action and the content of the response (provider, gender, accent, preview URLs), which is all a user needs to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially 100% covered. Per the rubric, a parameterless tool receives a baseline score of 4. The description does not need to explain parameter semantics, and no gaps exist.
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?
The description clearly states the action ('List'), the resource ('voices'), and the specific context ('for Retell AI agents'). It also enumerates the fields included (provider, gender, accent, preview audio URLs), making the tool's purpose unambiguous and distinct from sibling tools like retell_list_agents or retell_list_llms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: call this when you need to discover available voices for Retell AI agents. It provides clear context but does not explicitly mention alternatives or exclusions. Since there is no other voice-listing sibling tool, this level of guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![retell-mcp-server MCP server](https://glama.ai/mcp/servers/sunnysingh100/retell-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/sunnysingh100/retell-mcp-server)

Score Badge

Copy to your README.md:

[![retell-mcp-server MCP server](https://glama.ai/mcp/servers/sunnysingh100/retell-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/sunnysingh100/retell-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sunnysingh100/retell-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server