Patch MCP

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

Annotations already declare readOnly=false, destructive=false, so the safety profile is partly covered; the description adds genuinely new context, namely that no subscription or charge occurs, that the entitlement is pre-existing, and that new connections start unassigned. Slight tension with idempotentHint=false given 'create or return', which the description never reconciles.

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 entitlement constraint, then exclusions, then the next-step chain. The negative list is long but each item prevents a real misuse; no filler sentences.

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 covers the creation semantics and downstream workflow well. The one real gap is request_id, which matters for a non-idempotent create tool where callers need to know how retries behave.

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 two required parameters, so the description must compensate and does not: request_id (a uuid, presumably a replay/idempotency key) is never explained, and the provider parameter's single-value enum ('exa') is only implied by the prose. An agent gets no meaning beyond the raw 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+resource: creating or returning a managed Exa web-search connection tied to the account's paid entitlement. The 'create or return' framing is precise. It does not, however, distinguish itself from the sibling create_connector, leaving the agent to infer which creation path applies.

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 sets boundaries ('Does not subscribe, charge, search, discover tools or change assignments') and gives an ordered follow-up path: connect_connector, then get_connector_tools, then explicitly set_agent_connectors. This routes the agent through the multi-step workflow better than most definitions in the sibling list.

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

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

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 only say non-read-only, open-world, non-idempotent; the description adds the crucial behavior that it may launch third-party OAuth and return an authorization_url for out-of-band approval. The explicit 'never collect verification codes or credentials in chat' rule is high-value safety context not available anywhere in the structured fields, and the non-effects are stated clearly.

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?

Four short sentences, purpose front-loaded, negatives and the follow-up action packed into minimal text. Every sentence carries distinct, actionable information with no repetition of 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?

For an open-world, OAuth-triggering tool with an output schema, the description covers the flow, the human-in-the-loop step, and the follow-up call, so the agent can act correctly. The remaining hole is the unexplained request_id, which belongs to parameter semantics but slightly detracts from overall completeness.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only implicitly covers connector_id via 'owned connection'. The required request_id (a constrained UUID, presumably an idempotency/correlation key) is never mentioned, so an agent gets no guidance on it from any source.

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 ('contact ... to discover or refresh') and resource ('its individual voice-agent tools' on an owned connection), which is enough for an agent to distinguish it from list_connectors and create_connector. It is slightly muddled between 'connecting/authenticating' and 'discovering tools', but the two clarifying negatives ('does not invoke external tools or change agent assignments') remove the main ambiguity.

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

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

It states both when to use it (to discover/refresh tools, possibly starting OAuth) and what to do next ('Inspect get_connector_tools after authorization'), naming the sibling alternative explicitly. It also excludes two tempting misuses (invoking external tools, changing agent assignments), leaving no inference needed.

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

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

The description adds substantial context beyond the annotations: the link is Stripe-hosted, creating it triggers no charge/change/cancel, the user confirms on Stripe, and the flow returns to Patch's fixed billing page. It also discloses retry behavior (reuse request_id after a lost response) and a security constraint about card details. Note that request_id reuse reads as an idempotency key while idempotentHint=false; this is a nuance about deduplication rather than a direct 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?

Four short sentences, each earning its place: purpose first, then safety/what-it-does-not-do, then return destination, then operational and security guidance. No filler or repetition of schema fields.

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

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

With an output schema present, return values need not be described, and the description still adds the meaningful outcome (redirect to Patch's fixed billing page). For a one-parameter, non-destructive mutation with annotations covering the safety profile, 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?

Schema description coverage is 0% for the single request_id parameter, so the description must carry the meaning — and it does, explaining that the same request_id should be reused after a lost response, which tells the agent this is a deduplication key. It does not mention the UUID format, though the schema pattern already constrains that.

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?

"Create a Stripe-hosted billing portal link for this account's existing Stripe customer" states a concrete verb (create), resource (billing portal link), and scope (this account's existing Stripe customer). It also implicitly separates itself from the subscription-change siblings by noting it does not charge, change, or cancel a subscription, though no sibling is named 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 makes clear the intended path: the agent generates a link and the user makes billing changes on Stripe, so this is the tool for handing billing management off rather than executing changes directly. It also gives operational guidance (reuse request_id after a lost response) and a hard exclusion (never request or accept card details in chat). It stops short of naming a sibling like execute_subscription_change as the alternative when the agent is supposed to act directly.

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 non-readOnly, non-destructive, non-idempotent, closed-world behavior; the description adds genuinely new context by confirming the save performs no outbound contact with the connector and no agent assignment, and it imposes a hard safety rule against submitting secrets in chat. It stops short of stating duplicate-name behavior or what the saved object/response contains, so it is strong but not exhaustive.

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 operation and its scope, followed by the safety constraint and then the workflow chain. Dense and largely waste-free, though the opening sentence packs scope, exclusions, and side-effect notes into one long clause stack.

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 annotation profile is reasonably rich. But for a five-required-parameter mutation with 0% schema coverage, the description leaves the meaning of name, transport, and request_id unaddressed, which is a material 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 five required parameters are undocumented everywhere. The description only obliquely maps authType ('no credentials or standard browser OAuth') and url (the MCP endpoint); name, transport, and especially request_id (a UUID that reads like an idempotency key while idempotentHint is false) get no explanation at all.

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 ('Save a hosted voice-agent MCP connection') plus the exact scope it accepts ('requiring no credentials or standard browser OAuth'). It also names what it explicitly does NOT do (contact the connector, assign agents), which separates it from connect_connector and set_agent_connectors without opening a 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?

Gives an explicit when-not and the alternative route ('For API-key or custom OAuth setup, send the user to setup_url from list_connectors'), then a concrete next-step chain: connect_connector for browser authorization and discovery, set_agent_connectors to grant access. Nothing about selecting this tool 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 destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the danger profile is disclosed structurally. The description adds genuinely useful compliance context — consent must be explicit and never inferred — which goes beyond annotations. However, it omits reversibility (can a created voice be deleted?), whether this consumes a quota or incurs billing, and what subsequent verification entails.

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 tightly written sentences with zero waste. The core action is front-loaded, and the consent constraint immediately follows as a critical qualifier.

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 destructive mutation with 0% schema coverage, the definition should cover the required upload prerequisite, the meaning of request_id, and the likely next step (verify_voice). Those gaps leave the definition only minimally sufficient.

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

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

Schema description coverage is 0%, so the description carries the full burden for 4 required parameters. It only indirectly illuminates upload_id ('uploaded sample') and consent ('explicit permission'), leaving label and especially request_id (a UUID idempotency key) unexplained, as is the fact that all four are required.

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: cloning a voice from an uploaded sample of the user's own voice. The 'uploaded sample' phrasing implicitly distinguishes it from the sibling create_voice_upload, though no sibling is named explicitly. An agent can tell it apart from list_voices, delete_voice, or verify_voice.

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

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

The mention of 'an uploaded sample' implies upload_id must come from a prior upload (create_voice_upload), but the workflow ordering is inferred rather than stated. No explicit when-not guidance or pointer to verify_voice as the follow-up step.

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, and the description adds genuinely useful context the annotations cannot convey: the URL expires, the bytes are PUT out-of-band rather than passed as a parameter, and the resulting upload_id feeds create_voice. It omits the expiry window and whether abandoned uploads are cleaned up, which would be the remaining value-add.

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, and the core action plus the full two-step workflow are front-loaded. Every clause earns its place by describing a distinct step the agent must perform.

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 workflow and expiry are covered. However, for a 2-parameter tool at 0% schema description coverage, the description leaves both inputs undefined, which is a real completeness gap for an agent deciding what filename to supply.

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 both parameters, yet it explains neither. It never says that 'filename' determines the accepted audio extensions (mp3/wav/m4a/flac/ogg/webm) nor what 'request_id' is for — a notable gap given idempotentHint=false makes the idempotency-key role of a UUID request_id non-obvious. The only identifier it mentions, upload_id, is not a parameter of this tool.

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 — 'Create an expiring audio upload URL' — and immediately places it in the voice-creation flow, naming create_voice as the follow-up. An agent can distinguish this pre-upload step from create_voice and verify_voice 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 description gives an explicit sequence: create URL, PUT the bytes there, then call create_voice with the upload_id and consent. That is clear usage context, but it never states when not to use it (e.g. when an existing upload_id is already available, or that the URL expires and must be re-requested).

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?

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?

Beyond the `destructiveHint: true` annotation, the description adds critical operational behavior: it instructs the AI to reuse the `request_id` after a lost response and specifies the output must be a payment/authentication URL, preventing the AI from attempting to collect sensitive data in chat.

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?

Although long, the description is highly efficient and dense. Every sentence serves to define the scope, safety guardrails, or operational constraints, ensuring zero waste of words for this complex financial action.

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

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

Given the high complexity and financial risk of the operation, the description is exhaustive. It covers what the tool does, when it can be used, safety protocols, and expected response types.

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?

Given the low schema coverage (33%), the description is essential. It adds vital semantic meaning to the parameters: `quote_id` must be from an unexpired quote, and `user_authorized` means the user has actively consented to the financial terms.

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

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

The description clearly identifies the resource ('quote') and the action ('Apply the exact, unexpired quote'), specifically stating it executes a subscription change. It implicitly differentiates itself from `preview_subscription_change` in the sibling list by focusing on execution versus previewing.

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 explicit preconditions for use, such as the quote being 'unexpired' and the user having 'explicitly approved' it. It dictates when to use the parameter `user_authorized` (only after explicit approval).

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 the safety profile is fully covered by structured data. The description's added value is the content scope (what account facets are read), but it says nothing about auth/caller-verification requirements or freshness/caching behavior. With annotations carrying the safety burden, a 3 is appropriate.

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, zero filler. The read scope is front-loaded and the disambiguation sentence follows immediately, so an agent gets both purpose and routing in the first glance.

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 an output schema present, return values need no explanation, and with zero parameters there are no input semantics to cover. The remaining gap is minor: it does not hint at when in a workflow the read should be performed or what "caller verification" implies for authentication context.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool is 4. The description correctly does not waste words on inputs and instead spends its budget on scope and sibling routing.

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 ("Read") and enumerates the exact account facets returned: profile, caller verification, revision, account defaults, setup progress and notices. It also names the two siblings it is not (update_account, set_onboarding), so an agent can separate it from the mutation tools 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 second sentence gives explicit routing: use update_account for profile changes and set_onboarding for setup state. That is a concrete when-to-use-this-vs-alternative rule rather than an implied one.

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 clear. The description adds useful behavioral context: settings are null until configured, inbound includes editable greeting/instructions, and outbound prompt text plus Patch internal system prompts are not exposed.

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

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

The description is front-loaded with the core action and uses only three sentences with little waste. The second sentence is dense but carries useful caveats rather than filler.

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

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

The output schema and annotations reduce the description's burden, and the description covers important exposure and null-state caveats. However, it omits parameter semantics for number_id and lacks usage guidance, leaving clear gaps for an agent selecting and invoking the tool.

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

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

Schema description coverage is 0%, so the description must compensate, but it never mentions number_id or explains its format or role. It does add some meaning to direction by noting what is exposed inbound versus outbound, but the required number_id parameter remains 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 states a specific verb and resource: 'Read active user-configurable settings and revision.' It is clearly a read operation and distinguishes itself from update_agent implicitly, though it does not explicitly name or differentiate siblings like list_agents 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?

There is no explicit guidance on when to use get_agent versus alternatives such as list_agents or update_agent, nor are prerequisites or exclusions stated. The description implies inspection of settings but leaves usage selection to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely behavioral detail — that transcripts expire — which hints at urgency in retrieval, but says nothing about what happens when a test is still running or the transcript is unavailable.

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 verb and with zero redundant words. It is efficient, though its terseness leaves the gaps noted in the other dimensions rather than resolving 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still, the sole required parameter is undocumented and there is no mention of behavior for in-progress tests or expired transcripts — the main failure modes for a test-status read.

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 test_id, its format, where it comes from, or its length constraints. With a single required parameter the name is semi-self-documenting, but the description contributes nothing beyond the schema.

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

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

States a specific verb (Read) and resource (a synthetic test) plus the exact payload returned: status, transcript, result, and transcript expiry. That distinguishes it from start_agent_test/stop_agent_test, though it never names the related get_agent_test_listener or explains the difference.

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 polling/retrieval counterpart to start_agent_test, but the description never says when to call it, when not to, or how it relates to get_agent_test_listener or list_test_scenarios. No preconditions or timing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds value by disclosing that the tool reconciles subscription state with Stripe—an external side effect that matters despite read-only semantics. It does not mention auth requirements or rate limits, but the external reconciliation disclosure is meaningful context beyond annotations.

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

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

Two tightly written sentences. The resource list is front-loaded, and the behavioral and parameter guidance follows without filler. Every sentence earns its place.

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

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

With annotations covering safety traits, an output schema documenting return values, and only one parameter whose purpose is explained, the description provides everything an agent needs to select and invoke this tool correctly. The Stripe reconciliation note covers the main non-obvious 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%, and the single parameter (invoice_cursor) is only constrained by type and length in the schema. The description compensates by explaining that invoice_cursor is used for older invoices, giving the parameter practical meaning. It does not specify the cursor format, but the opaque nature of cursors makes that omission acceptable.

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 enumerates the exact resources covered: plans, usage, subscription state, payment-method summary, and invoices. It is clearly distinguishable from sibling mutation tools like update_billing_profile, though it does not explicitly name an 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?

It provides clear context for when to use the tool (reading billing information) and explicitly explains the invoice_cursor parameter's role for older invoices. It does not state when not to use it or name a specific alternative sibling, which keeps it below 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 only say read-only/non-destructive; the description goes far beyond by disclosing long-poll semantics (max 50s, early return on status change), the full terminal status set, that resolution can lag the terminal status by seconds, that recording_url links expire after ~1 hour and need the OAuth header on staging, and that recording_status=processing means a separate copy is still finalizing. These are exactly the operational facts an agent cannot infer from structured fields.

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

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

Purpose is correctly front-loaded, but the body is one dense run-on paragraph that crams terminal statuses, resolution shape, transcript, recording expiry, staging auth, public-call URLs, and retry advice together with no grouping. Some lines are near-redundant ('A recording can fail or be unavailable', the repeated 'call get_call again'), so it is longer than it needs to be for the information delivered.

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

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

Despite an output schema existing, the description supplies everything an agent needs to interpret the richer-than-usual response states: the meaning of 'rejected' vs other terminal statuses, what to do when outcome is 'unknown', that resolution precedes the transcript, and how listen_url/public URLs differ. Nothing material about calling or reading the result is left unexplained.

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, but the description adds real meaning: wait_seconds is not just 'server-side long-poll' — the server holds the request and returns early on any status change, which is how you avoid polling loops. call_id's origin (returned by place_call) is also restated usefully in context.

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 + scope: 'Get the status and, once terminal, the structured resolution of a call started with place_call.' It explicitly ties itself to place_call as the creator and names set_call_visibility as a different action, so an agent can distinguish it from the listing/diagnostics siblings without opening a 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?

Gives concrete when-to guidance: default is an instant check; pass wait_seconds to long-poll instead of round-tripping, and call again on a terminal call to wait for a recording state change. It also states when NOT to act ('use set_call_visibility only when the user explicitly asks', 'ended_by=user ... don't retry'). It does not, however, route the agent to get_call_diagnostics or get_call_listener for those sibling use cases.

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

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

Annotations 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?

Goes well beyond the readOnly/idempotent annotations by disclosing that the data is cached, that the call does not invoke the tools, does not refresh discovery, and does not return credentials. These are exactly the side-effect boundaries an agent needs to know before relying on results.

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, then lifecycle context, then exclusions. No filler or redundancy.

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

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

With an output schema present, the description need not describe return values, and it correctly focuses on caching semantics and non-behaviors. It is nearly complete; only the explicit when-to-call-this-tool guidance 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 0% for the single connector_id parameter, and the description only implies via 'owned connection' that the ID must belong to the caller. It adds a useful ownership constraint but not enough detail (format, lookup source, error behavior) to fully compensate for the undocumented 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: 'Read the cached individual tool definitions for an owned connection.' The word 'cached' plus 'individual tool definitions' distinguishes it from list_connectors and from set_agent_connectors without requiring the 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 description explains the lifecycle context (these tools become exposed to the voice agent after set_agent_connectors assigns the connection) and clarifies what the read does not do. However, it never states directly when an agent should call this versus alternatives like list_connectors or execute-style tools, so usage must be inferred.

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

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

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 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes further by disclosing required auth scopes ('calls:read or numbers:read') and which fields need the stricter numbers:read scope. It also sets boundaries on what the response will not contain.

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 dense sentences with zero filler, front-loading the core operation and the optional-parameter behavior. Auth and negative-scope details follow in a logical order.

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 documentation is unnecessary. With a single optional parameter, the description covers selection behavior, auth requirements, and scope boundaries — everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must carry the semantics — and it does, explaining that number_id selects a specific owned number and that omitting it returns the default outbound number. It stops short of stating accepted formats or whether unknown IDs error.

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 one owned number') plus the key scoping behavior (omit number_id to get the default outbound number). This clearly separates it from list_phone_numbers and search_phone_numbers, which return multiple records.

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 concrete usage rule (pass number_id for a specific number, omit it for the default outbound number) and useful exclusions ('Does not place a call or expose agent instructions or voices'). It does not explicitly name the sibling tools it competes with, which keeps it just short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety bar is covered. The description adds genuinely non-redundant behavior: the returned URL is short-lived, which tells the agent not to cache or reuse it — exactly the kind of context annotations 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?

Three short sentences, front-loaded with the outcome and each carrying a distinct fact (identity source, identity model contrast, catalog exception). Slightly compressed to the point of ambiguity — "Claudia's provider ID" is an unexplained proper noun that assumes prior context.

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 an output schema present and only one required param, the description covers what an agent needs: the identifier's origin, the correct identity type, and a case where the call is unnecessary. Minor gap: no mention of behavior for an invalid or unknown provider_voice_id.

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 carries the full burden and does: it names the parameter's origin (from list_voices), its accepted alternate (Claudia's provider ID), and the crucial distinction that it is a provider identity rather than the internal voice_id used by clone management. That is meaningful semantics beyond a bare string field.

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 outcome ("get a short-lived playable URL") for a specific resource (a voice identified by provider_voice_id), and explicitly contrasts the identity model with clone management which uses voice_id. An agent can distinguish this from list_voices, verify_voice, and rename_voice 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?

It tells the agent where the required identifier comes from (list_voices) and implicitly when not to call it ("Built-in catalog voices already include sample URLs"). Clear usage context is present, though there is no explicit statement of failure/error conditions or a named fallback 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 read-only and idempotency; the description adds what the annotations cannot: newest-first ordering, the fields each kind returns (statuses, resolution summaries/outcomes, listen links, finished synthetic tests), and the permission required per kind. It does not mention pagination end conditions or whether unfinished tests are excluded beyond 'finished'.

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?

Four tight sentences, front-loaded with the scope, then kind/permission mapping, then pagination. No filler and no restatement 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?

With an output schema present, the description correctly avoids over-explaining response shapes while still flagging what each kind yields. Permissions and paging are covered; the only real gap is `limit` (default 20, max 100), which the description never addresses.

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 compensate. It explains kind thoroughly and gives real cursor semantics (pass the returned next_cursor unchanged, keep the same kind), but the required `limit` parameter is never mentioned at all, and the description's 'next_cursor' label differs from the schema's `cursor`, which could confuse an agent.

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

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

States a concrete verb and resource ('Read owned history newest first') and immediately splits the resource into call/test/all kinds, which no sibling tool covers. It stops short of a single crisp noun phrase ('activity' is never named as calls+tests together), but an agent can still tell it apart from get_call, get_agent_test_listener, and the list_* 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 per-kind conditions (calls:read for kind=call, configuration:read for kind=test, both for kind=all) and states how to continue paging with next_cursor and the same kind. It never says when to prefer get_call or get_agent_test over this history view, so a small routing gap remains.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds real context beyond them: it returns a setup_url for entering API keys or OAuth credentials on the website, and it explicitly does not reach out to providers. It could say more about what 'authorization state' looks like, but the added value is genuine.

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, front-loaded with the core purpose, then the useful return hint, then the exclusion clause. No filler or restatement 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?

A no-parameter read tool with an output schema and full annotation coverage needs only scope, return hint and boundary. The description supplies all three, including the setup_url detail an agent would otherwise have to infer from the response.

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

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

Zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly spends its words on scope and return hints instead of inventing parameter detail.

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

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

States a specific verb+resource ('Read this account's saved voice-agent connections, authorization state and common providers') and names the scope. The closing negative clause explicitly separates it from connect_connector, get_connector_tools and set_agent_connectors, so an agent can distinguish it without opening a 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 description makes clear this is the inspection path (saved connections + auth state + known providers) and rules out the action-oriented siblings ('does not contact providers, discover tools, assign agents or invoke external actions'). It stops short of naming the sibling tools it defers to, so it is clear context rather than full routing 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 readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by naming the two accepted scopes and stating that management settings and workspace_revision appear only with numbers:read. The explicit exclusion ('Does not expose agent instructions or voices') further prevents a false expectation about the payload.

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 what is listed, then scoping/auth, then exclusions. No filler; every clause carries a distinct constraint or use case.

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, rich annotations, and an output schema, the description covers the remaining agent-relevant unknowns: required scopes, scope-dependent content, and what is deliberately omitted. 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 zero parameters, which is the baseline-4 case. The mention of number_id is about place_call, not this tool's input, so it adds navigation context rather than parameter semantics, but it does not mislead about inputs.

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') plus the concrete fields returned (direction availability, default_number_id). It doesn't differentiate from the close sibling search_phone_numbers or get_phone_number, which is the only thing keeping it from 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?

It provides one concrete downstream usage hint ('Use number_id to select a source for place_call') and explains scope-conditional output, which implies when the tool is useful. However, there is no explicit when-to-use-this-vs-search_phone_numbers guidance or exclusion statement.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only the shape of the payload (languages, preview URLs, clones, limit), which duplicates what the output schema likely conveys. No mention of auth scope, pagination, or whether preview URLs expire.

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, no filler, and the most important noun (supported languages/voices) is front-loaded. Every clause corresponds to a distinct part of the return 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?

With an output schema present, the description need not explain return values, and with zero parameters there is nothing else to document. The only gap is that it never says the results are scoped to the authenticated account, which the phrase 'owned voice clones and your clone limit' only hints at.

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 could add parameter meaning. The schema is fully closed (additionalProperties: false) and requires nothing.

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 'List' with four enumerated resources: languages, built-in voices with preview URLs, owned clones, and clone limit. An agent can distinguish it from create_voice/delete_voice/get_voice_preview. It stops short of naming a sibling it is not, so it lands at 4 rather than 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 only implied by the verb and the enumerated contents; there is no statement of when to call this versus get_voice_preview or verify_voice, and no prerequisite (e.g. account scope) is given. An agent can infer 'call this to discover available voices' but must do the inference itself.

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 destructive/openWorld/non-idempotent, and the description adds substantial context beyond them: real cost exposure including unsuccessful attempts and estimated provider cost, one concurrent call per account, geographic and paid-plan constraints, the user_name_required rejection path, the recording-disclosure obligation on the first objective-advancing turn, and the request_id-based retry key. This is exactly the operational knowledge an agent needs before committing an irreversible, open-world action.

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 opening sentence is well front-loaded, but the remainder is a dense ~350-word block with no paragraph breaks that hops between recording disclosure, pricing, timezone, concurrency, error handling and name requirements. Every fact is arguably useful, yet the recording-disclosure guidance spans three sentences and is interleaved with unrelated cost information, hurting scannability.

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

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

For a 9-parameter, destructive, open-world tool with an output schema, the description fills every operational gap an agent could hit: async polling contract, listen_url offering, cost semantics, language/locale behavior, and failure modes. Nothing needed 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?

Schema coverage is 100%, so the baseline is 3; the description earns credit for explaining the division of labor between objective/context (call-specific facts) versus the read-only outbound greeting, and for spelling out the user_name recovery flow after a user_name_required rejection. It adds marginal value over the already thorough schema, hence 4 rather than 5.

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 ('Place one real phone call' from the selected outbound number) plus the scope of what the call can accomplish (book a table, ask a question, chase an order). It names the sibling tools it is not (get_agent/update_agent for number settings and inbound greeting) and the companion it polls (get_call), so an agent can distinguish it 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?

Explicit about when to use it and when not: 'never for emergencies', outbound greeting/system instructions are read-only through MCP so call-specific facts belong in objective/context, and it routes number settings and inbound greeting to get_agent/update_agent. It also tells the agent how to follow up (poll get_call with wait_seconds until terminal status) and to relay error codes rather than retry blindly.

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?

Adds real context beyond annotations: it 'may read Stripe and save a local quote; does not charge or change a subscription,' which reconciles readOnlyHint=false with destructiveHint=false, and 'Each preview creates a new quote' explains idempotentHint=false. It also discloses the 15-minute TTL and required user approval step. Minor gap: no note on what happens when the quote expires or on failure modes.

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?

Four dense sentences, front-loaded with the core capability and the return contents, then the side-effect disclosure, then the workflow constraint. No filler or restatement of the 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?

Return values are covered by the output schema and are still summarized helpfully (immediate charges, list price, effective time, allowances), and the approval workflow is stated. The remaining gap is the undocumented optional parameters, which matters for a 4-param tool with 0% schema coverage.

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 maps the action enum well (subscribe/change/cancel/resume) but says nothing about `plan`, `trial`, or `promotion_code` — three of four parameters are left to the bare enum/type. Partial compensation only.

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 ('Create a 15-minute quote') plus the four supported lifecycle actions, immediately distinguishing it from the mutation sibling execute_subscription_change. An agent can tell exactly what this produces (a quote) versus what it does not do (charge or change a subscription).

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: this is the preview step, and 'obtain explicit approval before execute_subscription_change' names the alternative and the gate condition. Also notes the side effect of repeat calls ('Each preview creates a new quote'), which is actionable usage guidance.

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

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

Adds substantial context beyond the destructiveHint=true annotation: credentials are destroyed, the connection is revoked from every assigned agent, and configuration permission is required when an assignment is removed. It also discloses important non-actions — no external tool invocation and no third-party consent revocation — which are critical caveats for an agent to know before calling.

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 core action and follows with scope and permission caveats in four tight sentences. Most sentences earn their place; 'without applying unrelated settings' is slightly vague but still conveys a meaningful scope limit.

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 destructive mutation with an output schema present, the description covers destruction scope, permission prerequisites, and side-effect boundaries well. The remaining gap is that the two required parameters are never described, which the agent must resolve from the schema 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%, so the description carries the full burden, yet it never mentions connector_id or request_id. The purpose of request_id (likely an idempotency/dedup key given idempotentHint=false) is completely unexplained, leaving the agent to infer parameter behavior.

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 an owned connection and its saved credentials.' It clearly distinguishes the operation from siblings like create_connector/connect_connector by naming the ownership scope and what is destroyed. An agent knows exactly what this does without opening the 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?

Gives clear context for when it applies (removing an agent assignment requires configuration permission) and a scope boundary ('Does not invoke external tools or revoke consent at the third-party provider'). It does not explicitly name an alternative tool (e.g., revoke_authorized_app vs remove_connector), so it stops short of full when-not/alternatives routing.

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

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

Annotations already 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 and readOnlyHint=false, so the mutation profile is known. The description adds genuinely new context: the reset removes active external connection assignments and requires connector permission when such assignments exist — a side effect and an auth prerequisite 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 tightly packed sentences: the action and its scope come first, the side effect and permission requirement second. No filler and nothing misplaced.

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 the destructive/mutation profile is covered by annotations plus the description's side-effect note. But for a destructive reset requiring a revision token, the absence of any statement about concurrency semantics or partial-failure behavior leaves a meaningful gap.

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

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

Schema description coverage is 0% and the description never mentions number_id, direction, or revision. In particular the required `revision` parameter — clearly an optimistic-concurrency token — is completely unexplained, and the description does not tell the agent what happens if the revision is stale.

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 ("Reset user-configurable agent settings to defaults") plus the scope qualifier "for future calls", so the agent knows this is a reversion operation on the agent configuration. It doesn't name the sibling it differs from (update_agent, set_agent_connectors), so sibling differentiation is left implicit.

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?

"for future calls" implies the reset doesn't disturb in-flight behavior, which is a useful usage hint, and the connector-permission clause hints at a prerequisite. However, there is no explicit statement of when to choose this over update_agent, nor any exclusion or precondition 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?

Goes well beyond the annotations by disclosing the concrete side effects available (reconcile number provisioning, resolve an existing provider voice, retry the persisted request with its original idempotency key) and the guardrails (never creates a replacement request, never authorizes new spending). This meaningfully softens and explains the destructiveHint=true flag, though it leaves ambiguous how a destructive outcome could still occur given the 'no new spending' promise.

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?

Four tight sentences with the capability front-loaded and the safety constraints following; each sentence carries distinct information. Slightly dense sentence three stacks three behaviors, but 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?

With an output schema present, return values need not be explained, and the description covers permissions, scope, side-effect boundaries, and the no-op behavior for terminal states. The remaining gap is procedural: it doesn't say how to obtain or validate the operation_id, which matters because it is the only input.

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% for the single operation_id parameter, so the description must compensate. It adds useful semantics – the operation must belong to this account and must carry its original authorization grant – but never says where an operation_id comes from or what happens when it is stale or belongs to another account.

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 ('Recover') plus an enumerated resource scope (interrupted number claim, voice clone, subscription attempt) and ownership constraint ('owned by this account'). The framing of resuming an interrupted attempt implicitly separates it from siblings like claim_phone_number and create_voice, which start new operations rather than resume existing ones.

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

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

The description makes the trigger condition clear ('interrupted ... attempt') and adds the prerequisite that the original permissions are required, plus the exclusion that completed/definitively-failed operations are returned without action. It does not name a sibling for comparison (e.g., use get_operation to inspect state first), so the alternative-routing is only indirectly conveyed.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces this with replace semantics, empty-list clearing, and authorization prerequisites that go beyond the annotations. It does not explain the role of 'revision' (likely optimistic concurrency / conflict handling), which is a meaningful omission for a destructive replace operation.

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

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

Four sentences, front-loaded with the mutation and its scope, then prerequisites, then semantics, then exclusions. Efficient, though the middle sentence about individually exposed functions is more context than instruction.

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?

Has annotations and an output schema, so return values and safety profile are covered. Still, for a destructive, non-idempotent, four-required-parameter mutation, the unexplained 'revision' and 'direction' semantics leave a gap that matters 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% across four required parameters, so the description carries the full burden. It only adds meaning for connector_ids (empty list removes access); number_id, direction (enum), and especially revision are unexplained, leaving the agent to guess at required preconditions for a destructive write.

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 ('Replace'), a specific resource ('external connections available to one active voice agent'), and a scope ('for future calls'). It is distinguishable from siblings like create_connector, connect_connector, add_common_connector, and update_agent, especially via the closing 'Does not invoke tools or change unrelated agent settings.'

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 real prerequisite workflow ('Review get_connector_tools and obtain authorization for those capabilities first') and a clear edge case ('An empty connector_ids list removes access'). It implies full-replace semantics rather than additive, which separates it from add_common_connector, but never names an explicit alternative or when-not-to-use condition beyond the settings exclusion.

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

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

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 destructiveHint=true and readOnlyHint=false, so the description benefits from a lower burden. It adds the workspace_revision prerequisite, but it does not disclose what changing the default affects, whether the prior default is overwritten, or any permission or reversibility implications. For a destructive mutation, this is a meaningful behavioral gap.

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 redundant or filler content. Every word earns its place by stating the action and referencing the prerequisite source for workspace_revision.

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 annotations cover the safety profile. Still, the description omits what number_id represents and what effect changing the default has on existing configuration. It is minimally adequate but leaves gaps for a destructive operation with undocumented parameters.

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% with two required parameters, so the description must compensate. It explains where workspace_revision comes from, but it says nothing about number_id beyond the parameter name, leaving half the parameters without added semantic meaning.

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

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

The description states a specific action and resource: choose the default outbound phone number. It distinguishes the operation from general phone-number listing or updating siblings, though it does not explicitly name alternatives. The purpose is clear enough for an agent to identify the tool as the default-selection mutation.

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 gives a useful prerequisite by saying workspace_revision must come from get_phone_number. However, it does not state when to use this tool instead of update_phone_number or other phone-number tools, nor does it explain any exclusions. Usage context is implied and partially guided, but not fully explicit.

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

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

Annotations only say readOnly=false, destructive=false, idempotent=true; the description goes materially beyond them by asserting the write is progress-bookkeeping only and has no external side effects on payment, plans, or numbers. That is exactly the disambiguation an agent needs before committing a state change during checkout.

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 core action stated first and the side-effect disclaimer second. Every clause earns its place by either defining the action or blocking a misread.

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 only two enum parameters, an output schema present, and annotations covering the safety profile, the remaining need is to prevent conflating a progress write with an actual checkout action — which the description does explicitly. Nothing an agent needs in order to call this correctly is absent.

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 carries the load, and it does enumerate the meaningful values: inbound/outbound intent and checkout/complete/skipped status. It stops short of explaining what 'both' means for intent or why 'checkout' is a distinct state, leaving the enum semantics partly implicit.

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 and resource ('Save only setup progress') and immediately scopes it to the two fields being persisted (intent, checklist status). It also draws a bright line against the payment/number-acquisition siblings, so an agent can distinguish it from claim_phone_number or 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?

It gives clear when-to-use ('choose intent and mark the checklist') and a strong when-not ('never opens payment, buys a plan or acquires a number'), which prevents the most likely misfire toward billing/phone-number tools. What's missing is a positive statement of where in the onboarding flow this belongs and whether it is safe to call repeatedly mid-flow.

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 non-readonly, open-world, idempotent and non-destructive, and the description meaningfully extends that: it names LiveKit test rooms, warns that AI usage may be consumed, and enumerates what it explicitly will not do (dial, publish settings, invoke external tools). The notable gap is lifecycle behavior — with get_agent_test and get_agent_test_listener as siblings, an agent would benefit from knowing the call returns a test handle to poll rather than the result itself.

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 carrying distinct information: what it does, the direction/scenario rule, and the cost/safety boundaries. Front-loaded with the core action and 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 no explanation, and the cost and no-side-effect boundaries are covered. But for a 7-parameter tool with 5 required fields and a nested object, the absence of any hint about the async lifecycle (poll with get_agent_test, cancel with stop_agent_test) and the meaning of request_id leaves real operational gaps.

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%, so the description must carry weight and it only partially does: it clarifies the scenario/direction interaction and the preset-vs-custom split. It says nothing about number_id, revision, request_id (presumably an idempotency key), or the fields inside custom_scenario. responder_outcome is the one parameter the schema itself documents well.

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: runs one isolated synthetic conversation against the active agent settings at a given revision. It also carves out scope against siblings by declaring it never dials a phone number, which separates it from place_call and end_call, and the 'test' framing separates it from get_agent_test/stop_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?

Gives a concrete conditional rule: outbound accepts preset or custom fictional scenarios, inbound requires custom_scenario. That is real routing guidance for the scenario/direction parameters. It stops short of naming a sibling alternative (e.g., place_call for real calls) or stating prerequisites such as the agent needing a completed configuration.

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?

Annotations already declare destructiveHint=true and non-idempotent behavior, but the description adds real context beyond them: revision-based (optimistic-concurrency) writes, a permission gate on locale/voice fields, and a scope boundary ('internal system prompts are not exposed through MCP'). It still doesn't say what happens when the revision is stale or whether omitted fields are cleared, which matters given 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?

Three short sentences, front-loaded with the action and fields before moving to prerequisites and limits. The final sentence on system prompts is slightly tangential but earns its place as a scope boundary, so nothing is truly 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?

For a destructive, non-idempotent mutation with a nested `changes` object and an output schema already declared, the description covers the essentials: what it writes, the revision prerequisite, and permission requirements. The main residual gap is error/staleness behavior on a bad revision and merge-vs-replace 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?

With 0% schema description coverage, the description compensates well by mapping its wording onto the params: profile→changes.name, language→changes.call_locale, voice defaults→changes.voices_by_locale, and revision→the get_account-supplied token. It doesn't clarify whether `changes` is a partial merge or full replacement, nor what a null name or a locales/voices key mismatch means.

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 ('Update supplied profile, language and voice defaults') and enumerates the field groups the tool mutates, so an agent knows exactly what the call changes. It does not explicitly differentiate itself from update_agent, which is the nearest sibling, 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?

It gives a concrete prerequisite ('using the revision from get_account') and a permission condition ('Language and voice defaults require configuration permission'), which tells the agent how to prepare and when the call may fail. It stops short of explicit when-not-to-use guidance or naming alternatives beyond get_account.

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?

Adds real context beyond the annotations: an optimistic-concurrency revision requirement, and the fact that outbound greeting and system instructions are not exposed or editable via MCP at all. It does not disclose whether the `changes` object replaces or merges with existing settings — a meaningful gap given destructiveHint=true and additionalProperties=false.

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?

Four tight sentences with the mutation rule front-loaded, followed by editability constraints and sibling routing. No filler, though 'Apply supplied settings directly' is slightly awkward phrasing for what is a partial patch.

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?

Output schema and annotations cover the return shape and safety profile, and the description supplies the revision prerequisite and the inbound/outbound editability boundary. For a destructive write it should still state merge-vs-replace behavior on the `changes` object to be fully self-sufficient.

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

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

Schema coverage is 100%, so types, enums and the oneOf inbound/outbound split are already documented. The description adds provenance for `revision` and clarifies that greeting/instructions only apply to the inbound branch, but gives no semantics for number_id, direction, or the remaining change fields. Baseline 3 with modest value added.

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 ('Apply supplied settings directly to an agent for future calls') and scopes the mutation to agent-level configuration. It distinguishes itself from set_agent_connectors and place_call by naming them as the correct tools for connections and per-call facts, so an agent can separate this from 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 an explicit prerequisite ('using the revision from get_agent') and routes two adjacent needs elsewhere: external connections to set_agent_connectors, per-call facts to place_call objective/context. It stops short of stating when not to use it (e.g., read-only inspection should use get_agent), but the routing guidance is concrete.

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 safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), and the description usefully adds a boundary they don't convey: credentials are rejected. It says nothing about update semantics, though — whether changes are a partial merge or full replacement, whether omitted fields are cleared, or why a 'destructive' write is reversible or not.

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, ~20 words, no filler. The mutation scope is front-loaded and the credential exclusion follows as a supporting constraint rather than burying the lead.

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, but for a destructive, open-world mutation with 0% schema coverage and a nested object plus an unexplained required request_id, the description is thin. It should have covered update semantics, the request_id's role, and any required permissions or preconditions.

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 only half does: 'name, email or address' maps to three of the nested `changes` fields. The required `request_id` (which looks like an idempotency key, yet idempotentHint is false) is never mentioned, and partial-vs-full update of `changes` is unaddressed.

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 with scope: 'Update the Stripe customer's billing name, email or address.' That clearly names the resource (Stripe billing profile) and the mutable fields, which distinguishes it from most update_* siblings by resource. It stops short of explicitly separating it from the nearest lookalike, update_account, so an agent must still infer which mutator to reach for.

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?

'Payment credentials are never accepted here' is a real exclusion that steers the agent away from using this as a payment-method mutator. However, it never says where to go instead (e.g. create_billing_portal) nor states the precondition that an existing billing profile/customer must exist, so the guidance is implied rather than actionable.

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 is a destructive, non-idempotent mutation, so the description does not need to restate safety basics. The description does add useful context that changes are applied against a number revision, implying versioned updates, but it does not say whether updates are partial merges or replacements, what happens on revision mismatch, or what 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 single sentence is front-loaded and free of filler, with no repetition of annotations or schema metadata. It is appropriately concise, though the terse phrasing around 'number revision' could be clearer.

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 destructive six-parameter update with zero schema parameter descriptions, the description is thin. It does not explain number_id, the revision-based concurrency model, whether unspecified fields remain unchanged, or how to recover from a stale revision; the presence of an output schema offsets only the return-value gap.

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

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

Schema description coverage is 0%, so the description must compensate for six undocumented parameters. It names label, inbound, outbound, retained, and revision conceptually, but omits number_id entirely and gives no detail about optionality, allowed values, or the meaning of revision beyond 'number 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?

The description uses a specific verb, 'Change', and names the settings affected: label, inbound/outbound availability, and retention preference. It is clear what the tool does, but it does not explicitly differentiate this mutation from nearby tools such as get_phone_number_settings or set_default_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 only usage signal is 'using the number revision', which implies a prerequisite but does not explain where to obtain the revision or what happens if it is stale. There is no guidance about when to choose this tool over sibling update or settings tools, nor any when-not-to-use condition.

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

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

Annotations declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description only says "refresh," which reads as a benign status re-check and gives no hint that state may be invalidated or that the call is not safely repeatable. It also omits what happens to an existing verified voice_id and whether support intervention is a side effect of calling or only a fallback.

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 core action is front-loaded. Slight deduction because the second sentence spends words on a downstream support workflow rather than on the call itself.

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 the description leaves key gaps for a non-idempotent, destructive, open-world mutation: no statement of retry behavior, no note on what state changes on the voice, and no clarification of the single undocumented parameter.

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

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

The single parameter voice_id has 0% schema description coverage and is never mentioned in the description, so nothing clarifies whether it is the provider-side voice identifier or the local voice record. The name is largely self-explanatory, keeping this at baseline rather than lower.

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?

"Refresh provider verification status" names a verb and a resource, and it is clearly distinct from siblings like create_voice, delete_voice, and get_voice_preview. However, "refresh" is ambiguous — it does not say whether this re-triggers a check, polls the provider, or mutates the voice's verification state, and "provider" is never defined.

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

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

The description gives no condition for when to call this versus list_voices or get_voice_preview, and no prerequisites. The second sentence describes what happens after the call (user must finish verification with support), which is outcome information, not guidance on when to invoke it.

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