AgentLine

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

Annotations indicate a mutation (readOnlyHint=false) and open world. The description adds cost and agent limit but fails to clarify what happens if the agent already has a number (replacement? error?). This gap in expected behavior reduces transparency.

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

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

The description is fairly verbose, especially with the response section including detailed error schemas that are not essential. The parameter list repeats schema info, which could be streamlined. However, it is well-organized with clear sections.

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

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

Covers basic purpose and constraints but misses important details like behavior on conflict (agent already has a number), how to check availability, and success response shape. The empty output schema does not help, and the error schema is over-emphasized.

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

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

Schema coverage is 100%, and the description adds value by explaining parameter constraints (e.g., country must be 'US'), providing area code examples, and noting the 'pattern' parameter as legacy. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: buying a US phone number for an AI agent, distinguishing it from sibling tools like list_phone_numbers and make_outbound_call. It specifies the verb (buy), resource (phone number), and action (attach to agent).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides clear context for when to use (when an agent needs a phone number) and constraints (only US, $2 cost, one per agent). It does not explicitly mention when not to use or alternative tools, but the context is sufficient for most cases.

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

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

Annotations indicate a write operation, and the description confirms by detailing setup fields (system_prompt, voice, greeting). It adds context about the next step (buy phone number) but does not cover potential costs or idempotency.

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

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

The description is well-structured with a bullet list and response examples, but the inclusion of full output schemas for both success and error responses makes it somewhat verbose for an AI agent to parse efficiently.

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

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

Given the tool's complexity (7 parameters, no separate output schema), the description covers most aspects: field purposes, workflow, and response example. Missing elements include rate limits and explicit validation rules beyond HTTP 422.

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

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

The input schema has 100% coverage, but the description enhances each parameter with examples (e.g., 'female-1' for voice_id, GPT-4o-mini for model_tier) and practical context, adding significant value beyond the schema.

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

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

The description explicitly states the tool creates a new AI voice agent for telephony, which is a specific verb-resource pair. It distinguishes from siblings like update_agent and delete_agent by focusing on creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides clear context by mentioning the workflow: create an agent, then buy a phone number. However, it does not explicitly state when not to use this tool or compare to alternatives like update_agent.

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

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

Annotations already include destructiveHint:true and idempotentHint:true. The description adds behavioral context about phone number detachment, which is valuable. However, it does not elaborate on idempotency or other traits like reversibility, so the added value is moderate.

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

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

The description is front-loaded with a clear title and one-line summary, but then includes extensive response examples and error schemas. While the response details may be useful for invocation, the length could be reduced without losing essential information.

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

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

Given the simple input schema and lack of output schema, the description covers the main behavior (deletion and phone number detachment) and response structures (success empty, error format). It lacks prerequisites (e.g., agent must exist) but is otherwise complete for a destructive operation.

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

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

The single parameter 'agent_id' has no description in the schema (0% coverage). The description does not provide additional meaning beyond the parameter name, leaving the agent to infer its purpose from the tool's context. This is barely adequate.

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

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

The description clearly states 'Delete an AI voice agent' which directly conveys the action and resource. The verb 'delete' is unambiguous, but it does not explicitly differentiate from sibling tools like 'create_agent' or 'update_agent', though the action itself is distinct enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides context on when to use this tool by explaining the side effect: it permanently removes the agent and detaches phone numbers, which remain active. However, it does not explicitly mention when not to use it or suggest alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the returned fields (balance, currency, rates, coverage) and the use case, which are not covered by annotations. No contradictions or omissions observed.

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

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

The description is very concise: a title, a brief purpose sentence, a bullet-like list of outputs, and a usage recommendation. No extraneous content. Front-loaded with the key action and resource.

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

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

For a simple, parameterless, read-only tool with rich annotations, the description is fully adequate. It explains the return values, use case, and even mentions a response schema (though empty). No missing information for an agent to select or invoke this tool correctly.

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

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

There are zero parameters, and schema coverage is 100%. The description does not need to add parameter information. According to guidelines, baseline for 0 parameters is 4, which is appropriate.

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

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

The tool name and description clearly state it retrieves the account balance and rate card. It specifies the exact data returned (balance, currency, billing rates, coverage) and distinguishes itself from sibling tools like buy_phone_number or make_outbound_call by focusing on affordability checks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly advises using it to check affordability before making calls or buying numbers, providing clear when-to-use guidance. It does not explicitly exclude other contexts or mention alternatives, but the context is sufficient for a read-only information tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about override behavior and the return value (the default voice), which is consistent and adds value beyond the annotations.

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

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

The description is concise with a clear front-loaded purpose. The response section adds minor structure but is not essential since no output schema is defined. Overall efficient.

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

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

For a zero-parameter tool with good annotations, the description explains the core functionality and override behavior. However, it lacks any detail about the expected response structure (e.g., what fields are returned), which would be helpful for an agent.

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

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

No parameters exist, so baseline is 4 as per guidelines. The description does not need to add parameter information but could have clarified the response structure, which is missing.

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

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

The description clearly states the tool retrieves the account-level default voice for AI phone agents, and explains its scope and relationship to agent-level and per-call overrides. This distinguishes it from siblings like set_account_voice and reset_account_voice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description mentions the inheritance behavior but does not explicitly contrast with sibling list_available_voices (which lists all voices, not the current default). No explicit when-to-use or when-not-to-use guidance is given.

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

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

Annotations already declare read-only and idempotent. The description adds details of returned data without contradictions, though it includes extraneous schema details.

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

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

The core description is concise but is padded with unnecessary output schema and response code details, reducing clarity.

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

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

For a simple get tool, the description covers purpose and return data adequately, though parameter semantics are weak and error handling is over-detailed.

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

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

The lone parameter agent_id has no schema description and the description only implies its purpose without providing format or constraints, insufficient for 0% coverage.

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

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

The description clearly states 'Get details of a specific AI voice agent' and lists returned fields (system prompt, voice settings, etc.), distinguishing it from siblings like list_agents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description implies usage for retrieving a single agent's configuration, but does not explicitly mention when not to use it or alternative tools.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds that the tool returns metadata and transcript, which is useful context beyond annotations.

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

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

The description front-loads the purpose but includes redundancy ('Get Call' then 'Get full details') and a large error schema that inflates length. Core information is present but could be more streamlined.

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

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

The description enumerates return fields, compensating for the missing output schema. However, it lacks usage guidance, parameter details, and does not mention error cases beyond the 422 example. Adequate for a simple get tool.

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

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

The single parameter 'call_id' has no description in the schema (0% coverage) and the description does not explain its format or how to obtain it. While the parameter is self-explanatory, the description should compensate for the lack of schema documentation.

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

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

The description clearly states it retrieves full details of a specific voice call, listing included metadata and transcript. It implies comprehensiveness but does not explicitly differentiate from sibling tools like get_call_transcript, which returns only the transcript.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No guidance on when to use this tool versus alternatives such as get_call_transcript or list_calls. The description assumes the agent knows when to fetch full details.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying that the transcript is speech-to-text with each turn labeled by role ('human' for caller, 'assistant' for AI agent). No contradictions.

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

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

The description is concise, front-loading the key purpose. It includes helpful response codes and example structure, though the output schema is empty. Every sentence is useful.

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

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

Given no output schema, the description adequately explains the return format (roles labeled). It is complete enough for this simple tool with one parameter and well-understood behavior.

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

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

Schema description coverage is 0%, so the description does not explain the single parameter call_id. However, the parameter name is self-explanatory. The description does not compensate for the low coverage, making this baseline 3.

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

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

The description clearly states 'Get Transcript' and explains it returns the full conversation transcript with roles labeled by caller and AI agent, distinguishing it from siblings like get_call_details which likely return different info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description mentions it is 'useful for reviewing what was said on the call, extracting information, or auditing AI agent behavior,' providing context but not explicitly stating when not to use or comparing to alternatives like get_call_details.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds minimal behavioral context beyond the return content details (counts and averages). No contradictions. With annotations, the description provides adequate but not exceptional transparency.

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

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

The description is front-loaded with the main purpose and breaks down categories. However, it includes verbose response examples and output schema that could be trimmed. Still, it is well-structured and not overly long.

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

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

Despite the empty output schema, the description explains the return structure (categories, counts, averages) and covers the error response. Given the tool's simplicity, this is sufficient and contextually complete.

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

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

The sole parameter 'period' is already well-documented in the input schema with enumeration of allowed values. The description does not add any additional meaning, and schema coverage is 100%, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'expenditure breakdown', specifying it is for AI telephony usage with categories (voice calls, provisioning, etc.). It distinguishes from sibling tools which are about calls, agents, or phone numbers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description implies usage for tracking spending but does not explicitly state when not to use it or mention alternative tools like get_account_balance. Guidance is present but not thorough.

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

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

Description states termination and that final transcript/billing are processed automatically. Annotations already provide destructiveHint=true, so description adds useful behavioral context. Lacks mention of irreversibility, but overall adequate.

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

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

The essential description is concise and front-loaded. The appended response schemas add length but are useful for understanding error cases. Could be slightly more streamlined by merging the redundant title line.

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

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

Given no output schema, the description includes response schemas and examples, which helps. However, it does not explicitly describe the typical success response or failure modes in plain text. Adequate for a simple tool but not complete.

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

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

The only parameter, call_id, has 0% schema description coverage and is not explained in the description. The agent is not told what call_id is or where to obtain it, which is a significant gap for a required parameter.

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

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

The description clearly states the action 'Hang up an active phone call' and 'terminates an in-progress voice call'. It is distinct from sibling tools like make_outbound_call (starts a call) and get_call_details (retrieves info).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicit usage context is given: 'Use this when the AI agent needs to end the conversation, or to force-stop a call that is no longer needed.' No direct contrast with alternatives, but given no other end-call tool exists, it is clear enough. Could mention preconditions like call must be active.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds what is returned (system prompts, voice settings, phone numbers). No contradictions.

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

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

Description includes redundant heading 'List Agents' and an empty 'Responses' section. Otherwise concise, but could be streamlined.

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

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

For a zero-parameter, read-only list tool, the description adequately covers what is returned and purpose. Without an output schema, it provides expected fields.

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

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

No parameters; baseline of 4 applies. Description does not need to add parameter info. Schema coverage is 100%.

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

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

Clear verb 'List' and resource 'agents', explicitly states it returns all agents with details. Distinguishes from siblings like get_agent (single) and create_agent (create).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Provides a use case: checking which agents are ready to make/receive calls. Does not explicitly exclude other uses or contrast with siblings, but context implies listing all vs. individual retrieval.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining that the tool returns named TTS presets usable for agent configuration, and mentions the data source (Cartesia). This goes beyond the annotations but still omits potential behavioral details like pagination or account-scoping.

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

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

The description is concise, front-loads the purpose, and includes essential details without unnecessary verbosity. The structure (title, short paragraph, usage tip) is clear, though the response section could be trimmed.

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

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

Given no output schema, the description partially explains what is returned (named TTS presets) and gives examples, but lacks explicit structure of the response (e.g., fields like id, name). It also does not clarify if the list is account-specific or global. The description is adequate for a simple tool but could be more complete.

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

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

Schema coverage is 100% with no parameters. The description adds value by explaining how the returned voices can be used (preset names or direct UUIDs), which provides context for the tool's output rather than parameters. This compensates for the lack of schema details.

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

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

The description clearly states the tool lists all available voice presets for AI phone agents, using specific verb 'List' and resource 'Available Voices'. It distinguishes from sibling tools by focusing on voice presets, and includes additional usage details about preset names and UUIDs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description implies usage when you need to see available voice presets, but does not explicitly state when to use this tool versus alternatives. It includes a note on how to use the results (preset names or UUIDs) but lacks clear context for when not to use it or comparisons with other tools.

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

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

Annotations (readOnlyHint=true, destructiveHint=false) already indicate a safe read operation. The description adds no contradictory info and lists return fields, but does not disclose additional behavioral traits like rate limits or pagination specifics beyond offset/limit.

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

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

The description is well-structured with headings and bullet points, front-loading the purpose. However, including the full HTTPValidationError schema and empty output schema adds unnecessary verbosity for an AI agent.

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

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

Despite no output schema, the description explains return fields (direction, duration, phone numbers, status) and documents all four filters. This fully compensates for the missing output schema, making the tool's behavior clear.

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

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

Schema coverage is 100%, with each parameter described in the input schema. The description restates filter logic but adds no novel meaning beyond what the schema already provides, meeting the baseline for a well-covered schema.

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

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

The description clearly states 'List voice calls made by your AI agents' and is distinct from sibling tools like list_agents or list_messages. It specifies the resource (voice calls) and action (list) with optional filters, leaving no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description mentions optional filters by agent or status, providing clear context for usage. However, it does not explicitly state when not to use this tool versus alternatives like get_call_details for specific call info.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety is clear. The description adds that each entry includes direction, phone numbers, body, and delivery status, but does not disclose ordering, pagination behavior, or any potential rate limits. It meets the minimum bar with annotations present.

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

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

The description is well-structured with a title and bullet-like list of response fields. It is front-loaded with the main purpose and uses efficient language. The response section includes unnecessary boilerplate about error responses, but overall it is concise.

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

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

The tool is a simple list operation with 4 parameters and no output schema. The description covers the purpose, filters, and response fields. It could mention default sorting or pagination details, but for a straightforward list tool this is largely sufficient.

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

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

Schema description coverage is 100% and each parameter has a clear description. The description adds 'with optional filters by AI agent or conversation' which reinforces the schema but does not provide additional semantic richness beyond what the schema already offers.

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

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

The description clearly states 'List SMS messages sent and received by your AI agents' with a specific verb and resource. It distinguishes from siblings like list_calls and list_agents by focusing on SMS messages and mentioning optional filters by agent or conversation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides context on when to use the tool (to retrieve SMS history) and mentions optional filters, but does not explicitly state when not to use it or how it compares to similar list tools. However, the sibling set is diverse enough that this clarity is adequate.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so safety is covered. The description adds that it returns assignment, status, and country, which is helpful but not extensive. No contradictions.

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

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

The description is concise and front-loaded, but includes an unnecessary '### Responses:' section with an empty output schema, which adds clutter without value.

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

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

For a simple list tool with no parameters and no output schema, the description provides sufficient context about what is returned (assigned agent, status, country), making it complete.

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

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

There are no parameters, so schema coverage is 100%. The description does not add parameter info, but baseline for zero parameters is 4.

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

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

The description clearly states the tool lists all phone numbers provisioned on the account, using a specific verb ('list') and resource ('phone numbers'). It distinguishes from sibling tools like 'buy_phone_number' by focusing on existing numbers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description implies use when needing an overview of phone numbers, but lacks explicit guidance on when not to use it or alternatives. However, for a simple list tool with no parameters, the context is clear enough.

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

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

Annotations are minimal (not read-only, not destructive). The description adds value by disclosing that the call is autonomous, transcript is saved, and agent configuration is used with optional overrides. No contradictions.

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

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

The description is somewhat verbose, including a full response section and parameter list that redundantly duplicates the schema. However, purpose is front-loaded and structure is logical.

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

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

Given 7 parameters, no output schema, and complexity of initiating a call, the description covers the process, parameter options, and expected behavior. Missing explicit success response details, but transcript retrieval is mentioned.

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

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

Input schema has 100% description coverage. The description reiterates parameters with additional context (e.g., E.164 format, override behavior), adding meaning beyond the schema.

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

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

The description clearly states 'Make an outbound phone call from your AI agent' and details the autonomous process, distinguishing it from sibling tools like hangup_call or list_calls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No explicit when-to-use or when-not-to-use guidance. The description implies usage for initiating calls but does not contrast with alternatives like hangup_call or get_call_details.

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

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

The description transparently discloses idempotent and read-only behavior with phrases like 'without consuming them' and 'without removing them from the mailbox', aligning with annotations (readOnlyHint, idempotentHint). No contradictions found.

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

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

The main description is concise and front-loaded with purpose. However, the inclusion of full response schemas and error examples adds unnecessary length. The structure is otherwise clear.

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

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

The description covers purpose and use case but lacks details about the return format for a successful response (output schema is empty {}). This omission reduces completeness for an AI agent needing to interpret results.

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

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

Input schema has 100% coverage; both parameters are described in the schema itself. The description does not add extra semantics beyond what the schema provides, so baseline score applies.

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

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

The description clearly states the tool peeks at pending telephony events without consuming them, using specific verbs like 'peek' and 'preview'. It distinguishes from sibling tools by emphasizing non-destructive behavior, unlike poll_events which likely consumes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description guides usage by stating it's 'useful for checking if there are events to process before committing to retrieve them', implying the alternative is a consuming tool. However, it does not explicitly name the sibling tool poll_events, leaving room for ambiguity.

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

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

The description explicitly states the crucial behavioral trait: events are consumed and automatically deleted on retrieval. This goes well beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=false. The description clarifies the true destructive (consume) nature.

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

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

The description is well-structured with headers for behavior, filters, and responses. It is front-loaded with the core purpose. Minor redundancy with schema descriptions, but overall concise and scannable.

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

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

Without an output schema, the description fails to detail the response structure (e.g., list of event objects, fields). It only mentions the 200 status and error schema. For a polling tool, knowing the response format is critical, so this is a noticeable gap.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description reiterates these parameters and adds context ('Filters'), but does not significantly enhance meaning beyond the schema defaults. Baseline 3 is appropriate.

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

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

The description clearly states that the tool polls for telephony events (call completions, transcripts, failures) from AI agents. It is distinct from sibling tools like peek_events (non-destructive) and list_calls (historical). The verb 'poll' accurately conveys the pull-and-consume semantics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly advises periodic calling to receive notifications, which is strong guidance. It also mentions filters for agent_id and event_type. However, it does not explicitly contrast with peek_events or other sibling tools for when not to use this tool.

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

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

Annotations already give idempotentHint=true and destructiveHint=false. The description adds behavioral context: it removes the override and describes the consequence for AI agents. No contradictions with annotations.

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

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

The description is concise and well-structured. It states the purpose in one line, then explains the effect in two subsequent lines. Every sentence adds value without redundancy.

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

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

Given the tool has no parameters and no output schema, the description fully captures its behavior: what it resets, the consequence, and the exception. It is complete for an AI agent to understand and invoke correctly.

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

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

The tool has zero parameters, so the schema coverage is 100% by default. With no parameters, the baseline score is 4. The description does not need to add parameter semantics.

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

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

The description clearly states the action 'Reset account voice to the system default' and specifies what it accomplishes (removing account-level voice override). It distinguishes from sibling tools like set_account_voice and get_account_voice by indicating this resets to default rather than setting or retrieving a specific voice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explains the effect (agents fall back to system default) and an exception (unless they have own voice_id). This provides context for when to use the tool, but it does not explicitly contrast with set_account_voice or state when not to use it.

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

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

The description discloses that setting the account default affects 'ALL AI agents under this account' and is non-destructive (overridable). Annotations indicate idempotentHint=true and destructiveHint=false, which align; the description adds context like the priority and affected scope.

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

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

The description is well-structured with a summary, a numbered priority list, accepted value formats, and response status codes. Every sentence is informative and earns its place; no fluff.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the purpose, effects, accepted values, and possible responses (200 and 422). It is complete for an AI agent to select and invoke the tool correctly.

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

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

The schema already documents voice_id with a description, achieving 100% coverage. The tool description enhances it by listing specific examples of accepted values (preset names and UUIDs), going beyond the schema's description.

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

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

The description begins with 'Set the account-level default voice for AI phone agents,' providing a specific verb and resource. The priority list distinguishes this tool from per-call and per-agent voice settings, and from the sibling tools get_account_voice and reset_account_voice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The voice resolution priority explicitly states where this endpoint fits (level 3) and implies when to use it: for setting the account default, while alternative endpoints handle per-agent or per-call overrides.

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

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

The description adds behavioral context beyond annotations: 'Changes take effect on the next call the agent handles.' Annotations indicate idempotentHint=true and destructiveHint=false, which align with the described behavior. No contradictions. Could include more details like authentication requirements, but the given information is sufficient.

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

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

The free-text description is concise: two sentences for purpose, one listing fields, one behavioral note. Well-structured and front-loaded with essential information. The response documentation is appended but does not detract from conciseness.

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

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

Given the tool's complexity (8 params, 1 required, no output schema), the description covers purpose, modifiable fields, partial update behavior, and response codes. It could explain the success response structure more, but the provided detail is adequate for an AI agent to use the tool correctly.

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

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

Schema description coverage is high (88%), and the description adds value by summarizing modifiable fields and emphasizing partial updates. This goes beyond the schema's individual parameter descriptions. Score above baseline due to added semantics.

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

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

The description clearly states 'Update an AI voice agent's configuration' and lists specific modifiable settings (system prompt, voice, etc.), making the tool's purpose distinct from siblings like create_agent, delete_agent, and get_agent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Provides explicit guidance: 'Only include the fields you want to change — unset fields are preserved.' This clarifies partial update behavior. It lacks explicit when-not-to-use or comparison with alternatives, but the context from siblings and the description's phrasing implies usage for modifying existing agents.

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