Telnyx MCP Server

Server Quality Checklist

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

Latest release: v0.1.2
Disambiguation2/5
Several tools have overlapping purposes: `list_embedded_buckets` vs `cloud_storage_list_buckets`, `create_embeddings` vs `embed_url`, and `update_phone_number` vs `update_phone_number_messaging_settings` all could confuse an agent. The `update_connection` tool is a non-functional trap that always throws an exception, making it worse than useless.
Naming Consistency2/5
Naming conventions are inconsistent across domains: some tools use `cloud_storage_*` prefix, others use plain `verb_noun`, and `mcp_telnyx_delete_assistant` is an outlier with an unusual prefix. There is no uniform pattern, though most names are readable.
Tool Count2/5
With 46 tools, this server is overstuffed. It spans cloud storage, AI assistants, call control, messaging, phone numbers, and integration secrets—far too many distinct domains for a single MCP server. It would be better split into focused servers.
Completeness2/5
CRUD coverage is uneven: messaging profiles lack delete, connections lack create/delete, call control applications lack update/delete, and cloud storage lacks delete bucket. The non-functional `update_connection` tool creates a false sense of capability, and there are no update tools for integration secrets.
Average 3.4/5 across 46 of 46 tools scored. Lowest: 2.4/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 provided, so the description must carry the full burden. It implies a read-only operation via 'Retrieve,' but does not disclose error behavior, permissions, or side effects (if any). The return type 'Dict[str, Any]' is vague, and the mismatch between the documented 'id' and the schema's 'request' adds confusion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, with clear Args/Returns sections. However, the Args section inaccurately lists 'id' instead of 'request,' undermining the structure. It is concise but not well-formed due to the incorrect parameter documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and a vague input schema (request object with additionalProperties), the description must compensate. It does not explain how to construct the request, what the response contains beyond a generic Dict, or how this differs from list_call_control_applications. The id/request mismatch leaves the agent unable to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter 'request' (object, additionalProperties true) with 0% coverage. The description instead mentions an 'id' argument, which directly contradicts the schema. This misleads the agent about what to pass, and no meaning is added to the actual 'request' parameter.
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 begins with 'Retrieve a specific call control application,' which clearly states the action and resource. The word 'specific' differentiates it from sibling 'list_call_control_applications,' though it does not explicitly name the alternative.
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 list_call_control_applications. There is no mention of prerequisites, exclusions, or typical use cases. The only hint is the word 'specific,' which implies fetching one item, but this is not explicit.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It merely states 'Make a call' and lists arguments, but does not mention side effects, permissions, asynchronous behavior, or what actually happens when the call is made. This is a significant transparency gap for a mutating operation.
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 concise and front-loaded with 'Make a call', followed by a structured Args and Returns section. It avoids filler and each element serves a purpose. A slightly richer description could improve value, but the current structure is 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?
For a tool that initiates a call, the description is incomplete. It lacks prerequisites (e.g., existing connection or call control app), details about the expected request format (nested object vs top-level params), and any specifics about the response beyond 'Dict[str, Any]'. The presence of sibling tools like 'start_assistant_call' and 'hangup' makes contextual guidance even more important, which is missing here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is a single 'request' object with additionalProperties true, so the description's listing of 'to', 'from_', and 'connection_id' adds some meaning. However, it presents these as top-level arguments while the schema expects them inside a nested 'request' object, causing potential confusion. Only three fields are documented, leaving other possible parameters unspecified. The description partially compensates for low schema coverage but is incomplete and potentially misleading.
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 tool's purpose with a specific verb and resource ('Make a call'). It distinguishes from basic siblings like 'hangup' but does not explicitly differentiate from 'start_assistant_call', which also initiates calls. The purpose is clear enough for most contexts.
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. The description only lists arguments and return type without mentioning any preferred use cases, exclusions, or relationships to other call-related tools. It provides no 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, the description must disclose behavioral traits, but it only mentions that the bucket must exist and that a response dict is returned. It does not describe side effects (e.g., whether embeddings are persisted), required permissions, error handling, or the nature of the 'embed' operation, leaving significant gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description follows an Args/Returns structure with clear sections, but includes a long list of optional models and an extra instruction sentence. Typos like 'containe' and 'thenlper' reduce polish, though the length is justified by the number of parameters.
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 a nested request object, no output schema, and no annotations, the description is incomplete. It does not explain how to pass parameters into the 'request' object, does not specify the return structure beyond 'Dict containing embeddings', and provides no error conditions or examples. The prerequisite ('bucket must exist') is stated but not elaborated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists five parameters with types and some meaning (e.g., bucket_name, embedding_model with supported models), but the input schema only defines a single nested 'request' object. The description does not explain how these parameters map to the request structure, causing confusion about the actual invocation format. Schema coverage is 0%, so the description is the sole source, but the mismatch undermines its usefulness.
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 a specific verb ('Embed') and resource ('a bucket that contains files'), which distinguishes it from the sibling tool 'embed_url' (which embeds a URL). However, the term 'embed' is not explicitly defined, leaving some ambiguity about the exact scope and nature of the 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?
The description provides no guidance on when to use this tool versus alternatives like 'embed_url' or 'list_embedded_buckets'. The only usage-related instruction is 'Agent should prefer only rely on required fields unless user explicitly provides values for optional fields', which is about parameter handling, not 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?
Annotations are absent, so the description carries the full burden. It only says 'Initiate a phone number order' without disclosing potential billing implications, asynchronous order processing, or how to confirm completion. Given the nature of a purchase, this lack of behavioral detail is a notable gap.
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 very short and follows a clear structure with Args and Returns sections. No filler or redundancy, and the format is easy to parse. However, it is under-specified rather than merely concise, which slightly reduces the score.
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 initiates an order likely involving billing and asynchronous processing, but the description lacks return value details (just a generic 'Dict[str, Any]') and any information about order status, confirmation, or required preconditions. The mismatch between documented args and the schema further undermines completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema defines a single required 'request' object with additionalProperties true (schema description coverage is 0%). The description lists phone_number and connection_id as parameters, but these names do not appear in the schema, creating a mismatch: the schema expects a 'request' object, while the description implies top-level parameters. This adds some semantic hints but is potentially misleading.
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 a specific verb ('Initiate') and resource ('phone number order'), clearly distinguishing the action of ordering a number from sibling tools like get_phone_number or update_phone_number. The core purpose is understandable, though it could be even clearer by explicitly stating 'purchase' or 'buy'.
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?
It provides no guidance on when to use this tool versus alternatives such as list_available_phone_numbers (to find numbers) or update_phone_number (to modify an existing number). No prerequisites, exclusions, or typical scenarios 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?
Without annotations, the description carries full behavior disclosure burden. It mentions a default (use_profile_webhooks defaults to True) and a behavior (auto_detect for long SMS), but doesn't cover side effects, costs, delivery guarantees, or that sending may be asynchronous. The Returns field is vague ('Dict[str, Any]').
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 uses a clean Args/Returns structure with each field on a single line. It is somewhat long due to the number of parameters, but every line provides useful information. 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?
The tool is complex (many parameters, no annotations, no output schema, nested schema object), but the description is only a parameter list. It fails to explain how arguments relate to the 'request' object, what kind of response to expect, or any operational context (e.g., network needs, message delivery). This is insufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate with parameter meaning. It lists 11 fields with types and defaults, but critically fails to map them to the actual schema, which expects a single 'request' object. The description does not state that these arguments belong inside 'request', leaving invocation ambiguous and prone to error.
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 opens with 'Send a message', a clear verb+resource statement. It is distinct from sibling tools like make_call, get_message, or send_dtmf. However, it doesn't explicitly highlight SMS/MMS support or exclusions, though the 'type' parameter hints at it.
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 start_assistant_call or send_dtmf. There are no prerequisites, exclusions, or references to related tools. The description only explains parameters.
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 states the basic action but does not explain side effects, such as what happens to the original call after transfer, whether the transfer is blind or attended, or any permissions needed. This is insufficient for a mutating telephony operation.
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 concise and structured in a docstring format with Args and Returns sections. It is front-loaded with the core purpose and avoids fluff, though repeating 'Required' for each argument adds slight 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?
The tool lacks output schema and annotations, so the description should provide richer context. It only gives a generic 'Dict[str, Any]' return type and omits important context like the need for an active call, how to obtain the call_control_id, or what a successful transfer entails. This is incomplete for a complex call-control operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is a generic 'request' object with no property details (0% schema coverage), so the description must compensate. It lists 'call_control_id', 'to', and 'from_' with minimal descriptions, but does not clarify how these map to the schema's nested 'request' object, nor provide types or formats. This partial compensation is not enough.
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 ('Transfer a call to a new destination') and identifies the target resource (a call) and its destination. While it does not explicitly distinguish itself from sibling tools, 'transfer' is a distinct operation in the telephony context and is not ambiguous.
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 offers no guidance on when to use this tool versus alternatives like 'make_call' or 'hangup'. It lists required arguments but does not explain prerequisites (e.g., call must be active) or contexts where this tool is 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?
With no annotations, the description carries full burden for behavioral disclosure. It states the action 'Update' and lists connection_id/tags, implying mutation, but does not disclose side effects, permission requirements, idempotency, or any constraints. The return type is generic ('Dict[str, Any]') and adds no behavioral insight.
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 compact and organized with a one-line purpose followed by an Args list and a Returns line. It avoids excessive prose, though the return type line ('Dict[str, Any]') adds little value and the Args list partially conflicts with the schema.
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 that the schema has a nested 'request' object, no output schema, and no annotations, the description is insufficiently complete. It leaves the request payload format unexplained and does not provide enough context to distinguish this tool from closely related siblings like update_phone_number_messaging_settings. The documentation of extra fields without schema alignment further increases the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and exposes only 'id' and an opaque 'request' object, while the description documents 'connection_id' and 'tags' that are not schema properties. This mismatch is confusing: the required 'request' parameter is never explained, and the description does not clarify how the documented optional fields relate to the 'request' object. The description adds some meaning for optional fields but fails to align with the actual 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 states the verb and resource clearly ('Update a phone number') and lists parameters, making the core purpose understandable. However, it does not explicitly distinguish itself from sibling tools like update_phone_number_messaging_settings or get_phone_number, relying only on the tool name for differentiation.
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 simply says 'Update a phone number' and lists parameters, with no mention of use cases, prerequisites, or situations where another sibling 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?
With no annotations, the description carries the full burden. It does disclose the return value (a success string or exception message), but it fails to mention permissions, idempotency, duplicate-bucket behavior, or how the operation behaves beyond the return message. The phrase 'if it uploaded' is also inaccurate for a create-bucket operation, adding mild confusion rather than clarity.
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 concise and front-loaded with the purpose. It uses clear Args/Returns sections with no filler. It loses one point because it is too sparse to fully compensate for the weak schema and because of the minor 'uploaded' wording issue, but structurally it is 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?
Given no annotations, no output schema, and a schema that is just an open-ended 'request' object, the description needed to explain how to structure the call and what side effects to expect. It only provides field names and a terse return message, leaving critical gaps around request construction, error handling, and operation semantics. It is not complete enough for an agent to invoke reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only exposes a single opaque 'request' object with additionalProperties: true and 0% description coverage. The description instead lists bucket_name and region as required arguments, but does not explain that they belong inside the 'request' object or how to map them to the schema. It adds some value by naming fields and region values, but the mismatch between the described arguments and the actual schema parameter is likely to mislead an agent.
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 a specific verb+resource: "Create a new bucket." This clearly distinguishes it from sibling tools like cloud_storage_upload_file, cloud_storage_list_buckets, and cloud_storage_delete_object. 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 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 does not mention other cloud_storage tools, prerequisites, or scenarios where this should or should not be used. The only context is the action itself, which is implied by the 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 is the sole source of behavioral disclosure. It mentions scraping and saving to a new bucket but omits side effects like potential bucket creation, network dependencies, or whether existing data is affected.
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 relatively brief but slightly redundant with 'Scrape and embed a given URL' followed by a paraphrase. It includes structured Args and Returns sections, which aids parsing.
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 significant gaps: the parameter mismatch alone prevents reliable invocation. It also lacks details about return values, error conditions, and the embedding concept, making it incomplete for complex scraping operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description declares a required 'url' argument, but the input schema specifies a required 'request' object. This mismatch confuses the agent about the exact parameter structure; the schema coverage is 0% and the description does not explain how the URL maps to the 'request' field.
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 a clear verb-object pair 'Scrape and embed a given URL' and expands on the workflow (scrape pages, save to a new bucket, auto-embed). This distinguishes it from sibling tools like cloud_storage_upload_file and create_embeddings.
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 choose this tool over alternatives such as list_embedded_buckets or create_embeddings. The description only states what it does, not the intended 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 present, so the description carries full burden. It lists parameters and defaults (page, page_size) but does not disclose what phone numbers are included, authentication needs, rate limits, or response structure beyond 'Dict[str, Any]'.
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 concise and well-structured as a docstring with Args and Returns sections. No unnecessary fluff, but could be shortened by removing redundant parameter type mentions.
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, no output schema, and a nearly empty input schema, the description must provide comprehensive context. It offers only parameter list and vague return type, missing details about response fields, scoping of phone numbers, and the required request wrapper.
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 only has a required 'request' object with no properties, making it unhelpful. The description lists six optional args with types, defaults, and filter purposes, adding value. However, the mismatch between the described individual args and the schema's request object creates confusion.
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 states 'List phone numbers' which is a clear verb+resource. It distinguishes from get_phone_number (single item) but not clearly from list_available_phone_numbers, a sibling tool.
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 versus list_available_phone_numbers or get_phone_number. No scenarios or exclusions are provided.
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 explains parameter value semantics (e.g., empty string unassigns a profile), but it does not disclose side effects, permissions, idempotency, or error behavior. The return value is only vaguely described as 'Dict[str, Any]', leaving significant gaps.
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 front-loaded with a clear summary and uses a consistent Args/Returns structure. It is reasonably concise, though the parameter list is inconsistent with the schema, which slightly reduces clarity.
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 nested object parameter, no output schema, and no annotations. The description does not clarify how to construct the 'request' object, nor does it mention preconditions, error cases, or related messaging profile/product concepts. The vague return type further limits completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds semantics for messaging_profile_id and messaging_product, but these do not match the actual input schema, which only contains 'id' and an opaque 'request' object. The schema has 0% description coverage, and the description fails to explain that the real parameters are nested inside 'request', likely confusing the agent.
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: 'Update the messaging profile and/or messaging product of a phone number.' This is specific and distinguishes it from sibling tools like update_phone_number (which updates other properties) and update_messaging_profile (which updates the profile itself).
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 explicit guidance on when to use this tool versus alternatives. The description does not mention related tools or provide exclusions, leaving the agent to infer usage solely from the summary. It lacks any 'use this if...' or 'instead use...' details.
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 'List' which implies a read-only operation, but does not explicitly mention permissions, side effects, rate limits, or pagination behavior. This is a significant gap for a tool with no annotation support.
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 well-structured with a concise one-line purpose, a clear parameter list, and a return type. The parameter descriptions are necessary given the schema's lack of detail. The return type is vague ('Dict[str, Any]: Response data') but does not add clutter. Overall, the structure is appropriate.
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 lacks annotations and an output schema, so the description must provide complete context. It fails to explain what 'available' means, whether filters can be combined, the structure of the response, or any prerequisites. It also does not differentiate from siblings, leaving the agent under-informed for a filterable list operation.
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 a single 'request' object with additionalProperties true, providing 0% parameter coverage. The description fully compensates by listing all parameters (page, page_size, filters) with types, defaults, and intended meanings. However, it does not explicitly clarify that these parameters should be nested inside the required 'request' object, creating slight ambiguity.
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 'List available phone numbers' with a specific verb and resource. However, it does not distinguish itself from the sibling tool 'list_phone_numbers', which could be interpreted as listing owned numbers. The phrase 'available' implies a different scope but no explicit contrast is made.
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 like 'list_phone_numbers' or other filtering tools. The description simply lists parameters without providing context about appropriate use cases or 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?
The description discloses an important behavioral trait: the bucket_name parameter is optional and defaults to the default bucket if None. It also states the return type. However, with no annotations available, it does not cover other behavioral aspects such as error handling, authentication requirements, or side effects. It adds some value but is not comprehensive.
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 compact and well-structured with clear Args and Returns sections. Every sentence provides useful information without redundancy. It is appropriately sized for a simple get-location 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 simple tool, the description explains the default bucket behavior and return value. However, the lack of mapping to the actual input schema ('request' wrapper) is a significant gap. With no output schema or annotations, the tool definition is only partially complete for an agent to use reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema contains a generic 'request' object with additionalProperties true, which offers no inherent meaning. The description mentions 'bucket_name' as an optional parameter with a default behavior, but it does not explain how bucket_name maps to the required 'request' field. This mismatch creates confusion and prevents the agent from correctly constructing the input. Schema coverage is 0%, and the description only partially compensates.
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 tool's function: 'Get the region where a bucket is located.' This is a specific verb+resource combination. However, it does not explicitly distinguish this from sibling tools like cloud_storage_list_buckets, which might also return location information, so it lacks the explicit differentiation needed for a 5.
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. The description does not mention any prerequisites, exclusions, or scenarios where a different tool would be more appropriate. This leaves the agent without direction 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?
No annotations are provided, so the description must carry the full burden. It implies a read operation but does not explicitly confirm safety, permissions, side effects, or error behavior. The sparse description leaves significant behavioral gaps.
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 concise and well-structured with an opening purpose, an Args section, and a Returns section. Minor redundancy in 'Assistant ID' appears twice, but overall it is 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?
The tool has a simple purpose, but the description is minimal for the information needed. It does not explain the return format beyond 'Dict[str, Any]', does not mention use cases or alternatives, and lacks details about the relationship between the listed args and the actual schema wrapper. Given no annotations or output schema, this is 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 schema is a generic wrapper with only a 'request' object, providing 0% coverage. The description lists five parameters with brief explanations, adding meaning that the schema lacks. However, it does not reconcile these with the actual 'request' wrapper, which could confuse agents.
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 'Get an AI Assistant by ID' with a specific verb and resource. It distinguishes itself from sibling tools like list_assistants and create_assistant by noting the ID-based retrieval.
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 about when to use this tool versus alternatives such as get_assistant_texml or list_assistants. It only states what it does, without any 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?
There are no annotations, so the description must disclose behavioral traits. It implies a read-only operation and says it returns response data, but it doesn't mention authentication requirements, possible errors (e.g., profile not found), or any side effects. This is a significant gap for a tool with zero annotation coverage.
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 concise and front-loaded, with the purpose in the first line and a structured Args/Returns format. It avoids unnecessary detail and is easy to scan.
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 one-parameter getter, the description gives the bare minimum: what it does and a generic return type. Since there is no output schema, the promise of 'messaging profile details' is circular and doesn't inform the agent about the response structure. It also lacks error behavior and is therefore incomplete for a tool with no annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args section that restates the parameter name and says it is 'the ID of the messaging profile to retrieve,' which adds no meaningful information beyond the schema's property name and type. With schema coverage at 0%, the description fails to compensate with format, length, or other constraints.
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 'Retrieve a messaging profile by ID,' which clearly specifies the verb, resource, and retrieval scope. This distinguishes it from sibling tools like list_messaging_profiles and create_messaging_profile, even though it doesn't name them explicitly.
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 list_messaging_profiles or get_connection. It does not mention prerequisites like having a profile ID, nor does it state when other tools 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?
With no annotations, the description carries the full burden of behavioral disclosure. It only repeats the action name ('Hang up a call') and provides parameter info, but does not mention side effects, termination semantics, errors, or any state requirements.
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 short and front-loaded with the core purpose, followed by Args and Returns sections. However, the Returns line ('Dict[str, Any]: Response data') is generic and adds minimal value, preventing a perfect score.
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 is a stateful action (hanging up a call) but the description lacks essential context such as prerequisites (active call), failure conditions, side effects, or how it relates to sibling call-control tools. The absence of an output schema and annotations makes this gap notable.
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 only defines a generic 'request' object with no properties, giving 0% coverage. The description partially compensates by naming call_control_id as required, but it does not specify its type or where it fits within the 'request' object, leaving ambiguity.
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 'Hang up a call' with a specific verb and resource, clearly distinguishing it from sibling tools like make_call and transfer. The Args and Returns sections reinforce the operation's scope.
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, such as prerequisites like an active call or when transfer would be more appropriate. The description merely states the action without contextual 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 provided, so the description must carry the burden of behavioral disclosure. It lists parameters and a return type but does not explicitly state that the operation is read-only, mention authentication needs, or describe pagination behavior or side effects. The minimal detail is insufficient for full transparency.
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 structured, efficient docstring. It leads with 'List connections' and then lists arguments and return type in a clean, scannable format. Every line adds value with no fluff.
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 incomplete. The return type 'Dict[str, Any]' gives no information about the structure of connection objects or pagination metadata. It also lacks context about what connections are or any prerequisites, leaving significant gaps for an agent.
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 a generic wrapper with 0% coverage, so the description must compensate. It does so by naming each parameter (page, page_size, filters, sort), providing defaults for page and page_size, and explaining filter purposes. However, it does not specify types for the filters or clarify how these arguments map to the 'request' object, preventing a perfect score.
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 'List connections' with a verb and resource, making the purpose evident. It is distinct from sibling tools like get_connection and update_connection, though it does not explicitly call out those alternatives.
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 like get_connection or update_connection. No context or exclusions are provided, leaving the agent without direction on 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?
There are no annotations, so the description must convey behavior. It states the action and return value but does not disclose the destructive nature, idempotency, or error behavior. This is a significant gap for a deletion operation.
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 concise and front-loaded, with a clear action sentence followed by Args/Returns. While the Args section duplicates the schema, the overall length is appropriate at 5 lines.
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 one-parameter delete tool, the description provides the action and return type, but lacks essential context like error handling, permissions, or whether the deletion is permanent. Without annotations, this leaves the agent under-informed about risks.
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 repeats the schema's parameter information ('id: Required. Secret ID.') but adds no additional meaning beyond the schema, which already has 100% coverage. 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 'Delete an integration secret' – a specific verb and resource, distinguishing it from sibling tools like create_integration_secret and list_integration_secrets.
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 whether deletion is irreversible or if there are prerequisites. Usage is merely implied by the tool's 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?
Annotations are absent, so the description carries full burden. It discloses the return value but omits critical behavioral details such as irreversibility, error handling, idempotency, or 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 compact, structured with Args/Returns, and front-loaded with a clear action. Every sentence adds value without waste.
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 tool's simplicity, the description fails to address the mismatch between the schema's 'request' wrapper and the documented parameters, and it omits error scenarios and usage guidance. With no annotations or output schema, this is insufficient.
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 opaque (single 'request' object with additionalProperties), but the description compensates by defining object_name (required) and bucket_name (optional, default). It lacks type information but provides essential semantics.
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 with a specific verb ('Delete') and resource ('object from cloud storage'), distinguishing it from sibling upload/download/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 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, nor any prerequisites like permissions or bucket existence. The description is silent on exclusions or preferred contexts.
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 exist, so the description must carry full behavioral disclosure. It only states the action and a vague return type, omitting details about authentication, pagination, or side effects. The description does not explicitly confirm it is a safe read-only operation.
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 very brief and front-loaded with the purpose. However, the second sentence about the return type is of limited value, making it slightly less informative than ideal while still remaining concise.
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 no-parameter list tool, the description provides the essential purpose but lacks detail about the result shape, pagination, or what an assistant object includes. The absence of an output schema makes the vague return type insufficient for full contextual completeness.
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 takes zero parameters, so the schema trivially provides 100% coverage. With no parameters, the baseline is 4, and there is no additional meaning to add beyond what the schema already implies.
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 'List all AI Assistants' with a specific verb and resource, and the word 'all' distinguishes it from get_assistant. This is unambiguous and effectively differentiates from siblings.
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 get_assistant or start_assistant_call. There is no mention of exclusions, prerequisites, or comparison with similar tools.
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 discloses pagination and filtering capabilities (page, page_size, filter_name) and the return type (Dict), but it omits critical behavioral details like the required 'request' object wrapper, error handling, authentication needs, or side effects. Furthermore, the argument list (page, page_size, filter_name) does not mention that the schema requires a single 'request' object, creating ambiguity about the actual input format.
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 compact and well-structured: a one-sentence purpose, a clear Args list, and a Returns line. It avoids unnecessary filler, though the Returns line is a bit terse ('Dict[str, Any]') without elaboration. Overall, it is appropriately sized and front-loaded.
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 description covers the core purpose and key parameters, but it lacks context about the required 'request' object, potential errors, and the structure of the returned data. With no output schema or annotations, more detail is needed to fully guide an agent. The sibling tool names suggest related operations, but no guidance on how this tool fits into the broader workflow is provided.
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 zero descriptions for properties, so the description's Args section is the primary source of parameter semantics. It explains page (integer, defaults to 1), page_size (integer, defaults to 20), and filter_name (optional, filter by name), which adds meaning beyond the generic 'request' object in the schema. However, it fails to clarify that these are likely nested inside the required 'request' object, and filter_name lacks a type, so the semantics are incomplete.
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 messaging profiles,' which is a specific verb ('List') followed by the resource ('messaging profiles'), clearly distinguishing it from sibling tools like create/get/update_messaging_profile. It unambiguously states the action and target.
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 through its purpose ('List messaging profiles'), but it does not explicitly state when to choose this tool over alternatives or provide exclusions. No alternative tools are mentioned, and no context is given about filtering or comparison with similar list tools like list_phone_numbers or list_connections.
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 mentions the return value but does not disclose that deletion is permanent/irreversible or that it may have side effects. The description does not contradict annotations, but it lacks important behavioral context.
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 compact, with the key action in one sentence and a standard Args/Returns block. It is well-structured and front-loaded, though the Args/Returns block adds little over the 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?
Despite being simple, the tool lacks an output schema and annotations, so the description should compensate with details about deletion semantics. It provides only a vague 'deletion status' return and omits irreversibility or error conditions, leaving gaps for a destructive 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 'id' is fully described in the schema ('Assistant ID as string'), and the description repeats exactly that. No additional semantic information is added, but since schema coverage is 100%, 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 'Delete an AI Assistant' with a specific verb and resource, distinguishing it from sibling tools like create_assistant, update_assistant, and get_assistant.
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 explicit guidance on when to use or avoid the tool; the only guidance is the implied use case from the verb 'Delete'. It does not mention alternatives or prerequisites, so it is 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, the description bears full responsibility for behavioral disclosure. It does mention overlay and stop parameters, which add some behavioral nuance (e.g., ability to stop overlay vs. main audio). However, it omits side effects, error behavior, preconditions (e.g., active playback), and any permissions needed. This is a common gap for mutation tools.
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 concise and well-structured with a one-line summary followed by Args and Returns sections. It is front-loaded and each sentence contributes to understanding. No unnecessary fluff, though the Args section could have been more aligned with the actual input schema.
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 the tool's simplicity, the description is mostly complete in explaining the parameters, but it leaves a critical gap: the input schema requires a 'request' object, and the description does not explain how the listed parameters fit into that envelope. There is no example, no mention of errors, and no handling of edge cases. This incompleteness can lead to incorrect invocation.
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 a generic 'request' object with 0% coverage, so the description's detailed parameter list (call_control_id, overlay, stop) adds substantial meaning. It specifies requiredness, types, defaults, and valid values for the stop parameter. However, there is a mismatch: the schema expects a 'request' wrapper, which the description does not acknowledge, potentially confusing an agent on how to structure the call.
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 stops audio playback on a call, using a specific verb and resource. It is easily distinguished from siblings like playback_start, speak, and hangup. 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 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 does not mention situations where stopping playback is appropriate, nor does it reference any other tools as alternative options. Usage context is only implied by the action itself.
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?
There are no annotations, so the description must carry the behavioral burden. It lists parameters like 'stop' and 'service_level' but does not disclose side effects, whether TTS is synchronous, if it interrupts ongoing audio, or what happens on failures. The return value is vaguely described as 'Response data.'
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 uses a clear docstring format with Args and Returns sections. Each parameter entry is informative and scannable, though it is somewhat lengthy due to the number of parameters. No unnecessary fluff is present.
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 the lack of annotations and output schema, plus the generic request schema, the description should provide more context. It lists parameters but fails to explain how the 'request' object relates to the listed arguments, the response structure, or the behavioral semantics of the TTS action. For an agent to correctly invoke and interpret the result, more detail is needed.
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 schema only defines a generic 'request' object with additionalProperties true, providing 0% coverage of the actual parameters. The description compensates by listing each parameter with defaults and valid values (voice, payload_type, service_level, stop, language), which is essential for constructing the request. The mismatch between the schema wrapper and the listed arguments is not explicitly explained, but the description adds significant 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 clearly states 'Speak text on a call using text-to-speech,' identifying a specific verb and resource. It distinguishes from siblings like playback_start by explicitly mentioning text-to-speech, which is unique among the listed 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 implies the use case: speaking text on a call via TTS. However, it provides no explicit guidance on when to choose this tool over alternatives such as playback_start or send_dtmf, nor does it state any 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 for behavioral disclosure, but it focuses almost entirely on parameter documentation. It does not mention whether creation is idempotent, what side effects occur (beyond the obvious creation), any required permissions, rate limits, or the actual structure of the response beyond the vague 'Dict[str, Any]: Response data'. The description also lacks details about validation, potential errors, or asynchronous behavior.
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 long, but the length is justified by the tool's complexity with many nested object parameters. It is well-structured with clear 'Args:' and 'Returns:' sections, and the opening sentence is concise. While some repetition of 'Optional' and nested details could be tightened, the overall organization makes it easy to scan and extract necessary 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 high complexity, the description provides comprehensive parameter coverage that the schema lacks. It includes a Returns section, though minimal. It does not cover error scenarios, permissions, or worked examples, but for a create operation with rich parameter documentation, it is largely complete. The main gap is the lack of behavioral details, which is already reflected in the transparency score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a single 'request' object with additionalProperties allowed, so the description is the sole source of parameter meaning. It thoroughly documents every field, including types, optionality, defaults (e.g., 'model' defaults to 'meta-llama/Meta-Llama-3.1-70B-Instruct'), nested structures for tools (function, retrieval, webhook, hangup, send_dtmf, transfer), and even templating details for webhook URLs and headers. This comprehensive documentation fully compensates for the schema's lack of specificity.
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 'Create a new AI Assistant,' which uses a specific verb and resource, making the purpose immediately clear. This distinguishes it from sibling tools like update_assistant, get_assistant, and list_assistants. The additional context about handling both detailed and vague user requests reinforces the tool's role without 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. It does not mention exclusions, prerequisites, or situations where update_assistant or other tools would be more appropriate. The only statement is the creation action itself, leaving the agent without decision-support information.
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. It uses 'Get' to imply a read-only operation, but it does not disclose potential error conditions, permission requirements, rate limits, or any side effects. The return type is mentioned, but other behavioral aspects are absent.
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 very concise and front-loaded, with the first sentence stating exactly what the tool does. It includes clearly structured Args and Returns sections that are easy to parse, with no redundant or unrelated 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?
For a simple tool with one parameter and no output schema, the description adequately covers purpose, argument, and return type. It could be improved by explaining what TEXML is or mentioning error handling, but given the low complexity, the description is largely complete.
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 full coverage for the single parameter, describing it as 'Assistant ID'. The description's Args section merely repeats this exact information, adding no additional semantic value such as format, constraints, or usage examples. Since schema coverage is 100%, 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') and the specific resource ('assistant's TEXML') along with the identifying input ('by ID'). This distinguishes it from sibling tools like get_assistant, which would return the full assistant object rather than its TEXML content.
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 the TEXML content for an assistant, but it does not explicitly state when to prefer this tool over alternatives like get_assistant, nor does it mention any exclusions or prerequisites. The guidance is minimal but not misleading.
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?
The description discloses the return format ('Success!!' or exception message), which is additional behavioral information beyond the operation. However, it does not mention important behaviors like whether existing objects are overwritten, whether the bucket must exist, or any permission requirements. With no annotations, more transparency would be expected, but the return value disclosure is a positive.
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 well-structured and concise: purpose, args, return. Each sentence earns its place. No fluff or redundant wording.
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 description covers purpose, args, and return, but the mismatch between the documented arguments and the schema's 'request' object is a significant gap. The agent may not know to pass the listed args as properties of the request object. Also lacks alternative tool suggestions, but for a simple upload, this is near-sufficient.
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 description lists three parameters with clear meanings and optionality (absolute_file_path required, object_name and bucket_name optional). This compensates for the 0% schema description coverage. However, there is a mismatch: the schema shows a single 'request' object with additionalProperties, while the description implies separate arguments. This could confuse the agent about how to structure the invocation.
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 'Upload a file to cloud storage' with a specific verb and resource. It distinguishes from sibling tools like download, list, and delete. The name and description align perfectly.
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 versus alternatives like cloud_storage_download_file or list_objects. There are no prerequisites, exclusions, or context about when an upload is appropriate. The description only states what the tool does, not when to use it.
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 behavioral disclosure. It states the operation is a retrieval and promises 'message details', but it does not mention potential errors (e.g., invalid ID) or the exact structure of the return data. This is sufficient for a simple read 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 concise, with a clear one-sentence overview followed by structured Args and Returns sections. Every line earns its place with no extraneous information.
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-param retrieval tool, the description covers the essential purpose and parameter. However, the return type is generically 'Dict[str, Any]' with no indication of expected fields, and error handling is omitted. Given no output schema, this leaves noticeable gaps in 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 schema has no parameter descriptions (0% coverage), so the description's line 'message_id: The ID of the message to retrieve' adds some meaning. However, it essentially restates the parameter name and type without providing format, origin, or examples, offering only marginal value over 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 'Retrieve a message by ID', using a specific verb and resource. It unambiguously distinguishes itself from siblings such as send_message and get_webhook_events, with no other get_message tool present.
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 use when a message_id is known and details are needed, but provides no explicit comparison to alternatives or exclusions. It falls short of offering clear guidance on when not to use this tool or directing users to other tools for different scenarios.
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 lists parameters and a generic return type, omitting side effects, prerequisites (e.g., active call), error conditions, and whether the operation is idempotent or blocking. This is insufficient for a mutation-style 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 tightly structured docstring with Args and Returns sections. It front-loads the purpose and every line adds value. No unnecessary content.
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, it covers the necessary parameter info but lacks lifecycle context (e.g., must be used on an active call). The generic schema wrapper adds confusion, and the absence of an output schema means the return type 'Dict' is vague.
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 0% with only a generic 'request' object. The description compensates by listing call_control_id, digits, and duration_millis with types and defaults. However, it doesn't clarify how these map to the schema's 'request' wrapper, creating structural ambiguity.
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 'Send DTMF tones on a call', which is a specific verb and resource. It distinguishes itself from sibling tools like playback_start, speak, and transfer, which are for other call media operations.
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 during an active call by referencing a 'call_control_id'. It doesn't explicitly mention alternatives or when not to use, but among the telephony siblings, this is the only DTMF tool, 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?
With no annotations, the description carries the full burden for behavioral disclosure. It only states the basic action and a constraint on from_ (must be a Telnyx number), but does not mention side effects, prerequisites, whether the call is asynchronous, or what happens on failure. This is minimal transparency.
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 brief and well-structured with a summary line, parameter list, and return type. Every sentence adds value, with no redundant or fluff content.
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 description covers the parameters and return type but lacks preconditions (e.g., assistant must exist) and post-conditions (e.g., how to interpret the response). Given no annotations and no output schema, it is somewhat incomplete, though the core purpose is clear.
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 schema provides only titles ('To', 'From', 'Assistant Id'), so the description is essential. It adds meaning by explaining each parameter's role, including the requirement for from_ to be a number on the Telnyx account. While concise, it compensates well for the 0% 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 ('Start a call') and the specific context ('using an AI Assistant with a phone number'), which distinguishes it from generic call tools like make_call. The verb 'start' and resource 'assistant call' are explicit.
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 use case (calls involving an AI assistant) but does not explicitly state when to prefer this tool over make_call or other call-related siblings. It lacks any mention of alternatives, exclusions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 mentions the return type as a Dict containing Number Object(s) with record_type 'phone_number', but does not explicitly state that this is a read-only operation, nor does it cover error conditions or required permissions.
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 compact and well-structured: one line for the action, one for the argument, and one for the return value. There is no fluff or redundant information, and each sentence serves a clear 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 tool with one parameter and no output schema, the description covers the essential information: action, parameter, and high-level return shape. However, it could be more explicit about the cardinality (single object vs multiple) and the structure of the Number Object, but it is adequate for basic usage 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?
The input schema already fully describes the 'id' parameter as 'Phone number ID as string' with 100% coverage, and the description repeats the same text without adding any new meaning, formatting details, or examples. The baseline score of 3 applies because 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 clearly states 'Get a phone number by ID', which is a specific verb (get) with a resource (phone number) and a parameter (ID). This distinguishes it from sibling tools like list_phone_numbers and update_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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a phone number ID is available and a single record is needed. However, it does not explicitly mention alternatives like list_phone_numbers for browsing or update_phone_number for modifications, leaving the when-to-use 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?
The description includes a return type and example response structure (Dict with 'data' containing 'buckets' list), which adds some transparency. However, since there are no annotations, the description carries the full burden and does not disclose authentication requirements, potential errors, pagination behavior, or side effects.
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 very brief and front-loaded. The return example is useful and appropriately compact, with 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?
Given the tool has no parameters and no output schema, the description provides the essential return structure. However, it does not explain what 'embedded buckets' are or how this differs from similar tools like cloud_storage_list_buckets, which could lead to selection confusion. The simplicity of the tool mitigates this 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 schema already captures the absence of inputs. The description does not need to elaborate, and the baseline for zero-parameter tools 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 explicitly states 'List user embedded buckets,' which identifies the action and resource clearly. The qualifier 'user embedded' helps distinguish it from the sibling tool cloud_storage_list_buckets, which likely lists cloud storage buckets instead.
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 like cloud_storage_list_buckets or other listing tools. No context is provided about use cases, prerequisites, or selection criteria.
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 behavioral burden. It discloses the return value ('Success') but omits failure behavior, overwrite semantics, permissions, or error handling. This adds some context but significant gaps remain, making it 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 compact and well-structured with Args and Returns sections. It delivers necessary information without extraneous content. Every line serves a purpose, earning a perfect score.
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 no annotations and no output schema, the description provides key details about parameters and return value. However, it lacks error handling details and fails to address the mismatch between the listed arguments and the schema's required 'request' object. It is sufficient for basic understanding but incomplete for robust use.
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 only exposes an opaque 'request' object with no property descriptions, so the description's Args section is essential. It defines object_name, file_path, and bucket_name with meanings and defaults, which adds real value. However, it does not clarify that these arguments must be nested inside the 'request' object per the schema, creating a potential invocation mismatch.
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 'Download a file from cloud storage,' which is a specific verb+resource+action. It clearly distinguishes from sibling tools like upload, list, and delete by naming a different operation. The return value is also stated, reinforcing 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 description states the tool's function clearly (download a file) and implies when it should be used, but it does not explicitly compare with alternatives or provide exclusions. It offers a clear context without explicit 'when to use' guidance, fitting the 'clear context, no exclusions' level.
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. It does disclose the return type and the optional parameters, which adds some behavioral context. However, it does not mention whether the operation is read-only, any pagination behavior, or error conditions. It is adequate but not rich in behavioral context.
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 concise and well-structured, with a one-sentence purpose followed by a clear Args list and Returns note. Every sentence 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?
The description is incomplete because it lists 'prefix' and 'bucket_name' as separate arguments, but the schema requires a single 'request' object. It does not explain how these arguments map to the request object, leaving the agent confused about the exact call structure. Additionally, without an output schema, it does not document any possible error responses or edge cases, making it insufficient for a schema that is so generic.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only has a generic 'request' object with additionalProperties, providing no details about the actual parameters. The description compensates fully by specifying 'prefix' and 'bucket_name', their optionality, and defaults. This is critical because schema coverage is 0%, and the description adds all the necessary parameter semantics.
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 objects in a bucket with optional prefix filtering, which is a specific verb-resource pair. It distinguishes itself from sibling tools like cloud_storage_list_buckets by focusing on objects within a bucket.
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 context is implied by the function: it is used to list objects, optionally filtered by prefix and bucket. However, it does not explicitly mention alternatives or when not to use it (e.g., for listing buckets), nor does it provide exclusions. This falls under 'implied usage' rather than clear guidance.
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?
There are no annotations, so the description carries the full burden of behavioral disclosure. It states the arguments and return type but does not disclose any side effects, authorization requirements, error behavior, or whether the operation is idempotent. For a create operation, this lack of context limit transparency.
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 well-structured with Args and Returns sections, listing parameters clearly and concisely. Every sentence serves a purpose without redundancy, making it efficient and easily scannable.
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 covers purpose, parameters, and return type, and compensates for the poor schema. However, it omits usage guidelines and deeper behavioral context (e.g., prerequisites, error conditions), leaving some gaps for an agent selecting or invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is a generic 'request' object with additionalProperties true, yielding 0% schema coverage. The description compensates fully by listing all parameters (identifier, type, token, username, password) with their types and required/optional status, adding meaningful semantics that the schema lacks.
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 'Create an integration secret' uses a specific verb and resource, clearly distinguishing it from sibling tools like list_integration_secrets and delete_integration_secret. It is concise and unambiguous about 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 through the verb 'create' but does not explicitly state when to use it versus alternatives or provide any excluding context. It lacks a clear 'when-to-use'/'when-not-to-use' statement, though the purpose is evident.
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 explains some behavioral options (loop, overlay, stop, target_legs) but does not disclose prerequisites (e.g., call must be active), side effects, or failure modes. It adds moderate context beyond the schema 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The docstring is well-organized with Args and Returns sections, using concise bullet-like lines. No redundant text, though the Returns line is generic and could be more informative. Overall, it is clear and efficient.
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?
While the description explains all parameters, there is a critical mismatch: the schema expects a single 'request' object, but the description lists individual arguments. This relationship is not clarified. Additionally, no output schema, annotations, or usage guidance means the description is not fully self-contained for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines a 'request' object with additionalProperties, so schema coverage is 0%. The description fully compensates by listing each parameter, its required/optional status, valid values, and defaults. This is the sole source of parameter semantics.
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 audio playback') and the resource ('on a call'), which is specific and distinct from siblings like playback_stop and speak. The parameter list further clarifies the operation.
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?
Usage context is implied (when you need to play audio on a call), but there is no explicit guidance about when to use this tool versus alternatives like speak or playback_stop. No when-not-to-use scenarios or exclusions are mentioned.
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 clearly states the creation action and lists configurable settings with defaults, which is helpful. However, it does not disclose potential side effects (e.g., cost implications), required permissions, validation rules, or whether creation is idempotent. This is a moderate disclosure but leaves gaps.
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 well-structured with a one-line purpose statement followed by a clearly organized parameter list and a returns section. Every parameter earns its place, and the format is scannable. It is appropriately sized given the complexity of the 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?
The tool is complex with many optional parameters and nested objects, and there is no output schema. The description covers all parameters, but the return value is vague ('Dict[str, Any]: Response data'), providing no indication of what keys or data structure to expect. This leaves a notable completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is a generic 'request' object with additionalProperties true, providing 0% coverage. The description compensates by thoroughly explaining every parameter, including types, defaults, and nested structures (e.g., number_pool_settings, url_shortener_settings). This adds immense 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 opens with 'Create a messaging profile,' which clearly identifies the action (create) and the resource (messaging profile). This distinguishes it from sibling tools like list_messaging_profiles, get_messaging_profile, and update_messaging_profile.
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. The verb 'create' implies its use for new profiles, but there is no mention of prerequisites, typical scenarios, or exclusions. Usage is inferred from the tool name and the parameter list rather than made explicit.
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. 'Get' implies a read-only operation, and the return type is mentioned generically as 'Dict[str, Any]: Response data.' However, it does not disclose any side effects, permissions, or specifics about the response contents, leaving some ambiguity.
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 and structured with clear sections for a summary, args, and returns. Every line is necessary, and there is no redundant wording. It front-loads the primary 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 one-parameter getter, the description is nearly complete. It covers the operation, parameter, and return type. However, the return value is vaguely described as 'Dict[str, Any]: Response data' and lacks specifics about the response fields, which would improve completeness.
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 description adds semantic meaning to the sole parameter by stating 'Required. Connection ID,' which compensates for the schema's 0% description coverage. It clarifies what the ID represents, though it could be more detailed (e.g., format or example).
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 a specific action: 'Get a connection by ID.' It specifies the resource (connection) and the scope (by ID), which distinguishes it from sibling tools like list_connections and update_connection. The verb 'Get' accurately conveys a read operation.
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 a connection ID is available, but it does not explicitly state when to use this tool over alternatives or provide any exclusions. It lacks explicit guidance on when not to use it or how it relates to list_connections.
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 must carry the full transparency burden. It discloses that it returns a dict with events and metadata, but does not mention auth requirements, rate limits, pagination, or other behavioral nuances. For a straightforward getter, this is acceptable 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 concise and well-structured with an opening sentence followed by Args and Returns sections. Every sentence adds value and there is no irrelevant 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?
Given the tool's low complexity (two optional parameters, no output schema), the description covers the essential information: purpose, parameters, and return type. It lacks detail on event_type format and metadata structure, but is sufficient for basic usage.
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 description explains both parameters beyond the schema, including their defaults and meanings (limit for max events, event_type for filtering). This compensates for the 0% schema description coverage, though it does not specify valid event_type values.
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 purpose with a specific verb ('Get') and resource ('webhook events'). It specifies the scope ('most recent') and distinguishes itself from all sibling tools, none of which deal with webhook events.
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 describing what the tool does, but provides no explicit guidance on when to use it versus alternatives or any exclusions. For a simple read operation, this is adequate but not clearly differentiated from similar tools.
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 fully disclose behavioral traits. It does not mention whether updates are merged or replaced, what happens to existing fields, whether it is destructive, or any permission/authentication requirements. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with an Args section and nested bullet points. It is front-loaded with the purpose. Some redundancy exists (e.g., mention of integration secrets appears twice), but the length is largely justified given the generic schema and complex nested parameters.
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 complexity (many nested objects) and the absence of an output schema, the description is quite complete for input understanding. It covers all documented parameters. However, it lacks information about side effects, return value semantics (only vague 'Response data'), and error conditions, so it falls short of full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is minimal (assistant_id and a generic request object with additionalProperties). The description provides exhaustive documentation of all possible fields within request, including nested structures, allowed values, defaults (e.g., HTTP method default POST), and templating examples. This is essential for correct invocation and goes far 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 tool's purpose with a specific verb and resource: 'Update an AI Assistant.' It also distinguishes itself from the sibling create_assistant by focusing on updating an existing agent. The opening sentence 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 description gives clear context for when to use the tool: 'Once there is an agent created, you can talk the user about what can be updated in an easy manner.' This implies it is for existing assistants, but it does not explicitly mention alternatives or exclusions (e.g., use create_assistant for new ones). So it provides context but no 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 burden. It discloses configurable behaviors (e.g., enabling/disabling, webhook settings) but does not clarify update semantics (partial vs. full replacement), authentication requirements, or side effects. The return type is only vaguely stated as 'Dict[str, Any]'.
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 lengthy but well-organized with a clear parameter list and field explanations. It is front-loaded with the main purpose and each line adds necessary detail for a complex update operation. No redundant fluff.
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 no annotations and no output schema, the description is quite complete for invoking the tool. It explains all parameters and their types. The only gap is the minimal return description and lack of error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides profile_id and a generic request object with 0% coverage. The description compensates by detailing all request fields and their meanings, including nested settings like number_pool_settings and url_shortener_settings. This adds immense 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 'Update a messaging profile' with a specific verb and resource. It naturally distinguishes from sibling tools like create_messaging_profile and get_messaging_profile.
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 listing all updatable fields but does not explicitly state when to use this tool versus alternatives (e.g., create vs update). It gives no exclusions or prerequisites.
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. It adds useful behavioral details such as default sort order, case-insensitive filter, and a minimum filter length. However, it does not disclose response structure or pagination output, leaving some behavioral gaps.
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 well-structured: a one-sentence purpose, a clear list of arguments, and a return type. It is concise, front-loaded, and every line adds value without unnecessary prose.
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 lacks an output schema and the description only provides a vague 'Dict[str, Any]' for the return value. It does not describe the shape or fields of the returned list items, which is a significant gap for an agent trying to interpret results. The parameter details are strong, but the response is underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is a generic 'request' object with 0% actual parameter coverage. The description fully compensates by enumerating each parameter, its type, optionality, default value, and filtering behavior, providing substantial 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 opens with 'List call control applications,' which is a specific verb+resource statement that clearly distinguishes it from sibling tools like get_call_control_application and create_call_control_application.
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 usage for listing applications with optional filters, sorting, and pagination. However, it does not explicitly state when to use this vs. alternatives like get_call_control_application, so while context is clear, 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 for behavioral transparency. It discloses pagination and filter behavior and the return type, but does not explicitly state that it is read-only or have no side effects, which would be useful given the absence of annotations.
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 compact and well-structured: a one-line purpose, an Args section, and a Returns section. Every element is necessary and directly informative, with no redundant or tangential 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?
For a simple list tool with no output schema, the description adequately explains input parameters and return structure. It could mention pagination metadata or authentication requirements, but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines a generic 'request' object with no property descriptions, so the description's Args block adds critical meaning by documenting page, page_size, and filter_type with types, defaults, and allowed values. This fully compensates for the 0% 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 purpose: 'List integration secrets.' This is a specific verb+resource statement that distinguishes it from sibling create/delete operations. The return type mention further confirms its role.
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, but the verb 'list' implies a read-only retrieval operation. No exclusions or alternative tool references are provided, so usage guidance is merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and fully discloses that the API does not support direct updates, restricts allowed methods, and raises an Exception. This is unusually transparent for a stub tool.
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 well-organized with Note, Args, Returns, and Raises sections, but it repeats the unsupported-operation warning in both the Note and Raises sections. Minor redundancy, but still clear and scannable.
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 that always raises an exception, the description fully explains why, what methods are permitted, and what alternative to pursue. It lacks an output schema but describes the generic return type, which is acceptable since the tool never succeeds. The suggested alternative ('create a new connection') is not present as a sibling tool, but the description still points to an external action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only adds 'Connection ID' and 'Update data' — generic labels that do not explain the structure or valid fields of the free-form 'data' object. It fails to compensate for the schema's lack of property definitions.
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 'Update a connection' and then immediately clarifies that the Telnyx API does not support updating connections directly, making the tool's true purpose (raising an unsupported-operation exception) explicit. It distinguishes itself from sibling get/list tools, though the initial phrase could mislead if read out of context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says only GET, HEAD, and OPTIONS methods are allowed and instructs to 'create a new connection with the desired settings instead.' This provides clear when-not-to-use guidance and names an alternative action.
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 for behavioral disclosure. It states the return format and that it operates across all regions, implying a read-only operation. However, it does not mention permissions, pagination, or potential rate limits, which are relevant for a list operation that could return many buckets. The description adds some useful context but lacks full behavioral transparency.
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 concise, with two sentences. It front-loads the primary purpose and then provides a clear, structured breakdown of the return values. Every sentence earns its place without unnecessary verbosity.
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 low complexity (no parameters) and absence of an output schema, the description adequately covers the return values and global scope. It does not mention potential pagination or limits, which could be relevant for a list-all tool, but for a simple bucket listing operation, the description is largely complete. A brief note about pagination would make it fully 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 tool has zero parameters, so the baseline is 4. The input schema is empty and the description does not need to explain parameter semantics. The description's mention of the return fields adds value beyond the schema, which has no properties.
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) and the resource (buckets), with the scope 'across all regions.' This distinguishes it from sibling tools like cloud_storage_list_objects (which lists objects within a bucket) and cloud_storage_get_bucket_location (which gets a specific bucket's location). The purpose is unambiguous and well-differentiated.
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 indicates the tool's scope ('across all regions'), which implies it is the top-level bucket listing operation. However, it does not explicitly mention when to use this over the sibling tools or include any exclusions. The context is clear but lacks explicit alternative 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 full responsibility for behavioral disclosure. It explains parameter effects and defaults, such as 'Directs Telnyx to route media through the site with the lowest round-trip time' and 'Specifies whether the connection can be used.' However, it does not disclose authentication requirements, idempotency, or the shape of the response beyond the generic return type.
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 well-structured as a docstring with clear Args and Returns sections. Each parameter is concisely defined with its type, optionality, and default, and no unnecessary information is present. Despite its length, every line serves a purpose and the structure aids readability.
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 complexity and absence of an output schema, the description is largely complete, covering all parameters comprehensively. The main gap is that the return value is only specified as 'Dict[str, Any]' without describing its keys or meaning, and the schema-wrapping ambiguity remains unresolved.
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 a generic 'request' object with additionalProperties and 0% schema description coverage. The description compensates extensively by detailing each parameter, its type, optionality, and default. However, it does not clarify that these arguments must be nested inside the 'request' object, which creates ambiguity about how to invoke the tool correctly.
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 'Create a call control application' with a specific verb and resource. It distinctly differentiates from sibling tools like list_call_control_applications and get_call_control_application, 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 provides no explicit guidance on when to use this tool versus alternatives. It does not mention related tools (e.g., update_connection, get_connection) or specify when not to use it. Usage is only implied by the tool name and the verb 'Create'.
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:

[![telnyx-mcp-server MCP server](https://glama.ai/mcp/servers/fastmcp-me/telnyx-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/fastmcp-me/telnyx-mcp-server)

Score Badge

Copy to your README.md:

[![telnyx-mcp-server MCP server](https://glama.ai/mcp/servers/fastmcp-me/telnyx-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/fastmcp-me/telnyx-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/fastmcp-me/telnyx-mcp-server'

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