Patch MCP

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

The annotations already disclose that this is a non-read-only, non-idempotent, open-world, potentially destructive operation. The description adds useful context that the tool uses an existing premium entitlement and default assignments, but it does not explain why destructiveHint is true or what enabling a connector changes or destroys.

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-loaded with the core action, and contains no obvious filler. The second sentence adds relevant entitlement and assignment context without bloating the definition.

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 presence of an output schema means return values need not be described, and annotations cover the safety profile. However, for a write operation with two undocumented parameters and many connector-related siblings, the description is still missing selection guidance, request_id semantics, and an explanation of the destructive hint.

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

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

Schema description coverage is 0%, so the description needs to compensate for undocumented parameters. It clarifies that the provider is currently limited to Exa, but it does not explain what 'provider' means operationally or what 'request_id' is for.

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 clear verb, 'Enable,' and a specific resource, 'a managed common tool (currently Exa web search).' It distinguishes the action from generic connector creation by framing it as enabling a managed common tool, though it does not explicitly name sibling tools such as create_connector or connect_connector.

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

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

The description explains what the tool does but not when to use it versus nearby alternatives like create_connector, connect_connector, or remove_connector. 'Currently Exa web search' gives some scope, but there is no explicit when-to-use or 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 destructiveHint=true and openWorldHint=true, but the description adds two things they don't: the call consumes 'your plan allowance' (a billing consequence) and request_id should be reused after an interrupted response (retry/dedupe semantics). It stops short of explaining what happens to the offer if the claim fails or whether the number can later be released; the idempotentHint=false vs. request_id reuse is a nuance, not a contradiction, since dedupe is keyed on request_id.

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

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

Two sentences, front-loaded with the action and its cost, followed by the retry rule. No filler, nothing repeated from the 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?

An output schema exists and get_number_claim is available for checking state, so return values needn't be described. However, for a destructive, costly, open-world mutation the description omits prerequisites (how to obtain a valid offer_id), failure behavior, and what an interrupted response looks like.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains request_id well as an idempotency key to reuse, but offer_id (where it comes from, its lifecycle) and label (display name, 60-char cap) are left entirely undocumented.

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: 'Acquire an offered number using your plan allowance.' This clearly separates it from read-oriented siblings like get_phone_number, list_numbers, and search_phone_numbers. It does not name a sibling explicitly, so it stops short of a 5.

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

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

The phrase 'Acquire an offered number' implies the use case (an offer exists and you want it), and the retry sentence gives genuine operational guidance. But there is no explicit when-to-use vs. alternatives, no statement of where offer_id comes from (search_phone_numbers / get_number_claim), and no prerequisites.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and non-idempotency, so the safety profile is covered. The description adds useful behavior beyond that: the call may yield an authorizationUrl that should only be opened when consent is required, and that list_connectors is the follow-up probe. It still does not say what state is changed by 'refresh', whether existing tool configs are replaced, or what scopes consent grants.

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 and the action verbs front-loaded, which is good. But the compression goes too far: the first sentence bundles three distinct modes into one clause, and the second references a field name ('authorizationUrl') that never appears in the input schema, leaving the structure cryptic rather than efficient.

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

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

An output schema exists, so return values need not be explained. Still, a destructive, open-world, non-idempotent tool with two undocumented required parameters is not adequately described: the distinction from create_connector versus a refresh/reconnect path, and the meaning of request_id, are both 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 0% for both required parameters, and the description mentions neither connector_id nor the UUID request_id (plausibly an idempotency/correlation key despite idempotentHint=false). With zero compensation from the description, an agent must guess at both parameters' format and role.

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 three loosely-related actions ('discover tools', 'refresh tools', 'begin third-party OAuth') but never defines what 'discover' means concretely, and the name connect_connector does not map cleanly onto any single one. It does not distinguish this from siblings like create_connector, get_connector_tools, or list_connectors, which an agent would need to tell 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?

'Open authorizationUrl only when consent is required, then inspect list_connectors' gives a conditional and a follow-up step, which is real sequencing guidance. However, it says nothing about when to choose this over create_connector or get_connector_tools, and no prerequisites or when-not conditions are stated.

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

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

Annotations already declare destructive=true, openWorld=true, non-idempotent; the description adds real context beyond them by framing this as a redirect to a Stripe-hosted, human-driven flow and warning against handling card data in chat. It does not disclose session lifetime, whether a URL is returned (output schema covers that), or what makes the operation destructive/open-world.

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, purpose first and the security constraint second; every phrase carries decision-relevant information.

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

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

Covers what the tool does and the security posture, and an output schema exists so return values needn't be described. However, for a mutating, open-world billing tool the sole required parameter's semantics and failure/retry behavior (idempotency) are left entirely unstated.

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

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

Schema description coverage is 0% and the single required request_id (uuid format) is never explained in prose. The agent cannot tell whether it is an idempotency key, a trace identifier, or tied to a pending billing action, so the description fails to compensate for the schema 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?

Specific verb (create) plus a concrete resource (Stripe billing portal session) and the outcomes it enables (update payment methods, finish a person-required billing action). It is clearly distinct from siblings like get_billing or update_billing_profile, though it never names those alternatives explicitly.

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?

Gives a clear trigger ('finish a billing action requiring a person') and an explicit prohibition ('never ask the user to paste card details into chat'), which shapes agent behavior. It does not route the agent to or away from siblings such as update_billing_profile or execute_subscription_change, so it stops short of full when/when-not 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 the mutation profile (destructiveHint=true, idempotentHint=false, readOnlyHint=false), so the description needn't restate that. It does add two non-obvious behaviors: empty assignments leave the connector unassigned, and credentials are write-only. It still omits prerequisites such as permission requirements and validation constraints.

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, front-loaded with the core action and zero filler. It is concise, though the brevity contributes to the specification gaps rather than solving them.

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 creation tool with no schema descriptions, this is thin. The output schema covers return values, but the critical conditional auth parameters and their relationships are unexplained, leaving the agent to infer configuration from enums alone.

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

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

Schema description coverage is 0% across 11 parameters (6 required), so the description must carry the load, but it only clarifies assignments and the write-only nature of credentials. It says nothing about the auth model (how authType relates to token, clientId, clientSecret, issuer), transport, headerName, or request_id.

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+resource ('Create a hosted MCP connection'), which is clearer than the bare tool name. However, it does not distinguish this from the sibling tools add_common_connector or connect_connector, so an agent cannot be fully sure which creation path to take.

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?

There is no explicit when-to-use guidance and no reference to the closely related siblings (add_common_connector, connect_connector, remove_connector). The only conditional behavior mentioned is the assignments list, which is a parameter behavior, not a usage-selection rule.

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, openWorldHint=true, and idempotentHint=false, so the safety profile is carried structurally. The description adds one genuinely important non-schema behavior — consent must be explicit user permission and must never be inferred — but says nothing about irreversibility, what happens to the source upload, or any cost/latency.

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 front-loaded sentences with no filler; the consent restriction is stated as a hard rule in the second sentence where it commands attention.

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?

An output schema exists, so return values need not be described, and annotations cover the destructive/open-world profile. What remains thin is the role of 'label' and the idempotency/retry semantics, given a required uuid request_id is undocumented.

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

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

Schema description coverage is 0%, so the description must compensate, and it does partially: it clarifies that the source is an uploaded sample (upload_id) and gives real semantic meaning to the consent const. However, 'label' and 'request_id' are left entirely unexplained, so half the parameters remain opaque.

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 ('Clone an uploaded sample of the user's own voice'), which is clearly distinguishable from siblings like create_voice_upload, verify_voice, and list_voices. It doesn't explicitly name those siblings, so it stops short of a 5.

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

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

The phrase 'uploaded sample' implies a prerequisite upload step, and the consent sentence imposes a precondition, but the description never says when to call this versus create_voice_upload or verify_voice. Usage is inferable rather than stated.

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

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

The annotations already declare destructiveHint=true and idempotentHint=false, so the description is not responsible for basic safety disclosure. It adds useful behavioral context: the upload URL is expiring, the file bytes are PUT to that URL, and a separate create_voice call requires the user's own-voice consent.

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 the core action and next step front-loaded. There is no redundant or filler 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?

Given the output schema and annotations, the description covers the essential workflow and consent requirement. It leaves a gap around the two input parameters, but the main operational sequence an agent must follow is 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 0%, so the description should compensate by explaining filename and request_id. Instead, it does not describe either parameter, their constraints, or how request_id relates to the upload flow.

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 an expiring audio upload URL.' It also clarifies the relationship to the sibling tool create_voice, so an agent can distinguish this preparatory upload step from the actual voice-creation step.

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 clear usage workflow: create the URL, PUT file bytes, then call create_voice with the upload_id and consent. It does not state when not to use this tool or list alternative paths, but the sequencing with create_voice is 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 flag destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description earns credit for disclosing a real side effect beyond the obvious one — that provider-side samples are also deleted — and for stating the active-call precondition, which 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?

Two short sentences, the destructive scope front-loaded and the constraint second. Every sentence carries information and nothing is 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?

Return values need not be explained since an output schema exists, and the destructive/blast-radius picture is decent. However, for a permanently destructive operation with two fully undocumented required parameters, the description should say what request_id is for and whether a failed delete (voice in active call) leaves anything changed.

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

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

Schema description coverage is 0% and neither required parameter is mentioned. The meaning of voice_id is inferable, but request_id (a UUID request token) is completely unexplained — especially notable given idempotentHint=false, since an agent cannot tell whether request_id provides idempotency or is purely for tracing.

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+resource ('Delete your voice clone') and adds the scope detail that provider samples are removed too. It does not explicitly distinguish itself from rename_voice or create_voice, but the operation is unambiguous from the name plus description.

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 precondition ('A voice in an active call cannot be deleted') rather than guidance on when to choose this over alternatives such as rename_voice. Usage is implied by the verb but there is no explicit when/when-not framing or routing to 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?

With destructiveHint=true already declared, the description still adds real value: it says exactly what is destroyed (unpublished settings) and what state results (published version, or defaults if never published). That is the key outcome an agent needs before a destructive call. It does not mention auth requirements or whether the discard can be undone.

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

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

A single front-loaded sentence with no filler; the destructive outcome is stated first and the fallback case second. Every clause 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?

The output schema being present means return values need no explanation, and annotations cover the safety profile. However, three required parameters with zero schema descriptions and no parameter guidance in the description leaves an agent unable to confidently construct the call, which is a real gap for a destructive 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 description coverage is 0% across all three required parameters, so the description carries the full burden and does not compensate meaningfully. It never explains what number_id identifies, why direction (inbound/outbound) is needed to discard a draft, or what role revision plays. Only the notion of a 'published version' loosely gestures at revision.

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 pair: discard unpublished settings, restoring the published version or defaults. That is more precise than the tool name alone and implies the agent-draft resource. It does not differentiate itself from the similarly destructive sibling reset_agent, nor does it name the agent explicitly.

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 it (when a draft exists and should be thrown away), but never states preconditions, when NOT to use it, or the alternative of reset_agent, which is the closest sibling. An agent must infer the choice.

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 this as destructive and idempotent, yet the description adds real substance: the disconnect is implemented by deleting the LiveKit room, a spoken farewell is not guaranteed, transcripts are retained, and resolution is extracted separately. These are exactly the consequences an agent needs before a destructive call.

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?

Front-loaded with the action and mechanism, then usage, then verification. Four short sentences with little waste, though the transcript/resolution note is somewhat tangential to invoking the 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 one-parameter destructive mutation with annotations and an output schema, the description covers action, side effects, retention semantics, verification path, and trigger conditions. Nothing an agent needs to call it safely 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 single call_id parameter has 100% schema coverage with a description tying it to place_call, so the schema does the work. The prose adds no further parameter detail, making the baseline 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?

States a specific verb and resource ("End an in-progress call early") and immediately discloses the mechanism (deleting the LiveKit room), which clearly separates it from place_call and get_call in the sibling list.

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

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

Gives an explicit trigger ("Use when the user changes their mind or the call is no longer needed") and routes the agent to get_call to verify the resulting status. It stops short of naming an alternative action or a when-not condition, but the usage 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?

Annotations only flag destructiveHint=true and idempotentHint=false; the description adds that a saved payment method may actually be charged and that request_id is the retry key for lost responses, which materially clarifies the non-idempotent hint. It stops short of stating permission requirements or the full side effects of the charge (refunds, partial failure behavior).

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 tight sentences, front-loaded with the action and the biggest risk (charging a payment method). Every clause carries operational meaning; nothing is 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?

An output schema exists so return values need not be described, and the description covers the mutation risk, retry semantics, and the interactive-link outcome. Given a money-moving destructive operation, it could still say more about auth requirements or what a failed/duplicate execution returns.

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

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

Schema description coverage is 0%, so the description must carry the burden. It explains request_id's retry role, which is genuinely useful, but quote_id is only characterized indirectly as 'an authorized quote' with no format, provenance, or expiry guidance.

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+resource: 'Execute an authorized quote', which is concrete and distinguishable from the sibling preview_subscription_change (preview vs. execute). It does not explicitly name that sibling as the alternative, so it falls short of a 5.

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

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

Gives real operating guidance: reuse the same request_id after a lost response, and expect a payment/authentication link when interaction is required. It implies the precondition (an already-authorized quote) but never states explicitly when to prefer preview_subscription_change or what to do when no authorized quote exists.

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, non-destructive and closed-world, so the safety burdern is carried. The description adds that the result is scoped to the caller's own account ('your profile') and enumerates the data domains returned, which is useful context 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?

Two short sentences, no filler, with the read scope front-loaded and the alternative tool named second. Every clause 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?

A zero-parameter read tool with full annotation coverage and an output schema needs only to state what it reads and where to go for writes — both are present. Nothing an agent needs to invoke 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?

Zero parameters, so the schema imposes nothing to explain; baseline 4 applies. The description correctly says nothing about arguments rather than inventing any.

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?

A specific verb ('Read') plus an enumerated resource set (profile, caller verification, revision, account defaults) tells the agent exactly what this returns. It is distinguishable from get_billing/get_capabilities by the listed contents, though those siblings are never named.

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?

'Use update_account to change them' explicitly routes the mutation case to the correct alternative, which is the main confusion risk for a get/update pair. There are no explicit when-not conditions beyond that, but the read-vs-write split is fully covered.

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, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful content on what is returned (draft, published settings, revision), but does not add further behavioral context such as error behavior or permission requirements.

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

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

A single front-loaded sentence with no wasted words. It is appropriately sized for a simple getter.

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?

An output schema exists, so return values need not be explained. However, given 0% schema description coverage, the description leaves key parameter meaning (especially number_id) undocumented for an agent to call 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 0%, so the description must compensate. It only indirectly conveys that 'direction' refers to 'inbound or outbound'; it says nothing about what 'number_id' means or the relationship between the two parameters.

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

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

States a specific verb and resource: 'Read the draft, published settings and revision' for an agent. This clearly distinguishes it from mutation siblings like update_agent or publish_agent, though it does not explicitly name alternatives such as list_agents.

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

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

No guidance on when to use this versus list_agents, get_agent_test, or other read siblings. The phrase 'inbound or outbound agent' implies scope, but there are no explicit usage conditions or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is fully covered elsewhere. The description adds that a transcript and its expiry are returned, hinting that transcripts are time-limited, but says nothing about what happens when a transcript has expired or the test is still running.

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?

One front-loaded sentence with no filler; the enumerated return fields are the right lead information for a read 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?

An output schema exists, so return shape need not be described, and annotations cover the safety profile. What's missing for a test-status reader is lifecycle context: the relationship to start_agent_test/stop_agent_test and what the caller sees before or after transcript expiry.

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

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

Schema description coverage is 0% and the description never mentions the sole parameter, test_id. It is a self-explanatory identifier, but the description does not state where the id comes from (start_agent_test / list_test_scenarios) or the 200-character constraint, so it does not compensate for the coverage 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?

States a specific verb ('Read') plus the resource ('a synthetic test') and enumerates what is retrieved: status, transcript, result and transcript expiry. It is clearly distinguishable from list_test_scenarios or start_agent_test, though it does not differentiate itself from the close sibling get_agent_test_listener.

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?

There is no guidance on when to use this versus get_agent_test_listener or list_test_scenarios, nor any mention of prerequisites such as the test being started by start_agent_test. Usage is only implicit in the noun 'test' and the verb 'Read'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description earns credit by adding substance annotations cannot convey: the credential is short-lived and subscribe-only, tightly limiting what the caller can do with it. It stops short of stating expiry length or failure behavior when the test is not running.

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?

One sentence with no waste; the key qualifiers (short-lived, subscribe-only, running test) are packed in and front-loaded so an agent can decide 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?

An output schema exists, so return structure need not be explained, and the description adequately frames what the tool produces. The remaining gap is operational: nothing about credential lifetime, what a 'compatible client' means, or the failure mode when the test has ended.

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 0%, so the single test_id parameter carries no documentation in the schema itself. The description only indirectly signals that the parameter identifies 'your running synthetic test'; it gives no format, length, or source guidance for the ID. That is a marginal addition over field naming alone.

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 ('Get') and a precisely scoped resource ('a short-lived, subscribe-only LiveKit credential'), and pins the target to a running synthetic test. That resource distinction separates it from the parallel get_call_listener sibling, though the alternative is never named outright.

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 'your running synthetic test' implies the prerequisite that a test must be active, and 'from a compatible client' hints at consumer requirements. However, it never states explicitly when to call this versus get_agent_test or get_call_listener, nor what to do if no test is running.

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/non-destructive, so the description only needed to add context, and it does: 'Reconciles subscription state with Stripe' tells the agent the call reaches a live external system and returns authoritative state, which aligns with openWorldHint. Auth or rate-limit behavior is not mentioned, keeping it short of a 5.

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

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

Two sentences, front-loaded with the resource list, then the reconciliation behavior and the cursor guidance. No filler and nothing buried.

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?

An output schema exists, so return values need no explanation; the description covers scope, freshness/reconciliation semantics, and pagination. The remaining gap is any prerequisite or account/permission context before calling, which is minor for a read-only 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 description coverage is 0%, so the description must carry the single optional parameter, and it does clarify the intended use ('for older invoices'). It does not say the cursor is an opaque token returned from a prior response or what happens when it is omitted/exhausted, so it only partially compensates.

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?

Specific verb ('Read') followed by an enumerated resource set: plans, usage, subscription state, payment-method summary, invoices. That enumeration is clearly distinguishable from the mutation siblings (update_billing_profile, execute_subscription_change, create_billing_portal) without opening any schema.

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 only usage guidance is 'use invoice_cursor for older invoices', which explains one parameter's purpose rather than when to pick this tool over siblings. There is no statement about when this is not the right tool (e.g., that changing a plan requires execute_subscription_change or preview_subscription_change).

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 a safe, non-destructive, closed-world read, and the description adds substantial context beyond them: resolution lagging terminal status by seconds, private recording links expiring after ~1 hour and needing the OAuth header on staging, public calls returning token-free URLs, recording_status=processing meaning separate finalization, and that a recording can fail or be unavailable. These are genuine operational traits, not restatements of the hints.

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 lead sentence is well front-loaded, but the body is a dense ~250-word block that mixes usage rules, status enums, return-field explanations, and recording caveats without paragraph structure. Much of it earns its place, but several clauses (locale/language/voice/is_public, recording_url expiry repeated twice) could be trimmed, especially since an output schema exists.

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 polling tool on a live telephony call, nothing an agent needs to call or interpret the result is missing: terminal status semantics, the meaning of 'rejected' and 'unknown', resolution shape and what to read first, and the recording finalization path are all covered alongside a full output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by framing wait_seconds as a server-side hold that returns early on any status change and by stating the default returns instantly — value the schema's one-line note does not convey. call_id is only restated as 'the id returned by place_call', which the schema already says.

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?

Opens with a specific verb+resource ('Get the status ... structured resolution of a call') and ties the resource to its creator ('started with place_call'), so an agent knows exactly which object this addresses. It also enumerates terminal statuses, making the scope concrete rather than abstract.

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?

Gives clear operational when-to guidance: default instant check, pass wait_seconds to long-poll instead of repeatedly round-tripping, re-call or long-poll to wait on recording state, and do NOT retry when ended_by='user'. It explicitly routes set_call_visibility usage ('only when the user explicitly asks'). However it never distinguishes itself from the nearby siblings get_call_diagnostics and get_call_listener, which an agent could plausibly confuse with this tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds a real behavioral fact not in any structured field: diagnostics are private to the owner and cannot be reached via public visibility. It stops short of describing pagination behavior for cursor/limit, which matters for a multi-page read.

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, each earning its place, with the core purpose front-loaded before the access caveat.

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?

An output schema exists, so return values need no explanation, and the ownership rule is covered. However, for a paginated read with three required parameters at 0% schema description coverage, the absence of any cursor/limit guidance leaves a real gap 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 0%, so the description carries the full burden, yet it only hints at call_id via 'owned call'. The cursor and limit parameters (including the '0'-based cursor pattern and 1000 max) are left entirely unexplained beyond raw 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?

States a specific verb and resource ('Read private diagnostic events') scoped to 'an owned call', which distinguishes it from generic reads like get_call. It does not explicitly name a sibling such as get_call or get_call_listener, so the differentiation is implied rather than stated.

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 only guidance is an access rule ('Public call visibility never grants access to diagnostics'), which tells the agent a precondition but not when to pick this over get_call or get_call_listener. No alternatives, no exclusions, no usage context are given.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds real behavioral context beyond them: the credential is short-lived (expiry implied) and subscribe-only (cannot publish audio), which materially shapes how a client must use it. It stops short of stating actual lifetime or 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?

One sentence, front-loaded with the key qualifiers ('short-lived, subscribe-only') and no filler. Everything stated 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?

An output schema exists so return values needn't be explained, and annotations cover the safety profile. The description covers what the credential is and its limits; only the token lifetime/transport detail is left implicit for a credential-minting 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 description coverage is 0% for the single required call_id, so the description carries the burden. It does not explain the parameter at all, but 'call_id' is self-evident and the only input, keeping the gap small. A 3 reflects minimal compensation for an unambiguous param.

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?

Specific verb+resource: 'Get a short-lived, subscribe-only LiveKit credential' for 'listening to your active call'. An agent can tell this apart from get_call (fetches call data) and get_agent_test_listener (test-scoped listener), though it doesn't name those siblings explicitly.

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?

Implies the use case ('listening to your active call from a compatible client') but gives no explicit when/when-not or named alternative. An agent must infer that this is a pre-step for connecting a monitoring client rather than fetching call records.

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, closed-world behavior, so the description only needs to add context beyond that. It adds that the response covers granted permissions and feature prerequisites, which shapes how an agent should interpret the output, though it does not discuss limits or authentication.

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?

It is a single front-loaded sentence with zero filler. 'Start here' appears first, which is exactly the right emphasis for a discovery 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 zero-parameter discovery tool with full annotations and an output schema, the description supplies everything an agent needs: the entry-point role, the categories of information returned, and the fact that it recommends next tools.

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 takes zero parameters, so the baseline score is 4. No parameter guidance is needed or missing.

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

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

The description explicitly states the tool's job as discovering Patch actions, granted permissions, feature prerequisites, and next tools. The 'Start here' framing distinguishes it from every sibling action tool in the list.

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 'Start here' strongly signals that this is the entry-point tool and should be used before selecting further tools. It stops short of naming when not to use it or listing alternative discovery tools, which keeps it from 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description is not carrying the safety burden alone. It still adds genuinely useful scope information beyond the annotations: no external actions are invoked and no credentials are returned, which tells the agent what this read will not surface.

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-loaded with the action and scope, with the second sentence delivering a non-obvious negative constraint. Nothing is wasted.

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?

An output schema exists, so return-value detail is not required, and the annotations cover the safety profile. The only real gap is where connector_id comes from, which is minor for a one-parameter 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 description coverage is 0% for the single required connector_id, so the description must compensate. 'Owned external connection' does narrow the semantics (a connector belonging to this account) but gives no format, source, or lookup guidance for the ID.

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 ('Read') and a specific resource ('tool catalog of an owned external connection'), which clearly separates it from sibling mutations like create_connector or remove_connector. It stops short of explicitly contrasting with list_connectors, so an agent must infer the distinction between listing connectors and reading one connector's catalog.

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 'of an owned external connection' implies a prerequisite (the connector must already exist and be owned), but the description never says when to call this versus list_connectors or get_capabilities, nor how to obtain a valid connector_id. Usage is inferable rather than stated.

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

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

The description frames the tool purely as advisory retrieval ("Suggest...", "Carrier lookups are cached for a day"), yet annotations declare readOnlyHint=false and destructiveHint=true. Nothing in the text discloses what could be destroyed, what auth or verification is required, or why a lookup is destructive — the agent would reasonably treat this as a safe read. This is an annotation 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?

Two short sentences with the action front-loaded and the caching caveat second. The caching sentence is relevant but hangs without explaining whether a stale result is acceptable or how it affects retries.

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?

An output schema exists, so return values need not be described, but for a tool marked destructive with no parameters the description should still cover preconditions (number verified/claimed), side effects, and how it differs from get_forwarding_instructions. None of that is 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?

The tool takes zero parameters, so there is no parameter semantics burden; the schema already makes the empty input explicit. The phrase "the verified personal number" usefully confirms the target is inferred from account state rather than passed in.

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 first sentence gives a specific verb and resource ("suggest forwarding instructions") scoped to a specific object ("the verified personal number") and context ("inbound onboarding"). However, it never distinguishes itself from the very close sibling get_forwarding_instructions, leaving the agent to guess which one returns carrier-specific suggestions.

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 only usage cue is the phrase "during inbound onboarding," which hints at timing but states no when-to-use, when-not-to-use, or prerequisite (e.g. whether the number must already be verified/claimed). No alternative is named even though get_forwarding_instructions and get_phone_number_settings are obvious candidates for confusion.

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 the safety profile is covered. The description adds genuinely non-obvious behavioral context: the returned instructions must be executed by the user or carrier, and Patch cannot perform activation remotely, which prevents the agent from promising an automated result.

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 tight sentences with zero filler: the first states what is returned, the second states the critical constraint. Front-loaded and appropriately sized for the tool's simplicity.

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?

An output schema exists, so return value detail is not needed, and the key constraint (no remote activation) is disclosed. Still, for a 3-parameter tool with no schema descriptions, the description omits what 'mode' selects and whether 'number_id' is the Patch number or the existing carrier number, which materially affects 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 0%, so the description must carry the parameter burden and it largely does not. 'Carrier-specific' loosely hints at the provider parameter, but neither 'mode' (missed vs. all) nor 'number_id' is explained, leaving the most consequential enum undocumented.

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 ('Get carrier-specific steps for forwarding an existing phone to an owned Patch number') and makes the outcome concrete. It does not explicitly distinguish itself from close siblings like get_forwarding_carrier, so it stops short of a 5.

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

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

Usage is implied by the scenario ('forwarding an existing phone to an owned Patch number'), and the note that Patch cannot activate forwarding tells the agent this is an informational step, not an action. However, no sibling is named and there is no explicit when-not guidance relative to get_forwarding_carrier or update_phone_number.

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 declare readOnly, idempotent, non-destructive, and non-openWorld, so the safety profile is covered. The description's only addition is that this reads progress of an ongoing provisioning process rather than the claim's final state — useful framing, but it omits whether the claim is eventually consistent, how long provisioning takes, or whether repeated polling is expected.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though the terseness is closer to under-specification than to disciplined brevity.

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

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

The output schema covers return values, so that need not be explained. But for an async-progress tool the agent still needs to know the claim_id source, whether progress is terminal at some point, and whether to poll again — none of which this one-liner supplies.

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

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

Schema description coverage is 0% for the single parameter claim_id, and the description offers nothing about where that identifier comes from (presumably the response of claim_phone_number) or its format. With only one parameter at zero coverage, the description should have closed that gap and does not.

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?

"Read provisioning progress for a number claim" gives a specific verb (Read) and a specific resource (provisioning progress of a claim), which is more precise than a generic 'get claim'. It does not, however, distinguish itself from adjacent polling/inspection siblings such as get_operation or get_phone_number, so an agent must infer the boundary.

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?

There is no explicit statement of when to call this versus claim_phone_number, get_operation, or get_phone_number. The word 'progress' hints at post-claim polling, but no trigger condition, prerequisite (does the claim_id come from claim_phone_number?), or stopping condition is given.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description is consistent and adds the content categories read, but it does not add behavioral context such as permissions, rate limits, or how notices are produced.

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

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

The description is a single front-loaded sentence with no wasted words. It states the operation and the returned categories efficiently.

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

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

Given the zero-parameter schema, rich read-only annotations, and an output schema, the short description covers the essential scope of the tool. The main missing element is guidance on when to choose it over related account or onboarding tools.

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

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

The tool has zero parameters, so there is no parameter semantics for the description to compensate for. The empty schema is fully self-explanatory, making the baseline score 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, "Read," and names the onboarding resources returned: setup progress, prerequisites, and account notices. It implicitly distinguishes the read tool from the sibling set_onboarding, though it does not explicitly name that alternative.

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 only lists what the tool reads. It gives no explicit guidance on when to call it, when not to call it, or how it differs from related tools such as get_account or set_onboarding.

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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: that ID reuse is mandatory, and that re-submitting a running or needs_attention operation under a new ID is an error. It stops short of saying what is returned for in-progress operations, though an output schema 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?

Two sentences, roughly twenty words, with the core action first and the constraint second. Every clause earns its place and nothing is padded.

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?

Return values are covered by the output schema, and the safety profile by the annotations, so the description only needed to add the ID-reuse constraint, which it does. It is slightly incomplete in not covering the in-progress case or the error behavior when an operation is still running.

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

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

Schema description coverage is 0%, so the description has to carry the weight, and the phrase 'must not be retried under a new ID' meaningfully constrains operation_id to the existing ID rather than a freshly generated one. It adds real semantics over a bare 'operation_id: string' property, though it does not describe the expected ID format.

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 verb 'Recover' plus the resource 'a request's durable outcome' is specific and names the retrieval of a completed operation's result. It is not, however, explicitly distinguished from the sibling resume_operation, which an agent could easily confuse with this one given that both concern operations in flight.

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 clause 'must not be retried under a new ID' implies that this tool is the way to check on an operation that was already started and to poll an existing ID rather than re-issuing work. There is no explicit statement of when to call it versus resume_operation, and no mention of what to do while the operation is still running.

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/destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: resolution of the default outbound number only when the phone workspace is enabled, and that the resolved number may be a verified personal caller ID or an owned Patch number.

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 sentences, each load-bearing: the first defines the return, the second explains workspace-dependent resolution, the third routes to the alternative and precludes misuse. Front-loaded with the core purpose.

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

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

An output schema exists, so return values need not be enumerated, yet the key fields are named. Annotations carry the safety profile and the description covers workspace-conditional behavior, leaving no gap an agent would need to call 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 tool takes zero parameters and the description confirms this ('Takes no arguments'), matching the empty schema with additionalProperties=false. Nothing further is needed.

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 ('Get the phone number connected to the authenticated user's account') plus the output shape (E.164 format, caller_id_status, source_number_id). This clearly separates it from list_phone_numbers, which it names explicitly.

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?

Explicitly routes the agent to list_phone_numbers when it needs the set of available sources, and the closing clause 'does not place a call' implicitly rules out use where a call is intended. No guidance versus get_phone_number_settings or get_number_claim, but the primary alternative is covered.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds useful scope by naming revisions and recovery deadlines, but does not discuss permissions, rate limits, or error behavior beyond what annotations cover.

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

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

A single, front-loaded sentence that is appropriately sized and free of filler. It could be slightly improved by adding the sibling distinction, but it is efficient as written.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a getter with a required identifier, the description lacks guidance on when to use it versus its close siblings, leaving the selection context incomplete.

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

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

There is one required parameter (number_id) with 0% schema description coverage, so the description should explain its meaning. It only implies the tool reads settings for a number, without clarifying that number_id identifies the phone number or its format, leaving a meaningful 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?

States a specific verb ('Read') and resource ('number settings'), and enumerates the content returned (revisions, recovery deadlines, workspace revision). It does not explicitly differentiate from near-siblings like get_phone_number or list_numbers, so it falls short of a 5.

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

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

Usage is implied by 'Read number settings' rather than stated. There is no explicit guidance on when to choose this over get_phone_number, update_phone_number, or list_numbers, leaving the agent to infer the distinction.

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/non-destructive, so safety is covered. The description adds genuinely new behavioral context: the returned URL is 'short-lived' (an expiration trait nothing else conveys) and the reason catalog voices don't need this call. It does not state what happens if a catalog ID is passed, but the essential behavior is disclosed.

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

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

Two short sentences, zero filler, with the delivery guarantee front-loaded and the exclusion second. Nothing could be cut without losing information.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description supplies the temporal caveat and the main usage boundary; only the undefined 'Claudia' term and the lack of voice_id sourcing guidance keep it from 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?

Schema coverage is 0%, so the description must carry the load for voice_id. It does constrain the domain ('owned voice provider ID or Claudia', implicitly excluding catalog IDs), which is meaningful, but never gives format, allowed values, or where to obtain the ID, so compensation is only partial.

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?

Specific verb+resource: 'Get a short-lived playable URL' for a voice identifier. It also distinguishes this from the catalog-voice path by noting built-in catalog voices already carry sample URLs. The only ambiguity is the term 'Claudia', which is undefined jargon an agent may not recognize.

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 sentence 'Built-in catalog voices already include sample URLs' functions as an explicit when-not-to-use rule, steering the agent away from calling this for catalog voices. It stops short of naming a specific alternative sibling (e.g. list_voices) or stating prerequisites for an 'owned' voice.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the one non-obvious behavioral fact — that real calls and synthetic tests are interleaved in one feed — but says nothing about ordering, page size behavior, or how cursor traversal works.

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

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

A single front-loaded sentence with no filler, and the key differentiator (combined sources) appears immediately. Its brevity is close to under-specification, but nothing in it is wasted.

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?

An output schema exists so return shape needn't be explained, but for a paginated list tool with two fully undocumented parameters the description is too thin. It omits ordering/timeliness of the timeline and the pagination contract, which an agent needs to call 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 0%, so neither 'limit' (required, 1-100, default 20) nor 'cursor' carries any documentation. The description does not mention either parameter, leaving the agent to guess that this is a paginated feed and that cursor is opaque and returned from a prior page.

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 gives a specific verb (read) and a precise resource (the combined real-call and synthetic-test timeline), which is more informative than the bare name 'list_activity'. It implicitly separates itself from list_calls and list_test_scenarios by stressing that both sources are merged, but it never names those siblings explicitly.

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?

There is no statement of when to choose this merged timeline versus list_calls or list_test_scenarios, and no prerequisites or exclusions. The agent must infer the routing decision from the word 'combined' alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description's only additional behavioral content is the inbound/outbound scope, with nothing about ordering, pagination, or completeness of results; with an output schema present, return format doesn't need restating, so a 3 is fair.

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?

One sentence, front-loaded, with zero filler. The only quibble is the verb 'Find', which reads slightly odd for a list operation and costs a moment of interpretation.

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 parameters, an output schema, and annotations that cover safety and idempotency, the description supplies the one thing structure cannot: the scope of agents returned. It falls short only on how this relates to the single-agent sibling, which is the main remaining decision point for an agent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is empty and fully closed (additionalProperties: false). Baseline 4 applies, since no parameter semantics could be added beyond what exists.

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 the resource (agents) and what the caller gets back (identifiers and revisions), and adds a scope qualifier ('inbound and outbound') that the bare name does not convey. It does not distinguish itself from the sibling get_agent, which fetches a single agent, so an agent must infer the plural/singular division itself.

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 only implied: 'Find the identifiers' hints that this is a discovery step that produces IDs for get_agent or update_agent, but the description never says when to use it versus get_agent, nor whether inbound/outbound can be filtered. No explicit exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the useful scoping fact that results are account-level app grants rather than agent tools, but says nothing about result size, pagination, or whether revoked apps appear — minor gaps given the rich annotations and output schema.

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, zero filler, with the core purpose front-loaded and the disambiguation immediately following. Nothing is redundant with the title or annotations.

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 with an output schema and full annotation coverage, the description plus structured data give the agent everything needed to invoke it. The only material omission is the relationship to revoke_authorized_app, which would help in a revoke-after-list workflow.

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 takes no parameters, so the baseline is 4. Nothing in the description is needed to explain input semantics, and it correctly avoids inventing filter options that do not exist.

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+resource ("List applications authorized to access this account") so the agent knows exactly what is returned. The second sentence attempts to distinguish it from the connector family, but the phrasing "external tools used by voice agents" is loose enough that it only partly disambiguates from siblings like list_connectors.

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 by the verb (read-only inventory of account-level app authorizations), and the contrast sentence hints at when to prefer this over connector tools. However, it never names an alternative tool explicitly or states a when-not condition, and it does not mention that revoke_authorized_app is the paired mutation.

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/non-destructive, so the safety profile is covered; the description adds genuinely new behavior: ordering (newest first), cursor round-tripping, next_cursor being null at the end, and the limit default. No contradiction with annotations, though it says nothing about rate limits or empty-result behavior.

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?

Purpose is front-loaded in the first sentence, followed by use cases and then pagination mechanics. Slightly redundant with the schema on 'limit defaults to 20 (1–100)' and 'omit cursor', but no padding sentences overall.

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 two-param paged read with an output schema and safety annotations already in place, the description covers purpose, ordering, pagination lifecycle, and defaults. Nothing an agent needs 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%, so baseline is 3. The description goes beyond the schema by explaining the cursor contract in operational terms: pass the returned next_cursor as cursor, null means no older calls, omit to start at the newest — context the schema's one-liners only partially convey.

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 ('List the authenticated user's recent calls'), plus ordering ('newest first') and payload contents ('statuses and outcomes'). It reads clearly as a paged list distinct from the single-call get_call, but it never names a sibling or spells out the boundary against list_activity.

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?

'Useful to recover a lost call_id or review call history' gives concrete triggering scenarios, which is more than most list tools offer. It stops short of exclusions or naming an alternative tool for cases this one does not cover.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description contributes one useful behavioral fact, that results carry authorization and entitlement state, but says nothing about scope limits, pagination, or what a connector entry looks like beyond that.

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?

One front-loaded sentence with no filler, and the scope-defining clause comes first. Slightly dense phrasing ('available common tools') costs a point on clarity but not on length.

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 parameters, full annotation coverage, and an output schema that documents the return shape, the description needs only to state what is listed and that auth/entitlement state is included, which it does. Only the missing sibling differentiation keeps it from a 5.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is complete and closed. Baseline 4 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 verb 'List' and the resource 'external connections and available common tools' are specific, and the phrase about authorization and entitlement state signals scope. It stops short of distinguishing itself from close siblings such as get_connector_tools or list_authorized_apps, so an agent must infer which listing it needs.

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 only implied: an agent can guess this is the discovery call for connectors and their auth status. There is no explicit when-to-use, when-not, or pointer to get_connector_tools for per-connector tool details, so routing between the connector-family siblings is 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 read-only, idempotent, closed-world, non-destructive, so the safety profile is covered. The description contributes one genuinely new behavioral fact: agent settings are omitted from the response, i.e. a redaction/filtering trait. It says nothing further about result shape or scope, which keeps it at an adequate-but-thin level.

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

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

A single short sentence with no filler and the key caveat placed at the end where it reads naturally. It is efficient, though it errs toward under-specification rather than maximum information density.

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 zero parameters, full annotation coverage, and an output schema handling return values, the description need not say much. The one remaining gap an agent needs filled—disambiguation from the several nearby number/phone-number tools—is not addressed.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No misleading parameter claims are made.

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?

"List your numbers and routing" gives a verb and a resource, but "numbers" and "routing" are ambiguous given siblings named list_phone_numbers, get_phone_number, and get_phone_number_settings. Nothing in the sentence tells an agent how this list differs from those, so the purpose is only loosely graspable.

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?

There is no statement of when to use this over list_phone_numbers or get_phone_number_settings, nor any prerequisite or exclusion. The only hint is a negative constraint ("without exposing agent settings"), which does not route the agent between alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: it discloses that each entry carries direction availability, publication state, and default-outbound marking, which tells the agent what it can filter on client-side.

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 filler, with the resource scope front-loaded and the cross-tool usage hint trailing. Every clause 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?

An output schema exists, so return-value detail is not required, and the description still names the salient fields. For a zero-parameter read tool with full annotation coverage this is nearly complete; only the missing sibling differentiation keeps it from a 5.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description misrepresents the input surface, and the mention of source_number_id correctly frames it as an output field consumed by place_call rather than an input here.

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 ('List this account's phone numbers') and enumerates the notable fields returned (direction availability, publication, default outbound number). However, it never distinguishes itself from close siblings like list_numbers, search_phone_numbers, or get_phone_number, so an agent cannot arbitrate among them from the description alone.

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 second sentence gives a genuine downstream workflow hint — use the returned source_number_id with place_call for an enabled, published outbound number. But there is no guidance on when to pick this over list_numbers or search_phone_numbers, which is the primary ambiguity an agent faces here.

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, non-destructive, and closed-world behavior. The description adds useful context beyond that: scenarios are synthetic, use fictional data, and never invoke connected external tools, which clarifies what 'test' means in this environment.

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-loaded with what is listed and followed by the key caveat. 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 zero-parameter list tool with an output schema and strong annotations, the description covers what is important: the synthetic nature of the data and the fact that external tools are not invoked. It could be slightly more complete by routing the agent toward start_agent_test, but 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?

The tool takes no parameters, so the baseline is 4. Schema description coverage is also 100%, leaving nothing for the description to compensate for.

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: listing synthetic test scenarios and available responder outcomes. It is clear what the tool returns and that the data is fictional, though it does not explicitly contrast itself with sibling test tools like start_agent_test or get_agent_test.

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

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

Usage is only implied: an agent can infer this is a discovery tool for test scenarios before starting a test. There is no explicit when-to-use guidance, no named alternatives, and no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds useful scope detail (preview URLs, owned clones, clone limit) that hints at an account-scoped read, but says nothing about pagination, sorting, or whether unowned/public voices are included.

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

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

A single front-loaded sentence that enumerates the returned categories in a scannable order. No filler, no redundancy with the schema or annotations.

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 zero parameters, full annotation coverage, and an output schema present, the description only needs to frame what the call is for. It does that adequately, though a hint about how it relates to voice creation/preview flows would close the remaining 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 tool takes no parameters, so the baseline is 4; nothing in the schema needs explanation and the description introduces no parameter claims to validate.

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?

A specific verb (List) plus a precise enumeration of what comes back: supported languages, built-in voices with preview URLs, owned clones, and the clone limit. An agent can tell this is an inventory call rather than a mutation. It does not explicitly distinguish itself from get_voice_preview or get_capabilities, which keeps it below a 5.

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

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

The description says what is returned but never states when to call it versus siblings such as get_voice_preview, verify_voice, or get_capabilities. Usage is only inferable from the tool name and contents, with no exclusions or prerequisites.

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

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

Annotations declare a destructive, non-readOnly, non-idempotent, open-world call, and the description goes far beyond them: background execution with a 2–5 minute runtime, one concurrent call per account, plan-governed volume, error codes with retry guidance, upfront non-final cost estimates, and the recording-disclosure requirement. It also explains the automatic name-save behavior and how to recover from user_name_required.

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 purpose is front-loaded, but the body is a dense single block of roughly 350 words that mixes routing rules, recording-disclosure guidance, pricing, error handling, and the user_name recovery flow. Most sentences carry operational weight, yet the regional coverage sentence duplicates the to-field enum and the recording-disclosure passage could be tighter, so the structure is serviceable rather than clean.

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 full lifecycle for a high-stakes outbound-call tool: prerequisites (saved name), failure handling (machine-readable error codes), asynchronous polling, user-facing artifacts (listen_url), pricing caveats, and geographic limits. An output schema exists, and the description still usefully flags call_id, listen_url, and the cost estimate.

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, but the description adds real meaning: user_name is only for the rejection recovery flow and is persisted to the account, source_number_id defaults to the account number, and request_id is a lost-response retry key. The objective/timezone semantics are largely left 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?

States a specific verb (place) and resource (call) and immediately clarifies the salient mechanics: the call goes FROM the selected outbound number, a voice agent handles it, and the goal is a concrete objective. This makes it unmistakable versus siblings like get_call, end_call, or start_agent_test.

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

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

Explicitly routes the agent: use get_agent/update_agent to customize the number, poll get_call (with wait_seconds) until status is terminal, offer listen_url to the user, and never use this for emergencies. It also names the user_name_required fallback flow and the paid-plan condition for non-US/Canadian destinations.

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 useful behavioral context by saying the tool shows charges and limits to the user before execution, which clarifies the preview outcome 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 definition is two concise sentences and front-loads the core purpose. Every phrase contributes either the preview scope or the user-facing before-execution guidance.

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

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

The description is adequate for a preview tool whose annotations cover safety and whose output schema can explain return values. However, with four parameters at 0% schema description coverage, it should do more to explain plan, trial, and promotion_code 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 0%, so the description must compensate for four undocumented parameters. It implicitly maps the action enum through words like subscribing, upgrading/downgrading, canceling, and resuming, but it never mentions the plan, trial, or promotion_code parameters, leaving substantial 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 states a specific verb, "Preview," and enumerates the subscription operations covered: subscribe, upgrade/downgrade, cancel at period end, and resume. It is clear what the tool does, though it does not explicitly name the sibling execute_subscription_change as the execution counterpart.

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 "before execution" gives clear timing guidance: use this tool to show charges and limits before applying a subscription change. It does not explicitly name execute_subscription_change or state exclusions, but the intended 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 declare this as destructive and non-idempotent, so the description does not need to re-state safety category. It does add that all saved draft changes at the specified revision are affected, but it omits whether publishing is reversible, what happens to the live agent, or whether special permissions are required.

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

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

The description is a single front-loaded sentence with no wasted wording. It states the action and scope immediately.

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?

An output schema exists, so return values need not be explained. But this is a destructive mutation with three required, undocumented parameters and no schema descriptions; the description does not provide enough context about parameter meaning, side effects, or draft/live-agent behavior.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only clarifies that a 'revision' is involved and says nothing about number_id or direction, leaving two of three required parameters without semantic explanation.

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 gives a specific verb, 'publish,' and scopes the resource to 'all saved draft changes at this revision,' which is clear enough to understand the operation. However, it does not differentiate from nearby siblings such as discard_agent_draft or update_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 states what the tool does but gives no explicit when-to-use guidance, prerequisites, or alternatives. An agent can infer it applies to draft publishing, but must look elsewhere to decide between publish_agent and discard_agent_draft or update_agent.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=false, so the description adds real value by spelling out the cascade (credentials plus assignments are also destroyed) and the side-effect boundary ('without publishing unrelated drafts'). It stops short of saying the removal is irreversible, whether it requires specific scopes, or what happens if the connector is in use.

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?

One front-loaded sentence with no filler, and the destructive scope comes before the caveat clause. It is dense but every clause carries information; no repetition 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?

An output schema exists, so return values need no explanation, but for a destructive 3-parameter mutation with zero schema descriptions the description should cover request_id semantics, assignment handling, and irreversibility. It gives the destruction scope and one side-effect guarantee but leaves the calling contract underspecified.

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

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

Schema description coverage is 0% and none of the three parameters are explained. Notably, 'request_id' (a UUID, likely an idempotency/request key) and the optional 'assignments' array are never mentioned, and the description's 'all agent assignments' arguably conflicts with a caller-supplied assignment filter, leaving the agent guessing what to pass.

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 ('Remove') and resource ('a connection'), and enumerates the cascade: saved credentials and all agent assignments. That is far more specific than a bare 'delete connector', though it never names a sibling (e.g. connect_connector) to disambiguate lifecycle direction.

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 only implied – an agent can infer this is the teardown counterpart to connect_connector/create_connector. There is no explicit when-to-use, no prerequisite (e.g. what happens to live calls on the connector), and no statement of when not to use it versus revoke_authorized_app or discard_agent_draft.

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=false and destructiveHint=true, so the description should add context about consequences, reversibility, or permission requirements. It only restates the rename action and does not explain what is affected by the destructive hint.

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

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

The description is a single front-loaded sentence with no wasted words. It is structurally efficient, even though it is under-informative in other dimensions.

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

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

The tool is simple, has annotations, and has an output schema, so the description need not explain return values. However, for a destructive mutation with 0% parameter schema coverage, it should say more about the parameters and side effects.

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

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

Schema description coverage is 0%, so the description needs to compensate by explaining voice_id and label. It only implies that the tool renames a cloned voice, without clarifying that voice_id identifies the target and label is the new name.

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: renaming a voice clone. It is clear enough to distinguish from create_voice, delete_voice, and list_voices by the action itself, though it does not explicitly differentiate sibling behavior.

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?

There is no guidance on when to use this tool versus alternatives, nor any prerequisites such as ownership or permissions. The phrase 'one of your voice clones' implies a user-owned scope but does not explain exclusions or related 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 destructiveHint=true, so the description does not need to re-state danger. It adds real value beyond annotations by disclosing that tool assignments are removed and that the reset can be previewed with apply=false; it could say more about whether the reset is reversible or what happens to published versions.

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, front-loaded with the core action, followed by the immediate-effect caveat and then the side effect. No filler or repetition of the 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?

An output schema exists, so return-value explanation is not needed, and the destructive nature is covered by annotations. However, for a destructive reset with four required and completely undocumented parameters, the description leaves important operational details unresolved (notably revision and number_id/direction scoping).

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it only explains apply. The required number_id, direction, and revision parameters have no explanation anywhere – revision (likely optimistic concurrency) and the number/direction scoping are entirely left to inference from bare type/enum 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?

States a specific verb and resource: replace agent settings with defaults, and adds the notable side effect of removing tool assignments. An agent can distinguish it from update_agent conceptually (reset vs. modify), though the description never names that sibling or any other alternative.

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?

There is no guidance on when to use reset_agent rather than update_agent, discard_agent_draft, or get_agent, nor any stated preconditions. The only conditional sentence (apply=false) describes runtime behavior, not tool selection.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is known. The description adds real context — the original operation's permissions and grant are required, and this does not create a replacement purchase — but for a destructive, non-idempotent mutation it never explains what side effects resuming can have or what happens to partially-created state.

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, front-loaded with purpose, then prerequisites, then the key exclusion. 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?

An output schema exists so return values need not be described, and the one parameter plus the permission prerequisite are covered. What is still absent is failure behavior — e.g., what occurs if the original grant was revoked or the operation already completed.

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?

Only one parameter with 0% schema description coverage, so the description must carry meaning; 'using its original provider identity' hints at what operation_id refers to but does not confirm whether it is an internal ID or the provider's identifier, nor what happens with a stale or foreign ID.

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 ('Reconcile') and names concrete resources (number claim, voice clone, subscription attempt), plus the mechanism ('original provider identity'). It is distinguishable from read-only siblings like get_operation, though it does not explicitly name the boundary with execute_subscription_change or claim_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?

The phrase 'interrupted ... attempt' establishes the triggering condition for use, and 'Does not start a replacement purchase' is an explicit exclusion that prevents a common misuse. It stops short of naming alternatives or stating what to do if the original operation cannot be found.

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 the tool is destructive and not read-only. The description adds a key behavioral detail: revoking the current application terminates the MCP connection, which is crucial beyond what annotations convey. However, it doesn't disclose other potential side effects or permission requirements.

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

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

Two sentences, front-loaded with the core purpose, followed by a critical warning. No extraneous information; every sentence adds value.

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

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

Given the tool's simplicity, annotations covering safety, and the presence of an output schema, the description is nearly complete. The only missing piece is parameter guidance, but the warning about the current application is well-covered.

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 has 0% description coverage for the single parameter client_id. The description does not mention the parameter or explain what value to supply, leaving the agent to infer that client_id identifies the application to revoke. This is a significant gap given the lack of schema documentation.

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

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

The description states a specific verb ('Disconnect') and resource ('authorized application'), clearly distinguishing it from sibling tools like list_authorized_apps. An agent can immediately understand the tool's core action.

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

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

The description provides a critical usage warning: 'Revoking the current application ends this MCP connection.' This gives context about when not to use it (for the current app) but does not explicitly compare to alternatives or outline other usage scenarios.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld). The description adds genuine behavioral context beyond them: results are ephemeral offers that expire, and the exact returned offer must be used when claiming. It omits result-count limits and whether repeated searches return different offers.

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 tight sentences: the core action first, then the critical caveat about offer expiry. Every clause carries information an agent needs.

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?

An output schema exists, so return structure needn't be explained. For a two-parameter search the description is nearly complete; the only gap is not hinting at result volume or whether pagination/limits apply.

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

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

Schema description coverage is 0%, but the two parameters are self-explanatory (country enum US/CA, 3-digit area_code pattern) and the description confirms the US-or-Canadian and area-code semantics. It adds no format or constraint detail beyond that, so baseline 3 is right.

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 (search) and resource (currently available US/CA numbers) with the key scoping qualifier 'available', which implicitly separates it from list_phone_numbers/list_numbers (owned numbers). It stops short of naming any sibling explicitly, so an agent must infer that available-for-purchase differs from inventory listing.

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?

'Claim an exact returned offer' points to claim_phone_number as the follow-up action, and 'offers expire' implies time pressure, but the description never states when to prefer this over list_phone_numbers or get_phone_number, nor 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?

Goes well beyond the destructiveHint/openWorldHint annotations by naming exactly what becomes exposed (objective, phone numbers, transcript, result, audio, live audio), through what mechanism (permanent token-free listen_url), and what is and isn't reversible (signed links stay valid until expiry; public visitors cannot stop the call or change visibility). This is the security context the annotations alone cannot 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?

Front-loads the action, then layers the risk rationale and reversal behavior; nearly every sentence carries weight. It is on the longer side for a two-parameter tool, with minor repetition between 'private by default' and 'only publish when the user explicitly asks'.

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?

An output schema exists and parameters are fully documented, so the description's remaining burden is side-effect disclosure, which it covers thoroughly: exposure surface, default state, reversibility, link expiry, and what public visitors cannot do. Nothing needed to call this safely 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 schema already defines both parameters, so the description adds only modest value: it reinforces ownership scoping on call_id and clarifies that is_public=false removes token-free access while leaving existing signed links untouched. Slightly above baseline but largely redundant with 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?

States a specific verb and resource ('Make a call ... public or private') and scopes it to calls 'owned by the authenticated user'. An agent can immediately tell this is a per-call visibility toggle, distinct from call lifecycle siblings like end_call or get_call.

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?

Gives an explicit when-to-use rule plus an exclusion: 'Only publish when the user explicitly asks', with the default state ('Calls are private by default') spelled out. It also tells the agent how to reverse the decision by setting is_public to false.

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=false, destructiveHint=true, and idempotentHint=false, so the safety profile is covered. The description does not say what gets destroyed when the default changes, whether the previous default is cleared, or what happens on a stale workspace_revision. For a destructive mutation, that is a gap, though the annotations remove most of 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?

One short sentence, front-loaded with the action, and each clause is useful. It is arguably too terse for a destructive operation, but that is a completeness issue, not a structure issue.

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?

An output schema exists, so return values need not be explained. The description covers the action and the key revision dependency. What it omits are the effects on the existing default and the failure behavior on a stale revision, which matter for a destructive call.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain that workspace_revision comes from get_phone_number_settings, which is useful context. However, number_id (a 1-200 char string) is not explained: the description does not say where to obtain it (list_phone_numbers/get_number_claim) or that it identifies the number to promote.

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 object: 'Choose the default outbound number'. This clearly separates it from list_phone_numbers, get_phone_number_settings, and update_phone_number, which are nearby siblings. It stops short of naming those alternatives or saying what 'default' affects.

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 'using workspace_revision from get_phone_number_settings' is a genuine workflow dependency: it tells the agent to call a sibling first. However, there is no guidance on when to use this rather than update_phone_number, or on what happens if the revision is stale; the prerequisite is the only usage signal.

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 idempotentHint=false, so the risky profile is known. The description adds useful scope context (it does not purchase anything), but never states what is destroyed or whether setting 'skipped' or 'complete' is irreversible, which matters given the destructive and non-idempotent hints.

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 tight sentences with the capability stated first and the scope boundary second. Every clause earns its place, with no repetition of schema or annotation data.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The remaining gap is behavioural: what each status transition means (especially 'checkout') and how intent interacts with status.

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

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

Schema description coverage is 0%, so the description must carry the load, and it partially does by naming the inbound/outbound intent and the complete/skip states. However it never explains the 'checkout' status value or that 'intent' is optional and only meaningful for certain transitions.

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 ('set') plus the resource, and enumerates the actual modes: setup intent, mark complete, or skip. It also explicitly differentiates itself from the billing and number tools, which cover neighbouring onboarding steps among the siblings.

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

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

Gives a clear exclusion ('Does not buy a plan or number') and routes the agent to billing and number tools for those steps. The alternatives are named only by category rather than specific tool names (create_billing_portal, claim_phone_number), so the routing requires a little inference, but the when-to-use context is 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 declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false, so safety behavior is partially covered. The description adds useful context that the test runs without a browser and external tools are disabled, but it does not explain what makes the operation destructive or what side effects occur on the saved draft.

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

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

The description is two sentences, front-loads the primary action, and immediately follows with key constraints. There is no redundant or filler language.

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, seven-parameter destructive test tool with a nested custom_scenario object and low schema description coverage, the description is too thin. It omits guidance on required identifiers, revision handling, request_id usage, scenario lookup, and lifecycle alternatives such as get_agent_test or stop_agent_test.

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 14% for seven parameters, so the description must compensate heavily. It only clarifies direction and the inbound custom scenario requirement; it does not explain number_id, revision, request_id, custom_scenario fields, or how preset scenario values map to list_test_scenarios.

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: testing a saved draft for outbound or inbound scenarios. It clearly distinguishes this from reading a test result, but it does not explicitly contrast itself with siblings such as get_agent_test, stop_agent_test, or list_test_scenarios.

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 one useful usage constraint: inbound testing requires a custom caller scenario. However, it does not explain when to use this tool versus get_agent_test, stop_agent_test, or list_test_scenarios, nor does it state prerequisites for selecting preset scenarios.

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

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

Annotations already declare destructive=true, readOnly=false and idempotent=false, so the safety profile is covered. The description does add one genuinely valuable behavior beyond the schema — that the captured result is retained rather than discarded — but it omits what happens on a second stop (non-idempotent implies an error), whether in-flight calls are interrupted, and how the retained result is then retrieved.

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

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

A single front-loaded sentence with no filler. The action leads and the consequence ('retain its captured result') follows, which is the correct ordering for a destructive operation.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. But for a destructive, non-idempotent single-parameter tool with zero schema coverage, the description should at minimum source the test_id and warn about repeat 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 0% and the single parameter test_id is never referenced in the description. With one required parameter completely undocumented, the agent gets no hint about where test_id originates (presumably start_agent_test's response) or whether it accepts an agent ID.

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+resource: 'Stop your synthetic test', which an agent can map cleanly against the sibling start_agent_test and get_agent_test. What is missing is an explicit statement of that pairing, so differentiation is inferable from naming rather than spelled out.

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 — you call this after start_agent_test to end a run — but the description never says when to use it versus get_agent_test (read results), or what to do if the test has already finished. No exclusions or prerequisites are offered, leaving the agent to infer the workflow.

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 declare mutation, non-idempotency, and destructiveHint=true. The description adds useful partial-update semantics and revision-based concurrency context, but it does not explain why the operation is destructive or what risks accompany profile changes.

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-loaded with the update behavior and immediately followed by the revision prerequisite and permission note. There is no redundant or wasted 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?

The tool is a destructive mutation with nested parameters and 0% schema description coverage. Although an output schema and annotations exist, the description does not sufficiently cover destructive implications or field-level parameter semantics needed to invoke it safely.

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

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

Schema description coverage is 0%, and the nested changes object contains multiple fields with no descriptions. The description explains that revision comes from get_account and that only supplied fields are updated, but it does not clarify the meaning or constraints of name, call_locale, voices_by_locale, or agent_instructions.

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

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

The description clearly states a specific verb and resource: updating account profile fields. It distinguishes account profile updates from agent updates by referring to profile fields and agent defaults, though it does not explicitly contrast with sibling tools such as update_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?

It provides clear usage context: use the revision from get_account, update only supplied fields, and agent defaults require configuration permission. It does not state when not to use this tool or name alternatives explicitly, but the prerequisite guidance 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?