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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds valuable context: it is free, requires the sip_trunks:read scope, and explains an expected diagnostic discrepancy where probe.reachable false with a healthy Asterisk status is normal. This goes 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 compact but information-dense. It front-loads the purpose, explains the diagnostic mechanism, gives a real-world caveat, and includes cost and permission notes without 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?

Even though there is no output schema, the description explains enough of the result semantics (the two sources, the disagreement, the expected false-positive case) for an agent to interpret the outcome. Combined with the single well-documented parameter and rich annotations, the tool is fully actionable.

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 id parameter has a clear example. The description does not add parameter-specific guidance, but the schema fully documents the only parameter, 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 states a specific action (diagnose a trunk) and a distinctive method: comparing Asterisk's qualify result with a live network probe. This clearly differentiates it from siblings like get_sip_trunk, test_sip_trunk, and get_sip_trunk_logs.

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 an explicit usage condition: "Use this first when calls fail with carrier rejections." It does not explicitly name alternative tools or state when not to use it, but the primary routing guidance is present.

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?

All annotations are false, so the description carries the burden of behavioral disclosure. It adds valuable context by disclosing the exact error for invalid models (unsupported_model), the required scope (agents:write), and the exclusive voice-pipeline constraint. It does not mention idempotency or whether duplicate calls create duplicate agents, but the disclosed error and scope behavior go beyond what the schema and 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 compact and front-loaded. Every sentence serves a purpose: what the tool does, the prerequisite workflow, the key voice constraint, and the required authorization scope. There is no filler or repetition of the input schema.

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 complex tool with 8 parameters, a nested voice object, and no output schema, the description covers the most error-prone parts: model validation, voice pipeline exclusivity, and authorization. It does not describe the creation result shape or whether the agent is immediately usable, but the structured schema carries most parameter detail and the critical runtime constraints are present.

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%, so the individual parameters are already documented well. The description adds important semantic value for the nested voice parameter by explaining the composed pipeline vs. realtime-model exclusivity and reinforcing that model choices must come from list_engines. This helps an agent avoid invalid voice payloads even before opening the nested 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 opens with a specific verb and resource: 'Create a voice agent.' It clearly names the artifact being created and distinguishes this creation operation from sibling tools like update_agent, list_agents, and delete_agent. The voice pipeline detail further clarifies the specific type of agent being created.

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 a concrete prerequisite: call list_engines first to choose available models, and warns that unavailable or mistyped models will be rejected with unsupported_model. It also explains the voice structure choice clearly. It does not explicitly contrast with update_agent or state when not to use this tool, but for a create operation the usage context is mostly self-evident.

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

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

The description discloses critical behaviors beyond the annotations: the secret is returned once and cannot be retrieved again, it should not be logged, the new key cannot escalate beyond the calling key's scopes, and billing:write authorizes spending money. These are exactly the non-obvious behavioral facts an agent needs before invoking an API key creation tool.

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 compact and front-loaded with the most important operational warning: the secret is returned once and cannot be retrieved again. Every sentence earns its place, and there is no padding or redundant restating of the tool name.

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 mutative key-creation tool with no output schema, the description covers all essential invocation requirements: required caller scope, secure handling of the returned secret, scope-escalation limits, and the high-risk billing:write scope. An agent has enough information to use the tool correctly without additional 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%, so the baseline is 3. The description adds meaningful parameter-related guidance by explaining scope-escalation prevention and the financial implication of billing:write, going beyond the schema's enum list and field descriptions.

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 opens with 'Mint a new scoped key,' a specific verb and resource that clearly indicates creation of an API key. This distinguishes it from sibling tools such as rotate_api_key, revoke_api_key, and list_api_keys without any 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?

It states the required caller scope (api_keys:write) and gives concrete guidance on when this tool is appropriate: grant only needed scopes and avoid creating keys with billing:write unless spending is intended. It does not explicitly compare against rotate or revoke alternatives, but the context is clear enough for an agent to know when creation is the right operation.

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 annotations already signal that this is a write operation (readOnlyHint=false) and not idempotent. The description adds a useful authorization requirement ('Requires scope appointments:write') but does not disclose other behavioral traits, such as duplicate handling, return value, or what resources are affected beyond creating the appointment.

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 only two sentences: one for the core action and one for the required scope. Every sentence earns its place, and the most important information is 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 creation tool with no output schema and seven parameters, the description leaves significant gaps: no field-level guidance for most parameters, no mention of required preconditions, and no indication of what the response contains. The description is too sparse to fully support correct invocation beyond the action itself.

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 documents only 29% of parameters, and the description adds little to fill the gap. 'Against a lead and agent' clarifies that lead_id and agent_id are involved, but notes, client_name, duration_minutes, and other fields remain unexplained in both the schema and 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 uses a specific verb ('Book') and names the resource and its key relationships ('against a lead and agent'), making the operation clear. It clearly distinguishes this creation tool from sibling update/get/delete/list appointment 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?

The description gives no guidance on when to use this tool versus alternatives such as update_appointment, nor does it state prerequisites like whether the lead and agent must already exist. The only usage signal is the phrase 'Book an appointment', which is implied rather than 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?

Annotations already mark this as a write operation (readOnlyHint: false), but the description adds valuable behavioral context: creating does not start dialing, scheduled_at controls immediate versus scheduled start, and the campaigns:write scope is required. This goes beyond the structured fields and helps the agent set expectations.

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 compact and front-loaded with the most important caveat: 'Creating does NOT dial anyone.' Every sentence adds useful information, and the scope requirement is cleanly separated. There is no repetition of schema details or annotation facts.

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 creation tool with four parameters and no output schema, the description covers the key behavioral distinction from start_campaign, scheduling semantics, and scope requirements. It is sufficient for an agent to select and call the tool correctly, though it does not describe the response shape or what happens after creation.

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 50%, with lead_ids and scheduled_at already described. The description adds meaning by linking lead_ids to 'every listed lead' and clarifying scheduled_at semantics with 'Without scheduled_at the campaign is ready to start immediately,' but it does not elaborate on name or agent_id beyond their obvious roles.

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 action ('Create a campaign') and a concrete resource behavior: it will call every listed lead with an agent. It also distinguishes itself from the sibling start_campaign by explicitly noting that creating does NOT dial anyone, so an agent can tell the two apart.

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 when-to-use and when-not-to-use guidance: use create_campaign to set up, and call start_campaign when the user is ready to spend. It also explains the scheduled_at behavior, which helps the agent decide whether to include that parameter.

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

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

The description adds the auth requirement 'Requires scope knowledge_bases:write', which is not visible in the annotations. Combined with annotations that already indicate this is a non-read, non-idempotent, non-destructive operation, the description provides sufficient behavioral context without contradicting 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, front-loading the tool's purpose before stating the required scope. Every sentence contributes useful information without repetition 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 create operation with five parameters, one required parameter, and no output schema, the combination of description, schema, and annotations covers the essential usage context. The missing piece is explicit guidance on when to create versus update, but the schema's parameter descriptions and the scope note make the tool usable.

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 80%, so the schema already documents most parameters meaningfully. The description's mention of 'facts and FAQs' loosely maps to basic_info and faqs, but it adds no parameter-level detail beyond what the schema 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 the specific verb 'Create' with the resource 'knowledge base' and explains its purpose: storing facts and FAQs an agent can draw on during calls. This clearly distinguishes it from sibling tools like update_knowledge_base, delete_knowledge_base, list_knowledge_bases, and get_knowledge_base.

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 establishes that this tool is for creating a new knowledge base, but it does not explicitly say when to prefer it over update_knowledge_base or list_knowledge_bases. The scope requirement is helpful but does not guide an agent through the decision of when to create versus update.

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 that this is a mutating, non-idempotent operation. The description adds useful behavioral context by stating the required `leads:write` scope and clarifying the single-create semantic, which goes beyond the structured 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 short sentences front-load the primary action, then give the batch alternative and the required scope. Every clause earns its place with no padding.

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 plus schema and annotations covers the core needs: required fields, phone format, batch exception, auth scope, and mutating behavior. The lack of an output schema makes return-value information less critical, though a hint about the created object would have been a minor improvement.

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 adds no parameter-level semantics beyond the schema. With only 50% schema description coverage, `name` and `tags` remain effectively undocumented, and the prose does not compensate for this gap.

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 'Create one lead' with a specific verb and resource. It immediately distinguishes itself from the sibling tool import_leads, making its purpose unambiguous and non-tautological.

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 explicitly tells the agent to use import_leads when creating many leads at once, which is a clear alternative with a specific condition. It also states the required authorization scope, leaving little ambiguity about when this tool should be selected.

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 only provide false hints, so the description carries the full burden of behavioral disclosure. It clearly states that inbound calls are rejected if inbound_agent_id is not set, that carrier-level configuration is required for inbound to work, that numbers must already be owned (Wixzel does not sell them), and that the phone_numbers:write scope is required. These are concrete, useful behavioral details beyond what the schema or annotations 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 compact and front-loaded: the main purpose is in the first sentence, followed by the critical behavioral caveat, the carrier prerequisite, and the required scope. Every sentence adds value with no filler 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 create operation with four parameters and no output schema, the description adequately covers the intended use, prerequisite configuration, optional-agent behavior, and required permission. It references get_sip_trunk for the origination_uri detail, making it complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics for inbound_agent_id by explaining that omitting it means inbound calls are rejected, which goes beyond the schema's 'Agent that answers inbound calls to this number.' The other parameters are adequately defined by the schema, so a slight elevation to 4 is justified.

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, 'Register', and clearly identifies the resource: a number you already own, attached to one of your SIP trunks. It also distinguishes the tool from the sibling set by explicitly noting that Wixzel does not sell numbers, while the create/list/update/delete siblings in the phone number group make the intent unambiguous.

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 own a phone number and want to register it on a SIP trunk. It also provides actionable preconditions for inbound calling—set inbound_agent_id for an agent to answer, and point the carrier at the trunk's origination_uri for inbound to ring at all. However, it does not explicitly mention alternative siblings (e.g., update_phone_number) for subsequent changes, so it stops short of a perfect score.

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?

Beyond the annotations, the description discloses important behavioral outcomes: the returned platform_ip and origination_uri must be used for allowlisting and origination setup. It also states the required scope. This adds meaningful post-creation context and authentication expectations that the annotations do not 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?

Every sentence contributes: the core function, a key boundary (no resale), critical follow-up steps, and required scope. It is compact and front-loaded with the primary 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?

For an 11-parameter tool with no output schema, the description provides essential context about the returned values and next steps, plus scope requirement. It does not explain parameter interactions like send_plus or dial_prefix, but those are adequately documented in the schema. Overall it is sufficient for an agent to invoke the tool and continue the workflow 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 73%, so the schema already documents most parameters individually. The tool description adds no direct parameter-level guidance, but it gives contextual framing around carrier setup (allowlist, origination URI). It does not compensate for the three undocumented parameters (transport, username, auth_realm) but is not required to do so at this coverage level.

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 (connect) with a clear resource (user's own carrier) and names the operational outcome. It distinguishes itself from sibling operations like checking status or updating by describing the creation workflow, and the title reinforces the 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?

It clearly states when this tool is used: when the user brings their own carrier, and explicitly notes Wixzel does not resell telephony. It also gives a follow-up instruction to run check_sip_trunk_status. It does not explicitly name alternative tools or exclusion conditions, but the context 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 description goes well beyond the annotations by explaining that credit is applied only after payment settles, that a human must complete payment, and that automated payment or URL-opening is forbidden. It also discloses the required billing:write scope, giving the agent a full behavioral picture.

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 compact and front-loaded: primary action first, then critical safety and workflow instructions, then the auth requirement. Every sentence adds value, and there is no redundant restatement of schema details.

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

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

Despite having no output schema, the description tells the agent what to expect (checkout_url), what not to do, and when credit actually lands. Combined with the annotated openWorldHint and idempotentHint behavior, the tool is fully specified for correct 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?

Schema description coverage is 100%, so the schema fully documents amount_usd, return_url, and idempotency_key. The description adds only the confirmation guidance related to amount_usd, which is useful but not a substantial expansion of the parameter semantics.

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

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

The description opens with 'Start a top-up,' a specific verb and resource, and immediately explains the key output (a checkout_url for human payment). It is clearly distinct from siblings like get_balance, which reads rather than creates.

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 usage context: confirm the amount with the user first, and never open the URL or attempt payment yourself. It doesn't name explicit alternative tools, but no sibling appears to offer the same top-up functionality, so the guidance is sufficient.

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

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

The description goes well beyond the annotations. It confirms and elaborates destructiveHint=true with 'Permanently delete' and 'Not reversible,' explains downstream effects on phone numbers and campaigns, and discloses the required `agents:write` scope. This is rich behavioral context that annotations alone do not 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?

Three short sentences deliver the core action, consequences, and auth requirement with no filler. The warning about irreversibility is front-loaded and essential for a destructive 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 simple single-parameter destructive delete operation, the description covers what happens, the irreversible nature, the scope requirement, and the functional impact on related resources. No output schema exists, but the description is complete enough for an agent to invoke the tool correctly.

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

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

The input schema already documents the only parameter `id` with a clear example and 100% description coverage. The tool description adds no additional parameter-level 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 opens with a specific verb and resource: 'Permanently delete an agent.' This clearly distinguishes it from sibling tools like update_agent, get_agent, and delete_lead, and the title reinforces the same resource and action 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?

The tool's usage context is clear: use it to permanently delete an agent, with the consequence that associated phone numbers and campaigns stop working. It does not explicitly name alternatives or exclusions, but for a delete-specific operation the intended use case is sufficiently evident.

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 annotations already mark the operation as destructive and non-read-only, but the description adds meaningful context beyond them: permanence ('Permanently delete'), irreversibility ('Not reversible'), and the required OAuth scope 'appointments:write'. 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?

Every sentence earns its place: the action, the alternative, the irreversibility warning, and the scope requirement are each expressed in a short, front-loaded statement. There is no filler 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 one-parameter delete operation with annotations covering destructive/idempotent behavior and no output schema, the description fully equips an agent: what it does, when to avoid it, what happens afterward, and what scope is required.

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 documented with type and an example. The tool description adds no further parameter-level meaning, so it correctly relies on the schema 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 clearly states the tool's action ('Permanently delete an appointment') with a specific verb and resource. It also distinguishes itself from the cancellation path by telling the agent to update status to canceled when the record should be kept, separating it from sibling update_appointment.

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 explicitly gives the condition for using the alternative: 'To cancel but keep the record, update its status to canceled instead.' It also warns the operation is not reversible, making the appropriate use case unmistakable.

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?

Beyond the annotations, the description discloses important behavioral details: what is removed (transcript and recording), what is preserved (usage rows), the in-progress restriction, irreversibility, and the required scope. This goes well beyond the structured annotations and gives the agent a complete picture of side effects.

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

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

The description is compact and front-loaded: the core action appears in the first sentence, followed by essential caveats and the scope requirement. Every sentence provides useful information; there is no filler 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 single-parameter destructive tool with annotations already indicating destructive and non-read-only behavior, the description fully covers what is deleted, what is kept, the in-progress limitation, irreversibility, and authorization. Nothing critical is missing for an agent to invoke it correctly.

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

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

The schema already fully documents the single parameter 'id' with a concrete example, so schema coverage is 100%. The description does not add meaningful parameter-level semantics beyond referring to the call record, 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 uses a specific verb ('Remove') and resource ('a call log with its transcript and recording'), and clarifies the erasure-request context. It clearly distinguishes itself from sibling tools like hangup_call by noting that in-progress calls cannot be deleted and must be hung up first.

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 states when to use the tool ('as a caller's erasure request needs'), when not to use it ('A call still in progress cannot be deleted'), and the prerequisite action ('hang it up first'). This gives an agent clear decision-making guidance without needing to inspect sibling tool definitions.

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

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

The description goes beyond the annotations by adding that deletion is permanent and not reversible, requires the campaigns:write scope, and should be preceded by pausing if the campaign is running. These are operationally important details not present in the structural fields.

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?

Every sentence carries useful information: what it does, the safety precondition, the consequence, and the required scope. 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 one-parameter deletion tool with destructive and idempotent annotations, the description covers all essential operational context: behavior, prerequisite, irreversibility, and permission requirements.

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 fully documents the single required id parameter with an example. The description does not add parameter-specific meaning, which is acceptable given 100% 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 states a specific verb ('delete') and resource ('campaign'), and 'Permanently' clarifies the operation's finality. This distinguishes it from campaign lifecycle tools like pause_campaign, update_campaign, or delete_lead.

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 an explicit precondition: 'Pause it first if it is running.' The irreversibility warning also implies caution against using this when a temporary stop is sufficient, though it does not explicitly name pause_campaign as the alternative.

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?

Beyond the annotations, the description adds meaningful behavioral context: deletion is permanent, not reversible, and agents referencing the knowledge base lose that context. It also discloses a required authorization scope. This goes well beyond the destructiveHint and idempotentHint 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 three short sentences, with the core action front-loaded. Each sentence adds distinct value: what it does, the consequence, and the access requirement. There is 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 a single-parameter delete operation with no output schema, the description covers purpose, permanence, impact, and authorization. Nothing essential is missing for an agent to decide whether to invoke the tool and understand the result.

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 the id parameter already described and given an example. The description adds no additional parameter-level meaning, but that is acceptable because the schema fully documents the only 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?

States a specific verb and resource: 'Permanently delete a knowledge base.' It goes beyond a simple restatement by describing the consequence that agents referencing it lose context, and explicitly says it is not reversible. This clearly distinguishes it from update_knowledge_base and other knowledge base operations.

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 for when to use the tool, emphasizing that deletion is permanent and affects agents that reference the knowledge base. It also provides the required scope, knowledge_bases:write. It does not explicitly name alternatives, but for a delete operation the context is strong enough.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds the crucial context that deletion is permanent and irreversible, plus the `leads:write` scope requirement. This 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 brief sentences convey action, consequence, and authorization with zero waste. The most important information is 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 one-parameter destructive operation, the combination of annotations (destructive, idempotent, non-read-only) and description (permanent, irreversible, scope) fully equips an agent to invoke it correctly. No output schema is necessary for a simple delete.

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 gives no parameter-specific details, but the input schema fully documents the single `id` parameter with an example. With 100% schema coverage, the schema carries the semantic load.

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 specifies the exact action ('Permanently delete') and resource ('a lead'), making the tool's function unmistakable. It also distinguishes it from other lead tools like update_lead or get_lead and from delete_* siblings by naming the 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 implies use when a lead should be permanently removed, but does not explicitly compare this to alternatives or state when not to use it. The required scope is a prerequisite, not a usage guideline.

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

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

The description goes beyond the annotations by specifying the real-world consequence for agents, explicitly stating the operation is not reversible, and documenting the required OAuth scope. The destructiveHint annotation already signals deletion risk, but the description adds actionable 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 compact, front-loads the core action, and uses only two short sentences plus a scope line. Every sentence contributes essential information 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 single-parameter delete operation, the description covers the action, the side effects, irreversibility, and required permissions. The annotations supply the safety profile. No important context for an agent deciding to call this tool is missing.

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 described in the input schema with a concrete example, so schema coverage is 100%. The description does not add parameter-specific meaning, but none is necessary given the schema already documents it clearly.

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 clear verb ('Remove') and specific resource ('a phone number from the account'), and further differentiates itself by noting the impact on agents that use the number as their outbound caller. This distinguishes it from other delete tools such as delete_call or delete_agent.

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

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

The description clearly conveys when this tool is appropriate: when a phone number needs to be permanently removed from the account. It also gives practical context by warning that agents using it can no longer place calls. However, it does not explicitly mention alternative tools or conditions when not to use it, though the name and scope make that fairly obvious.

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 mark destructive and not read-only, but the description adds non-obvious context: the delete is irreversible, phone numbers on the trunk lose call capability, and the required scope `sip_trunks:write` is disclosed. 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?

Three short sentences, each carrying distinct information: the operation, the user-facing consequence, and the required permission. 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 a one-parameter destructive tool with annotations covering safety and a description covering irreversibility and scope, the definition is sufficient. It doesn't describe the success response, but there is no output schema and delete responses are typically minimal. Minor gap: what happens to assigned phone numbers beyond loss of call capability.

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 `id` parameter includes an example in the schema. The description adds no additional parameter semantics, but none are needed given the rich 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?

States a specific verb and resource ('Remove a SIP trunk') and adds a distinguishing consequence: phone numbers on it can no longer make or take calls. This clearly separates it from sibling delete_* tools like delete_phone_number.

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 when-to-use guidance or alternative routing is provided. The description explains the effect but not when an agent should choose delete_sip_trunk over update_sip_trunk or check_sip_trunk_status, nor any prerequisites such as ensuring no active calls.

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, idempotent, non-destructive behavior. The description adds useful context beyond annotations by stating the required `agents:read` scope and clarifying that the full voice configuration and prompt are included in 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?

Two concise sentences with no filler. The first sentence front-loads the purpose and return content; the second adds the auth prerequisite. 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?

For a simple get-by-id tool with one parameter and strong annotations, the description is complete: it states the operation, the required scope, and the key return content. No output schema exists, but the high-level return description is sufficient for this 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 documents the single `id` parameter with a description and example (100% coverage). The description only restates that the operation is by id, so it adds little beyond the schema. 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 uses a specific verb and resource: 'Fetch one agent by id,' and further specifies the return contents ('full voice configuration and prompt'). This clearly distinguishes it from list_agents and other agent-related 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?

The description makes the intended use clear: call this when you have a single agent id and need that agent's complete configuration. It also adds a scope requirement. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to choose correctly.

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 description's main behavioral addition is the required 'appointments:read' scope. This is useful context beyond the annotations, though it does not discuss 404 behavior or response format.

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 the core behavior front-loaded. The scope requirement is stated concisely, and there is no redundant or 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 single-parameter read operation, the description plus annotations provide the essential context: what to fetch, the required scope, and the safe/idempotent nature of the call. It does not describe the return payload, but that is not critical for a straightforward get-by-id 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%, and the id parameter already has a clear schema description with an example. The tool description adds little beyond 'by id', 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 states a specific action ('Fetch one appointment by id') with a clear resource and retrieval method. The word 'one' and 'by id' distinguish it from list_appointments and other collection-fetching 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?

The description implies when to use the tool: when a specific appointment ID is known and a single record is needed. However, it does not explicitly mention alternatives like list_appointments for fetching multiple appointments, nor does it provide exclusion criteria.

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 mark this as read-only, idempotent, and non-destructive. The description adds valuable behavior context beyond the annotations: the unit conversion (1,000,000 micro-USD = $1.00), the meaning of held_micros as reserved by live calls, and the required billing:read scope. It is fully consistent with 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 compact and front-loaded: it immediately defines the resource and return fields, then adds the usage context and scope. Every sentence earns its place, with no redundant phrasing or repetition of the title.

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

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

For a zero-parameter read-only tool with no output schema, the description provides all necessary information: return field names, units, the reserved-credit concept, the scope requirement, and when to call it. Nothing essential is missing for an agent to invoke or interpret the result.

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 schema description coverage is 100%, so there is nothing for the description to add about individual parameters. The description instead explains the meaning of the returned fields, which is the closest relevant semantic content. According to the baseline for 0 parameters, this is an appropriate score.

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 tool as retrieving the account's prepaid credit and specifies the exact fields returned: balance_micros, held_micros, and available_micros. It is obviously distinct from most siblings, but it does not explicitly differentiate itself from related reporting tools like get_usage_summary or list_ledger_entries.

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 says to check this before placing calls or starting campaigns, which gives a clear operational context for when the tool should be invoked. However, it does not name alternatives or provide exclusion criteria, so it stops short of a fully explicit when-to-use vs when-not-to-use guide.

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 safe-read profile is known. The description adds meaningful context beyond annotations: it requires scope 'calls:read' and explains failure_code semantics (Q.850 causes) and failure_reason guidance. This goes beyond the baseline safety hints without contradicting any 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 efficiently structured: first paragraph lists the full contents, second paragraph addresses failure specifics with useful codes. The Q.850 code list is slightly verbose but relevant for interpreting failure_code. Every sentence 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?

With no output schema, the description enumerates all expected return fields and failure fields, plus auth requirements. The input is covered by the schema. For a single-get tool, this is complete enough for an agent to call it correctly and interpret the response.

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 call id (not the session_id),' providing clear semantics. The description does not add any additional parameter-level meaning, so baseline 3 is appropriate given 100% 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 title 'Retrieve a call' and the description 'The full call record: status, duration, cost_micros, recording_url, summary, transcript, transfers, and any provider errors' clearly state a specific verb and resource. It distinguishes itself from siblings like get_call_transcript by enumerating all fields returned.

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 through the description of returning the full call record and failure diagnostics, but no alternatives are explicitly mentioned. It does not say when to use this instead of get_call_transcript or list_calls, nor when to avoid it. Thus guidance is present but left to inference.

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, so the safety profile is clear. The description adds useful context beyond annotations by specifying the required scope and the exact return structure. 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 extremely compact: two short sentences. The purpose and return format are front-loaded, and the scope requirement is cleanly separated. Every sentence adds value 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 single-parameter read-only tool, this description is complete. It specifies the return format, the auth scope, and is backed by annotations covering safety. No output schema exists, but the description explicitly defines the output structure, so nothing essential is missing.

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 covers the single id parameter with a description and example format. Schema description coverage is 100%, so the description need not add parameter details. Baseline 3 applies as the schema carries the parameter documentation load.

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 a call transcript and specifies the exact return format as a list of {role, content, timestamp} turns. The title reinforces the verb and resource. It does not explicitly differentiate from siblings like get_call, but the meaning is unambiguous.

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 'Just the transcript of a call' implies this tool is for when only the transcript is needed, and the scope calls:read indicates a prerequisite. However, there is no explicit statement about when to use this over get_call or list_calls, nor any 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 disclose readOnlyHint, idempotentHint, and destructiveHint, so the description's added value is limited to the campaigns:read scope requirement. It does not mention not-found behavior or response format, but the annotation safety profile lowers the burden.

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 terse sentences earn their place: the first states the operation and scope, the second the required permission. No 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?

With one parameter, a complete schema description, and strong annotations, the description is nearly sufficient. The only minor omission is explicit behavior when the id does not exist, but that is not critical for a simple read 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 the id property already described and given an example. The description's 'by id' adds no new parameter meaning beyond the schema.

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

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

Description uses a specific verb ('Fetch') with a specific resource ('one campaign by id'), making the tool's purpose immediately clear. It also distinguishes itself from sibling list_campaigns by emphasizing single-record retrieval.

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 'by id' implies the tool is for retrieving a single known campaign, which is useful context among sibling list/get/create/update/delete tools. It also states the required scope, but does not explicitly mention when to prefer get_campaign over list_campaigns.

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 covered. The description adds valuable context by noting the required scope 'knowledge_bases:read' and clarifying that the full content is returned. There is 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 concise sentences with no filler. The core action is stated first, followed immediately by the auth requirement, making it easy for an agent to parse quickly.

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

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

For a simple single-resource fetch operation, the description is complete: it states the resource, the retrieval semantics, and the required scope. Annotations cover safety, and the schema fully documents the only parameter. No critical information is missing.

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 the 'id' parameter already documented including an example. The description does not add parameter-level details, but it does not need to because the schema carries the full semantic load.

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 ('Fetch') with a clear resource ('one knowledge base') and even specifies it returns 'full content'. This clearly distinguishes it from siblings like list_knowledge_bases and create_knowledge_base.

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 intended use is implied: fetch a single knowledge base by id, given the required 'id' parameter and the contrast with list_knowledge_bases. However, the description does not explicitly state when to use this tool versus alternatives, nor does it mention 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 this as read-only, idempotent, and non-destructive. The description adds a valuable behavioral requirement: the `leads:read` scope must be held. This is auth context the annotations do not provide, so it goes beyond the structured metadata.

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 with no filler. The core purpose is stated first, and the scope requirement follows immediately. 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?

For a simple get-by-id tool, this is complete. The schema covers the id parameter, the description covers purpose and required scope, and the annotations cover the safety profile. No additional behavioral detail is necessary to invoke it correctly.

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

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

The schema fully documents the only parameter, id, with a description and example value, so schema coverage is 100%. The description does not add extra parameter details, but it does reinforce that the id identifies the single lead to fetch. The baseline of 3 applies because the schema carries the load.

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 'Fetch' with a clear resource ('one lead') and a precise selection method ('by id'). This clearly distinguishes it from list_leads and aligns exactly with the tool name and title.

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 conveys that this tool is for retrieving a single lead when the id is already known, which implies it should not be used for browsing or filtering. It does not explicitly name an alternative tool like list_leads, but the context is clear enough for an agent to select correctly.

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 mark it read-only, idempotent, and non-destructive, so the description only needs to add extra context. It adds the required scope (`phone_numbers:read`), which is genuinely useful and goes beyond what annotations express. 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?

Two short sentences; the core action is front-loaded and the scope requirement is a separate, clearly marked note. Every sentence earns its place 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?

For a simple single-record read with rich annotations and 100% schema coverage, the description plus schema leave no critical gaps. The only omission is explicit 404/not-found behavior, which is minor and conventional for a fetch-by-id 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?

Schema coverage is 100%, with the id parameter already described and given an example. The description adds no new parameter semantics beyond restating that lookup is by id, so 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 names a specific verb ('Fetch'), a specific resource ('one phone number record'), and the lookup key ('by id'), clearly distinguishing it from list_phone_numbers, which returns collections. Nothing ambiguous about what this tool does.

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: you call this when you have a phone number record id and want that single record. It does not explicitly contrast with list_phone_numbers or mention when not to use it, leaving the agent to infer from sibling names.

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

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

The description adds valuable behavioral details beyond the annotations: the password is never returned, and a specific OAuth scope is required. This is especially useful for a read-only retrieval that might otherwise be assumed to return all fields.

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 with the core purpose front-loaded and only essential security/scope context added. There is no fluff 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 a simple single-parameter read tool, the description covers purpose, id-based selection, auth requirement, and the key security consideration (password omitted). No output schema exists, but the description adequately implies a SIP trunk object is returned.

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 id parameter, so the schema already documents semantics. The description simply confirms 'by id' without adding new parameter information, making a baseline score of 3 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 states a specific verb ('Fetch'), resource ('SIP trunk'), and scope ('by id'). This clearly distinguishes it from list_sip_trunks and other SIP trunk operations like create/update/delete.

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 for fetching a single SIP trunk when you already have its id. It doesn't explicitly mention alternatives like list_sip_trunks, but the context is clear enough for an agent to choose correctly.

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 annotations already mark this as read-only and idempotent, but the description adds valuable non-obvious context: the data is a volatile in-memory ring buffer rather than durable history, and a `sip_trunks:read` scope is required. This is meaningful behavior disclosure beyond what annotations alone 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 compact and front-loaded, with each sentence earning its place: what the events are, the ring-buffer caveat, the polling instruction, and the required scope. No filler or redundant restatement.

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 tool with no output schema, the description covers event types, data volatility, auth requirements, and pagination. The main gaps are the precise role of the `id` parameter and the effect of `limit`, but those are minor against an otherwise thorough description.

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 adds useful meaning to `since_id` by tying it to `last_id` from the previous response. However, the required `id` parameter is ambiguous—the tool name implies a SIP trunk ID, but the description only refers to 'recent events for this account'—and `limit` is not explained beyond schema constraints.

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 resource (SIP engine events for the account) and the specific event content: registration, call setup, and carrier rejections with causes. This distinguishes it from sibling SIP trunk configuration/status tools, which are about trunk state rather than recent event logs.

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 explicitly describes the polling pattern: 'Poll with since_id set to the last_id of the previous response to get only new entries.' It also warns that this is a live in-memory ring buffer, not an audit trail, which tells agents when not to rely on it. It doesn't name an alternative tool, but the usage 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 cover read-only and idempotent behavior. The description adds useful behavioral context beyond annotations by stating the required authorization scope and clarifying output semantics: 'total_micros is micro-USD; total_display is human-readable.' This meaningfully supports correct invocation and interpretation.

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 three terse sentences: the first states purpose, the second explains output fields, and the third gives an auth requirement. There is no filler or redundancy; every sentence 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 simple two-optional-parameter read tool, the description covers the core purpose, grouping dimensions, output field units, and required scope. Since there is no output schema, the response structure is only partially explained—e.g., how the breakdown by component/provider/model is shaped—so it is strong 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 already fully describes both parameters with 'Period end. Defaults to now.' and 'Period start. Defaults to the start of the current month.' The description does not add date format, syntax, or other parameter-specific details, so it stays at 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 states a specific verb and resource: 'Total spend over a period, broken down by component, provider and model.' This clearly distinguishes the tool from siblings like list_usage_events or get_balance, even without naming them, because it defines exactly what summary it produces.

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 the tool—when you need a spend summary over time—and includes a prerequisite ('Requires scope usage:read'). However, it does not explicitly contrast it with alternatives such as list_usage_events for raw events or get_balance for current balance, so usage guidance is only implied rather than 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?

Beyond the annotations, the description discloses the billing impact, the return value, and the required authorization scope. It explains that ending the call stops billing and returns the updated call record, which is meaningful behavioral context not present in the structured 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 short, front-loaded, and every sentence adds value: what the tool does, the billing side effect, the return value, and the required scope. There is no redundant or filler 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?

For a simple single-parameter tool with one required id and an idempotent, non-destructive annotation profile, the description is complete. It covers the action, the response shape, the auth requirement, and the key side effect, so an agent has enough context to select and invoke the tool correctly.

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

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

The input schema fully documents the single `id` parameter with a description and example. The tool description adds no additional parameter-level semantics, so the baseline score 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 states a specific action and resource: "Hang up a live call." It clearly distinguishes itself from siblings like delete_call by noting the call is live and that the updated call record is returned, implying the record remains rather than being deleted.

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?

"Hang up a live call" gives clear context for when to use this tool: when a call is currently active and needs to be ended. It does not explicitly name alternative tools or exclusions, but the live-call framing makes the intended usage reasonably 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?

Beyond the annotations (which only deny read-only/idempotent/destructive), it discloses partial-success semantics, per-row validation, error indexing, the failed_count result field, and the required leads:write scope. This is substantial and operationally useful behavioral context for a write operation.

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?

Three focused sentences deliver purpose, partial-failure behavior, result guidance, and authentication requirements. Every sentence earns its place with no 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 batch mutation with no output schema, it covers limits, validation outcomes, error reporting, where to look for failures, and required auth scope. An agent has enough to call it correctly and interpret the response.

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?

With schema description coverage reported at 0%, the description needed to clarify the lead object fields, yet it only says 'rows' and effectively repeats the 1,000 cap already present in maxItems. It adds no meaningful explanation of name, phone_number, tags, or fields beyond what the schema structure already shows.

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 and resource ('Create up to 1,000 leads in one request') and the batch capacity makes it clearly distinct from the singular create_lead sibling. The title 'Import many leads' reinforces the same purpose 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?

The batch context is implied by 'up to 1,000 leads in one request', but the description never explicitly says when to choose import_leads over create_lead or another sibling. It leaves the routing decision to inference rather than naming an alternative or 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral detail beyond annotations by explaining that results are cursor-paginated and that `next_cursor` from a previous response is passed as `starting_after`.

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 compact and front-loaded: purpose first, pagination behavior second, required scope last. 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 read-only listing tool with all optional parameters and no required inputs, the description covers purpose, pagination, and authentication requirements. It omits a detailed return-shape description, but that is not critical when the output schema is absent and the tool's behavior is straightforward.

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 descriptions cover all three parameters, so a baseline of 3 applies. The description adds meaningful guidance by explicitly connecting `next_cursor` to `starting_after`, which clarifies the pagination flow beyond the individual parameter descriptions.

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 and resource: 'List the voice agents on this account.' It clearly distinguishes from sibling agent tools like get_agent, create_agent, update_agent, and delete_agent by indicating collection-level enumeration.

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 operational context: it explains cursor-based pagination and the required `agents:read` scope. It does not explicitly enumerate when to choose this tool over alternatives, but the context is sufficient for a list operation on the account's agents.

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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: secrets are never returned, only a prefix and last four characters, which is critical for agents handling sensitive 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?

Two concise sentences deliver the core purpose, output characteristics, and auth requirement with no redundant wording. The most important security behavior is front-loaded in the second sentence, making it highly scannable.

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

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

For a simple list operation with optional pagination parameters and no output schema, the description covers the essential return details (fields included, secrets omitted) and the required scope. It does not describe pagination response shape, but the schema already documents cursor semantics.

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%, so the parameters (limit, ending_before, starting_after) are fully documented in the schema. The description adds no parameter-specific detail, which is acceptable since the schema carries the burden.

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' with a clear resource ('the account's API keys') and specifies the returned fields (scopes, spend limits, last use). This clearly distinguishes it from sibling tools like create_api_key, revoke_api_key, and rotate_api_key.

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 states a clear prerequisite ('Requires scope api_keys:read') and makes the read-only nature obvious. It does not explicitly name alternative tools for creating/revoking keys, but the context of siblings and the 'List' action leave little ambiguity.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds useful behavioral context: the required `appointments:read` scope and the specific types and statuses of appointments returned. It does not contradict the annotations and provides meaningful information beyond 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 short sentences with no filler: the first states the core function and relevant domain context, and the second states the auth requirement. Both sentences earn their place, and the main action is 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?

The description plus annotations and a well-documented schema give the agent the auth requirement, resource scope, and pagination parameters needed to invoke the tool correctly. There is no output schema and the exact response shape is left implicit, but for a read-only paginated list tool this is a minor gap rather than a critical omission.

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 full description coverage for all three parameters, including limits, defaults, cursor semantics, and mutual exclusivity. The tool description adds no additional parameter-level detail, so the schema carries this dimension; 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 opens with the specific verb 'List' and resource 'appointments,' and adds meaningful context about the two creation sources (by agents or directly) and the statuses returned. This clearly identifies what the tool does and distinguishes it from get_appointment by signaling a collection-oriented 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 use case is implied by the verb 'List': an agent should call this when it needs a collection of appointments rather than a single one. However, the description does not explicitly mention get_appointment as the alternative for fetching a single appointment, nor does it provide any when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so no safety ambiguity. The description adds useful behavioral context beyond annotations: it returns summary data only, not transcripts, and requires the calls:read scope. This helps the agent understand what the call will and will not return.

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?

Three concise, information-dense sentences: scope qualifier, filter capabilities, single-call alternative, and auth requirement. Every sentence earns its place and the key differentiator is 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 12-parameter list tool with no output schema, the description covers purpose, filter categories, the correct alternative, and required scope. Pagination and individual param detail are handled by the schema. The only minor gap is that 'summary form' is somewhat vague about exact output fields, but it is sufficient for correctness.

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 documents 67% of parameters; the description adds a functional overview by grouping them into filter dimensions: status, direction, agent, campaign, engine, phone number, and time window. It does not add individual parameter detail beyond the schema, so it partially compensates but mostly relies on 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?

Description states a specific verb and resource: 'List calls', and adds a precise scope qualifier: 'in summary form (no transcript)'. It also names the alternative get_call for the full record, so an agent can distinguish list_calls from get_call and get_call_transScript without opening schemas.

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

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

Provides a clear when-to-use context: list calls in summary form; if the full record of a single call is needed, use get_call. It does not explicitly mention get_call_transcript for transcripts, but the phrase '(no transcript)' plus 'full record' gives sufficient routing information.

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 read-only, idempotent, and non-destructive, and the description is consistent with that. It adds meaningful behavioral context by stating the required OAuth scope and the specific status values returned, going beyond what annotations 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 tight sentences with no filler. The core listing purpose and returned fields are front-loaded, and the scope requirement is placed as a clear secondary line.

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

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

For a simple paginated read-only list tool, the description plus fully documented schema and safety annotations cover the essential invocation details. It could mention the response shape more explicitly since there is no output schema, but the schema's cursor descriptions and the mention of lead_count give sufficient 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?

The input schema has 100% description coverage, including pagination semantics for limit, starting_after, and ending_before, so the description does not need to repeat them. The description adds no new parameter-level meaning beyond what the schema provides, matching the baseline for 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 states a specific verb ('List'), a precise resource ('outbound calling campaigns'), and the key returned attributes (status and lead_count), making the tool's purpose immediately clear. It distinguishes itself from get_campaign and other campaign-mutating siblings by focusing on the listing of campaigns with their statuses.

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 browsing campaigns and checking their statuses, but it does not explicitly state when to prefer this over get_campaign or provide exclusions. The scope requirement is useful operational context but does not guide an agent on choosing among the sibling 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 read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: the list is a live snapshot of what the platform can serve right now, prices are in micro-USD, engines are either composed or realtime, and provider degradation causes engines to disappear before failures occur.

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 compact and front-loaded: it starts with the core purpose and pricing, then explains engine composition, then gives the usage rule. Every sentence contributes distinct information without 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 zero-parameter, read-only list tool, the description is remarkably complete. It explains what is returned, the pricing unit, the composed-vs-realtime distinction, the dynamic availability behavior, the recommended usage in the create_agent flow, and the only prerequisite. No output schema exists, but the description provides enough context to call the tool confidently.

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 schema provides 100% coverage by defining an empty object. The description still adds useful context by clarifying that no scope is needed beyond a valid key, which is helpful authentication/scoping 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 identifies a list operation over the engines/models resource, states that it returns what the platform can currently serve, and includes per-unit prices in micro-USD. It also distinguishes itself from the create_agent workflow by saying to call it before create_agent rather than guessing model ids.

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 explicit when-to-use guidance: call this before create_agent instead of guessing model ids. It also explains why this matters—degraded providers disappear from the list before calls start failing—and states the only prerequisite is a valid key.

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 cover read-only, idempotent, and non-destructive behavior. The description adds value beyond annotations by specifying the authorization requirement (scope) and the downstream use of the returned ID in create_agent/update_agent. 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 compact and front-loaded. 'List knowledge bases' states the core action immediately, the next sentence adds a valuable use-case, and the final line covers authorization. Every sentence earns its place with 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?

The description covers purpose, scope, and downstream usage, while the schema handles pagination details. The only gap is the absence of an explicit output shape, but the knowledge_base_id mention partially compensates by signaling what the returned objects contain.

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%: limit, ending_before, and starting_after are each fully described in the input schema. The description adds no parameter-specific 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 opens with 'List knowledge bases', a clear verb and resource. It adds a concrete downstream purpose ('Attach one to an agent with knowledge_base_id on create_agent or update_agent'), which distinguishes it from get_knowledge_base and other list_* siblings by making the output's role 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 clearly indicates the context for using this tool: to retrieve knowledge bases so they can be attached to agents. It also states the required scope ('knowledge_bases:read'). It does not explicitly contrast with get_knowledge_base or list alternatives, but the singular resource makes the use case 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?

There are no annotations, so the description carries the burden of disclosing behavior. It adds value beyond the schema by stating the required `leads:read` scope and calling out cursor pagination. Tis is a read-path tool, and the scope strongly reinforces that, though it does not describe response shape or rate limits.

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 with no filler: one states the operation and filtering modes, the other states pagination and auth requirement. Every clause earns its place and the most decision-relevant information is 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 moderately simple filtered-list tool, the description covers the core operational facts: resource, filterable fields, pagination, and auth scope. With no output schema, an explicit note about the returned lead shape would be a small bonus, but the tool name and list semantics make it reasonably inferable.

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 80%, so the schema already documents most parameter meanings. The description adds only a high-level mapping of tag/search to filtering and cursor-paginated to pagination, without drilling into syntax, constraints, or cursor interplay that the schema already covers.

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 clear verb and resource ('List leads') and characterizes leads as contacts, then adds distinguishing capabilities: filtering by tag or free-text search and cursor pagination. This adequately separates it from singular get_lead and mutation tools like create_lead/update_lead.

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 for when to call this tool – when you need a paginated, filterable list of leads – but it does not explicitly mention when not to use it or point to alternatives such as get_lead for a single record. Usage is implied rather than explicitly routed.

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

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

The description adds meaningfully beyond the annotations: it states that every movement type is included, that balances reconcile exactly, and that the response includes balance_after_micros. These are behavioral details not present in the annotations, and they are consistent with readOnlyHint=true and idempotentHint=true.

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, no wasted words. The core behavioral content is front-loaded, and the scope requirement is clearly stated. Every sentence 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 simple read-only paginated list with well-documented parameters and safety annotations, the description is nearly complete. It describes the returned data field (balance_after_micros) and the universe of entries, though it does not mention ordering, 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?

The input schema already documents all three parameters with 100% coverage, including cursor semantics and limit bounds. The description adds no additional parameter-level meaning, which is acceptable because the schema carries the full burden. 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 identifies the resource (ledger entries) and the action (listing every account movement), and it enumerates the movement types and the balance_after_micros field. However, it does not explicitly differentiate itself from potentially similar siblings like list_usage_events or get_balance, so it misses the full sibling-differentiation quality.

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 this tool should be used instead of alternatives such as list_usage_events or get_balance. The only practical instruction is the required `billing:read` scope, which is a prerequisite, not a usage guideline.

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 signal readOnly/idempotent/non-destructive, and the description adds value by disclosing the required OAuth scope and the specific related entities returned. This goes beyond the structured fields 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 compact sentences: the first states purpose and output scope, the second states auth. No filler or repeated schema details.

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

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

Covers the essential purpose, returned context, auth requirement, and pagination parameters are documented in the schema. It does not describe the response envelope (e.g., next_cursor), but the schema's cursor descriptions and read-only annotations make this 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%, so the limit and cursor parameters are already fully documented. The description adds no additional parameter-level meaning, which is acceptable given the schema carries that burden.

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?

States a specific action ('List the phone numbers registered on this account') and names the resource plus the key related data returned (SIP trunk and agent). It clearly separates this from get_phone_number and the SIP trunk/list tools by its list-level 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 gives clear context: it applies to phone numbers on the current account and lists all of them, which implies it is the right choice for enumeration rather than fetching a single number. It does not explicitly contrast with get_phone_number, so it stops just short of full 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: the returned trunks include platform_ip and origination_uri, and explains how those fields should be used with the carrier. It also states the required OAuth scope, which is useful operational guidance 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 tightly written: the first sentence states the purpose, the second provides practical guidance on the returned fields, and the third gives the required scope. Every sentence earns its place and there is no fluff or repetition of schema details.

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 with three optional, well-documented parameters and safety annotations, the description is complete. It covers the operation, key response fields, carrier configuration implications, and authorization scope. Nothing essential for calling this tool correctly is missing.

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 descriptions for limit, ending_before, and starting_after fully document their semantics, including the mutual exclusion of the two cursors. The tool description does not add parameter-level meaning beyond what the schema already provides, 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 operation ('List the account's SIP trunks') with a specific verb and resource. It naturally distinguishes the list operation from sibling get_sip_trunk and create/update/delete tools, and adds useful context about the key fields each trunk carries.

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 listing the account's SIP trunks and notes the required `sip_trunks:read` scope, giving the agent a concrete prerequisite. It doesn't explicitly name alternatives like get_sip_trunk, but the listing context and sibling names make the intended use evident.

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, idempotent, non-destructive behavior. The description adds valuable context beyond annotations by stating the required scope 'usage:read' and explaining that the sum of a call's events equals the debited amount. No behavioral 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 only two short sentences plus a scope requirement, with the core meaning front-loaded. Every sentence earns its place: the billable-line nature, the session_id use case, the cost-sum invariant, and the required scope.

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 7-optional-parameter list tool with no output schema, the description covers the essential semantics: what is returned, why it matters, and what authorization is needed. It does not describe pagination or response field format, but the schema already documents cursor parameters, and the core intent is clear.

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

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

With 86% schema description coverage, the baseline is already strong. The description adds meaning to the session_id parameter by clarifying it comes from a call record and that summing events for that session reveals the exact debited cost, which goes beyond the schema's minimal field 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 identifies the tool's output as 'Every billable line, itemised' and ties it to call-level cost breakdown via session_id filtering. It conveys the resource and purpose without ambiguity, though it does not explicitly name or contrast any sibling tool such as get_usage_summary.

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 a concrete usage pattern: filter by session_id to see exactly what one call cost and why. It does not explicitly state when not to use this tool or recommend an alternative, but the session_id use case is clear context for when this tool is appropriate.

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

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

The description discloses important side effects beyond the annotations: it explicitly says the tool will hang up in-flight calls and stop placing new ones. It also states the required scope. Annotations already capture idempotency and non-read-only status, so the description adds useful behavioral context without 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 two concise sentences with no filler. The primary action is front-loaded and the permission requirement is stated separately and cleanly.

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 mutation tool, the description covers purpose, behavior, side effects, and authorization. The lack of an output schema is not a major gap because the tool's effect is clearly described and no return value is needed to invoke it 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%, and the input schema already documents the single `id` parameter with a concrete example. The description adds no additional parameter semantics, which is acceptable when the schema already carries the full meaning.

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 clear, specific action: stop placing new calls and hang up any calls the campaign has in flight. This distinguishes pause_campaign from sibling actions like start_campaign or delete_campaign through its behavior rather than merely restating 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 guidance is given about when to use this tool versus alternatives such as start_campaign or delete_campaign. The only context provided is the required scope `campaigns:write`, which is a prerequisite, not a usage recommendation.

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?

Beyond the annotations, the description discloses real-world side effects (money spent, phone rings), credit reservation behavior and the specific insufficient_credits refusal, immediate return status (queued or ringing), and how to track progress via get_call. It also mentions the required calls:write scope. These details go far beyond the bare readOnly/idempotent flags.

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 critical warning (spends money, rings phone, confirm with user) is front-loaded, and every sentence carries necessary safety, prerequisite, or behavior information. It is dense but not padded; a bit of redundancy remains in restating the cost/ringing warning, but the structure is effective for such a consequential 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?

With no output schema, the description fully covers the immediate result (call record with status queued or ringing), how to get progress/transcript/cost (poll get_call), and the failure mode (insufficient_credits). It also gives auth scope and prerequisites. An agent has everything needed to invoke correctly and interpret the response.

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

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

The schema already documents all 7 parameters with 100% coverage, so the baseline is 3. The description adds value by explaining that from_number_id defaults to the agent's outbound_phone_number_id and that the agent_id and from_number_id reference prerequisite resources that must exist. This reinforces parameter relationships rather than just repeating schema text.

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 opens with a specific verb and resource: 'Dial a real phone number over the account's SIP trunk and connect the agent.' This makes the tool's purpose unmistakable and distinguishes it from read-only siblings like get_call and from hangup_call. There is no ambiguity about what action this tool performs.

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

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

The description explicitly warns to confirm with the user before dialing because the action spends money and rings a phone, and it lists prerequisite resources (agent, SIP trunk, phone number) that must already exist. It doesn't name an alternative tool, but since no sibling places outbound calls, the caution and prerequisites provide sufficient decision context.

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

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

Annotations already indicate destructive and non-read-only behavior. The description adds critical context beyond that: immediate effect with no grace period, impact on this MCP server if the key is in use, irreversibility, and the required scope. This fully discloses the behavioral profile for an agent.

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 compact and front-loaded with the most important fact ('Revoke immediately'). Every sentence adds value: immediate effect, consequences, irreversibility, and authentication requirement. No redundant or filler 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?

For a simple one-parameter destructive action, the description is largely complete: it covers timing, side effects, reversibility, and required scope. The main gap is the lack of any note about the response or behavior on an already-revoked key, but given the annotations and simple input, this is a minor omission.

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 single 'id' parameter fully described including an example. The description adds no extra parameter-level meaning, which is acceptable given the high schema coverage, 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 clearly states the action ('Revoke') and the resource ('an API key') with specific behavioral details (immediate, no grace period). However, it does not explicitly differentiate from sibling tools like rotate_api_key, though the verb and irreversibility provide some implicit distinction.

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: for immediate, irrevocable revocation. It mentions the required scope and the consequence that all users of the key will fail. But it does not explicitly state when not to use it or name alternatives like rotate_api_key for key rotation.

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

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

The description adds critical behavioral context beyond the annotations: the old key remains valid for 24 hours, the new secret is returned only once, and the operator must hand it to the user immediately. This is exactly the kind of non-obvious safety and lifecycle behavior an agent needs to know.

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 compact, front-loaded with the core action, and every sentence carries meaningful information: the replacement behavior, the 24-hour overlap, the single-return warning, and the required scope. There is no 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 single-parameter utility, the description covers the action, the grace-period behavior, the one-time return, the permission requirement, and a concrete deployment scenario. The only small gap is that no output schema exists and the description does not specify the exact response shape or property name for the new secret, though it does say the secret is returned once.

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 the single id parameter completely with type, minimum length, and an example. The description provides no extra parameter-specific detail, so based on 100% schema coverage, 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 opens with a specific action and resource: 'Issue a replacement secret.' The detail that the old key keeps working for 24 hours clearly distinguishes rotation from creating a fresh key or revoking immediately, and the required id parameter ties it to an existing API key.

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 a concrete use case: rotating a key during a deploy so there is no service gap. It also names the required permission scope, but it never explicitly says when to choose this over create_api_key or revoke_api_key, leaving that routing to the agent's inference.

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?

Beyond the annotations, the description reveals critical real-world behavior: 'THIS SPENDS MONEY AND MAKES REAL PHONES RING', one call per lead, and the insufficient_credits refusal. It also states the required scope. This gives the agent essential safety-relevant information that annotations alone do not 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 three sentences and every sentence earns its place: the core action, the cost/safety warning, and the error condition plus scope. The key purpose is 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 one-parameter mutation tool with no output schema, the description covers the main things an agent needs: what happens, the real-world side effects, the confirmation prerequisite, a specific failure mode, and the required scope. It doesn't describe the success response shape, but that is not essential for tool selection and 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?

Schema description coverage is 100%, so the baseline applies: the schema documents the single 'id' parameter with an example. The description doesn't add param-specific semantic detail, but the tool's purpose makes clear that 'id' refers to the campaign to start

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 and resource: 'Begin calling every lead on the campaign', clarifying the scope ('every lead') and the action. This distinguishes it clearly from sibling tools like pause_campaign, delete_campaign, or create_campaign.

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 clearly says when to use it: to start calling all leads on a campaign, and it adds an explicit precondition—'confirm with the user before calling it'. It doesn't explicitly name alternatives or when-not-to-use conditions, so it stops short of 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 description discloses critical behavioral traits beyond annotations: it puts traffic on a third party, records an outcome on the trunk, and warns that a negative result is not proof of failure. These are non-obvious side effects and interpretation caveats that annotations do not 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?

Every sentence earns its place: the action, the third-party side effect, the false-negative caveat, the preferred alternative, and the required scope. It is dense but not bloated, and the main action is 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 one-parameter action with no output schema, the description covers the operation, side effects, interpretation guidance, alternative routing, and authorization requirement. Nothing needed to call it correctly is missing.

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 single `id` parameter is fully described in the schema. The description doesn't add parameter-level details, but none are needed; the baseline of 3 applies because the schema carries the burden.

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 ('Send'), resource ('a SIP trunk'), and mechanism ('TCP connect or unauthenticated SIP OPTIONS to the carrier'), and clarifies that it records the outcome on the trunk. This is far more specific than the title and clearly distinguishes the tool's function from status checks.

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

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

It explicitly says 'Prefer check_sip_trunk_status', naming the alternative and signaling that this tool is secondary. It also explains when the result may be misleading (carriers drop unauthenticated probes), giving the agent enough context to decide whether to use it.

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

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

Annotations already flag non-read-only, non-idempotent, non-destructive, and the description adds meaningful nuance: unchanged fields are preserved and sending voice replaces the entire voice object. It also states the required authorization scope. 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?

Three short sentences, each carrying important information: operation, partial-update semantics, voice-replacement behavior, and required scope. No filler or restatement of schema details.

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 input schema and annotations, the description captures the essential non-obvious behaviors needed to invoke the tool correctly: patch semantics, voice object replacement, and authorization. It does not describe the success response, but the absence of an output schema makes that a minor gap rather than a correctness blocker.

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 documents every parameter at 100% coverage, so the baseline is 3. The description adds cross-cutting semantics beyond the schema: omitted fields are left unchanged, and voice is replaced as a whole object rather than merged. This clarifies how the top-level and nested parameters behave.

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?

States a specific operation ('Change an agent') and immediately clarifies the partial-update contract ('Only the fields you send are changed; omit the rest'), which distinguishes it from create_agent and delete_agent. This is more than a tautology of the title.

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 for use: modify an existing agent, send only the fields to change, and the required agents:write scope. It does not explicitly name alternatives such as create_agent/get_agent, but the id requirement and change semantics make the intended use 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?

Annotations already mark the operation as non-read-only, non-destructive, and non-idempotent. The description adds useful behavioral context by stating that only provided fields are changed and that the `appointments:write` scope is required. This 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?

The description is two short sentences with no filler. The core behavior is front-loaded, and the partial-update rule follows immediately. Every sentence 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 9-parameter update tool with no output schema and low schema coverage, the description is too sparse. It does not explain the meaning of many fields, the status transitions, or what happens after the update. While the partial-updateand scope notes are helpful, the overall context is incomplete for correct 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?

Schema description coverage is only 33%, so the description needed to compensate for the undocumented parameters. It broadly hints at 'reschedule' and 'annotate', which maps to date_time and notes, but it does not explain status, lead_id, agent_id, client_name, phone_number, or duration_minutes. This leaves several parameters ambiguous for an agent.

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 and resource: 'Reschedule or annotate an appointment' clearly states what the tool does and distinguishes it from create/delete/get/list siblings. The partial-update clarification ('Only the fields you send are changed') adds concrete 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 gives clear contextual usage: use this tool to reschedule or annotate an existing appointment, and the partial-update note tells the agent how to use it effectively. It does not explicitly mention alternatives or when not to use it, but the purpose is clear enough against sibling 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?

It discloses non-obvious behavior beyond the annotations: partial updates, the full replacement of the faqs list when faqs is sent, and the required authorization scope knowledge_bases:write. These are critical details for safe and correct invocation.

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 short and front-loads the key behavior. However, the first sentence ('Change a knowledge base') mostly restates the title and adds little; the remaining sentences are efficient and valuable.

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 six-parameter mutation with no output schema, it covers the invocation-critical facts: partial update semantics, faqs replacement, and required scope. It does not describe expected return values or errors, but those are less essential for correct selection and calling.

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

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

The schema already documents most parameters (83% coverage), and the description adds important cross-parameter semantics: only sent fields are changed, and sending faqs replaces rather than merges the list. This adds meaning beyond the schema, though it does not describe each parameter individually.

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 and resource ('Change a knowledge base') and immediately clarifies the key semantic: only the fields you send are changed. This clearly distinguishes it from sibling create/delete/get operations on the same 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?

Usage context is implied rather than stated: the name and 'Change' suggest updating an existing knowledge base, but the description gives no explicit when-to-use or when-not-to-use guidance and does not mention alternatives such as create_knowledge_base or delete_knowledge_base.

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

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

The description adds useful behavioral context beyond the annotations: it specifies PATCH-like semantics ("Only the fields you send are changed") and the required auth scope `leads:write`. It does not contradict the annotations, though it does not disclose side effects, error behavior, or idempotency characteristics.

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 with no filler. The core action is front-loaded, the partial-update behavior is immediately relevant, and the auth requirement is stated succinctly. Every sentence 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 simple update tool with five parameters and no output schema, the description covers the essential action, partial-update semantics, and auth requirement. It lacks guidance on error cases, unmodifiable fields, or response behavior, but it is adequate for basic 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 schema already documents `id`, `fields`, and `phone_number`, leaving `name` and `tags` undocumented. The description's partial-update statement adds general parameter semantics but does not compensate for the missing meaning of `name` or `tags`. Overall, it adds some value beyond the schema without fully covering the gaps.

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 and resource — "Change a lead" — which clearly identifies this as the mutation counterpart to get_lead, create_lead, and delete_lead. The partial-update clarification further distinguishes its behavior from a full-overwrite update.

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 is used when an existing lead needs modification, and the required `id` parameter reinforces that. However, it does not explicitly state when to prefer update_lead over create_lead or delete_lead, nor does it mention any exclusions such as immutable fields.

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

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

The description adds behavioral context beyond the all-false annotations by disclosing the scope requirement (`phone_numbers:write`) and the partial-update semantics ('Only the fields you send are changed'). However, it does not describe side effects, return behavior, or idempotency, and the mutation's other consequences remain undisclosed.

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 compact and front-loaded: the core action and partial-update behavior appear first, folowed by the scope requirement. It contains no fluff, though the use of 'label' and 'trunk' instead of the actual parameter names introduces minor ambiguity. Efficient for an agent 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?

For a 5-parameter mutation with no output schema and minimal annotations, the description covers purpose, partial update, and auth, but omits usage boundaries, full parameter list in natural language, and return/error behavior. The sibling list offers related phone-number tasks, but no routing guidance is provided. Adequate but not complete.

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

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

Schema description coverage is only 40%, and the description compensates for the undocumented `name`, `sip_trunk_id`, and `inbound_agent_id` by referring to them as 'label, trunk or inbound agent'. The `id` and `phone_number` are already described in the schema. The description does not clarify that `phone_number` itself is also updatable, but overall it adds meaningful mapping for the otherwise undocumented 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 ('Change') and resource ('a phone number') and enumerates the updatable fields ('label, trunk or inbound agent'). This distinguishes it from same-resource siblings like create_phone_number and delete_phone_number, though it doesn't explicitly contrast with other update_* tools. The title already identifies the resource, so the description adds useful field-level clarity.

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 when-to-use or when-not-to-use guidance is given, and no alternatives are mentioned. The description notes partial-update behavior and the required scope, but an agent must infer from sibling names when to choose update_phone_number versus create_phone_number or update_sip_trunk. There is no explicit exclusion or alternative routing.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description does not contradict them. It adds valuable behavioral detail beyond annotations: the PATCH-like behavior ('Only the fields you send are changed') and the required scope (`sip_trunks:write`), which helps the agent understand auth preconditions and non-destructive partial updates. It does not disclose response behavior, but this is not a contradiction and annotations reduce the burden.

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 carry the essential information: what the tool does, its update semantics, and its auth requirement. Every sentence earns its place, and the core verb-resource meaning is front-loaded. 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 12-parameter mutation tool with no output schema, the description is minimally viable but not rich. It states scope and partial-update semantics, but omits what the caller should expect in return, how errors are surfaced, or any explicit relationship to sibling tools such as get_sip_trunk for resolving ids. The basics are covered, yet an agent would benefit from more operational 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?

The schema covers about 75% of parameters with descriptions, and the description adds a key general semantic: sending only specific fields leaves others unchanged. However, it does not compensate for the three undocumented parameters (username, transport, auth_realm), nor does it add per-parameter meaning beyond the schema. The partial-update sentence is useful, but parameter guidance remains mostly delegated to 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?

Description opens with a clear verb and resource: 'Change a SIP trunk.' It also specifies the update semantics ('Only the fields you send are changed'), which unambiguously distinguishes it from create_sip_trunk, delete_sip_trunk, and get_sip_trunk. The purpose is immediately obvious.

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 is given about when to use this tool instead of alternatives. It never mentions create_sip_trunk for new trunks, delete_sip_trunk for removals, or get_sip_trunk for reading. The context is implied by the verb 'Change,' but exclusions and alternative routes are absent.

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