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

Annotations already flag destructive/non-idempotent/write behavior, and the description adds substantial context beyond them: server-side validation rules (/8 width limit, host bits, non-unicast/loopback rejection, no IPv6), the provisioning gate plus confirm requirement, and the return value. This is unusually rich disclosure of side effects and constraints.

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

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

Front-loaded with the purpose plus examples, then attachment, alternative, validation, return value, cleanup, and gating. Every clause carries actionable information with no filler.

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

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

For a 3-parameter mutation tool with an output schema and safety annotations, the description covers purpose, alternatives, attach/remove workflow, validation rejection cases, and the provisioning/confirm gate. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by stating the accepted formats (198.51.100.42, 10.20.30.0/24), the /8 rejection rule, and that confirm must follow explicit user approval. It stops short of explaining the name label semantics that the schema already covers.

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

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

States a specific verb+resource ('Allow-list a public IPv4 address or CIDR range') with concrete examples and the business purpose (static-IP PBX/SBC/carrier trunks without digest credentials). It is clearly distinguished from sibling tools it names, such as create_trunk_credential and delete_ip_acl_entry.

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: attach via update_sip_trunk (ipacl_uuid), use create_trunk_credential instead for dynamic-IP peers, and remove later with delete_ip_acl_entry. Preconditions (VOBIZ_ENABLE_PROVISIONING and confirm: true) are stated as well, so nothing about when/when-not 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, idempotentHint=true and openWorldHint=true, but the description meaningfully extends this: it discloses the server-side env-flag prerequisite, the user-approval gating for confirm, and the cross-tool consequence that send_message will refuse the number with 'opted_out'. The only redundancy is restating idempotency ('adding a number that is already blocked succeeds without change'), which idempotentHint already covers.

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?

Dense single paragraph, front-loaded with the action and endpoint before prerequisites and sibling routing. Every clause carries information, though the sentence is long and could be split for faster scanning.

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, idempotent mutation with an output schema present, the description supplies everything needed to call it correctly: prerequisites, approval gating, idempotent behavior, and routing to siblings. Return values need not be explained since an output schema exists.

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

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

Schema description coverage is 100%, so the schema itself documents reason, channel, confirm with enum and pattern constraints. The description only reinforces the confirm gating condition; it adds no syntax or format detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Block a phone number from receiving messages from this account on a channel') and even cites the endpoint POST /api/v1/sms/opt-outs. It clearly distinguishes itself from the neighboring remove_opt_out and check_opt_out tools, so an agent can select it without consulting either 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 trigger ('for example after a customer asks to stop'), names the reverse operation (remove_opt_out) and the pre-check alternative (check_opt_out) with their respective conditions. Prerequisites (VOBIZ_ENABLE_MESSAGING=true, confirm: true after user approval) are spelled out.

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 and idempotent=true, so the safety profile is covered; the description adds real value beyond that by disclosing the ownership-transfer semantics, the environmental gate (VOBIZ_ENABLE_PROVISIONING), and the confirmation requirement. It does not restate any annotation, but it also doesn't detail the return payload (which the output schema handles).

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 and its consequence in the first sentence, then layers the undo, the lookup helper, the alternative, and the gating condition. Every clause earns its place with no filler.

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

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

For a destructive, gated mutation with full parameter coverage and an output schema, the description supplies everything an agent needs: what changes, the gate, the confirmation requirement, the undo, and the sibling alternatives. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the confirm gating and points to list_sub_accounts as the source for sub_account_id, but these largely duplicate what the detailed schema descriptions already state, so it adds only marginal 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?

Uses a specific verb ('Move a number') with the resource and destination ('to one of its sub-accounts'), and explicitly frames the effect on both parties: the sub-account uses it, the main account no longer does. It clearly differentiates itself from the two nearest siblings, unassign_number_from_subaccount and release_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?

Names the exact undo (unassign_number_from_subaccount), the lookup tool for the required Auth ID (list_sub_accounts), and the alternative for a different intent (release_phone_number to give up the number entirely). This is explicit when-to-use / when-to-use-alternative guidance.

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

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

Annotations cover the safety profile (destructive, idempotent, openWorld), but the description adds substantial context beyond them: immediate charging of setup + first monthly fee to the account balance (parent charged for sub-accounts), the exact ordered precheck list including not_found and VOBIZ_MAX_NUMBER_COST and postpaid balance skip, and idempotency replay semantics. This is exactly the kind of billing/side-effect disclosure that 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?

Dense but front-loaded: the core action and immediate billing consequence lead, followed by prechecks, then alternatives. Every clause carries operational weight, though the description is long and could tighten the precheck enumeration slightly.

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, billed mutation with an output schema present, the description covers billing timing, precheck ordering, idempotency, confirmation, and the sibling workflow. Nothing an agent needs to invoke it safely is missing; return values are correctly left to the output schema.

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

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

Schema description coverage is 100% and the schema already documents confirm, idempotency_key, currency, and phone_number in detail. The description's 'requires confirm: true ... plus an idempotency_key' largely restates the schema rather than adding new per-parameter semantics (e.g. currency behavior is untouched). Baseline 3 applies when the schema does the heavy lifting.

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

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

Opens with a precise verb+resource+scope: 'Buy one phone number from Vobiz inventory and add it to this account.' It distinguishes itself from the obvious siblings by naming search_available_numbers (find candidates), update_phone_number (configure), and release_phone_number (undo). An agent can route correctly 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?

Gives explicit prerequisites and sequencing: find candidates with search_available_numbers first, configure with update_phone_number, undo with release_phone_number, and confirm:true only after showing the user the number and fees. The server-side precheck ordering is spelled out, so the agent knows exactly what conditions must hold before invoking.

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

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

Annotations already disclose readOnly=false, idempotent=true, destructive=true, and openWorld=true. The description adds substantial context beyond those hints: it restores the number to active, refunds the release fee, has a 24-hour validity window, requires re-linking of any detached trunk or application, and is gated by an environment flag and confirm flag. This is exactly the kind of side-effect and prerequisite disclosure that annotations cannot provide.

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

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

Four sentences, front-loaded with the core action and endpoint. Each subsequent sentence adds a distinct operational fact—undo relationship, cooldown window, re-linking requirement, and gating—with no redundancy or filler.

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

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

An output schema exists, so return values need not be explained. The description covers prerequisites, side effects, alternative tool, and required follow-up actions, making it complete for a complex provisioning operation that involves refunds and re-linking.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description mentions the confirm gate and the environment flag, but adds no new syntax or format detail for phone_number beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Keep a number that is in pending_release'), gives the exact endpoint, and explicitly distinguishes itself from the sibling tool by calling itself 'the undo of release_phone_number.' An agent can immediately tell what it does and how it differs from release_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?

Provides clear when-to-use context: the number must be in pending_release, the operation only works during the 24-hour cooldown, and it is gated by VOBIZ_ENABLE_PROVISIONING and confirm: true. It also names the follow-up action (re-link detached trunks/applications with update_phone_number), leaving no ambiguity about prerequisites or post-conditions.

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 and openWorldHint, so the safety profile is covered. The description adds genuine non-obvious behavior: the return is opted_out true/false and the answer is always definite because an unknown number is simply not opted out. It does not mention auth requirements or rate limits, but for a read-only lookup that is a minor omission.

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, all load-bearing: what it does, when to call it, and where to go for the sibling operations. The primary purpose is front-loaded before the alternatives.

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 spelled out, yet the description still states the opted_out true/false shape and the definite-answer guarantee. Combined with explicit sibling routing and a pre-send usage pattern, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% – both parameters are documented in the schema, including the channel enum and the E.164 pattern. The description adds no parameter-level meaning beyond what the schema already supplies, so the baseline 3 applies.

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

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

States a specific verb (check), resource (opt-out list), scope (ONE phone number), and even the endpoint GET /api/v1/sms/opt-outs/{phone}. It explicitly differentiates from list_opt_outs, add_opt_out, and remove_opt_out, so an agent can route 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?

Gives an explicit when-to-use ('call it before send_message to skip a blocked contact instead of handling the opted_out refusal') plus named alternatives for the adjacent jobs (list_opt_outs to enumerate, add_opt_out/remove_opt_out to modify). This is a complete routing rule.

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

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

Goes well beyond the destructiveHint/openWorldHint/idempotentHint annotations by disclosing the feature gate, the explicit user-approval requirement, the https/approved-host constraint on every URL, and the concrete hazard that each retry after a timeout creates another application. That last point is exactly the kind of non-idempotency detail an agent needs and the annotation 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-loaded with the purpose and kept to two sentences, but the second sentence is very dense, stacking linking, the alternative tool, gating, the confirm flag, and the retry hazard. Efficient overall, though a bulleted split would read better.

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 it still notes the app_id. For a 10-parameter destructive, non-idempotent creation tool with a feature gate, the description covers approval, preconditions, linking follow-up, and retry safety — nothing an agent needs is missing.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters in detail. The description consolidates a few facts (only app_name and answer_url required, hangup_url defaults to answer_url, all URLs must be https on an approved host) but it largely restates what the schema properties already say. Baseline 3 is appropriate.

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

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

States a specific verb+resource and then defines the resource concretely: 'the set of webhook URLs Vobiz calls for inbound calls on the numbers and SIP endpoints linked to it.' This lets an agent distinguish it from update_application and create_sip_endpoint 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?

Explicitly routes alternatives: use update_application to change an existing app, and link afterwards via update_phone_number(application_id) or create_sip_endpoint(application_id). It also states preconditions (VOBIZ_ENABLE_PROVISIONING, confirm:true) and a recovery path after timeouts (check list_applications before retrying).

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: host validation rules (public FQDN/IPv4 only, private/loopback/.local rejected), the fact that weight and transport are set elsewhere, the return value (id), and the critical non-idempotency warning that every call adds a URI so retries should list first. This is exactly the behavioral context an agent needs for a destructive, non-idempotent write.

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?

Dense but front-loaded: the purpose and example come first, then routing/priority guidance, then constraints, then gating and retry safety. Every sentence carries operational information with no filler.

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

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

Covers host validation, gating, non-idempotency, and retry guidance; the output schema already carries return details, and the description still notes the returned id. Nothing an agent needs to invoke this 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 all four parameters are already fully documented, and the description's priority explanation largely repeats the schema. The note that weight and transport are console-only adds scope clarity but is not parameter semantics per se, so the baseline 3 stands.

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 (Add) and resource (SIP origination URI) with a concrete example 'sip:sbc.example.com:5060', and distinguishes itself from siblings by naming update_sip_trunk and list_origination_uris. An agent immediately understands this creates an outbound routing destination.

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 says when to use which priority (1 = primary, 2+ = failover), how to attach the result to a trunk, and when to check list_origination_uris before retrying. It also names the gating conditions (VOBIZ_ENABLE_PROVISIONING, confirm: true), leaving little 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 declare destructive/non-idempotent/openWorld, and the description adds non-obvious behavior beyond that: the username is immutable after creation, the password is write-only and never returned, a feature-flag gate applies, and repeated calls create duplicate endpoints. This is exactly the mutation/irreversibility context an agent needs before invoking.

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?

Five tight sentences, front-loaded with purpose and use case, then attach behavior, immutability, return values, gating, and retry guidance. No filler or restatement of the tool name; every sentence carries actionable content.

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

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

Covers the full picture for a gated, destructive, non-idempotent creation tool: prerequisites, immutability, secret handling, defaults, duplicate risk, and where to look on retry. With an output schema present it does not need to detail return values, yet still names them usefully.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the immutability of username, the write-only nature of password, and the fallback semantics for application_id ('otherwise the account's default endpoint application applies, if set'). It does not, however, clarify the alias/confirm fields beyond what the schema already documents.

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

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

States a specific verb+resource ('Create a Vobiz SIP endpoint') and immediately scopes it to the concrete use case (soft-phone, desk phone, WebRTC client registering at registrar.vobiz.ai). It explicitly names the sibling it is not (update_sip_endpoint) and distinguishes itself from list_sip_endpoints, so an agent can route without opening either 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 explicit when-to-use, when-not-to-use ('use update_sip_endpoint for everything else'), and a retry/duplicate hazard rule ('every call creates another endpoint, so a retry after a timeout should first check list_sip_endpoints'). Preconditions (VOBIZ_ENABLE_PROVISIONING, confirm: true) are stated inline.

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

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

Beyond the annotations, the description discloses provisioning gating (VOBIZ_ENABLE_PROVISIONING and confirm: true), non-idempotency ('every call creates another trunk'), retry guidance, and that credential fields are redacted in the response. This adds substantial behavioral context while remaining consistent with annotations like destructiveHint=true and idempotentHint=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?

The description is dense but well front-loaded, leading with the core action and then layering prerequisites, defaults, auth, routing, gating, and retry advice. For a 19-parameter creation tool, every sentence contributes operational value without filler.

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

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

The tool is complex, but the description covers the essential workflow: required fields, defaults, dependency ordering, auth options, outbound routing, post-create routing, gating, and retry safety. Since an output schema exists, return-value details do not need fuller explanation beyond the redaction note.

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

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

Schema description coverage is 100%, so the schema already documents each parameter in detail. The description still adds cross-parameter meaning, such as authenticating with credential_uuid and/or ipacl_uuid and routing via primary_uri_uuid with fallback_uri_uuid, plus the defaults for transport, secure, and cps_limit.

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

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

The description states a specific verb and resource: 'Create a SIP trunk on this Vobiz account', then details the resources it provisions (voice gateway, SIP domain, authentication, call limits, outbound routing). This clearly distinguishes it from siblings like update_sip_trunk, delete_sip_trunk, and create_sip_endpoint.

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

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

It explicitly explains what is required ('Only name is required'), gives defaults, and instructs on prerequisites by naming create_trunk_credential, add_ip_acl_entry, and create_origination_uri. It also covers post-creation routing with update_phone_number and retry behavior after timeouts, naming list_sip_trunks as the check.

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 the write/destructive/open-world profile, but the description goes well beyond them: it discloses the VOBIZ_ENABLE_PROVISIONING feature gate, the confirm:true requirement, the main-account (MA_) credential requirement, that credentials are never returned here, and that KYC must be completed before calls flow. That is exactly the operational context annotations cannot carry.

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 and the primary alternative are front-loaded, and each remaining clause (KYC flow, return contents, gating, credentials) earns its place. The middle sentences are dense and slightly run-on, but 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?

For a 10-parameter creation tool with nested permissions and enums, the description covers the decision path, the prerequisites, the gating, and the KYC dependency. An output schema exists, so its brief return note is a bonus rather than a gap.

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

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

Schema description coverage is 100%, so every parameter is already documented, including the email-required-for-customer_use condition. The description restates the same key constraint but adds no format, default, or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a new Vobiz sub-account under this main account') and immediately bounds the scope with 'only name is required'. It also distinguishes itself from update_sub_account and create_sub_account_kyc_session, so an agent can route 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?

Explicitly says when to use a sibling instead ('to change an existing one use update_sub_account') and names create_sub_account_kyc_session as the follow-up path when kyc_mode is customer_use. The conditional 'customer_use needs email' is tied directly to a parameter value, leaving nothing 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 the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false) and the description is consistent with them. Beyond that, the description adds real behavioral context: gating by the VOBIZ_ENABLE_PROVISIONING flag, the requirement for explicit user approval before confirm: true, main-account (MA_) credentials, webhook event delivery, and the returned next_step hint. It does not disclose rate limits or failure modes, so not a full 5.

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

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

Front-loaded with the core action, then the two flow modes, then prerequisites and gating. Dense semicolon-chained sentences pack in a lot of information efficiently, though the last sentence's stacking of gating, confirm, and credential requirements is slightly crowded.

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

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

For a 7-parameter, side-effecting provisioning tool with an output schema already present, the description covers everything the caller needs: mode selection, per-mode required inputs, optional webhook, prerequisites (flag, confirm, MA_ credentials), and the follow-up tool for progress. Return values are correctly left to the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the flow_type default and the customer_email/redirect_url dependencies, which the schema already documents per-parameter; it adds little genuine meaning beyond reinforcing the flow-type coupling.

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 ('Start a Vobiz-hosted KYC session for a sub-account') and distinguishes itself from the sibling get_sub_account_kyc_status by naming that tool as the progress-tracking follow-up. An agent can tell it apart from create_sub_account and get_sub_account 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?

Clearly explains the two operating modes and the conditions that select them (email default vs redirect requiring redirect_url), plus the follow-up call for tracking status. It stops short of explicit exclusions ('do not use if KYC already verified'), so it is strong context rather than full when/when-not guidance.

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

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

Goes well beyond the annotations by disclosing the VOBIZ_ENABLE_PROVISIONING + confirm:true gate, that the password is write-only and never returned, that every call creates a new credential (so a timeout retry should first check list_trunk_credentials), and the permanence of the username. These are non-obvious destructive/idempotency details an agent could not 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?

Dense but every sentence carries an actionable fact, and the identifying verb+resource is front-loaded. Slightly information-heavy in one block, but no filler.

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

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

For a destructive, gated mutation with an output schema, the description covers safety gates, side effects, alternatives, and follow-up steps. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100%, so the schema already documents all three parameters well. The description still adds meaning beyond the schema by characterizing the password as write-only/never returned and the username as permanent, reinforcing constraint semantics.

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

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

States a specific verb (Create) and resource (SIP digest credential for trunk authentication) with the scope of context (dynamic-IP PBXs, remote sites, voice agents). It clearly distinguishes itself from siblings like add_ip_acl_entry and update_sip_trunk.

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 names when to use it, the alternative for the opposite case ('for static-IP peers use add_ip_acl_entry instead'), the follow-up action ('attach it to a trunk afterwards with update_sip_trunk'), and the rotation path ('rotate the password with update_trunk_credential'). Nothing 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 the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description adds value beyond them: the exact semantic effect on audio flow, and the error behavior ('a room that is not running, or a member who already left, returns the not_found error'). Endpoint is disclosed too. Missing only auth/rate-limit context.

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

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

Front-loads the action and its effect, then usage, then undo, then the error case. Every sentence earns its place with no redundancy.

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

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

With an output schema present, return values need not be explained, and the description still covers the effect, batch semantics, undo path, and failure condition. 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 coverage is 100%, so the schema with its pattern and description already documents both parameters thoroughly. The description reinforces member_id's batch usage ('one member_id, a comma-separated list, or all') but adds no syntax or format beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Deafen) and resource (members of a live Vobiz conference) plus the exact effect: 'they stop hearing the room; others still hear them.' This effect clause cleanly distinguishes it from mute_conference_member, which the sibling list contains.

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 use cases ('listen-only setups or private side conversations') and names the inverse tool for undo ('undeafen_conference_member'). It does not explicitly contrast with mute_conference_member, but the stated effect implies the distinction, so the guidance is clear without being exhaustive.

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=true, but the description adds material context beyond them: irreversibility, the 409-on-linked-numbers failure mode, cascade being off so SIP endpoints survive but become orphaned, not_found for a bad app_id, and the VOBIZ_ENABLE_PROVISIONING + confirm gating. This is exactly the pre-flight information 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?

Dense but front-loaded: the irreversible nature leads, then failure modes, then side effects, then the alternative, then gating. Every clause carries distinct operational information, though the run-on structure of the middle sentences packs several facts per clause and could be split for scanning.

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 description covers what remains: prerequisites, error behavior, non-cascading effects, and environment/auth gating. Nothing an agent must know to call this destructively and correctly is missing.

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

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

Schema coverage is 100% and both params are already documented, so the baseline is 3. The description still adds value the schema does not: that an unknown app_id surfaces as not_found, and that confirm: true is enforced server-side and gated by VOBIZ_ENABLE_PROVISIONING. Minor edge-case detail (no id format example in prose) keeps it off a 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?

Opens with a specific verb+resource+scope: "Permanently delete a Vobiz voice application; this cannot be undone." That cleanly separates it from update_application, get_application, and the other delete_* siblings in this account (delete_sip_endpoint, delete_sub_account, delete_recording), which are each named as distinct resources.

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 states the prerequisite (unlink numbers via update_phone_number first, else HTTP 409) and names the alternative path for the non-destructive case: "To stop using an application without deleting it, re-point its numbers instead." It also warns that attached SIP endpoints are not cascaded and require update_sip_endpoint, so the agent knows the follow-up call sequence.

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=true, and the description adds substantial context beyond them: the deletion 'cannot be undone', affected SIP traffic loses trust and needs digest credentials, the change is eventually consistent at the SIP edge, and unrelated auth on referencing trunks is preserved. It also discloses the not_found error and the environment gate.

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 consequence in the first clause, and every subsequent clause carries distinct information (irreversibility, SIP impact, propagation, trunk behavior, error, gating). It is dense and semi-colon heavy but not 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?

With an output schema present, return values need no explanation. The description covers the safety profile, the environment gate, the confirm requirement, the error case, and the eventual-consistency caveat — everything an agent needs to invoke this destructive tool correctly.

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

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

Schema coverage is 100%, so both parameters are already documented, including the not_found behavior on ip_acl_id and the confirm approval semantics. The description reinforces but does not extend the schema's parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (Remove) and resource (IP ACL entry) scoped to 'this Vobiz account', and anchors it against a named sibling by noting it 'reverses add_ip_acl_entry'. An agent can distinguish it from add_ip_acl_entry and update_ip_acl_entry 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?

Provides explicit prerequisites: gated by VOBIZ_ENABLE_PROVISIONING and confirm: true, and frames it as the inverse of add_ip_acl_entry. It does not explicitly contrast against update_ip_acl_entry or state when not to delete, so it stops short of 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 mark this destructive and non-readOnly, but the description adds real substance beyond them: the deletion is irreversible, the operational consequence is that trunks stop routing outbound calls to that destination, and an unknown uri_id raises not_found. That is exactly the kind of blast-radius and error 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?

Irreversibility is front-loaded in the first clause, then consequences, then the remediation path, then gates. No sentence is filler and the ordering follows the order an agent needs the information.

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

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

A destructive, gated mutation with an output schema; the description covers risk, consequence, preconditions, error behavior and required confirmation. Nothing material is left for the agent to infer before calling.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description reinforces the gating semantics ('Gated by ... confirm: true') and the not_found behavior for uri_id, tying the parameters to the failure and safety model rather than just restating types.

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 (Delete) and resource (origination URI) scoped to 'this Vobiz account', and immediately flags irreversibility. It is trivially distinguishable from the sibling create_origination_uri, update_origination_uri and list_origination_uris.

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 precondition ('if it is a trunk's only route') and names the alternative tools to run first (create_origination_uri, update_sip_trunk). It also states the enablement gates (VOBIZ_ENABLE_PROVISIONING, confirm: true), so the agent knows when the call will even succeed.

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, but the description adds meaningful context beyond them: irreversibility ('audio file cannot be restored afterwards'), the feature-flag gate, the confirm requirement, and the not_found error behavior. This is exactly the extra disclosure a mutation tool needs.

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 and its permanence, then adds alternatives, error behavior, and gating in tightly packed but non-redundant sentences. Every clause carries distinct information; nothing is filler.

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

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

With an output schema present, return values need no explanation, and annotations plus 100% schema coverage handle safety and parameters. The description still covers irreversibility, gating, confirmation, alternatives, and error behavior, leaving no meaningful gap for an agent calling this 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 100%, and the schema itself fully documents both confirm (approval attestation) and recording_id (source and pattern). The description only reiterates 'confirm: true' and the ID sources, so it adds little beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Permanently delete one call recording') with the underlying API call, and explicitly distinguishes itself from sibling tools get_call_recording (fetch/play) and list_recordings (find IDs). An agent can tell exactly what this does and does not do 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?

Explicitly routes adjacent tasks to alternatives ('to fetch or play use get_call_recording; to find IDs use list_recordings') and states the gating condition (VOBIZ_ENABLE_PROVISIONING and confirm: true). It also notes the not_found failure for stale IDs, so the agent knows what happens when the precondition is wrong.

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: it discloses the concrete blast radius (registered devices disconnect immediately, SIP URI stops working, username becomes reusable), the error behavior (not_found), and the feature-flag plus confirmation gating. The annotations only say destructive/idempotent; the description supplies the operational consequences.

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 clauses, front-loaded with the destructive action and its consequence, then the alternative, then error and gating notes. 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?

For a destructive 2-param tool with an output schema, everything needed to call it correctly is present: impact, alternative, error case, and authorization/confirmation gates. Return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so the schema already documents both endpoint_id and confirm. The description reinforces the confirm gating and the not_found behavior for unknown ids but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Opens with a specific verb+resource ("Permanently delete a Vobiz SIP endpoint") and immediately states irreversibility. The scope is distinct from delete_sip_trunk and from update_sip_endpoint, which it names as the 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?

Explicitly states when NOT to use it ("To block a device temporarily, change its password with update_sip_endpoint instead") and names the gating conditions (VOBIZ_ENABLE_PROVISIONING and confirm: true). Both the alternative and the prerequisites are spelled out.

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: discloses that the delete is soft, what disappears, what is preserved (account-level credentials, IP ACL entries, origination URIs are kept), the not_found behavior for unknown ids, and the env/confirm gating. This is exactly the extra context annotations cannot carry.

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

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

Every sentence earns its place, and the primary effect (soft-delete) is front-loaded ahead of the preservation details, the alternative, and the gating. No filler or redundancy despite covering a lot of ground.

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 tool with an output schema, all the decision-relevant information is present: effects, side effects, what survives, error behavior, safety gating, and the non-destructive alternative. Nothing an agent needs before invoking it 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, but the description adds value the schema lacks: the not_found outcome for an unknown trunk_id and the runtime gating tied to confirm. It does not restate the UUID format or the elicitation semantics, which the schema already covers.

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

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

States a specific verb (soft-delete) and resource (Vobiz SIP trunk), then spells out the concrete effects: disappears from list_sip_trunks, SIP domain stops accepting calls, routed numbers unlinked. This clearly distinguishes it from update_sip_trunk and from the credential/ACL/origination deletion tools that are named as 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?

Explicitly names the alternative and the condition that selects it: 'To pause a trunk and keep its configuration, use update_sip_trunk with trunk_status: disabled instead.' It also states the gating prerequisites (VOBIZ_ENABLE_PROVISIONING and confirm: true), so the agent knows both when to use it and when not to.

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, but the description goes further by spelling out what is actually destroyed ('anything using its Auth ID stops working') and that the action cannot be undone. It additionally discloses two operational gates (environment flag and explicit confirm) that annotations do not convey.

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

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

Three sentences, front-loaded with the destructive action and its irreversibility, then routing to the alternative, then prerequisites. No sentence is filler and each carries distinct information.

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

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

An output schema exists, so return values need no explanation, and the description covers the safety profile, the alternative route, and the auth/gating prerequisites for a two-parameter destructive tool. Nothing an agent needs to decide or execute the call correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already fully documented in the schema, including the SA_ pattern and the confirm semantics. The description reiterates the confirm/credential requirements but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Permanently delete a Vobiz sub-account') plus the consequential side effect ('revoke its credentials'). It clearly distinguishes itself from the sibling mutation update_sub_account, which 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?

It names the non-destructive alternative and the exact condition that selects it ('To take a sub-account out of use while keeping it, use update_sub_account with enabled: false instead'). It also states the preconditions for use: the VOBIZ_ENABLE_PROVISIONING gate, confirm: true, and MA_ credentials.

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 destructiveHint=true, the description discloses that the delete is irreversible, that authenticating PBX/devices are refused afterwards, that referencing trunks lose the credential, that Vobiz may refuse while calls are active, and that unknown ids raise not_found. The only nuance is that a repeated delete raising not_found sits in mild tension with idempotentHint=true, but the safety-critical behavior is fully disclosed.

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

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

Front-loaded with the irreversible consequence, and every clause (side effects, alternative, error, gating) earns its place. It is a single dense semicolon-chained sentence, which is efficient but slightly harder to scan than a short split would be.

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 provisioned delete with annotations covering the safety profile and an output schema covering returns, the description supplies the consequences, the safer alternative, the error case, and the gating flags. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by tying confirm: true to the gating requirement and by stating that an unknown credential_id raises not_found. It does not add format or syntax beyond the schema, which is already complete.

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 ("Delete a trunk credential from this Vobiz account") and immediately distinguishes this from the sibling update_trunk_credential. An agent can identify the operation and its scope 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?

Explicitly names the alternative and the condition that selects it: "To pause access and keep the credential, use update_trunk_credential with enabled: false." It also states the confirm requirement and the VOBIZ_ENABLE_PROVISIONING gate, leaving nothing 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 flag destructiveHint and idempotentHint, but the description adds valuable specifics: the blast radius (all members of all rooms disconnected) and the mandatory confirmation gate tied to explicit user consent. It does not discuss reversibility or rate/account limits, but the added context meaningfully exceeds the annotation baseline.

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: effect first, then exclusion/alternative, then the hard precondition. Every sentence earns its place with no filler.

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

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

For a one-parameter destructive tool with an output schema present, the description covers effect, scope, alternative, and the confirmation requirement. 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?

Schema description coverage is 100% and the single parameter's meaning is already documented in the schema. The description restates the confirmation requirement but adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (hang up), the resource (every running conference room), and the scope (account-wide, all members of all rooms disconnected). It also names the sibling it is not (end_conference), so an agent can distinguish the two conference-termination tools immediately.

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 says when to use it (account-wide cleanup or maintenance only) and routes single-room closure to end_conference. It also states the precondition for confirm: true (user must explicitly agree first), leaving nothing 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 cover the safety profile (destructive, non-readOnly, openWorld), and the description adds genuinely new context: the blast radius (terminates for every party), the live/queued precheck, and the two distinct failure modes (call_not_active, not_found). This goes well beyond what the annotations convey.

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

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

Four tight sentences, front-loaded with the action and scope, then alternatives, then preconditions, then error behavior. No filler and 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?

For a destructive two-parameter tool with full schema coverage, an output schema, and full annotations, this description supplies the remaining gaps: scope of termination, preconditions, and error semantics. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the confirm semantics. The description restates the confirm requirement without adding syntax or format detail beyond the schema — the baseline 3 applies.

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

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

States a specific verb and resource (terminate a call), the exact scope (active or queued, for every party on it), and even the underlying endpoint. It distinguishes itself from transfer_call and hold_call, which are named directly.

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 alternatives are named with their selecting conditions (move the call → transfer_call; park a leg → hold_call), and the precondition for invocation is spelled out (confirm: true only after the user explicitly asked to end this call).

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is partly carried. The description adds real context beyond them: the blast radius (all members disconnected, room ends), the confirm gate, and the not_found error for a non-running room. It stops short of describing the response payload, but the output schema covers that.

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

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

Three tight sentences, front-loaded with the destructive scope, then the alternatives, then the prerequisite and error case. Every sentence earns its place and none is redundant filler.

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

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

For a destructive, single-target tool with an output schema, the description covers scope, alternatives, the confirm prerequisite, and the not_found failure mode. An agent has everything needed to invoke it correctly; return values are handled by the output schema.

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

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

Schema description coverage is 100%, so both parameters (confirm, conference_name) are fully documented in the schema; baseline 3 applies. The description restates 'Requires confirm: true' but adds no naming syntax or format detail beyond the schema's pattern and description.

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

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

States a specific verb and resource ('Hang up one running Vobiz conference room ... DELETE /Conference/{name}/') and immediately distinguishes scope: the whole room ends and every member is disconnected at once. An agent can tell this apart from kick_conference_member/hangup_conference_member without opening either 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?

Explicitly names when to use it ('close a meeting on time or clean up an abandoned room') and routes to the alternatives for the partial case ('to remove only some people, use kick_conference_member or hangup_conference_member'). Nothing 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?

Far exceeds the annotation bar: digits are posted back, signature-checked and stored, read via get_gather_result with flow_id; a live transfer replaces and stops the call's current flow; input-ending conditions (num_digits, finish_on_key, digit_end_timeout) and post-input `then` behavior; the timeout path leaves get_gather_result reporting waiting; step TTL of 24h; HTTP mode requires VOBIZ_PUBLIC_URL. This is unusually rich behavioral disclosure.

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 purpose and creation, then live-transfer usage, then termination conditions, then alternatives. Dense and generally efficient, though a few sentences are long and clause-heavy, and the 24h/HTTP-mode constraints are appended without a clear structural break.

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 required, and the description still covers creation vs. live-transfer modes, the result-retrieval path, timeout semantics, and environment prerequisites. Nothing needed to call it correctly appears missing.

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

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

Schema description coverage is 100% (baseline 3), but the description adds meaning beyond it by explaining how num_digits, finish_on_key, and digit_end_timeout interact to terminate input, that the default `then` says 'Thank you' and hangs up, and that confirm:true is what makes the transfer destructive. That elevates it above the schema-only baseline.

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

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

States a specific verb and resource: 'Create a hosted IVR step that plays a prompt and collects keypad (DTMF) digits with Vobiz <Gather>'. It explicitly distinguishes itself from siblings send_dtmf (to press keys on a remote IVR) and generate_answer_xml (for free-form flows), and names get_gather_result as the reader of the result.

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 explicit selection criteria: pass call_uuid + confirm:true to move a LIVE call into the step now, or use the returned url as make_call answer_url / unhold_call resume_url for a call not yet up. It also names two alternatives (send_dtmf, generate_answer_xml) with the conditions that select them.

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

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

With annotations already declaring readOnlyHint/openWorldHint, the description still adds substantial behavior: XML escaping, approved callback/redirect hosts, dial destination policy (countries, blocked prefixes, allowlist), rejection of actions after redirect/hangup with invalid_input, and the 24-hour hosting lifetime plus flow_id for get_gather_result. The one tension is that hosting creates server-side state for 24 hours, which sits awkwardly with readOnlyHint=true — though the default no-host mode is a pure read/build, so this reads as a qualification rather than a 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?

Front-loaded with the core purpose and action list, and nearly every remaining clause carries load-bearing information (escaping, host allowlist, dial policy, redirect/hangup ordering rule, sibling routing). It is dense — one long paragraph with a couple of run-on clauses — but not 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?

For a complex validator/builder tool with an output schema present, the definition covers the build contract, validation failure modes, mode-dependent return (XML vs url+flow_id), and downstream consumption. Nothing an agent needs in order to call it correctly — or to predict a validation error — 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 documents `host` and the actions array in detail, so the baseline is met by structure. The description still adds non-schema meaning: why `host` matters (works in stdio without it; requires VOBIZ_PUBLIC_URL in HTTP mode), the ordered-execution model, and the validation rules that constrain `url`, dial `number`, and terminal actions.

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: 'Build a validated VobizXML document from an ordered list of actions', then enumerates every supported action type (speak, play, wait, gather, record, dial, redirect, hangup). An agent can immediately tell this apart from the step-specific sibling gather_dtmf.

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 states the alternative and the condition selecting it: 'For a simple keypad menu prefer gather_dtmf, which builds the step for you; this is the general builder.' It also gives the when-to-use split for `host` (stdio/XML-only vs HTTP/hosted) and names the concrete consumers of the returned url (make_call answer_url, transfer_call aleg_url, unhold_call resume_url).

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

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

Annotations already establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral nuance beyond that: when no currency is given the first wallet is repeated as `balance`, and billing can span INR/USD or other currencies — details an agent would otherwise have to discover empirically.

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?

Dense but orderly: the endpoint and return fields are front-loaded, the currency conditional follows, and the sibling pointer closes it out. No sentence is filler.

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

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

For a one-parameter read tool with an output schema present, the description supplies everything an agent needs: what comes back, how the currency flag changes the shape, and where to go for related data. Nothing material is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented, so the baseline is 3. The description goes further by explaining the observable effect of omitting currency (all wallets plus a duplicated first entry in `balance`), which is semantic behavior the schema does not state.

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

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

The description gives a specific verb and resource ('Return this account's wallet balance'), names the endpoint, and enumerates the returned fields. It also differentiates itself from list_transactions, so an agent can place it among the account-related siblings 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?

It gives clear conditional guidance for the two call modes (omit currency to get all wallets, supply currency for one) and routes the agent to list_transactions for the charges and top-ups behind the balance. No explicit 'when not to use' case is stated, but the practical context is well covered.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial context beyond them: credential-scope authorization rules, the specific failure mode for SA_ credentials, and the fact that auth tokens and secrets are returned as '[redacted]'. This is exactly the behavioral detail an agent needs before invoking.

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, all load-bearing: the first defines the resource and payload, the second covers redaction, the third covers auth failure mode and alternatives. The routing information is front-loaded with no filler.

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

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

An output schema exists, so return-shape explanation is not required, and the description still summarizes the fields plus the redaction behavior. Combined with the explicit auth constraints and sibling routing, nothing an agent needs to call this 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, so the baseline is 4; there is no parameter syntax or meaning for the description to add. The endpoint reference (GET /Account/{id}) hints at the implicit account identity, but no argument is exposed to document.

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 ('Return this Vobiz account's profile') and enumerates the exact fields returned (name, account type, status, CPS/concurrent-call limits, enabled features). It explicitly distinguishes itself from the closest siblings, get_account_balance and get_concurrency, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-not guidance: only main-account (MA_) credentials can read it, while sub-account (SA_) credentials return a forbidden error and should fall back to get_account_balance, get_concurrency or list_phone_numbers. It also names the two alternatives to use for money and live call capacity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the not_found error for foreign app_ids, the scope exclusion of linked numbers, and functional meaning for key fields (answer_url is where Vobiz fetches VobizXML, sip_uri dials the application directly). It stops short of auth or rate-limit detail, so not a 5.

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

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

Front-loaded with the core action and the lookup key, then the alternatives. It is dense but every sentence earns its place; however the long mid-sentence field enumeration partly duplicates the output schema, making it longer than strictly necessary.

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 read tool with annotations and an output schema, the description covers the remaining agent needs: the alternatives for discovery, the linked-number exclusion, and the exact failure condition. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100% and the single app_id parameter already documents the numeric format, its source, and the not_found failure mode. The description restates the 'by app_id' selector but adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return one Vobiz voice application's full configuration by app_id') and enumerates the configuration surface returned. It also explicitly carves out what it is not ('linked numbers are not included'), which separates it from list_phone_numbers and list_applications.

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 explicit routing: use list_applications to find the id or to view several applications, and use list_phone_numbers for linked numbers. It also names the precondition for success (the app must belong to this 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile, yet the description adds genuinely new behavior: an unknown call or stream fails with not_found, and streams of older calls may no longer be retrievable. That error and retention context is valuable beyond the annotations, though return formatting/pagination isn't addressed.

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, front-loaded with the operation and returned fields, then alternatives and error behavior. Dense and purposeful, though the field enumeration and error clause make it slightly longer than strictly necessary.

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 description still covers purpose, alternatives, and failure modes. For a simple two-parameter read tool, an agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so both call_uuid and stream_id already carry origin and pattern documentation. The description adds no additional parameter semantics such as formats or constraints beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource (return one audio stream on a Vobiz call), enumerates the returned fields, and names the endpoint. It clearly differentiates itself from list_audio_streams (all streams) and stop_audio_stream (end one).

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

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

It explicitly states when to use it (check whether a stream you started is still running or when it ended) and routes the agent to the correct alternatives for other needs: list_audio_streams for every stream, stop_audio_stream to end one. Nothing 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 readOnlyHint=true, so safety is covered. The description adds genuinely non-obvious behavior: the cross-account not_found error and the polling-for-progress pattern. It does not cover rate limits or auth, so it stops short of a 5.

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

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

Front-loaded with the purpose, but the long inline enumeration of every returned field (total, pending, sent, delivered, failed, optedOut, skipped) partly duplicates the output schema. Three sentences remain efficient overall.

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

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

Because an output schema exists, enumerating return fields is redundant rather than additive. The description nonetheless includes the error semantics and polling guidance an agent needs, so it is essentially complete for a one-param read tool.

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

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

Schema description coverage is 100% and the single parameter is fully documented there (including its pattern). The description only restates the domain of valid ids and the failure mode, so the baseline 3 is appropriate.

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

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

States a specific verb (return) and resource (one broadcast) with the endpoint, and names the singular/plural distinction against list_broadcasts. An agent can tell it apart from the sibling listing tool 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?

"Poll it while a broadcast is running to follow progress" gives explicit when-to-use, and "find ids with list_broadcasts" routes to the correct alternative when the id is unknown. The not_found condition for out-of-account ids is stated explicitly.

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 declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the not_found behavior, eventual-consistency delay for recently ended calls, and a security warning that third-party-authored text in the output (message bodies, caller names, speech) must be treated as data, not instructions. That last point is exactly the kind of behavioral context structured fields 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 resource and returned fields, then routes to alternatives, then states error/freshness behavior, then the safety note. It is dense but each sentence carries a distinct, load-bearing fact; only the field enumeration is slightly long given an output schema exists.

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

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

For a single-parameter read tool with full schema coverage, an output schema, and read-only annotations, the description supplies everything an agent needs: what it returns, when to prefer siblings, error semantics, timing caveat, and a prompt-injection precaution. Nothing material 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 explains that call_uuid comes from make_call's request_uuid or list_call_records, so the baseline is 3. The description adds meaning beyond the schema by constraining the parameter to COMPLETED calls and noting that unknown/active UUIDs produce not_found, which helps the agent avoid misuse.

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 (return) and resource (full CDR of one COMPLETED call by call_uuid) and enumerates the fields returned, including derived fields (outcome, retry_may_succeed). It explicitly names and contrasts the two nearest siblings (get_call_status, list_call_records), so an agent can route 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 explicit when-to-use-this vs. when-to-use-alternatives: ringing/connected calls go to get_call_status, lookups by number/date/hangup cause go to list_call_records. It also states the exclusion condition (unknown or still-active call_uuid returns not_found) and the freshness caveat for just-ended calls.

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

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

Annotations declare read-only/open-world, but the description adds non-obvious behavior the annotation cannot: unrecorded or unknown call_uuid returns ok with count 0 while an unknown recording_id returns not_found, and the cardinality cap of 20. It also flags the security sensitivity of recording URLs.

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 verb+resource+endpoint, then the parameter rule, then edge-case return behavior, then the alternative tool, then the security caveat. Dense but every sentence earns its place with no filler.

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

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

With an output schema present, return-shape detail is not needed, and the description still covers selection rules, edge-case responses, sibling routing, and the sensitive-data caveat. Fully sufficient for an agent to call it correctly.

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

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

Schema coverage is 100% so the parameter docs already exist, but the description adds meaning beyond the schema by stating cardinality ('every recording of that call, up to 20' for call_uuid vs 'that one recording' for recording_id) and the mutual-exclusivity rule, which the schema only hints at.

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 ('find the recording(s)'), the exact resource ('of one call on this account'), and what is returned ('metadata and recording_url'), plus the underlying GET /Recording/ endpoint. It is clearly distinguishable from list_recordings and get_call_details.

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 the explicit selection rule ('pass exactly one of call_uuid or recording_id') with the semantic difference between them, and names the alternative tool and its condition ('to browse recordings across calls or by date use list_recordings'). Nothing 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 only declare readOnly/openWorld, but the description adds real behavioral context beyond them: the lookup resolution order (Vobiz live, then queued, then records), the eventually-consistent window where a just-ended call returns not_found, the response shape for live/queued calls (`call` object), and a prompt-injection warning about third-party-written text.

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

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

The purpose and the three lifecycle states come first, then usage routing, then the operational gotcha and return-shape note, ending with the security caveat. Every sentence carries information an agent needs; nothing is padding.

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

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

An output schema exists, yet the description still contextualizes the not_found race and the `call` wrapper. Combined with explicit alternatives, polling guidance and the third-party-text caveat, an agent has everything needed to call this 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 coverage is 100% so the parameter is already documented, but the description adds meaningful semantic linking that the schema lacks: that the request_uuid returned by make_call is passed as call_uuid, and that UUIDs can come from list_live_calls or list_call_records.

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 (return the lifecycle state of ONE call) and enumerates the exact states returned with their meanings (queued, live, completed). It distinguishes itself from get_call_details and list_live_calls by name, so an agent can pick 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?

Explicitly names the primary use case (following a call placed with make_call, passing its request_uuid as call_uuid) and routes the agent elsewhere for adjacent needs: get_call_details for the full billing record, list_live_calls for every in-progress UUID. It also gives the polling cadence (every few seconds).

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 and openWorldHint, so the safety profile is covered. The description adds meaningful context beyond that: it clarifies the tool returns a count rather than a list and that it is useful as a pre-flight check before make_call batches, which is a real behavioral/workflow trait.

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: capability first, then the disambiguation from the list sibling, then the pre-batch usage tip. Every sentence earns its place and the most important scoping fact is front-loaded.

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

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

Output schema exists, so return-value detail is not required, yet the description still names the key fields (concurrent_calls, max_concurrent, utilization_pct) at a glance. Combined with annotations and the sibling routing, an agent has everything needed to call this correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly signals a parameterless account-level query rather than implying any filter 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 ('Return this account's live call capacity') and even cites the underlying endpoint GET /concurrency. It explicitly distinguishes itself from the sibling list_live_calls by noting it is a count, not a list.