aircall

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

Annotations already declare destructiveHint=true indicating a mutation. The description only adds the REST endpoint reference, which is technical context but not behavioral. It does not disclose side effects, permissions, or whether existing comments are affected.

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 short sentences: the first provides the clear purpose, the second gives the REST endpoint. No filler or redundant 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 mutation with two required parameters and no output schema, the description is adequate but minimal. It does not mention return values, side effects beyond adding a comment, or any authorization requirements, but given the low complexity this is acceptable.

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 clear descriptions for both 'id' (call id to comment on) and 'content' (the comment text). The description adds no additional parameter details, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Add' and the resource 'comment / note to a call'. This distinguishes it from sibling tools like tag_call (adds a tag) and get_call (reads call data).

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 the tool is used when you want to attach a comment to a call, but provides no explicit when-to-use or exclusion guidance comparing it to alternatives. It does not say 'use this instead of tag_call for textual notes' or mention any prerequisites.

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 destructiveHint: true whereas the description says 'Create a new contact' – a non-destructive, additive operation. This is a direct contradiction with the annotation. The description adds no behavioral context beyond the misleading annotation, so per rubric transparency is scored 1.

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 that are front-loaded with the core purpose and then the critical prerequisite. The REST endpoint is a compact, useful addition. 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?

For a simple create operation with no output schema, the description covers the essentials: what it does, where, and the parameter prerequisite. It omits return-value details and failure modes, but with 6 optional parameters and no required ones, the description is sufficient. The annotation contradiction does reduce overall reliability but is already scored under transparency.

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 already provides 100% parameter descriptions. The description goes beyond the schema by stating the conditional requirement on first_name/last_name/company_name, which is not encoded in the schema (since no required fields are declared). This adds meaningful semantic guidance beyond the structured fields.

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+resource: 'Create a new contact in the shared address book.' It clearly distinguishes from the update_contact sibling tool and other contact-related tools. The REST endpoint mention 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 description clearly implies when to use this tool (when you need to create a contact). It adds a practical prerequisite: 'at least one of first_name / last_name / company_name.' It does not explicitly name alternatives or exclusions, but the purpose is unambiguous given the tool name and sibling list.

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 readOnlyHint=true annotation already signals a safe read operation. The description adds the HTTP method (GET) but does not provide further behavioral context such as error handling, rate limits, or how fetch_contact affects the response. 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 two short sentences with no filler. The purpose is front-loaded, and the REST endpoint is a useful extra detail. Every word 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?

This is a simple get-by-id tool with only two parameters, both documented in the schema. The description is sufficient for the agent to invoke the tool, though it does not mention that fetch_contact alters the response shape. Given no output schema, some ambiguity remains about the return format, but the tool is simple enough that this is acceptable.

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 both 'id' and 'fetch_contact' have clear descriptions in the schema. The description only mentions 'id' implicitly and does not add additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Get'), the resource ('a single call'), and the identifier ('by id'), and it also mentions the REST endpoint. This distinguishes it from sibling tools like list_calls or search_calls, which have different scopes.

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 this tool should be used when you have a specific call id and need its details, but it does not explicitly mention when not to use it or recommend alternatives like list_calls or search_calls. There is no exclusions or comparative 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?

With readOnlyHint=true in annotations, the safety profile is already declared. The description adds context that the action items are AI-extracted via the Aircall AI Voice feature, but does not disclose behavior like pagination or error handling. This is acceptable but not rich 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 one clear sentence followed by the REST endpoint, with no wasted words. It is front-loaded with the primary purpose and immediately specifies the API reference.

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 GET tool, the description is complete: it states what is returned (action items/follow-ups). Since there is no output schema, the plural 'items' implies a list, but return structure is not detailed. This is adequate for the tool's simplicity.

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: it describes 'id' as 'The call id.' The description adds no further parameter meaning, but the schema fully documents the only parameter, so the baseline 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 states the tool retrieves AI-extracted action items/follow-ups from a call, with a specific REST endpoint. This distinguishes it from sibling tools like aircall_get_call_summary or aircall_get_call_transcription by naming the exact resource.

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 gives clear context: use this when you need action items or follow-ups from a call. It does not explicitly mention alternatives or exclusions, but the purpose is specific enough that an agent can decide when to invoke 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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that the data is AI-generated and part of the Aircall AI Voice feature, plus the endpoint. It does not disclose potential edge cases like missing sentiment data or authentication requirements, but with annotations present, this level of additional context is acceptable.

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, front-loads the core purpose, and includes the endpoint without any filler. Every word adds value: the feature context ('Aircall AI Voice') and the REST reference are both useful and 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 read-only tool, the description is nearly complete. It identifies the output (sentiment analysis), the source (AI), and the endpoint. No output schema exists, but the description doesn't need to detail return values for such a focused retrieval tool. It could mention what happens if sentiment data is unavailable, but that 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 description coverage is 100% and the single parameter 'id' is already described as 'The call id.' The description does not add new parameter semantics beyond what the schema provides, but it does imply the id is used in the URL path. Baseline 3 is appropriate since the schema carries the explanatory weight.

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 a specific action ('Get') and resource ('AI-generated sentiment analysis of a call'), and explicitly ties it to the Aircall AI Voice feature. It differentiates from sibling tools like aircall_get_call_summary and aircall_get_call_transcription by naming the specific 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 implies usage context: this tool is for retrieving sentiment analysis, not other call insights. It provides the REST endpoint for reference, but does not explicitly state when to prefer it over sibling analysis tools or exclude alternatives. Still, the purpose is clear enough to guide selection.

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 the description adds context that this is the 'AI-generated summary' from the 'Aircall AI Voice feature,' which is useful. However, it does not discuss potential error cases, auth requirements, or the format/availability of summaries beyond what annotations already convey.

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 one compact sentence that conveys the core purpose and the REST endpoint. It is front-loaded with the action and resource, and every word contributes 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?

For a simple read-only tool with a single parameter and no output schema, the description is largely complete. It identifies the tool's unique function and provides the REST path. However, it could optionally mention what the summary contains or any known limitations, but that is not essential given the simplicity.

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 'id' is fully documented in the schema (100% coverage with description 'The call id.'). The description does not add extra meaning beyond the schema, simply echoing the endpoint placeholder {id}. 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 the tool's function: 'Get the AI-generated summary of a call.' It names the specific resource and distinguishes it from sibling tools like transcription, sentiments, and action items by focusing on the AI summary. The REST endpoint reference 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 description implies usage by identifying the tool's purpose, but it does not explicitly state when to use this tool versus the many similar sibling tools (e.g., aircall_get_call_transcription). No alternative tools or exclusion criteria are mentioned.

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 set readOnlyHint=true, so the read-only nature is known. The description adds the REST endpoint and the AI Voice feature context, which is useful but limited. It doesn't disclose potential nuances like authentication requirements, rate limits, or behavior for calls without AI topics. Given the annotations cover the safety profile, the description adds some value but not extensive behavioral detail.

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 front-loads the core purpose and adds the REST endpoint for precision. Every word earns its place, with no redundant content.

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?

This is a simple read-only tool with one required parameter and no output schema. The description clearly conveys what the tool does and how to call it via the endpoint. With good annotations and a fully documented schema, the description is nearly complete. It could mention the structure of the returned topics but that isn't essential for this simple 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 input schema fully documents the only parameter 'id' with the description 'The call id.' (100% coverage). The description's REST endpoint path confirms id is used as a path variable but adds no new semantic meaning beyond the schema. This meets the baseline of 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 the tool's purpose: 'Get the AI-detected topics of a call' with the Aircall AI Voice feature context. The REST endpoint GET /calls/{id}/topics further clarifies the resource. It distinguishes from sibling tools like aircall_get_call_sentiments and aircall_get_call_summary by specifying exactly which AI output is retrieved.

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 this tool (to retrieve AI-detected topics for a call). It doesn't explicitly exclude alternatives or mention sibling tools, but the specificity of 'topics' and the reference to the Aircall AI Voice feature make the intended use obvious. No when-not-to-use guidance is provided, so not a 5.

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 readOnlyHint annotation already establishes safe read behavior. The description adds that this is the Aircall AI Voice feature, which may imply availability constraints, but it doesn't disclose error handling or when transcription might be unavailable. 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?

Two sentences: the first states the purpose, the second provides the REST endpoint. No redundancy or filler; both sentences contribute 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?

Given the simple tool with one parameter and no output schema, the description adequately conveys that the result is the transcription, and the REST endpoint adds specificity. It doesn't explicitly state response format, but for a getter this is 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 coverage is 100%, with the only parameter 'id' fully described as 'The call id.' The description mentions the REST path containing {id}, which reinforces the meaning but adds no new semantic information.

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 AI-generated transcription of a call, using a specific REST endpoint. This distinguishes it from sibling tools like get_call_summary or get_call_sentiments, which handle different aspects.

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 the use case: when needing the transcription text from a call. It does not explicitly contrast with sibling tools or state when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint: true, so the safety profile is known. The description adds useful context about the scope (authenticated company) and the specific fields returned (name, plan, usage) plus the REST endpoint, but does not elaborate on response format or rate limits, which is acceptable for a simple GET.

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, front-loads the purpose, and includes only essential information (what it returns and the REST endpoint). 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?

For a parameterless, read-only tool with no output schema, the description is complete. It clearly defines the resource, scope, and returned details. The sibling context shows no overlap, so no additional guidance 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 tool has zero parameters, so the base score is 4. The description correctly indicates no inputs are needed and clarifies that it operates on the authenticated company, which adds meaning without needing parameter explanations.

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 details of the authenticated Aircall company, specifically listing name, plan, and usage. The verb 'get' and resource 'company' distinguish it from sibling tools like aircall_get_call or aircall_get_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 needing company-level details for the authenticated account. However, it does not explicitly mention alternatives or situations where another tool would be more appropriate, though the unique resource makes this less critical.

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 provide readOnlyHint=true, so the read-only nature is already disclosed. The description adds the REST endpoint (GET /contacts/{id}) which reinforces idempotence but does not disclose additional behavioral traits like error handling, pagination, or rate limits. It meets the baseline but adds minimal 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 is two short sentences that immediately state the purpose and the REST endpoint. No redundant information, front-loaded with the action, and every word 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?

This is a simple single-parameter read-only getter. The description sufficiently covers what the tool does and which parameter it requires. No output schema exists, but the return value (a contact) is implied and no complex behavior needs explanation. The context is complete for this level of 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 input schema fully describes the only parameter 'id' as 'The contact id.' with a 100% coverage rate. The description's mention of 'by id' and the REST path /contacts/{id} reiterate the same meaning without adding new constraints or formatting details. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states 'Get a single contact by id', which uses a specific verb and resource. It distinguishes from siblings like list_contacts and search_contacts by focusing on a single record lookup via id. The REST endpoint 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 'single contact by id' clearly implies this tool is for fetching one specific contact when the id is known. It does not explicitly mention alternatives (e.g., list/search) but the context is unambiguous. No explicit exclusions are provided, but the usage context is well defined.

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 annotation readOnlyHint=true already communicates the safe read-only nature. The description adds the REST method 'GET /numbers/{id}', which aligns with the annotation but does not disclose other behavioral traits such as authentication requirements, error responses, or return format. This adds minimal extra value beyond the annotation.

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 core action and object. It includes the REST endpoint as a useful detail without redundancy. Every word earns its place, and it is appropriately concise for a simple tool.

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 single-parameter getter with a read-only annotation, the description is nearly complete. It states the action and target but does not explicitly describe the return value or response format, which would be helpful since no output schema exists. However, the tool's name and sibling context imply a straightforward number object return, so the gap is minor.

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 already provides 100% description coverage for the single 'id' parameter, with a clear description 'The number id.' The tool description merely says 'by id' and adds no new meaning or format details beyond what the schema provides. 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 'Get a single phone number by id', using a specific verb and resource. It distinguishes from sibling get tools (e.g., aircall_get_call, aircall_get_contact) by specifying 'phone number'. The REST endpoint pattern further reinforces the purpose.

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 makes usage context clear: use this tool when you have a number id and need that single number. It does not explicitly contrast with list_numbers, but the singular 'a single' implies a targeted lookup, and sibling names fill the alternative use case. No exclusions are stated, but none are necessary for this 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 readOnlyHint=true, and the description adds the REST GET method, reinforcing read-only behavior. However, no additional behavioral context is provided (e.g., error handling, response format, rate limits), so it only slightly exceeds what annotations already convey.

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 with no redundancy. It front-loads the core purpose and includes a useful REST endpoint reference.

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 trivial one-parameter read-only operation with strong annotations and no output schema, the description covers everything needed. The REST endpoint adds a helpful extra context.

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 parameter is already described as 'The tag id.' The description's phrase 'by id' adds no new meaning beyond the schema, so it does not elevate beyond 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?

Clearly states 'Get a single tag by id' with a specific verb and resource. Distinguishes itself from sibling tools like aircall_list_tags by explicitly targeting a single tag by id.

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 the use case (fetching one tag by id) but does not explicitly mention when to use this versus aircall_list_tags or other alternatives. No exclusions or alternative tool references are provided.

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 readOnlyHint annotation already establishes the safety profile. The description adds only the REST endpoint (GET /teams/{id}), which is redundant with readOnlyHint and provides no additional behavioral context such as error handling, response contents, or authentication. Given the simple nature of the tool, the description is minimally adequate but adds no value beyond the annotation.

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 front-loads the action ('Get a single team by id') and adds the API endpoint. No filler or repetition.

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 this simple one-parameter read-only getter, the description is largely complete in stating the action and the key identifier. However, without an output schema, it does not explicitly mention the response format (e.g., the team object), so it is slightly incomplete. Overall, the complexity is low and the description suffices.

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%: the sole parameter 'id' is described as 'The team id,' and the description also indicates retrieval by id. The description does not add new semantic detail (e.g., format, example, or special constraints), but the schema already fully documents the parameter. Baseline 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 a specific verb ('Get') and resource ('team') with a 'by id' qualifier, clearly distinguishing it from list_teams and other get_* tools. The REST endpoint reference reinforces the exact operation.

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 makes clear this is for retrieving a single team by ID, implying not for listing, but it does not explicitly name alternatives like aircall_list_teams or state when not to use it. The context is clear but lacks explicit exclusion/alternative 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, so safety is covered. The description adds the REST endpoint (GET /users/{id}) as extra context, but does not disclose error behavior, return format, or any other behavioral traits beyond the annotation.

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, front-loaded sentences with no redundancy. It communicates the essential purpose and the corresponding REST call 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?

For a simple get-by-id tool with one parameter and no output schema, the description is adequately complete. It states the resource, the identifier, and the endpoint. The absence of output format details is a minor gap but not critical for such a straightforward 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 input schema fully documents the single 'id' parameter with a clear description, achieving 100% coverage. The tool description adds no additional parameter semantics beyond what the schema already provides, so baseline 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 states the action ('Get'), the resource ('a single user (agent)'), and the scope ('by id'). It unambiguously distinguishes from sibling list/get tools by naming the specific resource 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?

Usage is implied: use when you have a user id and need that specific user. However, the description does not explicitly mention alternatives (e.g., list_users for multiple users) or exclusion criteria, so guidance is minimal but not misleading.

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

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

The readOnlyHint=true annotation already covers the safe read behavior. The description adds the REST endpoint but provides little additional behavioral context such as pagination behavior, rate limits, or return format beyond what the schema already declares.

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 two short sentences, front-loaded with the core action. The second sentence about the REST endpoint is somewhat redundant but not verbose or counterproductive.

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 comprehensive input schema and the read-only annotation, the description is adequately complete for a list operation. It lacks explicit differentiation from aircall_search_calls and return format details, but these are not critical given the context.

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 six parameters have full descriptions in the schema (100% coverage). The description's mention of 'creation-date window' and 'ordered' merely echoes the schema's from/to and order fields, adding no extra semantic value.

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' with a specific verb and resource, and mentions optional filtering by creation date and ordering. This distinguishes it from sibling tools like aircall_get_call (single call) and aircall_search_calls (search-based).

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 through 'optionally filtered by a creation-date window and ordered' but does not explicitly state when to use this tool versus aircall_search_calls or other alternatives. No exclusions or alternative guidance is provided.

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 the description adds context about the shared address book and date-window filtering. However, it does not disclose pagination behavior, default ordering, or any limits beyond what the schema properties already indicate.

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 key information front-loaded. The second sentence mentioning the REST endpoint is extra but not verbose; it could be considered unnecessary 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?

Combined with the full parameter schema and readOnly annotation, the description covers the resource scope and optional filters. Missing mention of return shape, but for a straightforward list tool this is acceptable.

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 all parameters described, so the description adds little beyond the schema. It references 'creation-date window and order' which maps to from/to and order parameters, but provides no new syntax or format 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 uses a specific verb ('List') and resource ('contacts in the shared address book'), clearly distinguishing from siblings like get_contact (single retrieval), create_contact, and update_contact. Mentioning optional creation-date window and order further clarifies the tool's scope.

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 for listing contacts with optional date filtering and ordering, but does not explicitly state when to prefer this over aircall_search_contacts or other alternatives. No exclusions or alternative tool references are provided.

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?

With readOnlyHint=true already providing safety, the description adds value by enumerating the returned fields (id, name, digits, country) and specifying the REST endpoint (GET /numbers). This gives the agent a clearer expectation of the response shape and reinforces the read-only 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 two sentences long, front-loads the core purpose ('List the phone numbers owned by the company'), and includes useful inline details (fields and REST endpoint). Every sentence earns its place with no 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 list tool with paginated parameters, the description adequately covers the purpose, scoping, and return fields. The schema covers pagination details, and annotations cover read-only behavior. It lacks an explicit pointer to sibling tools for single-number retrieval, but this is a minor gap given the simplicity.

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%: both page and per_page have clear descriptions ('1-based page number to fetch (default 1)' and 'Results per page (default 20, max 50)'). The tool description does not add further parameter context, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's action ('List'), resource ('phone numbers owned by the company'), and specifies the returned fields (id, name, digits, country). It distinguishes itself from siblings like aircall_get_number by emphasizing the company-owned scope and the plural listing nature.

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 all company phone numbers but does not explicitly state when to use this tool versus alternatives like aircall_get_number. No exclusion criteria or alternative tool references are provided, so the context is clear but not fully explicit.

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 annotation readOnlyHint=true already covers the read-only nature. The description adds only the output fields (id, name, color) and the REST endpoint, which provide minimal behavioral context beyond the annotation. No pagination behavior, filtering scope, or other traits are disclosed.

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, compact sentence with no redundant words or filler. It is front-loaded with the action and includes the most relevant information (endpoint and output fields) 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?

For a simple list tool with two optional parameters and a readOnly annotation, the description plus schema provides sufficient context. It mentions the output fields, which is useful given the lack of an output schema. A slight deduction for not explicitly noting pagination behavior, but that is covered in the 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?

The input schema covers both parameters (page and per_page) with descriptions, defaults, and bounds, so schema coverage is 100%. The description does not add parameter-specific information, but the baseline of 3 applies because the schema handles the 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 (list) and resource (company's call tags), specifies the returned fields (id, name, color), and references the REST endpoint. It distinguishes from siblings like aircall_get_tag (single tag) and aircall_tag_call (tagging action).

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 listing all tags but does not explicitly mention when to use it versus alternatives like aircall_get_tag for a single tag. No exclusions or alternatives are stated, so guidance is only implied.

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 annotation readOnlyHint already declares the operation is safe. The description adds useful context that the response includes team members and specifies the REST endpoint (GET /teams). Since there is no output schema, this helps infer the return content, but no additional behavioral traits (e.g., pagination behavior, permissions) are disclosed.

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 immediately states the core purpose and includes the REST method. It is front-loaded and every word earns its place, with no unnecessary 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 list tool with readOnlyHint, optional pagination parameters (documented in schema), and no output schema, the description provides sufficient context about the resource and return content. It could be more complete by describing the response structure or pagination behavior, but given the low complexity, it is adequate.

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%: both 'page' and 'per_page' parameters include descriptions with defaults and constraints. The tool description adds no extra parameter meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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 ('the company's teams and their members'). It distinguishes from the sibling tool aircall_get_team, which fetches a single team, by using 'list' and mentioning the plural '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 implies usage for retrieving all teams, and the context is clear. However, it does not explicitly mention alternatives like aircall_get_team for a specific team, nor any exclusions or when-not-to-use scenarios.

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 the description adds the specific fields returned (id, name, email, availability) and the REST endpoint, providing useful context without contradicting 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 sentence that front-loads the tool's purpose and includes the REST endpoint, with no unnecessary text.

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 two optional pagination parameters and no output schema, the description sufficiently covers the resource, fields, and API reference. The pagination behavior is documented in the schema, so the description is 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?

Both parameters (page, per_page) are fully described in the schema with 100% coverage, so the description does not need to repeat parameter details. It neither expands nor detracts from schema 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 states 'List users (agents) in the Aircall company (id, name, email, availability)', clearly identifying the verb (List), resource (users), and scope (Aircall company). It distinguishes from sibling tools like aircall_get_user by indicating this is the plural list operation.

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 that this tool is for listing all users in the company, but does not explicitly mention alternatives or exclusions (e.g., use aircall_get_user for a single user). The REST endpoint hint reinforces its purpose but doesn't add usage 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 declare readOnlyHint=true, and the description adds that it is a health check with a GET endpoint, which is consistent. However, it doesn't disclose response format or any rate-limit/error behavior. With annotations covering safety, a score of 3 is appropriate for minimal added behavioral context.

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

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

The description is extremely concise: one sentence with a dash clarification and an endpoint reference. Every word earns its place, and it's front-loaded with the key action.

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 ping tool, the description covers the essential purpose and endpoint. It lacks return value/response details, but since there is no output schema, the description could have explained what the response looks like. Still, the tool is simple enough that the current description is nearly 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 tool has no parameters, and the schema is empty. The description doesn't need to explain parameters. The baseline of 4 for zero parameters applies, and the description adds no unnecessary 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 uses a specific verb ('health check') and clearly states the resource (API) and what it verifies (reachability and credentials). It distinguishes this tool from the sibling tools, which are all get/list/update/search operations, by making it a connectivity test.

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 when to use it: to verify API reachability and credential validity. It doesn't explicitly exclude alternatives, but given the tool's unique purpose among the siblings, the context is sufficient. No explicit alternatives are needed.

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 readOnlyHint annotation already indicates this is a safe read operation. The description adds the search-oriented behavior and the REST endpoint, but does not disclose details like return format, pagination behavior, or potential edge cases. Given the annotation coverage, the description provides adequate but not rich additional 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 a single, efficient sentence that front-loads the purpose and includes the REST endpoint for additional reference. There is zero redundancy or unnecessary commentary.

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 read-only search tool with three optional parameters, no output schema, and a clear purpose, the description is mostly complete. It could explicitly mention that the tool returns a list of calls or describe pagination behavior, but the schema covers pagination parameters and the readOnlyHint covers safety. Overall it is adequate without being exhaustive.

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 already describes all three parameters (q, page, per_page) with full coverage. The description goes beyond the schema by giving concrete examples of valid search terms (phone number, tag, direction) for the q parameter, which helps the agent understand what can be searched. This extra context justifies a 4 instead of the 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 the tool's function: 'Search calls by a free-text term'. It identifies the resource (calls) and the mechanism (free-text), which distinguishes it from simple list/get operations. However, it does not explicitly name sibling alternatives like aircall_list_calls or aircall_get_call, so it falls just short of a 5.

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 this tool: whenever you need to find calls based on a free-text term such as phone number, tag, or direction. It does not include explicit when-not-to-use guidance or references to alternative tools, but the intended usage is unambiguous.

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 annotation 'readOnlyHint: true' already indicates a safe read operation, so the bar is lower. The description adds context that the search is via the REST endpoint 'GET /contacts/search' and that the search term matches against name, phone, or email, but it does not disclose additional behavioral aspects such as pagination behavior, result ordering, or response structure. It adds some value but not substantial behavioral details.

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

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

The description is a single, well-structured sentence that immediately states the action and scope. It includes the REST endpoint as supplementary context without redundancy. Every word earns its place, and it is front-loaded with the core purpose.

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 relatively simple with three optional parameters, full schema documentation, and a read-only annotation. However, there is no output schema, and the description does not explain what the search returns (e.g., a list of contact objects, pagination details). While the core functionality is clear, the lack of return-value information leaves a modest gap in completeness.

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 for all three parameters, each with a description, so the baseline is 3. The description enriches the 'q' parameter by providing concrete examples (name, phone number, email), but it does not add any information about 'page' or 'per_page' beyond what the schema already provides. The added value is minimal.

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: 'Search contacts by a free-text term (e.g. name, phone number, email).' This is a specific verb ('search') plus resource ('contacts') and scope ('free-text term'), which distinguishes it from sibling tools like 'aircall_list_contacts' (list all) and 'aircall_get_contact' (get by ID). The purpose is unambiguous and well-defined.

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 provide explicit guidance on when to use this tool versus alternatives. It implies usage when a free-text search term is available, but it never mentions exclusions or alternative tools such as 'aircall_list_contacts' for unfiltered listing or 'aircall_get_contact' for direct retrieval. There is no comparison or when-not-to-use advice.

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 provide destructiveHint=true, so the description's job is lighter. The description adds the REST endpoint (POST /calls/{id}/tags) and the instruction to get IDs from aircall_list_tags, which are useful technical details. However, it does not disclose whether tagging is additive or replaces existing tags, or any permission requirements, beyond what the annotation hints at.

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 information. It front-loads the core action and includes a practical hint about obtaining tag IDs, making every word 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?

For a tool with 2 simple parameters, no output schema, and minimal annotations, the description provides the essential context: what it does, how to get inputs, and the underlying REST call. It is sufficient for an agent to select and invoke the tool correctly, though it could potentially mention response behavior or side effects for fuller completeness.

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 clear descriptions for both parameters. The description adds extra value by specifying that tag_ids should come from aircall_list_tags, and it clarifies the id is a call id via the REST path. This goes beyond the schema alone, which is helpful.

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 ('Apply tags to a call by tag id') with a specific verb and resource, and it distinguishes the tool from siblings by focusing on tagging a specific call. It also provides a pointer to aircall_list_tags for obtaining IDs, which reinforces the purpose.

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 gives clear context on the tool's use and explicitly references aircall_list_tags as the source for tag IDs, which serves as a prerequisite guideline. It does not explicitly state when not to use the tool or mention alternatives, but the context is clear and no misleading 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 provide destructiveHint=true, so the description does not need to restate that. It adds value by disclosing partial-update semantics ('Only provided fields are changed') and the specific REST method, going beyond the annotation.

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, front-loaded with the core action, followed by the key behavioral note and REST hyperlink. No filler or redundant 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 update tool with full schema coverage and a destructive-hint annotation, the description covers the essential behavior needed for invocation. It does not describe return values or errors, but those are not required for selection or basic usage.

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 7 parameters have individual descriptions in the schema (100% coverage), so the description does not need to repeat them. It adds general update context but no per-parameter semantics 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 verb and resource: 'Update fields on an existing contact.' The phrase 'existing contact' distinguishes this update tool from create/get/list tools among the siblings.

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 mentions that 'Only provided fields are changed,' which is a useful partial-update nuance, but it does not explicitly state when to prefer this over aircall_create_contact or aircall_get_contact, nor does it name alternatives.

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