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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable behavioral context by noting the prerequisite 'Requires the applicable Aircall AI feature,' which informs the agent about potential failure conditions 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 two sentences with no filler. The first sentence front-loads the core purpose, and the second adds a critical prerequisite, making it appropriately 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?

For a simple single-parameter tool with no output schema, the description adequately explains what it does and a key prerequisite. Combined with thorough annotations, it is complete for the agent to select and invoke the tool.

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

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

The schema provides 100% coverage for call_id with a clear description. The tool description does not add any new parameter details, so the baseline of 3 applies as the schema does the heavy lifting.

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 specific resource 'AI-extracted action items for one Aircall call,' distinguishing it from sibling tools like aircall_get_transcription and aircall_get_summary. The scope 'one Aircall call' is explicit.

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?

It provides clear context: this tool retrieves action items for a single call and requires the AI feature. It does not explicitly mention alternatives or when not to use it, but the single-call scope implies appropriate usage compared to list/search 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 already declare readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds 'full metadata' but doesn't elaborate on what that includes, rate limits, or response shape. 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.

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

The description is a single, front-loaded sentence that wastes no words. It effectively communicates the core action and object.

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 rich annotations and 100% schema coverage, the simple description is sufficient for a straightforward GET operation. It could mention return details, but the optional boolean parameters in the schema already hint at available metadata facets, and this is not a complex mutation 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?

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds no additional parameter semantics beyond the schema, which is acceptable given full schema coverage.

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

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

The description clearly states the tool retrieves full metadata for a single call with a specific verb and resource. It distinguishes from list/search siblings by focusing on one call, though it doesn't explicitly name alternatives.

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 guidance on when to use this tool versus list_calls/search_calls. The description implies you need a call_id, but it provides no context or exclusions, leaving the agent to infer usage from the name and schema.

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, so the agent knows this is a safe, read-only operation. The description adds that it concerns the 'authenticated' company and returns 'basic information', which provides some scoping but no additional behavioral details like response format or rate limits. This aligns with the calibration example where a read operation with annotations got a 3.

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

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

The description is a single, focused sentence that immediately conveys the tool's purpose. There is no redundant wording or unnecessary detail, making it perfectly concise and front-loaded.

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

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

For a simple, parameterless read-only operation with strong annotations, the description is largely sufficient. It identifies the target resource and scope ('authenticated company') but does not specify the exact fields returned. Given the absence of an output schema, a slightly richer description of the return value would make it fully complete, but it remains adequate for this simple tool.

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

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

The tool has zero parameters, and schema coverage is 100% (empty object). Per the rubric, 0 params receives a baseline of 4. The description doesn't need to elaborate on parameter meanings, and it correctly implies that authentication is handled outside the parameter list.

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 'basic information about the authenticated Aircall company', which precisely identifies what the tool does. It distinguishes itself from sibling tools like aircall_get_user or aircall_get_call by uniquely targeting the company entity.

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?

Usage context is implied by the tool name and description—it's for retrieving company-level information. However, there is no explicit guidance on when to prefer this over alternatives, nor are there exclusions or prerequisites mentioned. It is adequate 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?

Annotations already provide a strong safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description need not repeat that. The word 'shared' adds a slight contextual nuance about the contact type, but the description does not clarify access requirements, error behavior, or return format. This is acceptable given the annotations, but the added value is minimal.

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

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

The description is a single, concise sentence that states the core purpose without any filler or repetition. It is front-loaded with the verb and resource, making it immediately scannable for an 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?

For a simple get-by-ID tool with one parameter and robust annotations, the description is mostly sufficient. However, it does not clarify what 'shared' means or explicitly state that the full contact object is returned. These are minor gaps given the tool's simplicity, but the description could be slightly 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?

The input schema provides 100% coverage with a clear description for contact_id ('Unique Aircall contact ID'). The tool description adds no additional parameter semantics, so the schema already carries the burden. A baseline score of 3 is appropriate when the schema fully documents the 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 verb 'Get' and the resource 'shared Aircall contact', indicating a single-contact retrieval operation. It implies distinction from list/search siblings by focusing on 'one' contact, though it does not explicitly mention the contact_id parameter or specify how it differs from listing all contacts.

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?

Usage guidance is only implied through the singular 'one' – suggesting this tool is for retrieving a specific contact rather than listing or searching. No explicit alternatives are named, and there is no mention of when to choose this over aircall_list_contacts or aircall_search_contacts, leaving the context to be inferred.

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 non-destructive behavior, so the description doesn't need to repeat safety traits. It adds 'assigned users' as part of the return, giving behavioral context beyond annotations. No contradiction.

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

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

The description is a single clear sentence that front-loads the verb and resource. Every word earns its place—no fluff or 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?

For a simple read tool with well-documented schema and rich annotations, the description is adequate. It hints at the return contents (number and assigned users), though it doesn't explicitly mention the include_message_urls effect; schema covers that 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 description coverage is 100%, with both number_id and include_message_urls fully described. The description adds no additional parameter semantics, so baseline 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 uses a specific verb 'Get' with a clear resource 'one Aircall phone number' and adds 'assigned users' to define scope. This clearly distinguishes it from sibling tools like aircall_list_numbers, which retrieves all 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 word 'one' implies this is for single-number retrieval, but there is no explicit mention of when not to use it or reference to alternatives like aircall_list_numbers. Usage guidance is only implicit, not stated.

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, openWorldHint, idempotentHint, and destructiveHint false, indicating a safe read operation. The description adds one useful behavioral detail: the requirement of an Aircall AI feature, which acts as a feature gate. However, it does not describe potential error conditions, return format, or what happens when sentiment analysis is unavailable, so the added value beyond annotations is modest.

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 consists of two concise sentences. The first sentence immediately communicates the core function, and the second adds a necessary prerequisite. There is no redundancy or filler, and the structure is front-loaded with the most important 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?

For a simple tool with one parameter, the description covers the action and a key prerequisite. However, there is no output schema and the description does not explain what the sentiment analysis returns (e.g., label, score, per-speaker, or overall). This leaves the agent uncertain about the result shape, although the read-only and idempotent hints provide some safety context. The description is adequate but not fully complete.

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

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

The input schema for call_id has full coverage with a description ('Unique Aircall call ID'). The tool description adds no additional parameter meaning beyond what the schema already provides. Since schema coverage is 100%, the baseline of 3 applies without further contribution from the 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 clearly states the action ('Get sentiment analysis') and the specific resource ('one Aircall call'). This distinguishes it from sibling tools like aircall_get_transcription or aircall_get_summary, which target different analysis types. The tool name and description align well with the intended function.

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 a prerequisite ('Requires the applicable Aircall AI feature') but provides no guidance on when to use this tool versus alternatives like aircall_get_summary or aircall_get_action_items. It does not explain when not to use it or which sibling tools serve overlapping purposes, leaving the agent to 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.

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 a beyond-annotations behavioral context: the call requires a specific AI feature to be enabled. This is useful prerequisite information not present in 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?

Two concise sentences, front-loaded with the verb and resource. No wasted words; the prerequisite is stated succinctly.

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

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

For a simple one-parameter read-only tool with complete annotations and schema coverage, the description fully covers the essential context: what it does and a key prerequisite. No output schema exists, but return value is implicit in 'summary'.

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% (call_id is described as 'Unique Aircall call ID'), and the description adds no additional parameter semantics. The baseline for full schema coverage is 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 states a specific verb ('Get') and resource ('AI-generated summary for one Aircall call'). It clearly distinguishes from sibling tools like aircall_get_transcription and aircall_get_sentiments by naming the output type.

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: use this tool to obtain an AI-generated summary for a single call. It also notes a prerequisite (requires the Aircall AI feature), but does not explicitly mention when to use alternatives or exclusions.

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=false, covering the safety profile. The description adds no behavioral context beyond that (e.g., error behavior, permissions); it is consistent with the annotations but not informative.

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

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

The description is a single concise sentence with no wasted words. It clearly and directly states the tool's action and target 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?

Given the tool's simplicity (one parameter, no output schema, strong annotations), the description is nearly sufficient. However, it doesn't clarify whether the tag is specific to calls or could apply to other entities, which is a minor 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 the 'tag_id' parameter well-described as 'Unique Aircall tag ID'. The description repeats the resource type but adds no detail about the parameter beyond what the schema already provides.

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 uses a specific verb ('Get') and resource ('one Aircall call tag'), clearly indicating it retrieves a single tag. This distinguishes it from the sibling tool 'aircall_list_tags' by emphasizing 'one' versus listing multiple tags.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when a list vs. get-by-ID is appropriate, or any exclusions.

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 the tool as read-only, idempotent, and non-destructive. The description adds the behavioral detail that the response includes team members, which is not covered by the annotations. No contradictions exist.

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

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

The description is a single, front-loaded sentence that conveys the essential information without any wasted words. It is concise and directly states the tool's function.

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-by-id tool with strong annotations (read-only, idempotent) and one well-documented parameter, this description is sufficiently complete. It explains the core purpose and the return scope ('team and its members') despite the lack of an output schema.

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% for the single 'team_id' parameter, which already has a clear description. The tool description does not need to repeat parameter details, but it also adds no additional semantic context 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 'Get one Aircall team and its members' uses a specific verb ('get') and resource ('team'), and adds scope ('one') and included content ('and its members'). This clearly differentiates it from sibling tools like aircall_list_teams, which lists multiple teams.

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 clearly implies this is for retrieving a single, specific team by ID, contrasting with listing tools. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusion guidance.

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 safety profile is clear. The description adds one useful behavioral constraint—the requirement for an Aircall AI feature—but does not elaborate on behaviors like error responses when the feature is unavailable or the format of returned topics.

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

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

The description is two sentences, with the primary purpose stated first and the prerequisite following. Every word earns its place; there is no redundancy or filler.

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

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

For a simple read-only tool with one parameter and strong annotations, the description is largely complete. It covers the main purpose and a key prerequisite, though it could optionally mention whether the tool returns an empty result when no topics are detected, but this is not a significant 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?

The input schema has 100% coverage with a clear description for call_id ('Unique Aircall call ID'). The description adds no parameter-specific information, but since the schema fully documents it, the baseline score of 3 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 identifies the verb 'Get' and the resource 'AI-detected topics for one Aircall call', making its purpose specific. It does not explicitly contrast with sibling tools like aircall_get_summary or aircall_get_sentiments, but the unique resource ('topics') is enough to distinguish it.

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

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

The description provides a prerequisite ('Requires the applicable Aircall AI feature') but gives no guidance on when to use this tool versus alternatives like aircall_get_transcription or aircall_get_action_items. It fails to state when this tool is preferred or when it should be avoided.

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 establish read-only and idempotent behavior, and the description adds valuable context by explaining that utterances are paginated locally to keep responses bounded. This is useful behavioral information beyond what annotations provide.

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

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

The description is two short sentences, front-loaded with the tool's purpose followed by a key behavioral note. It is appropriately sized with no wasted words.

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 is minimally viable for a simple read-only tool, especially with good annotations. However, since there is no output schema, the lack of explicit return-format or response-structure information leaves a clear gap, and pagination mechanics are not fully explained.

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 low (17%), and the description does not explain parameters like mode, limit, format, offset, or include_timestamps. The only hint is the word 'paginated,' which vaguely relates to limit/offset but does not add meaningful semantic detail.

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 an AI-generated call transcription, using a specific verb and resource. It is distinct from sibling tools like aircall_get_summary or aircall_get_sentiments, as transcription is a unique output type.

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

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

No guidance is provided for when to use this tool versus alternatives such as summary, sentiments, or action items. The description does not mention call_id requirements, use cases, or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the 'v2 Users API' detail, which provides minor context beyond the schema. It does not disclose return formats, error handling, or pagination (not applicable for a single-get), but the annotation coverage lowers the burden. This meets the baseline for a read-only tool with some added context.

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

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

The description is a single concise and front-loaded sentence: 'Get one Aircall user by numeric ID or email address using the v2 Users API.' No wasted words; every part earns its place.

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

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

For a tool with one parameter, no output schema, and rich annotations, the description is largely sufficient. It identifies the exact lookup method and the API version. The only omission is a statement that the response contains the full user object, which is expected but not explicit. Minor gap, hence 4 rather than 5.

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% for the single parameter 'identifier', already defining it as 'Aircall user ID or email address'. The description repeats this ('numeric ID or email address') without adding new semantics. According to the guidance, baseline is 3 when schema coverage is high, and the description adds no extra value beyond the schema.

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

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

The description clearly states the tool's function: 'Get one Aircall user by numeric ID or email address.' It uses a specific verb ('Get') and resource ('Aircall user'), and specifies the two supported lookup identifiers. It is immediately distinguishable from sibling tools like 'aircall_list_users' because it explicitly targets a single user.

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 when to use this tool: when you need one user identified by ID or email. It provides clear context but does not explicitly contrast with alternatives such as 'aircall_list_users'. However, given the tool name and the phrase 'Get one', the use case is evident and no exclusionary guidance is needed for a simple getter.

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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful context about the six-month history limit, default compact format, and newest-first ordering, which goes beyond the annotations without contradicting them.

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

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

Two sentences, tightly written, and front-loaded with the core action and scope. Every word contributes value; no redundancy or filler.

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 list tool with no output schema, the description adequately conveys the default response shape and points to the call-by-ID path for full details. It could mention pagination behavior, but the schema already documents page/per_page, making this sufficient for an agent to select 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 100%, with all 10 parameters individually documented. The description itself doesn't add parameter-specific detail beyond what the schema already provides, but it does reinforce the default compact behavior. This meets the baseline for high schema coverage.

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

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

The description clearly states 'List calls from Aircall's available six-month history' with a specific verb, resource, and scope. It also distinguishes from get_call by noting that full details require retrieving by ID, which differentiates it from the sibling tools.

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 useful context: lists calls within a six-month window and defaults to compact metadata, with a hint that complete details come from a call-by-ID request. However, it does not explicitly mention when to use aircall_search_calls for filtered queries, so the guidance is clear but lacks an explicit exclusion.

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, covering safety. The description adds the 'shared' scope constraint, which is not present in annotations or schema and clarifies that this is not a list of all contacts or personal contacts. This is valuable behavioral context beyond the structured data.

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

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

The description is a single, efficient sentence that conveys the essential purpose without redundancy. It is perfectly sized for a simple list operation.

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, rich annotations, and comprehensively described schema (83% coverage), the description is nearly complete. It includes the key scope restriction ('shared') and does not need to explain return values since no output schema exists. Minor gap: it doesn't clarify what 'shared' means in the Aircall context, but this is not critical.

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 83%, so the parameters are mostly self-documenting. The description does not add any parameter-specific semantics; it solely says 'List shared Aircall contacts.' With high schema coverage, a baseline 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 'List shared Aircall contacts' uses a specific verb ('list') with a clear resource ('shared Aircall contacts'), distinguishing it from siblings like aircall_get_contact (single contact) and aircall_search_contacts (search). The scope ('shared') adds precision.

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 phrase 'List shared Aircall contacts' implies usage for retrieving a batch of shared contacts, but there is no explicit guidance on when to prefer this over alternatives like search_contacts or get_contact. No exclusions or conditions are mentioned, so it is clear but underexplained.

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 false; the description adds no behavioral traits beyond the resource scope. It does not mention pagination, response shape, or any operational constraints, though it does not contradict 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 a single, front-loaded sentence with no filler. However, it largely restates the title with only modest clarification, so it is concise but not maximally informative.

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 schema and annotations provide strong structural context, but the description omits usage boundaries, pagination/ordering expectations, and return-value info (no output schema). It is adequate for a basic list tool but leaves gaps for an agent deciding between list and get operations.

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% description coverage for all six parameters, so the schema carries the parameter semantics. The description adds no additional parameter meaning beyond clarifying the resource being listed, keeping it at the baseline.

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 uses the specific verb 'List' and resource 'phone numbers' with a clear ownership scope ('owned by the Aircall company'), distinguishing it from sibling tools like aircall_get_number or aircall_list_calls. The purpose is unambiguous and directly aligned with the tool name.

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

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

No explicit when/when-not guidance or alternative tool references are given. The 'List' verb implies use when a listing is needed, but the description does not state exclusions such as filtering by user/workspace or suggest aircall_get_number for a single record.

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=false, covering the safety profile. The description adds the company scope ('configured for the Aircall company'), which is useful context, but it does not disclose pagination behavior or other traits beyond what annotations provide.

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

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

The description is a single, clear sentence with no wasted words. It is front-loaded with the verb and resource, and every word contributes meaning.

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 operation with two optional parameters and no output schema, the description combined with annotations fully covers what the tool does. The company scope is explicitly stated, and the schema handles parameter details.

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%, with both page and per_page already described. The tool description adds no additional parameter meaning, so the baseline of 3 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 uses the specific verb 'List' and the resource 'call tags', scoped to 'the Aircall company'. This clearly distinguishes it from the sibling tool aircall_get_tag, which retrieves a single tag.

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 no guidance on when to use this tool versus alternatives, such as aircall_get_tag. It only states what it does, leaving the agent to infer usage from the tool name and purpose.

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 disclose read-only, idempotent, open-world, and non-destructive behavior. The description adds the scope detail that teams include member information, which is useful context, but it does not describe pagination behavior or return format. No contradiction 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 a single, front-loaded sentence with no waste. It clearly states the action and resource in a concise manner, earning a perfect score for brevity.

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

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

For a simple read-only list tool, the description, schema, and annotations together are adequate. The schema documents all parameters, annotations cover safety, and the description hints at response scope (members). A fully comprehensive description might explicitly mention default pagination, but the schema already covers defaults, so there is no critical 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?

All three parameters (page, order, per_page) have detailed descriptions in the schema, so coverage is 100%. The description does not add any parameter-specific meaning beyond what the schema already provides, keeping it at the baseline.

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 uses a specific verb ('List') and resource ('Aircall teams') plus additional detail ('and their members'), making it clear this tool fetches all teams. It is distinct from siblings like aircall_get_team (single team) and aircall_list_users (users only).

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/when-not instructions or alternative tool names are given. Usage is only implied by the 'list' verb and the presence of sibling get_team, which would be used for a specific team. There is no mention of pagination needs or when to use this over other list/search 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. However, the description adds no additional behavioral context such as pagination behavior, response format, or any limitations. It only restates that it lists users and mentions the API version.

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

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

The description is a single, concise sentence that directly states the tool's purpose without any filler. It front-loads the key information and is easy to parse.

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 straightforward list operation with all parameters optional and well-documented in the schema. Annotations cover safety and idempotency. The only missing piece is a description of the response shape, but 'list users' reasonably implies an array of user objects. Given the simplicity and strong schema/annotations, the description is sufficiently 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 description coverage is 100%, with clear descriptions for all five parameters (from, to, page, order, per_page). The description adds no further parameter meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action (list) and the resource (Aircall users/agents), and it distinguishes itself from the sibling tool aircall_get_user by being a plural list. The mention of 'v2 Users API' adds specificity without 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?

No guidance is provided about when to use this tool versus alternatives. It does not mention that aircall_get_user should be used for fetching a single user, nor does it describe any context such as 'use this to get all users'. The usage is implied only by the name.

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 the operation as read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context by specifying that it verifies reachability and credential validity, which goes beyond the generic safety hints. No contradiction 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 a single, focused sentence that immediately states the tool's purpose. Every word earns its place, and there is no unnecessary detail.

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 ping/health-check tool with no parameters, no output schema, and supportive annotations, the description is fully sufficient. It clearly explains what the tool does (verify reachability and credentials) and is complete for the tool's low complexity.

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, and the input schema is empty, so schema coverage is 100%. There is nothing for the description to explain about parameters, and the zero-parameter baseline 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 uses a specific verb 'Verify' and clearly identifies the resource (Aircall reachability and API credentials). It distinguishes itself from sibling tools that target specific entities like users, calls, or contacts.

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 does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. Its role as a connectivity/credential health check is implied by the verb 'Verify' and the context of the sibling tools, but explicit guidance is missing.

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`, covering the safety profile. The description adds meaningful behavioral context with 'Aircall applies multiple tags as an AND condition,' which is not present in the schema or annotations. No contradiction exists.

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

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

The description is two concise sentences with no redundant phrasing. The first sentence front-loads purpose and scope, while the second adds a specific behavioral nuance. Every word contributes meaning.

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

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

With 12 optional parameters and no output schema, the description captures the essential search dimensions and tag behavior, which is sufficient for selecting the tool. Pagination and default behaviors are not described, but they are largely covered by the schema (`page`, `per_page`, `order`, etc.), so the description remains adequate for initial invocation.

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

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

The description maps several schema parameters that lack explanations (`user_id`, `phone_number`, `direction`, `tags`) to simple search criteria. It also introduces the important semantic that multiple tags are combined with AND, which is absent from the schema. Since schema coverage is 67%, the description compensates for the undocumented parameters.

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

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

The description states 'Search calls by date, direction, user, phone number, and tag IDs,' clearly naming the resource and specific search dimensions. It implies differentiation from sibling tools like `aircall_list_calls` and `aircall_get_call`, though it does not explicitly highlight these alternatives.

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 calls need to be filtered by the listed criteria, but it does not explicitly contrast with `aircall_list_calls` or state when not to use this tool. The note that 'Aircall applies multiple tags as an AND condition' provides usage guidance for the tags parameter, but overall selection guidance remains implicit.

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, idempotent, and non-destructive behavior. The description adds minimal extra context by specifying 'shared' contacts, which is a useful scoping detail. 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?

A single, front-loaded sentence with no fluff. Every word adds value, directly stating the tool's purpose and primary search fields.

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 search tool with 8 optional parameters and no output schema, the description covers the core purpose and key searchable fields. Pagination and sorting parameters are self-explanatory from the schema, so no additional context is needed.

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 covers 63% of parameters with descriptions, but the two key search parameters (email and phone_number) lack descriptions. The description explicitly names these as search criteria, directly compensating for the gap. Other parameters like page and per_page are adequately described in 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 action ('Search'), the resource ('shared Aircall contacts'), and the specific search criteria ('by phone number or email address'). This distinguishes it from sibling tools like aircall_list_contacts (which lists all) and aircall_get_contact (which retrieves a single contact).

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?

It provides clear context for when to use the tool (when finding a contact by phone or email), but does not explicitly mention alternatives or exclusions. The differentiation from list/get tools is implied through the phrase 'by phone number or email address.'

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