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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the write/high-impact nature is covered. The description adds genuinely new behavior: an environment-flag gate (VOBIZ_ENABLE_PROVISIONING) and the required confirm: true, plus the security effect of removing digest-credential needs. It stops short of describing duplicate handling or response shape.

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

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

Three dense sentences with the purpose front-loaded, then the linkage instruction, then the gating prerequisites. No filler, though the confirm/gate sentences could be tightened.

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-param mutation with no output schema, the description covers purpose, linkage, and gating prerequisites adequately. It omits what happens on duplicates or the returned identifier (schema hints name is returned as `description`), which an agent might want, but nothing critical for correct invocation 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 name/ip_address/confirm are already documented in the schema (including the CIDR format and the name→description mapping). The description's example addresses add little 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 (allow-list) plus resource (public IPv4/CIDR for trunk ACL) and explains the concrete outcome: PBX/SBC/carrier trunks usable without digest credentials. It is clearly distinguishable from siblings like update_ip_acl_entry, delete_ip_acl_entry and list_ip_acl_entries.

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

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

Gives clear operating context: use it to attach an IP to a trunk via update_sip_trunk (ipacl_uuid), and notes it is gated by VOBIZ_ENABLE_PROVISIONING and confirm: true. It does not explicitly state when NOT to use it (e.g. reusing an existing entry vs. create), but the usage path is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=true). The description adds real value beyond them by disclosing the environment-flag prerequisite (VOBIZ_ENABLE_MESSAGING=true) and the confirm gate, and by restating the idempotency guarantee in plain terms ('Safe to repeat'). It does not mention how the block is reversed or any permission model, which keeps it at a 4.

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

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

Three short sentences, front-loaded with the action and effect, followed by prerequisites and the idempotency note. No filler or redundancy.

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

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

For a 4-parameter mutation with no output schema, the description covers effect, example trigger, prerequisites, and repeat-safety. The only meaningful omission is how to undo the block, though the sibling remove_opt_out partially signals that.

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 75%, so the schema already documents reason, channel, and confirm well. The description only restates the confirm requirement and implies channel scoping without adding format or syntax detail, so it adds little beyond the structured fields.

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

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

The description states a specific verb and resource: 'Block a phone number from receiving messages on a channel.' That phrasing distinguishes it cleanly from the sibling check_opt_out (query), list_opt_outs (enumerate), and remove_opt_out (reverse), without needing to open any schema.

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

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

It gives a concrete usage context ('for example after a customer asks to stop') and a hard precondition (confirm: true), so the agent knows when this tool is appropriate. It stops short of explicitly naming the alternatives or stating when NOT to use it, so it falls just short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the environment-flag gating, the confirm gate, and the fact that the number leaves the account pool and is then used by the sub-account for its calls. It does not state reversibility or what happens on repeated calls despite the idempotent hint.

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

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

Three tight sentences with the core action front-loaded and preconditions trailing. Including the raw endpoint path is slight overhead, but every sentence carries signal and nothing is redundant.

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

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

For a destructive mutation with no output schema, the description covers the essential context - gating flag, explicit confirmation, and the state change to both accounts. A note on reversibility (that unassign_number_from_subaccount exists) would close the remaining gap.

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

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

Schema description coverage is only 33%: confirm is documented in the schema, but phone_number and sub_account_id have no descriptions. The description compensates partially by restating the 'confirm: true' requirement and hinting at E.164 format via the {e164} path segment, but it adds nothing about the sub_account_id parameter or the phone number pattern.

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 with directionality: 'Move a number from this Vobiz account's pool to one of its sub-accounts.' The effect on both parties (parent pool loses, sub-account uses it for calls) and the underlying endpoint are given, so an agent can immediately distinguish it from the sibling unassign_number_from_subaccount.

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

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

Gives real preconditions: the tool is 'Gated by VOBIZ_ENABLE_PROVISIONING' and requires 'confirm: true'. The direction of the move implicitly selects it over unassign_number_from_subaccount, but there is no explicit when-not-to-use statement or note about when the number must first be in the pool.

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

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

Annotations only flag destructive/idempotent/openWorld; the description adds substantive behavior the agent could not infer: immediate setup + monthly charges, five server-side preconditions (provisioning, inventory, cost cap, balance, daily cap, ownership), and idempotency replay semantics. This is exactly the beyond-annotation context 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?

The cost consequence and the confirm prerequisite are front-loaded before the server-check list, which is the right ordering for a destructive purchase. It is a dense run-on block rather than cleanly separated sentences, but no clause 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 no output schema, the description still covers what an agent needs: the charge model, all gating checks, the mandatory confirmation flow, and replay behavior. Nothing material for correct invocation is left unstated.

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

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

Schema coverage is 75%, and the description reinforces the two riskiest parameters: why confirm must be true and that repeating idempotency_key 'never buys twice'. The currency parameter is left entirely to the schema's regex, so it adds meaning on most but not all parameters.

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

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

States a specific verb and resource ('Buy one number from Vobiz inventory') and even pins the underlying endpoint. An agent can distinguish this from search_available_numbers and release_phone_number without opening any schema, since the purchase action and its inventory source are named.

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

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

It specifies the operative condition for calling it — 'Requires confirm: true (after showing the user the number and its fees)' — which is real when-to-use guidance tied to a user-approval step. It does not explicitly name the sibling to run first (search_available_numbers) or state when not to use it, 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 declare it a non-read-only, idempotent, open-world mutation, and the description adds substantial context beyond them: the restore-to-active effect, the fee refund, the 24-hour cooldown window, the env-var and confirm gating, and the side effect that detached trunks/applications must be re-linked. The destructiveHint=true flag is not explicitly reconciled, but the described restorative behavior is not contradicted by it.

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

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

Four dense sentences, front-loaded with the action and its effect, then preconditions, then side effects. The parenthetical endpoint and env-var gating add useful precision rather than filler, though the middle sentences are packed tightly enough to be slightly heavy.

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

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

For a two-parameter mutation tool with no output schema, the description covers the essential gates, time window, state effects and follow-up remediation. The only real gap is that phone_number's expected format is left to the endpoint placeholder and the schema pattern.

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 50%: confirm is fully documented in the schema ('Must be true, set only after the user explicitly approved'), while phone_number carries only a pattern. The description partially compensates by embedding the {e164} placeholder in the endpoint path and reiterating the confirm: true gate, but adds no meaning beyond what schema plus endpoint already convey.

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

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

States a precise verb and resource ('Keep a number that is in pending_release'), names the exact API endpoint, and spells out the resulting state change (restored to active, fee refunded). It is unmistakably the inverse of the sibling release_phone_number, so an agent can select it without opening the schema.

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

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

Gives clear preconditions for use: only valid during the 24-hour cooldown, requires VOBIZ_ENABLE_PROVISIONING and confirm: true. It also routes the agent to update_phone_number for the follow-up re-linking of detached trunks/apps, but it never names release_phone_number as the counterpart decision, so alternative routing is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and 'Read-only' merely restates them. The description does add one piece of real platform behavior — that sends to opted-out numbers are refused — but omits what happens on an invalid/unknown number and what the result looks like.

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

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

Three short sentences, front-loaded with the core action, then the operational reason, then the safety profile. Nothing is padded or repeated.

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

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

For a read-only lookup with no output schema, the description should indicate the shape of the answer (boolean, status object, etc.) and it does not. With annotations covering the safety profile and only two simple parameters, the omission is a gap but not a severe one.

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 only 50%: the channel enum carries a description while phone_number only has a regex pattern. The description mentions 'a phone number' and 'a channel' but adds no format, default-value, or channel-selection meaning beyond what the schema already states.

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) plus a precise resource (opt-out status of one phone number on a channel), which implicitly separates it from the sibling list_opt_outs. It never names an alternative sibling explicitly, so it falls short of the top band.

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?

'Vobiz refuses sends to opted-out numbers' supplies a rationale for checking, implying the tool is used before sending. However, it never states when to use this versus list_opt_outs, add_opt_out, or remove_opt_out, so guidance remains implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation/safety profile is covered. The description adds genuinely useful context beyond that - feature-flag gating via VOBIZ_ENABLE_PROVISIONING, the approved-host URL constraint, and the explicit confirm gate - but does not explain the side effects implied by destructiveHint (e.g., what provisioning actually creates or whether it can be rolled back).

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 dense sentences, front-loaded with the action and required fields, then the host constraint, then the gating rules. No filler or repetition of the tool name.

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

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

For a 10-parameter, non-idempotent mutation tool with no output schema and near-zero schema coverage, the description leaves most parameter semantics undocumented and never describes what the created application looks like or what is returned. The gating and host constraints are valuable but not enough to make the definition self-sufficient.

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

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

Schema description coverage is only 10%, with just 'confirm' documented, so the description carries the burden for the other nine parameters. It restates the two required fields (already in the schema's required array) and adds the approved-host rule for URLs, but leaves hangup_url, the three *_method enums, fallback_answer_url, and both default_*_app booleans completely unexplained.

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 Vobiz application') and names the two required fields, which cleanly separates it from get_application, update_application, and delete_application in the sibling list. It stops short of explicitly routing the agent away from those siblings, but the create semantics are unambiguous.

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

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

Gives concrete preconditions for invocation: the VOBIZ_ENABLE_PROVISIONING flag must be enabled and confirm: true is required, and the description also states the approved-host constraint on URLs. What is missing is any statement of when to prefer update_application over a new create, or exclusions for cases where creation should not be attempted.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the operation is gated by VOBIZ_ENABLE_PROVISIONING, requires confirm: true, and the host must be public. It stops short of describing failure modes or what happens on duplicate URIs.

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 with zero filler; the core purpose is front-loaded, followed by priority semantics, attachment workflow, and gating preconditions in descending order of importance.

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 4-required-param mutation tool with 100% schema coverage, full annotation coverage, and no output schema, the description supplies everything an agent needs: purpose, routing convention, attachment workflow, environment gate, and confirmation requirement. 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%, so baseline is 3; the description goes further by linking sip_uri and priority semantics to downstream behavior and explaining that the created URI is consumed via update_sip_trunk's primary_uri_uuid/fallback_uri_uuid fields. That cross-tool relationship is not visible in the schema, so it adds real value.

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

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

States a concrete verb and resource ('Add a SIP destination (origination URI)') with an example value and the business purpose (outbound call routing for Vobiz trunks). This clearly separates it from list_origination_uris, update_origination_uri, and delete_origination_uri in the sibling set.

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 usage guidance: priority 1 for primary and 2+ for failover, plus the follow-up step of attaching via update_sip_trunk (primary_uri_uuid or fallback_uri_uuid). It does not explicitly state when NOT to use it or name a competing tool to prefer, so it stops short of a full when/when-not routing statement.

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

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

Goes well beyond the annotations by disclosing irreversible traits (username cannot be changed later), the secret handling model (password write-only and never returned), and the activation gate (VOBIZ_ENABLE_PROVISIONING plus confirm: true). These are exactly the behavioral facts an agent needs and none are in the annotation block.

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

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

Three dense sentences with zero filler: purpose first, then the application-attachment behavior and its default, then the gate and secret-handling caveats. Front-loaded and each sentence earns its place.

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

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

For a 5-parameter creation tool with no output schema and a rich annotation block, the description covers what an agent needs: what gets created, the immutable field, the secret's lifecycle, the environment gate, and the confirm requirement. 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 every parameter is already documented in the schema, including username permanence and password secrecy. The description largely restates those facts (immutable username, write-only password) rather than adding new syntax or format 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 and resource ('Create a Vobiz SIP endpoint') plus the concrete outcome (a soft-phone, desk phone or WebRTC client registering at registrar.vobiz.ai with its own credentials). This clearly separates it from siblings like create_sip_trunk, update_sip_endpoint and delete_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?

Gives clear context for when this tool applies (provisioning a registering endpoint) and explains the fallback when no application is attached ('otherwise the account's default endpoint application applies, if set'). It also names the gating conditions. It does not, however, explicitly contrast itself with create_sip_trunk or state when not to use it.

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

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

Annotations already declare destructive/non-idempotent/open-world, so the bar is lowered, and the description adds real context beyond them: an environment-flag gate and a mandatory confirmation precondition, plus the auth-model choice (credential vs IP ACL). It does not explain consequences of the destructiveHint (e.g. what provisioning changes), leaving a small gap.

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

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

Three tight sentences, front-loaded with the operation and endpoint, then preconditions, then the gate. Every clause carries information that is not repeated elsewhere.

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 19-parameter create tool the description covers the decision-critical pieces — validation gate, confirm requirement, auth wiring, failover ordering — and with no output schema it does not need to describe returns. It is somewhat under-specified for the many optional configuration parameters the agent may need to populate on a real provisioning call.

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

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

Schema coverage is only 16% across 19 params, so the description must compensate; it explains the two auth options (credential_uuid and/or ipacl_uuid), the routing pair (primary_uri_uuid with fallback_uri_uuid as failover) and the confirm gate, adding role semantics the bare schema lacks. The remaining majority of params (transport, secure, cps_limit, trunk_direction, recording, inbound_destination, etc.) get no explanation in either place.

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 even names the underlying endpoint (POST /trunks), which pins down the operation unambiguously among create_* siblings like create_sip_endpoint and create_trunk_credential. It does not explicitly contrast itself with update_sip_trunk, but the resource/verb pair is distinctive enough that an agent can select it 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 concrete preconditions — supply credential_uuid and/or ipacl_uuid, and set confirm: true behind VOBIZ_ENABLE_PROVISIONING — which tell the agent when the call will succeed. It stops short of stating when to use this tool versus create_sip_endpoint or create_trunk_credential, so routing among provisioning siblings is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=true, non-idempotent), and the description adds genuinely non-obvious behavior: credentials are NOT returned and must be copied from the console, calls are blocked until the sub-account completes its own KYC, and the operation requires an environment flag plus confirm. That is material context an agent cannot get 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?

Four sentences, front-loaded with the creation action, then requirements, then the credentials caveat, then the gating condition. Dense but efficient; each sentence carries a distinct fact. Minor cost is that parentheticals and the trailing gating clause make it slightly hard to scan.

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, non-idempotent provisioning tool with no output schema, the description covers prerequisites (KYC, env flag, confirm), the required-parameter minimum, and the surprising absence of returned credentials. Only secondary semantics like permission inheritance on omission are left to the schema.

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

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

Schema coverage is 80%, so the schema already documents name, email, confirm, enabled, kyc_mode, rate_limit, and permissions. The description mostly restates the required-parameter rule ('only name is required', email for customer_use, confirm gating) rather than adding format, defaults, or interactions 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 ('Create a Vobiz sub-account under this main account') and immediately scopes it with the resource hierarchy. It also names the adjacent KYC-session sibling, letting an agent separate it from create_sub_account_kyc_session and from update_sub_account/delete_sub_account without opening other 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 clear conditions: name alone suffices, email is needed when kyc_mode is customer_use, and provisioning is gated by VOBIZ_ENABLE_PROVISIONING plus confirm: true. It points to create_sub_account_kyc_session for the follow-on KYC step, but never explicitly frames when to prefer this over update_sub_account or when not to create at all.

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 openWorld=true, so the write/external-effect profile is covered. The description adds valuable context those annotations don't: the VOBIZ_ENABLE_PROVISIONING gate, the confirm:true requirement, and the fact that the email flow actually contacts the customer—important for a side-effecting operation.

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

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

Four dense sentences, each carrying distinct information (purpose, email flow, redirect flow, webhook/tracking/gating) with no repetition or filler. The primary action is front-loaded.

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

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

For a 7-param mutation with no output schema, the description covers flow selection, prerequisites, gating, and the redirect widget_url return. It doesn't state what the email flow returns or expiry defaults beyond expires_in_days, leaving a small 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 coverage is 100%, so the baseline is 3, but the description adds conditional logic the schema states only per-field: customer_email is required for email flow, redirect_url for redirect flow, and webhook_url/webhook semantics. This conditional pairing genuinely helps correct invocation.

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 implicitly distinguishes itself from the read-only sibling get_sub_account_kyc_status, which is named as the tracking counterpart. An agent can identify the operation 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 describes the two flow_type modes and their prerequisites (email requires customer_email; redirect requires redirect_url), and routes the agent to get_sub_account_kyc_status for progress. It lacks an explicit 'when not to use' or eligibility conditions beyond the gating flags, so it falls just short of a 5.

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

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

Annotations already flag this as non-idempotent, open-world and destructive, and the description adds materially beyond them: the username is permanent, the password is write-only and never returned, and the call is gated by VOBIZ_ENABLE_PROVISIONING plus confirm: true. These are exactly the irreversible/secret-handling facts an agent needs before invoking a destructive 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?

Four tight sentences, front-loaded with the action and scope, then the follow-up step, then the irreversibility and gating constraints. No filler or repetition of the title.

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

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

For a 3-required-param mutation with no output schema, the description covers everything an agent needs: what it creates, the required approval gate, the permanence of the username, and the fact that the password is never returned (so nothing is expected back in the response).

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

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

Schema coverage is 100% and the schema already documents all three parameters including the SECRET warning on password and the permanence of username. The description restates permanence and write-once behavior but adds no syntax, format or constraint 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 SIP digest credential ... on this Vobiz account for trunk authentication') and immediately scopes its purpose to dynamic-IP PBXs, remote sites or voice agents, which cleanly separates it from list/update/delete_trunk_credential siblings.

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

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

Gives the follow-up workflow explicitly ('Attach it to a trunk afterwards with update_sip_trunk (credential_uuid)') and implies the use case boundary by scoping to dynamic-IP rather than static-IP alternatives. It never states an explicit 'do not use this when...' exclusion, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true. The description adds reversibility context ('Undo with undeafen_conference_member') and the underlying endpoint, which is useful. It doesn't restate idempotency or describe error behavior, but the annotations carry that load.

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 effect before the use cases and the undo path. 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 two-parameter mutation with full annotation coverage and no output schema, the description covers effect, parameters, use cases and reversal. Minor omission is any auth/permission requirement or confirmation of response shape, but nothing essential is missing.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema, including the 'all'/comma-list pattern. The description's 'Pass one member_id, a comma-separated list, or all' only restates 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 (deafen) and resource (conference member) and explains the exact effect: the member stops hearing the room while others still hear them. This distinguishes it from mute, the closest sibling, without requiring the schema.

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

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

Gives concrete when-to-use cases (listen-only setups, private side conversations) and names the inverse operation (undeafen_conference_member) as the undo. It does not explicitly contrast with mute_conference_member, but the 'others still hear them' clause lets an agent infer the distinction.

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

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

Goes well beyond the annotations by disclosing the cascade side effect: linked numbers are unlinked and inbound calls to them stop being handled. Combined with the feature-flag gate and the explicit confirm requirement, the agent knows the irreversible consequences 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 short sentences, front-loaded with the action, then the side effect, then the gating conditions. Every clause carries information the 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?

For a destructive, non-readonly mutation with no output schema, the description covers the side effects, the feature-flag prerequisite, and the confirmation gate. It omits whether the deletion is permanent/recoverable and what a successful response contains, but the annotations and the required confirm parameter cover most of the remaining risk.

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

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

Schema description coverage is 50%: confirm is documented in the schema while app_id is not, and the description only reinforces the confirm: true requirement rather than explaining the app_id pattern (^\d{5,25}$) or how to obtain one. Baseline 3 is appropriate given the schema carries half the load.

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

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

States a specific verb and resource ('Delete a Vobiz application') and immediately scopes the blast radius ('Linked numbers are unlinked'). An agent can distinguish it from delete_sip_trunk, delete_recording, or delete_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?

Gives an explicit precondition pair — the VOBIZ_ENABLE_PROVISIONING gate and confirm: true — which tells the agent when the call is even permitted. It does not name alternative tools or spell out when deletion is preferable to update_application, 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 declare destructiveHint/idempotentHint, but the description adds genuine value beyond them: the consequence of deletion (SIP traffic from that address is no longer trusted and needs other authentication) and the feature-flag precondition. It does not restate idempotency or error behavior, but the added consequence is substantive.

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

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

Three short sentences, front-loaded with the action, then the consequence, then the gating. No ceremonial or redundant phrasing; every sentence carries information.

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

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

For a destructive mutation with no output schema, the description covers the effect, prerequisites, and the confirm gate, while annotations carry the safety profile. Only minor gaps remain (error/idempotency behavior when the entry is absent, which the idempotentHint partly covers).

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 50%: confirm is well documented in the schema, but ip_acl_id has only a pattern and no prose. The description mentions confirm: true (repeating the schema) and says nothing about what ip_acl_id selects, so it does not compensate for the coverage gap. Baseline 3.

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

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

States a specific verb and resource ('Remove an IP ACL entry from this Vobiz account') and immediately clarifies the downstream effect on SIP trust. The add/update/list/delete_ip_acl_entry sibling family makes the scope unambiguous.

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

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

Gives real prerequisites (gated by VOBIZ_ENABLE_PROVISIONING and confirm: true), which is more than implied usage. But it never states when to prefer this over update_ip_acl_entry or what to do instead if the entry should merely be untrusted, so routing guidance is incomplete.

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, so the safety profile is covered; the description adds value beyond that by disclosing the downstream effect (trunks stop routing outbound calls to that destination), the prerequisite for trunk-only routes, and the environment/confirmation gate. It does not say whether the deletion is reversible or what error surfaces when the gate is closed, which keeps it below 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?

Three short sentences with zero filler: effect first, prerequisite second, gates third. Every clause carries actionable information and the most important constraint is front-loaded.

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

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

For a destructive, gated mutation with no output schema, the description covers consequence, prerequisite, environment gate and confirmation semantics — enough for an agent to call it correctly. The remaining gap is the absence of any statement about failure behavior or irreversibility.

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

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

Schema description coverage is 50%: confirm is already documented in the schema and its full meaning is restated here, but uri_id carries no description beyond a UUID regex pattern. The description clarifies the confirm requirement in prose but adds nothing about uri_id, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource (delete an origination URI) scoped to the Vobiz account, which cleanly separates it from list_origination_uris, create_origination_uri and update_origination_uri in the sibling set. An agent knows exactly which operation this is without opening the schema.

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

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

Gives a real precondition ('add a replacement first if it is a trunk's only route') and a gating condition (VOBIZ_ENABLE_PROVISIONING plus confirm: true), which tells the agent when this call is permissible. It stops short of naming the alternative tool (update_origination_uri / create_origination_uri) as an explicit fallback, so it is context rather than full routing guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them: the deletion is permanent, the audio cannot be restored, and the call is gated by an environment flag plus an explicit confirm. It does not describe behavior on a nonexistent/already-deleted id or the response, keeping it at 4.

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

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

Three short sentences, each carrying distinct load: action and scope, irreversibility, and gating. The most decision-critical facts (permanent, unrecoverable) are front-loaded.

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

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

For a two-parameter destructive tool with no output schema and safety already covered by annotations, the description supplies the irreversibility warning and the feature/confirm gating an agent needs before calling. It omits only error/edge-case behavior, which is a minor gap.

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

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

Schema coverage is 50% – the confirm parameter is well documented in the schema, but recording_id has only a regex pattern and no prose. The description's 'DELETE /Recording/{id}/' hints at the id parameter and restates the confirm gate, adding modest meaning but not compensating for the undocumented recording_id.

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

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

The description states a specific verb and resource ('Permanently delete one call recording'), names the scope ('from this Vobiz account'), and even gives the underlying endpoint DELETE /Recording/{id}/. An agent can immediately distinguish it from list_recordings or get_call_recording among the siblings.

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

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

It states two concrete preconditions for use: the VOBIZ_ENABLE_PROVISIONING gate and confirm: true. That is clear when-to-use guidance, but it never names alternatives (e.g., use get_call_recording to inspect before deleting) or says when not to use it, so it falls short of a full 5.

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

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

Beyond the destructiveHint/idempotentHint annotations, the description discloses exactly what is destroyed and what breaks: registered devices disconnect immediately and the SIP URI stops working. It also reveals a non-obvious operational gate (VOBIZ_ENABLE_PROVISIONING), which 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?

Three short sentences, front-loaded with the operation and its irreversible nature, followed by side effects and prerequisites. No redundant or filler content.

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

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

For a 2-parameter destructive tool with no output schema, the essentials are covered: irreversibility, downstream impact, and the env-var/confirm gate. It omits post-deletion behavior (e.g., whether the ID can be reused or what error a missing/invalid ID returns), which is minor but leaves a small 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 coverage is 50%; the 'confirm' parameter is fully documented in the schema (and the description's 'confirm: true' only restates it). endpoint_id is never described in prose — only a regex pattern hints at its format — so the description does not compensate for the uncovered half.

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 ('Permanently delete') and a precisely named resource ('Vobiz SIP endpoint'), which is enough to distinguish it from the adjacent delete_sip_trunk and delete_trunk_credential siblings. An agent can pick this 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?

The word 'Permanently' plus the disclosed consequence (registered devices disconnect immediately) makes the usage context clear: only for irreversible removal. It names no explicit alternative (e.g., update_sip_endpoint) and gives no when-not guidance, so it stops short of a 5.

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

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

Annotations already declare destructive/idempotent/openWorld, but the description adds material context they don't: this is a soft delete, routed numbers are unlinked and stop receiving calls through it, and the call is gated by an environment flag plus an explicit confirm. Those downstream consequences are exactly what 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?

Three short sentences, each earning its place, with the operation, its side effects, and its gating requirement front-loaded. No filler or restatement of the title.

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

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

For a two-parameter destructive tool with no output schema, the description covers side effects, gating, and confirmation adequately. It stops short of saying whether a soft-deleted trunk can be restored or what the response returns, a minor omission given the annotations already carry the safety profile.

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

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

Schema description coverage is only 50% — confirm is documented in the schema, trunk_id only via a pattern. The description reinforces 'confirm: true' but adds no format or constraint detail for trunk_id beyond the schema's regex, so it does not fully compensate for the gap.

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

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

States a specific verb and resource ('Delete a SIP trunk') and immediately qualifies the operation as a soft delete, which separates it from hard-delete siblings and from delete_sip_endpoint/delete_application by resource. An agent knows exactly what entity is affected and how.

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

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

It gives a prerequisite ('Gated by VOBIZ_ENABLE_PROVISIONING and confirm: true') but never states when to choose this over alternatives such as update_sip_trunk or release_phone_number, nor any when-not condition. Usage is implied by the destructive nature rather than explained.

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, readOnlyHint=false, and idempotentHint=true, so the safety profile is partly covered. The description goes further by disclosing the concrete consequences: credentials are revoked, the action cannot be undone, and anything using the sub-account's Auth ID stops working, plus the runtime gating conditions. That is real behavioral context beyond the 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?

Three compact sentences, front-loaded with the destructive action and its irreversibility before the gating conditions. Every clause earns its place; nothing is redundant 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 two-parameter mutation with no output schema, the description covers the essentials an agent needs: permanence, credential revocation, downstream impact, and required preconditions. Annotations cover the safety hints, so 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%, so both parameters (confirm, sub_auth_id) are already fully documented in the schema. The description restates the confirm: true gate but adds no new syntax, format, or sourcing detail for sub_auth_id. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Permanently delete a Vobiz sub-account and revoke its credentials') with the exact scope of the operation. An agent can distinguish it from get_sub_account, update_sub_account, and create_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?

Gives clear preconditions for invocation: the tool is gated by the VOBIZ_ENABLE_PROVISIONING environment flag and requires confirm: true. It does not explicitly name a safer alternative (e.g. update_sub_account or unassign_number_from_subaccount), so it stops short of full routing guidance, but the when-to-use context is clear.

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

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

Beyond the destructive/idempotent annotations, it discloses concrete effects: any PBX or device authenticating with the credential is denied afterward, and the operation may be refused mid-call. It also exposes the feature-flag gate and the confirm requirement, which are non-obvious runtime behaviors.

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

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

Three short sentences, no padding: purpose, blast radius, then gating requirements. The most decision-relevant fact (devices are refused) is front-loaded right after the verb.

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 no output schema, it covers effects, preconditions and the feature gate, which is most of what an agent needs. The remaining omission is how to source the credential_id and whether related trunk/ACL state is affected.

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 50%: confirm is documented in the schema and the description only restates 'confirm: true'. The credential_id parameter has no description and the tool text never explains where to obtain it (e.g., list_trunk_credentials) or its UUID format, so the gap is only partly compensated.

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 plus resource ('Delete a trunk credential') and names the account scope, so it is trivially separable from create_trunk_credential, update_trunk_credential, and the SIP-endpoint deletes.

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

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

It states the two preconditions (VOBIZ_ENABLE_PROVISIONING and confirm: true) and the operational consequence that authenticating devices are refused, which signals when the call is appropriate. It stops short of naming alternatives (e.g., use update_trunk_credential to rotate instead of delete) or an explicit when-not-to-use.

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?

Although annotations already mark the tool destructive and idempotent, the description adds the concrete consequence: all members of all rooms are disconnected at once. It also discloses the confirmation protocol, which is important behavioral context beyond the annotations.

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

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

The description is front-loaded with the action and scope, then immediately provides the alternative and confirmation requirement. Every clause adds useful selection or safety information with no wasted text.

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

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

For a destructive account-wide bulk operation with one parameter and no output schema, the description supplies scope, consequence, alternative routing, and confirmation requirements. An agent has enough information to decide when and how to call it safely.

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

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

Schema coverage is 100%, so the single `confirm` parameter is already fully documented by the schema. The description reinforces the `confirm: true` requirement but does not add new parameter semantics beyond what the schema already states.

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: "Hang up EVERY running conference room on this Vobiz account at once," and states the scope as account-wide. It also explicitly distinguishes this from the sibling tool `end_conference`, which handles a single room.

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

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

It states the intended use precisely: "only for account-wide cleanup or maintenance," and names the alternative for closing one room. The confirmation requirement is tied to explicit user agreement, giving clear invocation 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 flag destructive=true, idempotent=true and readOnly=false, so safety is covered structurally. The description adds genuine extra behavior: a precheck that the call is live or queued on this account, and the call_not_active error result when the call already ended.

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

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

Three dense sentences: the action and endpoint come first, followed by the precheck, the required inputs, and the failure result. No filler or repetition.

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

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

For a two-parameter mutation with no output schema, the description covers the action, preconditions, required confirmation guardrail, and the one notable error return. Annotations handle the safety profile, so 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 coverage is 100%, so call_uuid and confirm are already fully documented in the schema, including the same confirm-after-explicit-request wording. The description repeats rather than extends that 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 (terminate) and resource (active or queued call) and even names the underlying endpoint. An agent can distinguish this from hangup_conference_member and end_conference, which act on conference participants or whole conferences.

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

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

Gives a clear usage condition: confirm:true must be set only after the user explicitly asked to end this call, which is real routing/guardrail guidance. It stops short of naming alternatives (e.g. hangup_conference_member for conference members), so it lacks explicit when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds value by clarifying that the blast radius is the entire room and that confirm:true is mandatory, which is behavior beyond the raw flags.

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

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

Front-loads the action and its scope, then the usage case, then the alternative, then the prerequisite. Every clause earns its place and nothing is redundant 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 two-parameter destructive tool with full schema coverage and annotations covering the safety profile, the description supplies everything needed: scope, effect, alternatives, and the confirm gate. No output schema is needed or expected.

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 gating semantics. The description only restates the confirm requirement, adding no syntax or naming detail beyond the schema. 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 ('Hang up one running Vobiz conference room'), gives the HTTP endpoint, and describes the exact effect (all members disconnected, room ends). An agent can distinguish it from sibling conference tools 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?

Names two concrete scenarios (close a meeting on time, clean up an abandoned room) and explicitly routes partial removal to kick_conference_member or hangup_conference_member. The when/when-not split is complete.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true; the description adds real context beyond them, notably that supplying call_uuid replaces the live call's current flow (a transfer), and that digits are posted back, verified, and stored server-side. It stops short of describing failure/timeout behavior for a live-call transfer.

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 what it creates, then the read path, then the two invocation modes and the environment constraint. No filler despite the density of 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?

No output schema exists, but the description redirects the agent to get_gather_result for the collected digits, covering the return-value gap. With annotations carrying the safety profile, only minor detail on defaults (num_digits, timeout) is absent.

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

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

Schema coverage is 60%; the description explains call_uuid, confirm, and the answer_url/returned-url distinction, but adds nothing for num_digits, finish_on_key, digit_end_timeout, prompt_text/prompt_audio_url selection, or the 'then' post-input flow. Baseline 3 is right with partial schema coverage.

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

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

Specific verb and resource: 'Create a hosted IVR step that plays a prompt and collects DTMF digits (Vobiz <Gather>)'. It also names the companion read tool get_gather_result, so an agent can separate creation from retrieval 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?

Explicitly gives the two usage modes: pass call_uuid (+ confirm: true) to transfer a LIVE call now, or use the returned url as make_call answer_url. It also states the HTTP-mode prerequisite (VOBIZ_PUBLIC_URL), so the condition for each path is unambiguous.

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

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

Adds real behavioral context beyond the readOnlyHint/openWorldHint annotations: XML-escaping of text, an approved-host requirement for callback/redirect URLs, rejection of actions after redirect/hangup, and the fact that non-host mode makes no API call. Return behavior (URL string vs raw XML) is only lightly covered.

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

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

Three dense sentences, front-loaded with purpose, then validation constraints, then the mode switch. Every clause carries information, though the middle sentence is run-on and slightly compresses several distinct rules together.

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 nested oneOf action schema with no output schema, the description covers action vocabulary, constraints, and the dual output mode well. It stops short of describing the returned XML/URL shape in detail, but the key invocation decisions are all supported.

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 baseline is 3, but the description adds meaning beyond it: it clarifies what host: true does (serve and return a URL), the allowed action vocabulary, and ordering constraints on the actions array that the schema does not express.

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 ('Build a validated Vobiz XML document') and enumerates the exact action types it accepts (speak, play, wait, gather, record, dial, redirect, hangup). It also positions itself against siblings by naming make_call answer_url and transfer_call aleg_url as the consumers of its output.

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 distinguishes the two operating modes ('With host: true ... Pure generation otherwise') and explains where the produced URL is consumed. It lacks an explicit when-not-to-use or direct alternative comparison, but the mode split and downstream routing give an agent enough to choose correctly.

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

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

Annotations already declare readOnlyHint=true, so the trailing 'Read-only.' is redundant. The description does add real behavioral context the annotations cannot: the tool fans out across multiple currency wallets when no currency is supplied, which affects both result shape and size.

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

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

Two tight sentences with the field list up front and the multi-wallet caveat second. 'Read-only.' earns nothing given the annotation, but the waste is a single word.

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?

There is no output schema, and the description compensates by naming the returned fields (balance, available balance, reserved funds, credit limit, postpaid flag) plus the multi-wallet behavior. An agent knows both what it will get and when it will get many records.

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 the ISO pattern and the omit-to-list-all behavior. The description's restatement of the currency omission is consistent but adds no syntax or format detail beyond the schema, so this sits at the 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 ('Return the account balance') and enumerates the returned fields. It does not differentiate itself from the nearby sibling get_account_details, so an agent could hesitate between the two.

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

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

The currency-omission behavior gives an implicit usage rule ('omit to list every wallet'), but there is no explicit when-to-use guidance, no exclusion, and no pointer to get_account_details as the alternative for profile-level data.

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 the 'Read-only' sentence is largely redundant, but 'Credentials are redacted' adds a genuinely useful behavioral fact about the response that the annotations do not convey.

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

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

A single sentence, front-loaded with the verb and resource, listing the salient fields and the redaction caveat 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 no output schema and no parameters, the description must carry the return-value burden itself, and it does so by naming the profile fields and noting credential redaction; 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?

The tool takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. The field list describes return content rather than inputs, which is fine given no schema parameters exist.

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

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

States a specific verb (Return) and resource (Vobiz account's profile) and enumerates the returned fields (name, account type, status, CPS/concurrent-call limits, features), which clearly separates it from siblings like get_account_balance or get_sub_account.

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

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

Usage is implied by the zero-parameter, profile-fetching nature of the tool, but the description never says when to call it versus get_account_balance or get_sub_account, and there are no exclusions or prerequisites stated.

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

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

Annotations already declare readOnlyHint=true, and 'Read-only' merely restates that. With annotations carrying the safety profile, the description should add value such as what happens on an unknown app_id or what 'configuration' includes, but it adds nothing beyond the annotation.

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

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

Two short sentences, front-loaded with the verb and resource, with zero filler. Nothing could be trimmed without losing content.

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

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

For a one-parameter read tool with no output schema this is minimally adequate, but 'configuration' is vague about what is returned and the description says nothing about error behavior for an invalid or missing app_id.

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

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

Schema description coverage is 0% and there is a single required app_id parameter. The description says nothing about app_id — its meaning, source, or that it must be a 5-25 digit numeric ID as implied by the pattern — so it fails to compensate for the schema gap.

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

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

States a specific verb (Return) and resource (one Vobiz application's configuration), and the word 'one' implicitly distinguishes it from the sibling list_applications. It stops short of naming that sibling or spelling out the single-vs-list distinction explicitly.

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

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

There is no explicit when-to-use guidance and no mention of alternatives such as list_applications or the id source. The only hint is the word 'one', which is purpose framing rather than usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so 'Read-only' in the description earns no credit. The enumeration of returned fields (status, WebSocket URL, track, audio format, timestamps) adds genuine context given no output schema, but there is no mention of auth requirements, error behavior for unknown/ended streams, or whether the stream must be active.

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

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

A single front-loaded sentence that leads with the action, resource, and scope before the endpoint and field list. 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 read-only getter with two required path params and no output schema, listing the response fields is exactly what's needed. It falls short only on failure modes and any precondition about the stream's state.

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

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

Schema coverage is 0%, so the description carries the burden; it does map call_uuid and stream_id into the URL path template, clarifying they are path identifiers on a call's stream. However it adds no format, length, or validity guidance beyond the regex patterns already in the schema, leaving the required-parameter contract thin.

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 one audio stream'), the resource, the underlying endpoint (GET /Call/{uuid}/Stream/{stream_id}/), and enumerates the fields returned. The singular 'one' implicitly separates it from the sibling list_audio_streams.

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

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

Usage is only implied: retrieving a single known stream, versus list_audio_streams for enumeration or start_audio_stream/stop_audio_stream for lifecycle changes. No explicit when-to-use or when-not-to-use statement routes the agent among those siblings.

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 "Read-only" is largely redundant, but the description adds genuine value by disclosing the shape of the returned payload down to the individual stat counters. It stops short of describing behavior for an unknown or expired broadcast_id.

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

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

One front-loaded sentence lists the returned components efficiently, with no preamble. The trailing "Read-only." adds little beyond the readOnlyHint annotation already present, a minor redundancy rather than a flaw.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so by naming the composite fields and the four stat counters. The only gap is error/edge-case behavior, which is minor for a simple getter.

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

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

The single broadcast_id parameter is fully documented in the schema (100% coverage), including a regex pattern, so the description needn't repeat it. No added semantic detail on the identifier is offered, which matches the baseline for a fully covered schema.

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

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

"Return one broadcast" is a specific verb+resource, and the enumeration of what comes back (template, schedule, send rate, stats) further pins it down. The singularity of "one broadcast" implicitly separates it from list_broadcasts, though no sibling is named outright.

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

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

Usage is only implied: an agent can infer this is for fetching a single broadcast's detail rather than enumerating them. There is no explicit when-to-use statement, no guidance on which identifier form to pass, and no alternative tool named.

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's 'Read-only' line largely repeats that. However it adds a genuinely useful behavioral constraint not in the annotations — the record only exists for COMPLETED calls — and enumerates the returned fields in lieu of an output schema.

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

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

Front-loads what the tool returns, then the routing rule, then the safety note — three short clauses with no filler. The field enumeration is dense but each item earns its place given there is no output schema.

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

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

For a single-parameter read tool with no output schema, the description compensates by listing the CDR fields returned and by gating on call completion state. 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?

Only one parameter (call_uuid) with 100% schema description coverage, so the schema carries the semantics. The description adds no format, validation, or sourcing detail beyond what the schema already states, which is the expected baseline for this case.

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 full call detail record) and scopes it to COMPLETED calls. It explicitly distinguishes itself from the sibling get_call_status, 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?

Explicitly names the alternative (get_call_status) and the condition that selects it (call still in progress). The when-to-use boundary is fully specified rather than inferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds genuinely useful context beyond them — empty-result semantics (no error, just nothing found) and a privacy caution about sharing audio URLs. The trailing 'Read-only' is redundant with the annotation, and it omits things like rate limits or pagination.

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, then constraints, then behavioral notes, in four tight sentences. Minor waste in repeating 'Read-only' after the readOnlyHint annotation, but overall appropriately sized with no digressions.

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

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

For a two-parameter read tool with no output schema, the description adequately covers what is returned ('metadata and recording_url'), the exactly-one input rule, and empty-result behavior. Enough for correct invocation; only engagement-level details (pagination, URL expiry) are absent.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the 'exactly one of call_uuid or recording_id' mutual-exclusion constraint is not expressed by the schema's two independent optional properties. That makes the parameter guidance additive rather than redundant.

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 ... and return') and resource ('the recording(s) of a call') with account scope, and distinguishes itself from the generic list_recordings/delete_recording siblings by being a point lookup keyed on a call or recording. It is clear, but never names the alternative tools, so it stops short of full sibling differentiation.

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

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

Gives clear invocation context: 'Provide exactly one of call_uuid or recording_id' and warns that 'an empty result means no recording exists,' which steers correct usage and interpretation. It does not, however, tell the agent when to prefer this over list_recordings or other recording tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds genuinely new behavioral context by defining what each state means and signalling that 'completed' comes from the call detail record (i.e., after the fact). It stops short of describing polling/eventual-consistency behavior, so it is 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?

One dense sentence front-loads the action and the state vocabulary, followed by a short qualifier. The trailing 'Read-only' restates the readOnlyHint annotation and is the only mild redundancy.

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

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

For a single-parameter read tool with no output schema, the description conveys the core return semantics (three lifecycle states) that the schema cannot. It omits whether additional fields are returned and how often to poll, which are minor but real gaps.

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

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

Schema description coverage is 100% and the parameter description already states that request_uuid from make_call is accepted. The description repeats that information rather than adding format, charset, or error semantics, 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 precise verb and resource ('Return the current lifecycle state of one call') and enumerates the possible states, which distinguishes it from get_call_details and list_live_calls. It does not name those siblings explicitly, which is the only thing separating it from a 5.

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

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

The description implies when to use it (after make_call, using its request_uuid) but never states when NOT to use it or points to get_call_details / list_live_calls as alternatives. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description's 'Read-only' merely restates that. Its real added value is disclosing the return content (current running calls vs. account maximum), which matters since there is no output schema. It says nothing about scope (account vs. subaccount) or any rate limits.

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

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

Two short sentences with the substantive payload (current vs. maximum concurrency) front-loaded and no filler.

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

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

With no output schema, the description usefully carries the return-value meaning. It omits scope (which account/subaccount the limit applies to) and does not distinguish itself from neighboring live-call tools, which is the only real gap for such a simple read.

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

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

The tool takes zero parameters, so the baseline is 4. There are no arguments whose semantics could be misread, and the description correctly introduces none.

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: returns current running calls versus the account's maximum concurrency. It is distinguishable from call-listing siblings because it reports a capacity ratio rather than calls themselves. It does not explicitly name a sibling it differs from, so it falls short of a 5.

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

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

No explicit when-to-use or when-not-to-use statement, and no alternative tools are referenced (e.g., list_live_calls for the actual call list). The purpose implies a capacity-check use case, but the agent must infer it.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower, and the description still adds real context: it constrains the lookup to a 'running' conference and itemizes the response payload, which matters since no output schema exists. It does not mention failure behavior for a non-existent or ended conference.

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

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

Two sentences, no filler, with the retrieval action and endpoint front-loaded and the workflow guidance second. Every clause carries information.

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

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

For a single-parameter read tool with no output schema, the description adequately covers what is returned and how the result is consumed downstream. Only minor gaps remain around error/empty-result behavior.

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

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

Schema description coverage is 100%, and the schema already states the name must match the <Conference> XML element exactly. The description adds only the phrase 'by name,' 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 and resource ('Get one running Vobiz conference room by name') with the underlying endpoint, and enumerates the returned fields (run time, member count, member_id, call_uuid, caller, mute/deaf state). This clearly distinguishes it from the sibling list_conferences, which enumerates rather than retrieves a single room.

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

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

Gives a concrete downstream purpose: 'Use it to find the member_id values that the mute, deafen, kick, hang-up and play tools need,' naming the sibling tools that consume its output. It lacks an explicit when-not clause (e.g., use list_conferences to enumerate rooms), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, so 'Read-only' adds nothing new; the ordering guarantee ('oldest first') is genuine added behavioral context. It does not describe pagination behavior, result volume, or the limits of the openWorld data source.

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

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

Two short sentences that are entirely front-loaded: the action first, then the sourcing hint, then the safety/ordering note. 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 simple read tool with an output schema absent, the definition covers identity, sourcing, and ordering, and the schema covers the page-size parameter. Missing only a note on how paging/offset works in practice, which is a minor gap.

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

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

Schema coverage is 67%: limit and conversation_id are documented inline, offset is not. The description adds only the provenance of conversation_id and says nothing about paging, so it neither compensates for the gap nor overrides the schema.

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

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

States a specific verb and resource ('Return the messages of one conversation'), and the parenthetical identifies the ID's provenance, distinguishing it from siblings like list_messages and get_message. An agent knows exactly what this returns 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 tells the agent where the required conversation_id comes from (list_conversations or a message's conversationId), which is real routing guidance. It does not, however, state when not to use it or contrast it with get_message for a single message.

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=false, so 'Read-only.' in the description adds nothing. What does add value is the enumeration of the return payload, which is useful given there is no output schema. However, it omits important behavior: what is returned when no input was captured, whether the result is retained/consumable once read, and any retention or race conditions.

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

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

A single front-loaded sentence with the resource first and the return payload in a compact parenthetical; nothing is redundant. The trailing 'Read-only.' is the one wasted clause since it merely restates the annotation.

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

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

With no output schema, the description must carry the return contract, and listing the three result fields is a reasonable start. But for a retrieval tool tied to an asynchronous gather, an agent still lacks the key lifecycle facts: when a result becomes available, whether calling too early returns empty or errors, and how flow_id is sourced.

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

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

There is exactly one parameter, flow_id, with 0% schema description coverage and only a hex pattern constraint. The description never mentions flow_id, its origin, or how to obtain it from gather_dtmf, so it does not compensate for the empty schema documentation.

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

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

The description uses a specific verb ('Return') plus a specific resource ('the DTMF input') and even enumerates the returned fields (digits, call_uuid, signature verification). It distinguishes itself implicitly from the sibling gather_dtmf, which initiates the gather rather than retrieving its result, though it never states that contrast outright.

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

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

Linking the tool to 'a gather_dtmf / hosted flow' gives an implied usage context, but there is no explicit guidance on when to call it (e.g. after the gather completes), no statement of what happens if the gather is still pending, and no alternatives named.

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 'Read-only' line is largely redundant, but the description goes beyond the annotations by disclosing the return payload (status, error details, status history) and the lifecycle states sent → delivered / failed, which tells the agent what meaningful states to expect.

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

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

A single front-loaded sentence with the resource, return contents, and state flow, plus a two-word safety tag. No wasted words.

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

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

For a single-resource read with no output schema, the description adequately conveys what comes back and the entity's lifecycle. It omits only edge behavior such as not-found handling and whether history is paginated or bounded.

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

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

There is 1 parameter and the schema description coverage is 0%, so the description must carry the load; it only says 'by ID', which conveys that message_id is an identifier but adds no format, source, or lookup guidance beyond the schema's own regex pattern.

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 message by ID) and enumerates what the payload contains: current status, error details, and status history. The singular 'one message by ID' implicitly and clearly distinguishes it from list_messages and get_conversation_messages.

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

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

Usage is only implied via the read-only nature and the ID-based lookup; there is no explicit statement of when to use this versus list_messages or get_conversation_messages, nor any mention of prerequisites or failure behavior.

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 'Read-only' in the description is largely a repeat of structured data. The description does add value by scoping the call to 'one phone number on this account' and by disclosing the shape of the returned metrics, but it says nothing about rate limits, data freshness, or error behavior for unknown numbers.

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 tool's purpose and the returned fields in a single dense sentence, with no filler. The trailing 'Read-only.' is marginally redundant given the annotations, but it is short and harmless.

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

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

With no output schema, the description compensates by enumerating the key return fields, and annotations already carry the safety profile, so an agent has enough to call it correctly. It is only slightly incomplete on the historical window (days) and the meaning of 'usage status'.

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

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

Schema coverage is 100%, so the schema already documents phone_number (E.164), granularity (daily/hourly) and days (default 30, max 90); baseline is 3. The description's mention of 'daily/hourly' statistics loosely mirrors the granularity enum but adds no window, default, or format detail beyond the schema.

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

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

The description gives a specific verb and resource ('Return usage and health of one phone number') and enumerates the returned data (spam flag, usage status, answer rate, failed calls, minutes), which meaningfully separates it from the similarly named sibling get_phone_number_details. It stops short of naming or contrasting that sibling explicitly, so it lands at 4 rather than 5.

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

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

There is no guidance on when to choose this tool over get_phone_number_details or list_phone_numbers, and no stated prerequisites or exclusions. The only usage signal is 'Read-only', which is a safety note rather than selection guidance.

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

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

Annotations already declare readOnlyHint=true, and the description's only behavioral statement, 'Read-only', merely repeats that. It adds nothing about error cases (e.g., number not on this account, unowned numbers) or any constraints on repeated calls, so there is no value beyond the structured hints.

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

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

A single front-loaded sentence that names the resource first and the scoping constraint immediately after. No filler, no restatement of the title.

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

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

With no output schema, the enumerated field list usefully tells the agent what comes back, and annotations cover the safety profile for a simple read. The only gap is what happens when the number is invalid or not owned by the account.

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

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

Only one parameter with 100% schema description coverage, so the schema already documents the E.164 format and example. The phrase 'on this account' slightly implies the number must belong to the caller's account, but no format or syntax detail is added beyond the schema baseline.

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

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

States a specific verb (return) and resource (details of a phone number) and enumerates the returned fields (status, capabilities, application, sub-account, fees, billing dates), which sharply separates it from get_number_health and update_phone_number. The 'ONE phone number on this account' scoping also contrasts it with the list_* siblings, though no sibling is named explicitly.

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

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

No when-to-use or when-not-to-use guidance. It never says to prefer this over list_phone_numbers when you need a single number's configuration, nor does it point to get_number_health for health metrics or list_phone_numbers for enumeration.

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?

Confirms 'Read-only', consistent with readOnlyHint=true, and adds context beyond the annotations: registration details appear only when a device is registered, and passwords are never returned here (reset via the Vobiz console). Useful negative and conditional disclosure; error/permission behavior is still unstated.

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 what is returned, then the use case, then the two caveats. Nothing redundant, though it is close to the maximum useful length for a single-read tool.

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

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

With no output schema, the description carries return-value burden and does so by listing the fields, plus the online-status and password caveats. Only the endpoint_id semantics/value source is left uncovered.

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

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

Schema description coverage is 0% and the description never explains the sole required parameter endpoint_id — no mention of its format (the schema enforces ^\d{4,25}$) or where to obtain it. The description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Return one Vobiz SIP endpoint') and enumerates the returned fields: username, alias, SIP URI, attached application, registration details. This distinguishes it cleanly from the sibling list_sip_endpoints, which returns many.

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

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

Gives a concrete use case: 'Use it to check whether a soft-phone or WebRTC client is online.' No explicit when-not or named alternative, but the task context is clear and actionable.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: SIP credentials are redacted, and it lists which configuration facets are returned. It does not discuss auth requirements or error behavior, but for a single read that is a minor gap.

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

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

Three short sentences, front-loaded with the core action, then the returned surface, then the redaction caveat. No filler and nothing buried.

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

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

With no output schema, the description compensates by naming the returned fields, which is what an agent needs for a single-resource GET. Missing only error/not-found behavior and any note that the trunk must belong to the caller's account.

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

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

Schema description coverage is 0%, and the description says nothing about trunk_id beyond its name. The name is self-explanatory and the schema's UUID pattern carries the format constraint, so this is adequate but adds no meaning beyond structured data.

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 SIP trunk's configuration') and enumerates the fields returned (domain, status, direction, limits, transport, recording). The singular 'one' implicitly separates it from list_sip_trunks, but no sibling is named explicitly, so it stops short of full differentiation.

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

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

There is no statement of when to use this tool versus list_sip_trunks, get_sip_endpoint, or list_trunk_credentials, and no prerequisites or exclusions. The only contextual cue is the trailing 'Read-only', which is a safety claim rather than usage guidance.

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

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

Annotations already declare readOnlyHint=true, so the bar is lower, but the description adds a genuinely useful disclosure beyond them: credentials are redacted, so the agent knows the response will not contain secrets and must not be relied on for auth material. It still omits what happens when the ID does not exist or is not accessible.

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

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

Three short sentences, front-loaded with the return contents, then the redaction caveat, then the read-only note. No filler, no repetition of the tool name, and every clause carries information.

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

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

For a single-parameter read tool with no output schema, the description enumerates the returned fields (name, contact, status, KYC mode, rate limit, permissions, timestamps) plus the redaction behavior, which covers the return contract the schema omits. 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?

Only one parameter, and schema description coverage is 100% — the schema already documents the SA_... pattern and even points to list_sub_accounts as the source. The description adds nothing about the ID's format or provenance, 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 sub-account's details') and enumerates the fields returned, so the agent knows exactly what it retrieves. It implicitly distinguishes itself from list_sub_accounts via 'one', but never names the sibling, so differentiation is left to inference.

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

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

The description implies the natural use case (fetch a single sub-account's details) and the schema points at list_sub_accounts as the source of the ID, which implies a list-then-get flow. However there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. get_sub_account_kyc_status for KYC detail).

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 the trailing 'Read-only' largely restates structured data. The description does add real behavioral context beyond the annotations by disclosing the aggregation shape (overall + per-document + pause flag), which is the kind of information an agent needs to interpret the call without an output schema.

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

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

One dense sentence front-loads the return payload, followed by a terse two-word annotation echo. Nothing is padded, though 'Read-only' is redundant against readOnlyHint=true and could be dropped.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields, and the single required parameter is fully covered by the schema. It is nearly complete for a read-only lookup; only the relationship to the KYC session tool is left unstated.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema already fully documents sub_auth_id including its SA_ pattern and its source (list_sub_accounts). The description adds no parameter-level detail, which is the expected baseline 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+resource (returns a Vobiz sub-account's aggregated KYC state) and enumerates exactly what comes back: overall status, per-document status for PAN/GST/CIN/Aadhaar, business type, and call-pause state. An agent can immediately distinguish this from the sibling get_sub_account (general account data) and create_sub_account_kyc_session (which creates a session rather than reading status).

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

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

Usage is only implied by the purpose: an agent can infer it should call this to check KYC status. There is no explicit statement of when to prefer this over get_sub_account or the KYC session tool, and no prerequisites (e.g., needing a completed session first) are mentioned.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, and the description adds genuinely useful behavior beyond them: 'Read-only, no API call' clarifies this is a local content lookup with no network side effects, and it discloses the return payload shape. It does not cover edge cases such as an unmatched or empty section value, so it is good but not exhaustive.

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

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

Two tight sentences, front-loaded with the tool's output purpose, then the optional parameter nuance and the safety note. No filler and nothing buried.

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

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

With no output schema, the description correctly carries the burden by describing what is returned (endpoints, request shapes, VobizXML rules, pitfalls), and it explains the section-filtering behavior. Minor gaps exist around invalid/empty section handling, but an agent has enough 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%: the `name` enum and the `section` prefix-match semantics are already documented in the schema. The description only restates that `section` loads one `##` section and that names come from list_vobiz_skills, which is marginally useful cross-tool context but adds little beyond the schema baseline.

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

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

States a specific verb and resource ('Return the instructions of one Vobiz Agent Skill') and immediately enumerates the content type (endpoints, request shapes, VobizXML rules, pitfalls). It also contrasts with list_vobiz_skills by noting where skill names come from, so an agent can distinguish the two 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?

The description gives clear usage context: use `section` to fetch a single `##` section, and names list_vobiz_skills as the source of valid names. It stops short of an explicit when/when-not rule (e.g. 'call list_vobiz_skills first, then load only the skill you need'), so it is strong context but not full routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds real value beyond them: it explains that the member leaves the room AND their call terminates, and that confirm: true is required. It does not cover what happens on partial failure when a comma-separated list contains an invalid ID, which keeps it short of a 5.

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

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

Three compact sentences, front-loaded with the action and effect, then routing to the sibling, then parameter notes. The trailing 'Pass one member_id, a comma-separated list, or all. Requires confirm: true.' is somewhat redundant with the schema and the embedded DELETE path adds little, but nothing is bloated.

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, annotation-covered conference tool with full schema coverage and no output schema, the description supplies the necessary effect, sibling routing and confirmation gate. Only edge-case behavior (mixed valid/invalid member lists, idempotent repeat behavior) is unaddressed, which is minor here.

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 conference_name, member_id and confirm, including the 'all' keyword and the comma-separated pattern. The description's restatement ('one member_id, a comma-separated list, or all' and 'Requires confirm: true') largely duplicates that, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource — 'End the calls of members in a live Vobiz conference' — and clarifies the effect (they leave the room and their call hangs up). It explicitly distinguishes itself from the closest sibling, kick_conference_member, so an agent can choose correctly 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 an explicit when-to-use ('drop a participant completely') plus a named alternative and the condition that selects it ('to keep their call going after they leave, use kick_conference_member'). It also states the confirm: true prerequisite, so the invocation gate is clear.

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

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

Annotations already declare destructive/openWorld/idempotent hints, so the bar is lower, but the description still adds real behavioral context: the hold works by transferring the leg to a hosted flow, music loops until resume, and it only works in HTTP mode with VOBIZ_PUBLIC_URL. It does not detail the effect on the live call state during the hold, a minor gap.

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

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

Four short, front-loaded sentences with no filler; the mechanism, the resume path, the mode constraint, and the confirm requirement each carry information. Slightly choppy phrasing ('and the XML URL that should take over') but nothing wasteful.

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 mutation tool with no output schema but full annotation coverage, the description supplies the mechanism, resumption path, mode constraint, and confirmation requirement an agent needs to invoke it correctly. Only the state effect on the call during hold is unaddressed.

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 75%, so the schema already documents legs, confirm, and music_url well. The description reinforces the confirm requirement and that music is optional (silence if omitted), but adds little syntax or meaning beyond what the schema fields 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 ('Puts a leg on hold') and explains the mechanism (transferring to a hosted flow playing hold music or silence on loop). It also names the counterpart action, unhold_call, so the agent can distinguish this from its resume sibling 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?

Explicitly names unhold_call as the way to resume, and states two preconditions: 'HTTP mode with VOBIZ_PUBLIC_URL only' and 'Requires confirm: true.' This gives clear context for when the tool is valid, though it stops short of stating when-not-to-use or distinguishing from play_audio/stop_audio alternatives.

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

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

Annotations already declare destructive=true, readOnly=false, idempotent=false, but the description adds the crucial nuance that the member's call is NOT terminated and instead continues to the next VobizXML element. It also flags the confirm:true requirement. This clearly exceeds the annotation layer, though rate-limit/return details are absent.

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 what the operation does and its key behavioral trait (call stays up), then routes to the alternative and covers the confirm requirement. No wasted sentences; every clause carries information.

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

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

For a 3-param mutation tool with full schema coverage and no output schema, the description supplies the behavioral context an agent needs (call persistence, confirm requirement, alternative tool). Return-value detail is unnecessary here, so coverage is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents member_id formats (single, comma-separated, or 'all') and the confirm requirement. The description restates these but adds no syntax or format detail beyond what structured data provides — baseline 3.

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

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

States a specific verb (Remove/Kick) and resource (members of a live conference), and explicitly distinguishes itself from the sibling hangup_conference_member. An agent can tell the two apart 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?

Names the alternative tool explicitly ('To end their call instead, use hangup_conference_member') and gives the selecting condition, which is exactly the when-to-use guidance required. It also describes the positive outcome of using this tool (call continues with next VobizXML element).

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