Telnyx MCP Server

Official

by team-telnyx

Overview Schema Related Servers Score Discussions

Python

Hybrid

Server Quality Checklist

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

Latest release: v0.1.2
Disambiguation4/5
Most tools have distinct purposes, but some overlap exists, such as 'cloud_storage_upload_file' and 'cloud_storage_create_bucket' potentially confusing for storage creation, and 'make_call' vs. 'start_assistant_call' for initiating calls. However, descriptions clarify differences, and most tools target specific resources and actions clearly.
Naming Consistency4/5
Tools generally follow a consistent verb_noun pattern (e.g., 'create_assistant', 'list_phone_numbers'), with minor deviations like 'mcp_telnyx_delete_assistant' and 'get_assistant_texml' that break the pattern. Overall, naming is readable and mostly predictable across the set.
Tool Count2/5
With 46 tools, the count is excessive for a single server, making it overwhelming for agents to navigate. While the domain (Telnyx API) is broad, this many tools suggests poor scoping and could lead to confusion or inefficiency in tool selection.
Completeness5/5
The tool set provides comprehensive coverage for Telnyx services, including cloud storage, AI assistants, call control, messaging, phone numbers, and integrations. It offers full CRUD operations for most resources and supports key workflows like embedding, webhooks, and call management, with no obvious gaps.
Average 3/5 across 46 of 46 tools scored. Lowest: 1.9/5.
See the Tool Scores section below for per-tool breakdowns.
This repository is archived. Archived repositories automatically receive an F maintenance tier.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions pagination parameters and filtering/sorting options, it doesn't describe authentication requirements, rate limits, error conditions, or what happens when no connections exist. For a listing tool with no annotation coverage, this 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably structured with Args and Returns sections, but contains contradictory information about parameters. The first sentence 'List connections' is under-specified, while the parameter documentation is detailed but mismatched with the schema. The structure is clear but the content has significant issues.
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?
Given the parameter mismatch between description and schema (5 described vs 1 actual), 0% schema description coverage, no annotations, and no output schema, this description is completely inadequate. An agent would be unable to correctly invoke this tool due to the contradictory parameter information and lack of behavioral context.
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 description documents 5 parameters (page, page_size, filter_connection_name_contains, filter_outbound_voice_profile_id, sort), but the input schema shows only 1 parameter ('request') with 0% schema description coverage. This creates a serious mismatch where the description suggests specific filtering parameters that don't appear in the actual schema. The description fails to explain the 'request' object parameter that the schema requires.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List connections' which is a tautology that merely restates the tool name without adding meaningful context. It doesn't specify what type of connections (Telnyx voice connections, messaging connections, etc.) or what information is included in the listing. Compared to sibling tools like 'list_phone_numbers' or 'list_messaging_profiles', this lacks 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?
No guidance is provided about when to use this tool versus alternatives. There's no mention of prerequisites, typical use cases, or how this differs from other list tools in the sibling set. The description doesn't help an agent understand when this specific listing 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?
No annotations are provided, so the description carries full burden. It mentions pagination defaults (page=1, page_size=20) and filtering by name, which adds some behavioral context. However, it doesn't disclose critical traits like authentication requirements, rate limits, error handling, or what 'Response data' entails (e.g., structure, fields). For a list operation with no annotations, this is insufficient.
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 appropriately sized and front-loaded with the purpose, followed by parameter and return details. However, the parameter section is misleading due to schema mismatch, and the return statement is vague ('Dict[str, Any]: Response data'). Overall, it's concise but structurally flawed.
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 complex input schema (1 required parameter with nested objects), the description is incomplete. It fails to explain the 'request' parameter or its properties, and the return value is poorly defined. For a tool with such gaps, more detail is needed to guide the agent effectively.
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 input schema has 1 parameter ('request') with 0% description coverage and no details. The description lists 3 parameters (page, page_size, filter_name) that don't match the schema, creating a contradiction. This adds confusion rather than meaning, failing to compensate for the schema's lack of coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'List messaging profiles' which is a clear verb+resource combination, but it's vague about scope (e.g., all profiles vs. filtered). It doesn't distinguish from sibling tools like 'get_messaging_profile' (singular) or 'list_connections' (similar pattern). The purpose is understandable but lacks specificity.
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. For example, it doesn't mention when to use 'list_messaging_profiles' versus 'get_messaging_profile' (for a single profile) or other list tools. The description only lists parameters without context, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions pagination defaults and filtering capabilities, it doesn't describe authentication requirements, rate limits, error conditions, or what the response structure looks like beyond 'Dict[str, Any]'. For a listing tool with 1 required parameter and nested objects, this 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 well-structured with clear sections for Args and Returns. It's appropriately sized with no redundant information. However, the front-loaded purpose statement is overly brief and could benefit from more context before diving into 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?
Given the complexity (1 required parameter with nested objects, 0% schema coverage, no output schema, and no annotations), the description is incomplete. It documents filtering parameters that don't match the schema structure and provides minimal information about the response format. For a tool with schema/description mismatch, this creates significant uncertainty for an agent.
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 input schema has 0% description coverage and shows only a single 'request' parameter of type object, while the description lists 6 specific filtering parameters. This creates a direct contradiction between schema and description. The description provides parameter semantics that don't align with the documented schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose as 'List phone numbers', which is a clear verb+resource combination. However, it doesn't distinguish this tool from its sibling 'list_available_phone_numbers' or other listing tools in the server, leaving ambiguity about what specific type of phone numbers are being listed (owned vs available).
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 'list_available_phone_numbers' or 'get_phone_number'. There's no mention of prerequisites, context for filtering, or comparison with sibling tools, leaving the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions that the bucket must exist (a prerequisite) and lists optional parameters with some details (e.g., supported models), but it doesn't disclose critical behavioral traits such as whether this is a read-only or destructive operation, authentication needs, rate limits, or what happens during processing (e.g., does it modify the bucket?). The return type is mentioned but without specifics on format or errors.
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 structured with sections for Args and Returns, which helps organization, but it's moderately verbose with redundant information (e.g., repeating 'Optional' and 'Required'). Sentences like 'Agent should prefer only rely on required fields unless user explicitly provides values for optional fields' could be more concise. Overall, it's front-loaded with the main purpose but includes some unnecessary wording.
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 complexity (embedding operation with multiple parameters), no annotations, low schema coverage (0%), and no output schema, the description is incomplete. It provides basic parameter info and return type but lacks details on behavior, error handling, output structure, or how it integrates with sibling tools. For a tool with such gaps in structured data, the description should do more to fill in context.
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 has 0% description coverage with only one parameter 'request' of type object, which is poorly documented. The description lists 5 parameters (bucket_name, document_chunk_size, document_chunk_overlap_size, embedding_model, loader) that aren't reflected in the schema, adding some semantics like required/optional status and examples for embedding_model. However, this creates a contradiction with the schema, and the description doesn't fully compensate for the schema's lack of coverage, leaving parameter details incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Embed a bucket that containe files' which indicates the general purpose of embedding files from a bucket. However, it's somewhat vague about what 'embed' specifically means (e.g., generating vector embeddings for AI/ML use) and doesn't clearly differentiate from sibling tools like 'embed_url' or 'list_embedded_buckets'. The verb 'embed' is clear but the resource 'bucket that containe files' is imprecise.
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 minimal guidance: it mentions that the agent should prefer required fields unless optional ones are explicitly provided, but this is generic advice rather than specific usage context. It doesn't explain when to use this tool versus alternatives like 'embed_url' or how it relates to other cloud storage tools. No explicit when/when-not scenarios or prerequisites are given.
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. While it mentions fetching dynamic variables from webhook as an option, it doesn't explain what 'dynamic variables' are, how the webhook integration works, authentication requirements, rate limits, error conditions, or what the response structure looks like. For a retrieval tool with potential side effects (webhook calls), this is insufficient.
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 reasonably concise with clear sections (Args, Returns). However, the parameter documentation is misleading given the schema mismatch, and the 'Returns' section is vague ('Dict[str, Any]: Response data'). The structure is good but the content has significant accuracy issues.
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?
Given the complexity (retrieval with potential webhook side effects), lack of annotations, schema contradiction (description vs. actual parameters), and no output schema, the description is completely inadequate. It doesn't provide enough information for an agent to understand what the tool actually does, what parameters it accepts, or what it returns.
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 description lists 5 parameters with brief explanations, but the input schema shows only 1 parameter ('request') with 0% schema description coverage. This creates a severe contradiction: the description documents parameters that don't exist in the schema, while the actual schema parameter ('request') is completely undocumented. This makes parameter understanding impossible.
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: 'Get an AI Assistant by ID.' This specifies the verb ('Get') and resource ('AI Assistant'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'list_assistants' or 'get_assistant_texml', which would require more specific scope details.
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. There are multiple sibling tools related to assistants (e.g., 'list_assistants', 'update_assistant', 'get_assistant_texml'), but the description doesn't mention any of them or explain when this specific 'get' operation is appropriate versus listing or other retrieval methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. 'Initiate' suggests a write operation that likely creates/purchases a phone number, but it doesn't disclose critical behavioral traits: whether this is a synchronous purchase or just starts an order process, what permissions are needed, if there are costs/rate limits, or what happens on failure. The description mentions a return type but gives no details about response structure or success/failure indicators.
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 appropriately brief but poorly structured. The first sentence is clear, but the Args/Returns sections are misleading due to parameter mismatch. While concise, the structure creates confusion rather than clarity, with documentation that doesn't match the actual interface.
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 write operation with no annotations, 0% schema coverage, no output schema, and a nested object parameter, the description is insufficient. It doesn't explain what 'request' should contain, how to format phone numbers, what 'connection_id' refers to, or what the response includes. The parameter mismatch makes it actively misleading rather than merely incomplete.
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?
Schema description coverage is 0%, and the description lists two parameters (phone_number, connection_id) that don't exist in the actual schema (which has only one 'request' object). This creates a severe mismatch. The description adds incorrect parameter information rather than compensating for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 'Initiate a phone number order' - a specific verb ('initiate') and resource ('phone number order'). It distinguishes from siblings like 'list_available_phone_numbers' (browsing) and 'get_phone_number' (retrieving). However, it doesn't explicitly contrast with 'update_phone_number' (modifying existing numbers), which would make it a perfect 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 on when to use this tool versus alternatives. The description doesn't mention prerequisites (e.g., needing available numbers first), nor does it differentiate from similar tools like 'update_phone_number' or 'get_phone_number'. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions pagination and filtering capabilities, it doesn't disclose important behavioral traits like whether this is a read-only operation, what permissions are required, rate limits, error conditions, or what the response structure looks like. For a list operation with no annotation coverage, this is insufficient.
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 reasonably structured with a purpose statement followed by parameter documentation. However, the parameter documentation is extensive and detailed for parameters that don't match the actual schema, making it inefficient. The 'Returns' section is vague ('Dict[str, Any]: Response data') and doesn't add meaningful value.
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 complexity mismatch between description and schema, no annotations, and no output schema, the description is incomplete. It documents parameters that don't exist in the schema while failing to document the actual single 'request' parameter. For a tool with nested objects in the schema and no annotation coverage, this leaves significant gaps in understanding.
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 description documents 5 parameters (page, page_size, filter_application_name_contains, filter_outbound_voice_profile_id, sort) with details about defaults and constraints. However, the input schema shows only 1 parameter ('request') with 0% schema description coverage. The description's parameter documentation doesn't match the actual schema structure, creating confusion rather than adding value.
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 as 'List call control applications' which is a specific verb+resource combination. However, it doesn't differentiate this tool from other list tools in the sibling set like list_assistants or list_connections, so it doesn't fully distinguish 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?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, when this tool is appropriate versus get_call_control_application, or any contextual usage information. It's purely a functional description without usage 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?
No annotations are provided, so the description carries full burden. It mentions pagination and filtering behavior, which is helpful, but lacks critical details: authentication requirements, rate limits, error handling, or whether it's safe for read-only operations. The return format is vaguely described as 'Response data containing Integration Secret Object(s)', without structure or examples.
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 structured with sections for Args and Returns, which aids readability. However, it includes parameter details that conflict with the schema, adding confusion rather than clarity. The core purpose is stated upfront, but the mismatched details reduce overall effectiveness.
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 1 parameter with 0% schema coverage, no annotations, no output schema, and nested objects in the schema, the description is incomplete. It attempts to document parameters but contradicts the schema, and lacks behavioral context like authentication or error handling. For a tool handling sensitive data (secrets), this is inadequate.
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 input schema has 1 parameter ('request') with 0% description coverage, and the schema provides no details on properties. The description lists 3 parameters (page, page_size, filter_type) that don't appear in the schema, creating a contradiction. This misalignment means parameter semantics are effectively undocumented and 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 verb ('List') and resource ('integration secrets'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_assistants' or 'list_connections' beyond the resource name, nor does it specify scope (e.g., all secrets vs. filtered).
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 doesn't mention prerequisites, permissions, or context for listing secrets (e.g., after creation, for configuration). With sibling tools like 'create_integration_secret' and 'delete_integration_secret', usage context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'Make a call' implying a write/mutation operation but doesn't disclose behavioral traits like authentication needs, rate limits, side effects, or what 'Response data' entails. This is inadequate for a tool with potential telephony implications.
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 appropriately sized and front-loaded with the purpose, followed by structured sections for Args and Returns. It avoids unnecessary fluff, though the 'Returns' section is vague ('Response data'), which slightly reduces efficiency.
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 complexity (telephony call tool with nested objects), no annotations, no output schema, and low schema coverage, the description is incomplete. It lacks details on behavioral context, full parameter coverage, and output specifics, making it insufficient for reliable agent use.
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 input schema has a single nested object 'request' with no details. The description adds parameter semantics for 'to', 'from_', and 'connection_id', explaining their roles, but it doesn't cover the 'request' object or other potential parameters, failing to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose ('Make a call') which is a clear verb+resource, but it's vague about what type of call (e.g., voice, SIP, telephony) and doesn't distinguish from sibling tools like 'start_assistant_call' or 'transfer'. It provides basic functionality but lacks specificity.
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 'start_assistant_call' or 'transfer' is provided. The description only lists parameters without context about prerequisites, scenarios, or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions the action 'Send a message' (implying a write operation), it doesn't describe authentication requirements, rate limits, error conditions, delivery guarantees, or what happens when sending fails. The return type is mentioned but without details about success/failure indicators or response structure.
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 reasonably structured with clear sections for Args and Returns, but it's somewhat inefficient. The first line 'Send a message.' is overly brief, while the parameter list is detailed but doesn't align with the actual schema. The structure helps readability, but the content doesn't fully earn its place due to schema mismatch.
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 message-sending tool with no annotations, no output schema, and a complex nested input schema (1 parameter with additionalProperties: true), the description is inadequate. It attempts to document parameters but doesn't match the actual schema structure, provides minimal behavioral context, and offers no output details beyond 'Dict[str, Any]: Response data'. The mismatch between described parameters and actual schema is particularly problematic.
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 input schema has 0% description coverage with only one parameter ('request') that's completely undocumented in the schema. The description attempts to compensate by listing 11 specific parameters with brief explanations, but these don't map to the actual schema structure. This creates a serious mismatch between described parameters and actual schema, making parameter understanding difficult.
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 as 'Send a message' with a verb+resource combination. It distinguishes itself from sibling tools like 'get_message' or 'make_call' by focusing on message transmission rather than retrieval or voice calls. However, it doesn't explicitly differentiate from potential messaging alternatives within the same domain.
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. While sibling tools include messaging-related functions like 'create_messaging_profile' and 'update_messaging_profile', there's no indication of how this tool relates to them or when one should be chosen over another. No prerequisites, exclusions, or contextual recommendations are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool updates a phone number, implying a mutation, but fails to detail critical aspects like required permissions, whether changes are reversible, error handling, or rate limits. The return type 'Dict[str, Any]' is too vague to understand the response structure.
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 structured with sections for Args and Returns, which is clear, but it includes unnecessary details like 'Dict[str, Any]' without explaining the response content. The mismatch between described and actual parameters reduces efficiency, as the tool's true usage isn't accurately conveyed.
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 mutation tool with no annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't cover behavioral traits, parameter details, or response format, leaving significant gaps for an AI agent to understand how to invoke the tool correctly and interpret results.
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 description lists parameters (id, connection_id, tags) that do not match the input schema, which only has 'id' and 'request'. With 0% schema description coverage, the description adds no meaningful semantics beyond naming mismatched parameters, failing to compensate for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 ('Update') and resource ('a phone number'), making it immediately understandable. However, it doesn't differentiate from its sibling 'update_phone_number_messaging_settings', which handles a specific subset of phone number updates, leaving some ambiguity about when to use each 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?
The description provides no guidance on when to use this tool versus alternatives, such as 'update_phone_number_messaging_settings' for messaging-specific updates or 'get_phone_number' for read-only access. It also lacks context about prerequisites, like whether the phone number must exist or be in a specific state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the return value ('Success!!' or exception message) which is helpful, but lacks critical details like required permissions, rate limits, whether the operation is idempotent, or what happens on conflicts. The description doesn't contradict annotations, but is incomplete for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with clear sections (Args, Returns). The first sentence directly states the purpose. However, the parameter documentation is misleading given the schema mismatch, which slightly reduces effectiveness.
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 mutation tool with no annotations, 0% schema coverage, no output schema, and a parameter mismatch, the description is inadequate. It provides basic purpose and return format but misses critical context about permissions, error conditions, and doesn't align with the actual schema structure.
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 description lists 'bucket_name' and 'region' as required parameters with some region examples, but the input schema shows only one parameter 'request' with no description (0% coverage). This creates a serious mismatch - the description documents parameters that don't exist in the schema, failing to compensate for the schema's deficiencies.
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 verb 'create' and resource 'bucket', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'cloud_storage_list_buckets' or 'cloud_storage_get_bucket_location' beyond the obvious create vs. list/get distinction.
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. There's no mention of prerequisites (e.g., authentication needs), when not to use it (e.g., if a bucket already exists), or comparison with sibling tools beyond what's 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?
No annotations are provided, so the description carries the full burden. It mentions that it returns 'Success!!' or an exception message, which gives some behavioral insight, but lacks details on permissions, rate limits, file size constraints, or error handling. For a mutation tool with zero annotation coverage, this is insufficient.
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 clear sections for Args and Returns, and it's front-loaded with the core purpose. However, the parameter mismatch adds unnecessary confusion, slightly reducing efficiency.
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 complex input schema with nested objects (100% coverage gap), the description is incomplete. It fails to explain the 'request' parameter or how it relates to the listed args, leaving significant gaps for a mutation 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 input schema has 1 parameter ('request') with 0% description coverage, and the description lists 3 parameters (absolute_file_path, object_name, bucket_name) that don't match the schema. This creates a contradiction and confusion, as the schema and description are misaligned, making parameter understanding impossible.
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 verb ('upload') and resource ('file to cloud storage'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like cloud_storage_download_file or cloud_storage_delete_object, though the upload action is inherently distinct.
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. For example, it doesn't mention prerequisites like needing an existing bucket or how it relates to cloud_storage_create_bucket. The description only states what the tool does, not when or why to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action ('hang up a call') which implies a destructive write operation, but doesn't disclose important behavioral traits like whether this requires specific permissions, what happens to the call participants, whether the action is reversible, or any rate limits. The mention of 'Response data' is too vague to be helpful.
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 appropriately concise with three sentences that cover purpose, parameters, and return value. It's front-loaded with the core purpose. However, the parameter section contains incorrect information that undermines its efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive call control tool with no annotations, 0% schema coverage, no output schema, and a complex nested parameter structure, the description is inadequate. It doesn't explain the actual parameter structure ('request' object), provides misleading parameter information, and gives no insight into what the response contains or the tool's behavior beyond the basic action.
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?
Schema description coverage is 0%, and the description mentions 'call_control_id: Required. Call control ID.' However, the actual input schema has only one parameter named 'request' (an object), not 'call_control_id'. This creates a direct contradiction between the description and the actual schema, making the parameter information misleading rather than helpful.
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 ('hang up') and resource ('a call'), making it immediately understandable. However, it doesn't distinguish this tool from potential sibling call-related tools like 'transfer' or 'playback_stop' in terms of call termination vs. other call control actions.
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 about when to use this tool versus alternatives. With sibling tools like 'transfer', 'playback_stop', and 'make_call' available, the description doesn't indicate that this is specifically for terminating active calls versus transferring them or stopping media playback.
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 'speak text on a call' but does not disclose behavioral traits like required permissions, rate limits, whether it interrupts existing audio, or error conditions. This is inadequate for a mutation 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the purpose, followed by clear parameter and return sections. Each sentence adds value, though it could be more concise by integrating parameter details more seamlessly.
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 complexity of a TTS tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral aspects (e.g., how it interacts with call state), error handling, and output format, despite providing parameter info that contradicts the schema.
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 input schema has 0% description coverage with only one parameter ('request'), but the description lists 7 detailed parameters (e.g., 'call_control_id', 'payload', 'voice'). This is a severe contradiction—the description provides rich parameter semantics that do not align with the schema, making it misleading rather than helpful.
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: 'Speak text on a call using text-to-speech.' It specifies the verb ('speak'), resource ('text'), and context ('on a call'), but does not explicitly differentiate it from sibling tools like 'playback_start' or 'send_dtmf', which are also call-related actions.
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 lacks context about prerequisites (e.g., needing an active call), exclusions, or comparisons to sibling tools such as 'playback_start' for audio playback or 'send_dtmf' for tones, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states the tool performs a transfer action, implying it's a mutation that changes call state, but doesn't cover critical aspects like authentication needs, rate limits, error conditions, or what happens to the original call. This leaves significant gaps in understanding the tool's 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 well-structured and front-loaded, with the core purpose stated first, followed by parameter and return details. It's concise with no wasted sentences, though the parameter section could be more efficient given the schema mismatch.
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 complexity of a call transfer operation, no annotations, no output schema, and a contradictory parameter schema, the description is incomplete. It doesn't explain the return value beyond 'Response data', error handling, or how the transfer affects the call. For a mutation tool with such gaps, it falls short of providing adequate context.
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 description lists three parameters (call_control_id, to, from_) with brief notes, but the input schema shows only one parameter ('request') with 0% description coverage. This creates a contradiction: the description suggests specific parameters, while the schema indicates a generic object. The description fails to clarify this mismatch or provide meaningful semantics beyond what's implied, resulting in poor parameter guidance.
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: 'Transfer a call to a new destination.' It specifies the verb ('transfer') and resource ('a call'), making the action explicit. However, it doesn't distinguish this tool from potential sibling tools like 'hangup' or 'make_call' in the context of call management, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing an active call, or differentiate from other call-related tools like 'hangup' or 'playback_start'. Without this context, the agent lacks clear usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that scraping occurs, content is saved in a new bucket, and embedding is automatic, but lacks critical behavioral details: required permissions, rate limits, error handling, whether the operation is idempotent, or what happens if the URL is invalid. For a mutation tool with zero annotation coverage, this is insufficient.
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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by elaboration and parameter/return details. However, the 'Args' and 'Returns' sections are somewhat redundant with the prose and could be integrated more seamlessly.
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 mutation tool with no annotations, 0% schema coverage, no output schema, and nested input objects, the description is incomplete. It misses behavioral transparency (e.g., side effects, auth needs), parameter details beyond 'url', and output specifics. The return statement is vague ('Response data containing bucket information'), leaving gaps for agent 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 description coverage is 0%, with 1 parameter ('request') documented only as an object with no properties. The description adds value by specifying 'url' as a required argument, but this contradicts the schema's 'request' parameter. It doesn't explain the 'request' object's structure or other possible parameters, failing to compensate for the coverage gap.
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: 'Scrape and embed a given URL' with specific verbs (scrape, embed) and resource (URL). It distinguishes from sibling tools like 'create_embeddings' or 'list_embedded_buckets' by focusing on URL-specific scraping and embedding. However, it doesn't explicitly differentiate from potential similar tools not in the sibling list.
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 is provided. The description doesn't mention prerequisites, limitations (e.g., website types, size limits), or compare with siblings like 'create_embeddings' or 'cloud_storage_upload_file'. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'retrieve' which implies a read operation, but doesn't disclose behavioral traits like authentication requirements, rate limits, error conditions, or response format details beyond 'Dict[str, Any]'. For a tool with no annotations, this leaves significant gaps in understanding how it behaves.
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 appropriately sized and front-loaded with the core purpose in the first sentence. The Args and Returns sections are structured but could be more concise. No extraneous information is included, though the parameter mismatch slightly reduces efficiency.
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, 0% schema coverage, no output schema, and a complex nested parameter structure, the description is incomplete. It doesn't explain the 'request' object, provide error handling, or detail return values beyond a generic type. For a retrieval tool in this context, more guidance is needed to be fully helpful.
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 minimal semantics: it notes 'id' is required and identifies the application, but schema description coverage is 0% with 1 parameter, and the input schema shows a nested 'request' object instead of a direct 'id'. This creates confusion as the description doesn't align with or clarify the schema structure, failing to compensate for the low coverage.
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 verb 'retrieve' and the resource 'specific call control application', making the purpose unambiguous. It distinguishes from sibling tools like 'list_call_control_applications' by specifying retrieval of a single item. However, it doesn't explicitly contrast with 'create_call_control_application' or other siblings, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing application ID), exclusions, or comparisons to sibling tools like 'list_call_control_applications' for browsing or 'create_call_control_application' for creation. Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions the action ('download') and success return value, it doesn't describe error handling, authentication requirements, rate limits, file size constraints, or what happens if the file already exists at the destination path. For a mutation tool with zero annotation coverage, this 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 well-structured with clear sections (Args, Returns) and uses minimal sentences. Each sentence serves a purpose: stating the tool's function, documenting parameters, and specifying the return value. However, the parameter documentation is misleading given the actual 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?
For a file download tool with no annotations, no output schema, and a complex nested input schema (1 parameter with nested objects at 0% coverage), the description is incomplete. It fails to explain the actual 'request' parameter structure, doesn't describe error cases or side effects, and provides parameter documentation that contradicts the actual schema.
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 description lists three parameters (object_name, file_path, bucket_name) with brief explanations, but the input schema shows only one parameter ('request') with 0% description coverage. This creates a direct contradiction - the description documents parameters that don't match the schema structure, providing misleading information rather than adding value beyond what the schema provides.
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 specific action ('Download a file') and resource ('from cloud storage'), distinguishing it from sibling tools like upload_file, delete_object, and list_objects. It uses precise verb+resource language that leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like cloud_storage_list_objects (to check what's available) or cloud_storage_upload_file (for the opposite operation). It doesn't mention prerequisites, error conditions, or contextual constraints for choosing this download operation.
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 mentions the tool lists objects with optional filtering and returns a list of names, which covers basic read-only behavior. However, it fails to disclose critical traits such as pagination behavior, rate limits, authentication requirements, error conditions, or whether it's a safe read operation. For a tool with zero annotation coverage, this leaves significant gaps in understanding its operational characteristics.
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 appropriately sized and front-loaded, starting with the core purpose in the first sentence. The Args and Returns sections are structured for clarity. However, the mismatch between described parameters and schema parameters introduces inefficiency, as the description doesn't accurately reflect the tool's interface.
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 moderate complexity (list operation with filtering), no annotations, low schema coverage (0%), no output schema, and a parameter mismatch, the description is incomplete. It provides basic purpose and return type but fails to address the schema discrepancy, behavioral details like pagination or errors, and doesn't fully guide usage in context of sibling tools. For a tool with these gaps, it should do more to compensate.
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 description documents two parameters ('prefix' and 'bucket_name') with semantics like 'Only list objects beginning with this prefix' and 'Bucket to list from'. However, the input schema shows only one required parameter ('request') with 0% description coverage and nested objects. The description's parameters do not align with the schema's structure, failing to compensate for the schema's lack of documentation and creating confusion about actual parameter usage.
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 ('List') and resource ('objects in a bucket'), and mentions optional prefix filtering. It distinguishes this tool from siblings like 'cloud_storage_list_buckets' by focusing on objects rather than buckets. However, it doesn't explicitly contrast with other object-related tools like 'cloud_storage_download_file' or 'cloud_storage_delete_object'.
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 context through 'optional prefix filtering' and 'defaults to instance default', suggesting when to use this tool for filtered or default bucket listings. However, it lacks explicit guidance on when to choose this tool over alternatives like 'cloud_storage_list_buckets' for bucket-level operations or other object-handling tools. No clear exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the destructive action ('Delete') and a success return value, but lacks critical details like required permissions, whether deletion is permanent, error conditions, or rate limits. This is inadequate for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well-structured with clear sections (purpose, args, returns). Every sentence serves a purpose, though the parameter documentation could be more integrated with the main description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations, 0% schema coverage, no output schema, and complex nested parameters, the description is insufficient. It lacks critical context about permissions, consequences, error handling, and the relationship between described parameters and the actual schema structure.
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 documents two parameters (object_name and bucket_name) with basic semantics, but the input schema shows only one parameter ('request') with 0% description coverage. While the description adds value by naming parameters, it doesn't fully compensate for the schema's poor coverage or explain the nested 'request' object structure.
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 ('Delete') and resource ('object from cloud storage'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'cloud_storage_list_objects' or 'cloud_storage_upload_file' beyond the obvious action difference.
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 about when to use this tool versus alternatives, prerequisites, or constraints. The description only states what the tool does without indicating appropriate contexts or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action is destructive ('Delete') and mentions the return value, but lacks critical details like required permissions, whether the deletion is permanent/irreversible, error conditions, or rate limits. This is inadequate for a mutation 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 well-structured and front-loaded with the core purpose, followed by brief sections for args and returns. Every sentence earns its place with no wasted words, making it highly 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 destructive tool with no annotations and no output schema, the description is incomplete. It lacks behavioral context (e.g., permanence, auth needs), usage prerequisites, and error handling details. The return value is mentioned but without schema, leaving gaps in understanding success/failure responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'id' documented as 'Secret ID as string'. The description adds minimal value by restating 'Secret ID' without providing additional context (e.g., format, where to obtain it). Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('an integration secret'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'cloud_storage_delete_object' or 'mcp_telnyx_delete_assistant' beyond the resource type, which prevents a perfect score.
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 doesn't mention prerequisites (e.g., needing an existing secret ID), exclusions, or comparisons to sibling tools like 'list_integration_secrets' or 'create_integration_secret' for context.
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 it's a read operation ('Get'), implying it's likely safe and non-destructive, but doesn't cover aspects like authentication requirements, error handling, rate limits, or what 'Response data' entails. For a tool with zero annotation coverage, this is insufficient.
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 clear sections for Args and Returns, using minimal sentences. However, the 'Returns' section is vague ('Response data'), which slightly reduces efficiency, preventing a perfect score of 5.
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 (1 parameter, no output schema, no annotations), the description is incomplete. It doesn't explain the return value format, error cases, or how it differs from siblings like 'list_connections'. For a basic read tool, more context is needed to guide the agent effectively.
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 adds minimal semantics beyond the input schema, which has 0% description coverage. It specifies that 'id' is 'Required' and is a 'Connection ID', but doesn't explain the ID format, source, or constraints. With one parameter and low schema coverage, the description partially compensates but lacks depth, aligning with the baseline for moderate coverage.
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 'Get a connection by ID', specifying the verb ('Get') and resource ('connection') with a key constraint ('by ID'). However, it doesn't differentiate from sibling tools like 'list_connections' or 'update_connection', which would require explicit comparison for a score of 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_connections' for browsing or 'update_connection' for modifications, nor does it specify prerequisites such as needing a valid connection ID. This leaves the agent without contextual usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and return type, missing critical details like whether this is a read-only operation, if it requires specific permissions, how results are paginated or sorted, and any rate limits. This leaves significant gaps for an agent to understand the tool's behavior.
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 brief with two sentences, but the second sentence about the return value is somewhat redundant since it doesn't add meaningful structure (e.g., it vaguely states 'Dict[str, Any]: List of assistants' without clarifying the format). It could be more front-loaded and efficient, but it avoids excessive verbosity.
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 complexity of listing resources (which often involves pagination, filtering, or authentication) and the lack of annotations and output schema, the description is insufficient. It doesn't cover behavioral aspects like how results are returned, error conditions, or usage constraints, making it incomplete for effective tool 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 tool has 0 parameters, and the input schema has 100% description coverage (though empty). The description appropriately doesn't discuss parameters, which is correct for a parameterless tool, earning a high baseline score for not adding unnecessary information.
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 ('List all AI Assistants') and specifies the resource ('AI Assistants'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_assistant' or 'create_assistant' beyond the basic verb, which prevents a perfect score.
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 'get_assistant' (for retrieving a specific assistant) or 'create_assistant' (for creating new ones). It lacks any context about prerequisites, such as whether authentication is required or if there are filtering options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'List' implies a read-only operation, the description doesn't mention authentication requirements, rate limits, pagination behavior beyond the parameters, error conditions, or what happens when no numbers match filters. The parameter documentation in the description adds some context but doesn't fully describe the tool's 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 well-structured with clear sections for Args and Returns. Each parameter gets its own line with brief but informative explanations. The opening statement is direct, though the Returns section is somewhat generic ('Dict[str, Any]: Response data'). Overall, the structure is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 logical parameters despite schema showing 1), no annotations, and no output schema, the description does a good job with parameter documentation but leaves gaps in behavioral context. It doesn't explain what 'available' means, how results are structured, error handling, or authentication requirements. For a tool with rich filtering capabilities but no structured metadata, the description is adequate but incomplete.
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 provides detailed documentation for 9 parameters (page, page_size, and 7 filter parameters) with clear explanations of their purposes and optionality. This is excellent compensation for the 0% schema description coverage and single parameter in the input schema. The description transforms an opaque 'request' object into well-documented filtering options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List available phone numbers' which is a clear verb+resource combination, but it's somewhat vague about scope and doesn't distinguish from sibling tools like 'list_phone_numbers' (which likely lists already-owned numbers). The purpose is understandable but lacks specificity about what 'available' means in this context.
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 about when to use this tool versus alternatives. There's no mention of prerequisites, when this tool is appropriate, or how it differs from sibling tools like 'list_phone_numbers' or 'initiate_phone_number_order'. The description assumes the user knows when to list available numbers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the action ('Delete') without behavioral details. It doesn't disclose whether deletion is permanent, requires specific permissions, has side effects, or includes confirmation steps—critical for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and uses a structured format for args and returns, making it efficient. However, the return statement is vague ('Response data containing deletion status') and could be more precise without adding bulk.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description is inadequate. It lacks details on behavioral traits, error handling, and return values, leaving significant gaps for an agent to operate safely and effectively.
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 parameter info ('id: Assistant ID as string') that's already fully covered in the schema (100% coverage). It adds no additional meaning, such as format examples or where to obtain the ID, so it meets the baseline but doesn't enhance understanding.
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 verb ('Delete') and resource ('AI Assistant'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'delete_integration_secret' or 'cloud_storage_delete_object' beyond the resource type, which prevents a perfect score.
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 doesn't mention prerequisites (e.g., needing an existing assistant ID), exclusions, or relationships with sibling tools like 'list_assistants' or 'get_assistant' for verification.
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 that the tool creates an assistant but does not mention any behavioral traits such as permissions required, whether the creation is idempotent, rate limits, or what happens on failure. The description focuses heavily on parameter details but lacks critical operational context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly verbose and poorly structured. It front-loads the purpose but then devolves into a lengthy, nested parameter documentation that belongs in the schema. Sentences like 'The user will provide some details...' are vague and do not earn their place. The text is bloated with implementation details that hinder quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (1 parameter with nested objects, no annotations, no output schema), the description is partially complete. It thoroughly documents parameters but lacks behavioral context, usage guidelines, and output details. For a creation tool with no structured safety or output information, this leaves gaps in operational understanding, though parameter coverage is strong.
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 has 0% description coverage and only one parameter ('request') with no details, but the description compensates extensively. It provides detailed semantics for 15+ parameters (e.g., 'name', 'model', 'instructions', 'tools' with nested structures), explaining their purposes, optionality, defaults, and data types. This adds significant value beyond the minimal 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 clearly states the purpose: 'Create a new AI Assistant.' It specifies the verb ('Create') and resource ('AI Assistant'), making the intent unambiguous. However, it does not explicitly distinguish this tool from its sibling 'update_assistant' or other creation tools like 'create_call_control_application', which slightly reduces clarity in context.
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 mentions that 'The user will provide some details (sometimes detailed, sometimes vague) about the agent they want to create,' but this is generic and does not specify prerequisites, constraints, or when to choose this over other tools like 'update_assistant' or 'get_assistant'. No explicit alternatives 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.
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 mentions the return format (a dict with a 'buckets' list), which is helpful, but fails to address critical aspects like authentication requirements, rate limits, pagination, error handling, or what 'embedded' means operationally. This leaves significant gaps for an agent to understand the tool's 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 front-loaded with the core purpose ('List user embedded buckets.') and efficiently provides a return example. It avoids unnecessary fluff, though the example formatting could be slightly cleaner. Every sentence adds value, making it appropriately 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?
Given the tool's low complexity (0 parameters, no annotations, no output schema), the description is moderately complete—it states the purpose and shows a return example. However, it lacks details on behavioral traits (e.g., auth, errors) and doesn't clarify how 'embedded' buckets differ from other bucket types in the sibling tools, leaving room for improvement in contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the input schema has 100% description coverage (though empty). The description doesn't need to add parameter details, so it appropriately focuses on the return value. However, it could have mentioned if any implicit parameters (like user context) are involved, but this is a minor omission given the zero-param baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('user embedded buckets'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'cloud_storage_list_buckets' or 'list_buckets' (implied from context), leaving some ambiguity about what makes 'embedded' buckets distinct.
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 'cloud_storage_list_buckets' or other list tools in the sibling set. The description lacks context about prerequisites, constraints, or typical use cases, offering minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states this is a 'Get' operation, implying it's read-only, but doesn't disclose behavioral traits like authentication requirements, rate limits, error conditions, or whether the TEXML content is returned as raw text or structured data. The description is minimal and lacks operational 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 appropriately sized and front-loaded with the core purpose. The two-sentence structure (purpose and returns) is efficient, though the 'Args' and 'Returns' sections are slightly redundant with the schema but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally complete. It covers the purpose and return type, but lacks context on usage, behavior, or output format details, which could be helpful for an agent despite the simple schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'assistant_id' documented in the schema. The description adds no additional meaning beyond what's in the schema (e.g., format, examples, or constraints), so it meets the baseline of 3 where 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 the specific action ('Get') and resource ('assistant's TEXML by ID'), distinguishing it from sibling tools like 'get_assistant' (which likely returns general assistant info) and 'list_assistants' (which lists multiple assistants). The mention of 'TEXML content' specifies the exact data returned.
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 is provided on when to use this tool versus alternatives. While the description implies it's for retrieving TEXML content for a specific assistant ID, it doesn't mention when to choose this over other assistant-related tools like 'get_assistant' or prerequisites for usage.
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 tool retrieves a message by ID but doesn't cover critical aspects like authentication requirements, rate limits, error handling, or whether it's a read-only operation. This leaves significant gaps in understanding how the tool behaves.
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 front-loaded with the core purpose, followed by clear sections for Args and Returns. Every sentence earns its place with no redundant information, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate but incomplete. It covers the basic operation and parameter but lacks behavioral context and usage guidelines, which are needed for a retrieval tool in a messaging system.
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 meaningful context for the single parameter ('message_id: The ID of the message to retrieve'), which is valuable since schema description coverage is 0%. However, it doesn't specify the format or constraints of the ID (e.g., string length, pattern), 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 the tool's purpose with a specific verb ('Retrieve') and resource ('message by ID'), making it immediately understandable. However, it doesn't differentiate from sibling tools like 'get_assistant' or 'get_phone_number' beyond the resource type, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for message retrieval, or compare it to related tools like 'send_message' or 'list_connections' for messaging workflows, leaving the agent without usage direction.
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 implies a mutation operation ('update') but does not specify required permissions, whether changes are reversible, rate limits, or error handling. The mention of 'Returns: Dict[str, Any]: Response data' is vague and adds minimal value beyond indicating a dictionary output.
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 front-loaded with the core purpose but becomes lengthy due to exhaustive parameter documentation. While each parameter detail is useful, the structure could be more streamlined, and some redundancy exists (e.g., repeating 'Optional' for each param). It balances completeness with verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 required params, 16 optional params, nested objects, no output schema, and no annotations), the description is partially complete. It excels in parameter semantics but lacks behavioral context, usage guidelines, and output details, making it adequate but with clear gaps for a mutation 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 description compensates fully for the 0% schema description coverage by detailing all 16 optional parameters with clear semantics, including data types, constraints (e.g., ISO codes, boolean flags), and nested structures. This adds significant value beyond the minimal input schema, which only lists 'profile_id' and 'request' without specifics.
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 verb 'update' and resource 'messaging profile', making the purpose evident. However, it does not differentiate from sibling tools like 'update_assistant' or 'update_connection', which have similar naming patterns but operate on different resources, so it lacks explicit sibling 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?
No guidance is provided on when to use this tool versus alternatives. For example, it does not mention prerequisites like needing an existing profile or compare with 'create_messaging_profile' or 'get_messaging_profile', leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Get[s] the region' and describes a default bucket behavior, but lacks details on permissions required, error handling (e.g., if bucket doesn't exist), rate limits, or response format beyond a string. For a read operation with no annotation coverage, this is insufficient to fully inform agent behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the core purpose stated first, followed by concise sections for arguments and returns. Every sentence adds value without redundancy, making it easy for an agent to parse quickly.
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 complexity (1 parameter with nested objects, 0% schema coverage, no output schema, and no annotations), the description is incomplete. It explains the purpose and return type but does not address the input schema mismatch, behavioral aspects like error cases, or provide enough detail for reliable tool invocation. This leaves significant gaps for an agent to operate effectively.
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 input schema has 0% description coverage and includes a nested object 'request' with no documented properties, while the description mentions 'bucket_name' as an optional parameter. This creates a contradiction: the description adds semantic meaning for a parameter not reflected in the schema, but fails to address the actual schema parameter 'request'. With low schema coverage and mismatched parameters, the description does not compensate effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('region where a bucket is located'), making the purpose specific and unambiguous. It distinguishes this tool from siblings like cloud_storage_list_buckets (which lists buckets) or cloud_storage_create_bucket (which creates buckets), as it focuses on retrieving location information for a specific bucket.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool by specifying it retrieves bucket region information, implying it's for location queries rather than creation, deletion, or listing operations. However, it does not explicitly state when not to use it or name alternatives (e.g., cloud_storage_list_buckets for general bucket info), leaving some guidance gaps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions required/optional parameters for different secret types, it doesn't disclose important behavioral traits like authentication requirements, rate limits, whether this is a mutating operation, error conditions, or what happens if a secret with the same identifier already exists.
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 clear sections for Args and Returns, making it easy to parse. While concise, it could be slightly more front-loaded by stating the purpose more prominently before diving into parameters. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of creating different types of secrets with varying required parameters, the description does a good job explaining parameter semantics. However, with no annotations and no output schema, it should provide more behavioral context about the operation's effects, error handling, and the structure of the returned Integration Secret Object beyond just its record_type.
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 description provides comprehensive parameter documentation that fully compensates for the 0% schema description coverage. It clearly explains each parameter's purpose, requirements, and relationships (e.g., which parameters are required for which secret types). This adds significant value beyond the minimal input 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 clearly states the verb 'create' and the resource 'integration secret', making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling 'delete_integration_secret' beyond the obvious action difference, nor does it explain what an 'integration secret' is in this context.
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. There's no mention of prerequisites, when this operation is appropriate, or how it relates to sibling tools like 'list_integration_secrets' or 'delete_integration_secret' in a workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool retrieves 'most recent' events with default filtering, implying read-only behavior, but does not mention rate limits, authentication needs, or what 'metadata' includes. It adds some context but misses key behavioral details for a tool with no 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by parameter and return details. It uses bullet-like formatting for clarity without unnecessary elaboration. Every sentence adds value, making it efficient and easy to parse.
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 adequate basics but lacks completeness. It covers parameters and return type broadly but does not specify the structure of the 'Dict' or 'metadata', which could hinder accurate tool invocation. For a tool with no structured support, more detail would improve usability.
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 meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'limit' controls the maximum number of events and 'event_type' filters by type, including default values. This compensates well for the schema's lack of descriptions, though it could detail allowed event types.
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: 'Get the most recent webhook events received by the handler.' It specifies the verb ('Get') and resource ('webhook events'), making the function unambiguous. However, it does not differentiate from sibling tools, as none appear to be webhook-related, so this is not a deduction.
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 lacks context about prerequisites, such as whether webhooks must be configured, or comparisons to other event-fetching methods. This leaves the agent without usage direction beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Update an AI Assistant' which implies a mutation operation, but it doesn't describe permissions needed, whether changes are reversible, rate limits, or error handling. The mention of 'talk the user about what can be updated' adds some conversational context but is vague.
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 front-loaded with the purpose, but it includes a lengthy, detailed parameter list that could be better structured. While informative, the parameter section is verbose and might be more efficiently presented, though it serves a clear purpose given the schema's deficiencies.
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 complexity (2 parameters with nested objects, no annotations, no output schema), the description does a good job of covering parameter details. However, it lacks information on return values (only states 'Dict[str, Any]: Response data') and behavioral aspects like error cases or side effects, leaving some gaps.
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 description provides extensive details on parameters beyond the input schema, which has 0% coverage and only lists 'assistant_id' and 'request'. It documents optional fields like 'name', 'model', 'instructions', and nested structures for 'tools', 'greeting', etc., adding significant semantic value that compensates for the schema's lack.
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 verb 'Update' and resource 'AI Assistant', making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'create_assistant' or 'get_assistant' beyond the update action, though the distinction is implied.
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 mentions 'Once there is an agent created, you can talk the user about what can be updated' which implies usage after creation, but it lacks explicit guidance on when to use this tool versus alternatives like 'create_assistant' or 'get_assistant', and provides 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 provided, the description carries full burden for behavioral disclosure. It implies a write operation ('Create') and documents many configuration parameters with defaults, which adds useful context. However, it lacks critical behavioral details like authentication requirements, rate limits, error handling, or whether the creation is idempotent/reversible, leaving significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately front-loaded with the core purpose, but the parameter documentation is verbose and could be more structured. While comprehensive, some details like nested dictionary keys could be streamlined. The 'Returns' section is minimal but adequate given no output schema exists.
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 complex creation tool with 14+ parameters, nested objects, and no annotations/output schema, the description provides good parameter coverage but lacks important contextual elements. Missing are authentication requirements, error responses, typical use cases, and relationship to sibling tools. The parameter documentation is strong, but other aspects remain 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 description provides extensive parameter documentation that fully compensates for the 0% schema description coverage. It clearly explains all 14+ parameters (including nested structures for inbound/outbound), their purposes, data types, defaults, and constraints (e.g., URL scheme requirement). This adds substantial value beyond the minimal input schema that only shows a generic 'request' object.
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 verb 'Create' and the resource 'call control application', providing specific purpose. However, it doesn't differentiate from sibling tools like 'create_assistant' or 'create_messaging_profile' beyond the resource name, missing explicit comparison to similar creation tools in the same domain.
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. There are no prerequisites mentioned (e.g., required permissions, account setup), no comparison to sibling tools like 'get_call_control_application' or 'list_call_control_applications', and no context about typical workflows where this creation 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?
No annotations are provided, so the description carries the full burden. It states the tool retrieves data, implying a read-only operation, but doesn't disclose behavioral traits such as authentication requirements, rate limits, error handling, or what happens if the ID is invalid. For a retrieval tool with zero annotation coverage, this is a significant gap 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by structured 'Args' and 'Returns' sections. Every sentence earns its place by providing essential information without redundancy or fluff, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the basic purpose and parameter semantics, but lacks behavioral context (e.g., error cases, permissions) and output details (only mentions 'Response data containing messaging profile details' without schema). This is adequate but not fully comprehensive for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema. The schema has 1 parameter with 0% description coverage (only a title 'Profile Id'), while the description explains that 'profile_id' is 'The ID of the messaging profile to retrieve,' clarifying its purpose and usage. This compensates well for the low schema coverage, though it doesn't detail format or constraints.
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: 'Retrieve a messaging profile by ID.' It specifies the verb ('Retrieve') and resource ('messaging profile'), and distinguishes it from siblings like 'list_messaging_profiles' (which lists multiple) and 'create_messaging_profile' (which creates). However, it doesn't explicitly differentiate from 'get_connection' or 'get_phone_number' which are similar retrieval operations on different resources.
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 stating it retrieves a profile 'by ID,' suggesting it's for fetching a specific known profile. It doesn't provide explicit guidance on when to use this versus alternatives like 'list_messaging_profiles' (for browsing) or other retrieval tools, nor does it mention prerequisites or exclusions. The context is clear but lacks detailed alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It implicitly indicates a write operation ('Create') and documents many configuration options, but doesn't explicitly state permission requirements, rate limits, error conditions, or what happens on success/failure. It provides moderate context about what gets created but lacks comprehensive behavioral details.
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 well-structured with clear sections for Args and Returns, but it's overly verbose with detailed parameter documentation that might be better handled in the schema. While comprehensive, it could be more concise by focusing on high-level guidance rather than exhaustive parameter details that belong in structured fields.
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 complexity of creating a messaging profile with many configuration options, no annotations, and no output schema, the description provides substantial context through detailed parameter documentation. However, it lacks information about the return value structure beyond 'Dict[str, Any]' and doesn't cover error handling or operational constraints, leaving some gaps in 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?
Despite having 0% schema description coverage (the schema only shows a generic 'request' object), the description provides extensive parameter documentation with 14 detailed parameters, including required/optional status, data types, defaults, and specific usage examples. This fully compensates for the poor schema coverage and adds substantial value beyond what the schema provides.
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 verb 'Create' and the resource 'messaging profile', making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'update_messaging_profile' or explain what distinguishes creation from updating, which prevents a perfect score.
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 'update_messaging_profile' or 'get_messaging_profile'. There's no mention of prerequisites, dependencies, or typical use cases, leaving the agent with insufficient context for proper tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates this is a mutation tool ('update'), which implies it modifies data, but doesn't disclose behavioral traits like required permissions, rate limits, or side effects. The description adds some context about parameter handling (null, empty string, UUID), but lacks comprehensive behavioral details.
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 appropriately sized and front-loaded, with the purpose stated first. The Args and Returns sections are structured clearly. However, the 'Returns' section is vague ('Response data') and could be more specific, slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (mutation tool with 2 parameters, nested objects, no annotations, no output schema), the description is moderately complete. It covers parameter semantics well but lacks behavioral context (e.g., permissions, side effects) and output details. It's adequate but has clear gaps for a mutation 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 description adds significant meaning beyond the input schema. The schema has 0% description coverage and only shows 'id' and 'request' as parameters, while the description explains 'id' as 'The phone number ID to update' and introduces 'messaging_profile_id' and 'messaging_product' with detailed semantics (null to keep current, empty string to unassign, UUID to assign). This fully compensates for the schema's lack of coverage.
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: 'Update the messaging profile and/or messaging product of a phone number.' It specifies the verb ('update') and resource ('phone number'), but doesn't explicitly differentiate from sibling tools like 'update_phone_number' or 'update_messaging_profile', which is why it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'update_phone_number' or 'update_messaging_profile', nor does it specify prerequisites or exclusions. Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions what the tool does, it doesn't describe important behavioral aspects like whether this requires specific permissions, what happens to ongoing audio streams, error conditions, or response format details. The description provides basic functionality but lacks depth for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, args, returns) and uses bullet-like formatting. While efficient, the 'Returns' section could be more specific than 'Dict[str, Any]: Response data' given there's no output schema. Overall, it's appropriately sized with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 1 parameter (though the description documents 3), 0% schema coverage, no annotations, and no output schema, the description does a reasonable job. It covers parameters well but lacks behavioral context about permissions, side effects, and response structure. The description is adequate but has clear gaps given the complexity of an audio control 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 description provides comprehensive parameter documentation that fully compensates for the 0% schema description coverage. It clearly explains all three parameters (call_control_id, overlay, stop) with their purposes, requirements, optionality, default values, and valid values. This adds significant meaning beyond what the minimal input schema provides.
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 specific action ('Stop audio playback') and resource ('on a call'), distinguishing it from sibling tools like 'playback_start' and 'speak' which start audio rather than stop it. The verb+resource combination is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (stopping audio during a call) but doesn't explicitly state when to use this tool versus alternatives like 'hangup' or 'transfer'. No guidance is provided about prerequisites or exclusions, leaving usage context somewhat implied rather than explicitly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the source phone number requirement but doesn't describe authentication needs, rate limits, error conditions, or what happens during call initiation. For a mutation tool with zero annotation coverage, this 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear opening statement followed by organized parameter and return sections. Every sentence serves a purpose with zero wasted words, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 3 parameters, no annotations, and no output schema, the description provides adequate basic information but lacks details about authentication, error handling, response format, or call behavior. It's minimally viable but has clear gaps given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides clear semantic meaning for all three parameters: 'assistant_id' (ID of assistant to use), 'to' (destination phone number), and 'from_' (source phone number with account requirement). This adds substantial value beyond the bare 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 specific action ('Start a call'), resource ('using an AI Assistant with a phone number'), and distinguishes it from siblings like 'make_call' by specifying it uses an AI assistant rather than a generic call. It provides a complete verb+resource+scope combination.
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 context by specifying 'must be a number on your Telnyx account' for the 'from_' parameter, but doesn't explicitly state when to use this tool versus alternatives like 'make_call' or provide clear exclusions. Guidance is present but not comprehensive.
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 describes the action and parameters but lacks details on permissions, rate limits, error conditions, or what 'Response data' contains. It doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear purpose statement followed by parameter and return sections. Slightly verbose in listing all parameter details, but each sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and complex parameters, the description covers purpose and parameters well but lacks behavioral context (e.g., side effects, error handling) and details on the return value beyond 'Response data', leaving gaps for agent 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?
Schema description coverage is 0% with only one undocumented parameter ('request'), but the description compensates by detailing six specific parameters (call_control_id, audio_url, loop, overlay, stop, target_legs) with meanings, requirements, valid values, and defaults, adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Start audio playback') and resource ('on a call'), distinguishing it from sibling tools like 'playback_stop', 'speak', or 'make_call' which involve different audio/call operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for playing audio during calls but doesn't explicitly state when to use this versus alternatives like 'speak' (for text-to-speech) or 'playback_stop'. No exclusions or prerequisites 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?
With no annotations provided, the description carries the full burden. It discloses the action ('Send DTMF tones') which implies a write/mutation operation, and specifies parameter details like digit format and default duration. However, it lacks critical behavioral context such as whether this requires specific call permissions, if it's synchronous/asynchronous, error conditions, or rate limits. The description adds some value but doesn't fully compensate for 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 perfectly structured and concise: a clear purpose statement followed by well-organized parameter documentation in a bullet-like format. Every sentence earns its place by providing essential information without redundancy. The information is front-loaded with the core purpose immediately stated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (sending DTMF tones during calls), no annotations, and no output schema, the description does reasonably well by explaining parameters thoroughly. However, it lacks important contextual information about the operation's behavior (e.g., synchronous nature, error handling), the structure of the return value beyond 'Dict[str, Any]', and integration with call states. For a mutation tool with zero annotation coverage, more behavioral context would be beneficial.
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 description coverage is 0% (only a generic 'request' object), but the description provides comprehensive parameter details: it names three parameters, specifies required/optional status, describes valid digit formats ('0-9, *, #, w, W'), and indicates default values. This significantly compensates for the poor schema coverage, though it doesn't fully explain the nested 'request' object structure mentioned in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Send DTMF tones') and resource ('on a call'), with a precise verb+resource combination. It distinguishes itself from sibling tools like 'playback_start', 'speak', or 'hangup' by focusing specifically on DTMF tone transmission rather than audio playback, voice synthesis, or call termination.
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 context through the parameter descriptions (e.g., 'call_control_id', 'digits'), suggesting it should be used during an active call to send DTMF tones. However, it doesn't explicitly state when to use this tool versus alternatives like 'playback_start' for audio or 'speak' for text-to-speech, nor does it mention prerequisites like requiring an active call or specific call states.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return format (list of dictionaries with name and region fields), which is valuable behavioral information. However, it does not mention potential limitations like rate limits, authentication requirements, pagination behavior, or error conditions, leaving gaps in operational 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 extremely concise and well-structured: the first sentence states the purpose, and the second clearly documents the return format. Every sentence adds essential value with zero wasted words, making it easy for an agent to parse and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is nearly complete: it explains what the tool does and what it returns. However, it lacks information about behavioral aspects like error handling or performance characteristics, which would be helpful for robust agent 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 tool has 0 parameters with 100% schema description coverage (empty schema). The description does not need to explain any parameters, which is appropriate. No additional parameter semantics are required, so it meets the baseline for this condition.
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 specific action ('List all buckets') and resource ('across all regions'), distinguishing it from siblings like 'cloud_storage_list_objects' (which lists objects within a bucket) and 'cloud_storage_get_bucket_location' (which gets location for a specific bucket). The verb 'List' is precise and the scope 'across all regions' is explicitly defined.
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 needing to enumerate all storage buckets globally, but does not explicitly state when to use this tool versus alternatives like 'cloud_storage_list_objects' or 'cloud_storage_get_bucket_location'. No exclusions or prerequisites are mentioned, leaving the agent to infer context from the tool name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool retrieves data (a read operation) and describes the return format, which adds value. However, it lacks details on error handling, authentication needs, rate limits, or whether the operation is idempotent, leaving behavioral gaps 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose ('Get a phone number by ID'), followed by structured sections for arguments and returns. Every sentence is necessary and contributes to understanding, with zero wasted words, making it highly efficient and well-organized.
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 (single parameter, no output schema, no annotations), the description is mostly complete: it explains the purpose, parameter, and return format. However, it could improve by addressing potential errors or behavioral nuances, slightly reducing completeness for a tool with no structured safety hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'id' documented as 'Phone number ID as string' in both the schema and description. The description adds no extra semantic meaning beyond what the schema provides, such as format examples or constraints, so it meets the baseline for high schema coverage without enhancement.
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 specific action ('Get') and resource ('phone number by ID'), distinguishing it from sibling tools like 'list_phone_numbers' (which retrieves multiple numbers) and 'update_phone_number' (which modifies a number). It precisely defines the tool's scope as retrieving a single entity by identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'by ID', suggesting it should be used when you have a specific phone number identifier rather than browsing or filtering. However, it does not explicitly state when not to use it (e.g., vs. 'list_phone_numbers' for multiple numbers) or name alternatives, keeping it from a perfect score.
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 full burden and excels by disclosing critical behavioral traits: it reveals the tool will fail due to API limitations (only GET, HEAD, OPTIONS allowed), warns about raising an exception, and explains the workaround. This goes far beyond basic functional description.
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 clear sections (Note, Args, Returns, Raises) and front-loads the critical limitation. While slightly longer due to the warning, every sentence earns its place by conveying essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (it's essentially non-functional due to API constraints), no annotations, and no output schema, the description provides complete context: it explains the purpose, documents parameters, warns about the exception, and provides an alternative solution. This is comprehensive for a tool with inherent limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents both parameters (id, data) with basic semantics ('Required. Connection ID' and 'Required. Update data'), but doesn't elaborate on data structure or constraints. This provides minimal value beyond the schema's property names.
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 as 'Update a connection' with a specific verb and resource. It distinguishes itself from siblings by explicitly noting the Telnyx API limitation and providing an alternative approach (create a new connection), making it highly specific and differentiated.
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 provides explicit guidance on when NOT to use this tool ('The Telnyx API does not support updating connections directly') and offers a clear alternative ('Please create a new connection with the desired settings instead'). This directly addresses usage context and exclusions.
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/team-telnyx/telnyx-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/team-telnyx/telnyx-mcp-server)

Score Badge

Copy to your README.md:

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

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