DIDWW MCP

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

With annotations present, this still adds substantial context: success preconditions, the non-purchase/reversible nature of the operation, the release semantics of channels_count:0, and the return payload. These behavioral traits are not derivable from the annotations alone. There is only mild tension with destructiveHint=true (the release path), which the description actually explains rather than contradicts.

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

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

Front-loaded with the purpose, then parameters, preconditions, release semantics, the not-a-purchase clarification, and returns. Every sentence carries distinct information; none is filler.

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

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

For a mutation tool with no output schema, the description covers what is mutated, preconditions, reversibility, the alternative purchasing path, and the return payload (DID number, reserved count, pool). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters and their formats, giving a baseline of 3. The description adds semantic meaning by tying capacity_pool_id and channels_count to the pool's free-channel and country-coverage constraints, going slightly beyond the schema text.

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

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

States a specific verb and resource ('Reserve dedicated inbound channels for one of the customer's DIDs out of a Capacity Pool') and explicitly distinguishes itself from buy_capacity_channels, which it names. An agent can tell it apart from the assign_did_to_trunk/capacity_group siblings by the 'dedicated channels out of a pool' scope.

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

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

Gives explicit when-to-use (reserving dedicated channels) and when-not (purchasing, which is buy_capacity_channels), plus the prerequisites for success: country must be covered by the pool, the pool must have free channels, and the DID Group must allow additional channels. It also explains the channels_count:0 release case, which is a distinct usage mode.

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

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

Annotations already declare the mutation/idempotency/no-cost safety profile, and the description reinforces cost behavior and reversibility plus return semantics. It does not, however, warn about the destructiveHint=true angle — that moving the DID into a group may displace its previous channel allocation — so the destructive side is under-communicated relative to 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?

Front-loaded with purpose and effect, then parameters, then preconditions, then the cost clarification and return value. Each sentence carries distinct information with 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?

With no output schema, the description correctly covers the return value (DID number and new group, or a readable error) and all call preconditions. The only shortfall is that the destructive/reassignment behavior implied by destructiveHint=true is not spelled out.

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

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

Schema coverage is 100% and both parameters are fully documented there (including the 'must belong to the customer' constraint). The description restates the two parameter names but adds no format or syntax detail beyond what the schema provides, so it meets the baseline rather than exceeding it.

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+target (assign a DID to a Shared Capacity Group) and immediately explains the effect: the DID draws inbound channels from the group's Capacity Pool. It distinguishes itself from siblings by contrasting with buy_capacity_channels and by the unassign counterpart, so an agent can route correctly without opening a schema.

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

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

Gives explicit preconditions for use (DID's country must be covered by the Capacity Pool; its DID Group must allow additional channels) and names the alternative that money-spending cases should use ('only buy_capacity_channels spends money'). It clearly frames this as allocation of already-purchased channels rather than a purchase.

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

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

Annotations already declare destructive=true and idempotent=true, and the description corroborates rather than contradicts them. It adds substantial beyond-annotation detail: all-or-nothing batch atomicity, the validation preconditions (inbound-capable trunk, SMS-enabled group), error behavior naming offending ids, and the re-routing side effect when a number was already routed.

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 dense but front-loaded passage leading with the core action and immediately following with the batch/unassign mechanics. Some validation detail is packed into parentheticals, but every clause carries operational information rather than filler.

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

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

For a two-parameter mutation with no output schema, the description covers return values (the trunk or null, affected numbers, count), batch failure semantics, and the disabled-incoming-SMS outcome of unassigning. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the interdependence that every id must belong to the customer account and pass group/trunk validation, and that omitting sms_trunk_id is an unassign rather than an error. The 1..100 range itself is already in 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 — routing incoming SMS for one or many DIDs to an SMS trunk — plus the scope (single batch call) and the inverse operation (bulk unassign). The 'incoming SMS ... SMS trunk' framing distinguishes it from voice-oriented siblings like assign_did_to_trunk and assign_did_to_capacity_group.

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?

Clear context for both directions of use: assign by providing sms_trunk_id, or unassign by passing null/omitting it, with the consequence (incoming SMS disabled) spelled out. It never explicitly names a sibling alternative to defer to, 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 cover the safety profile (destructiveHint=true, idempotentHint=true), and the description adds substantial extra context: all-or-nothing batch semantics, that assigning replaces existing routing (reported as re-routed FROM the previous trunk), the null-to-unassign overload, and what the response contains. This is far beyond what annotations provide.

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

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

A single front-loaded paragraph where each sentence carries distinct information (routing, accepted ids, unassign mode, atomicity, return shape). It is dense but no sentence is wasted; only the length of the single block slightly hurts scanability.

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 proactively documents return contents (trunk name/type, assigned/unassigned numbers and count, re-routed reporting). Combined with atomicity and unassign behavior, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema: trunk_id accepts any type returned by list_trunks (SIP, PSTN, phone.systems, trunk group), and null/omit means unassign rather than a normal target.

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 (assign) and resource (DIDs → Voice IN Trunk) plus the routing consequence. It is clearly distinguishable from siblings like assign_did_to_sms_trunk and assign_did_to_capacity_group by naming the Voice IN Trunk target.

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: which trunk ids are acceptable, the null/omit path that turns the call into an unassign, and the max-100 batch constraint. It doesn't explicitly name the sibling assignment tools to steer between them, but the routing scenario 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?

Far exceeds the annotations (which only flag non-readOnly, destructive, non-idempotent): it discloses prorated pricing to the renew date, immediate balance charge, immediate channel availability, and the confirmation_token preview-then-execute flow with safe retry semantics. 'This spends real money' makes the financial consequence unmistakable.

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

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

Front-loaded with the core action, then layers pricing, delivery, and pre-check details in order. It is somewhat long, but nearly every sentence carries actionable information for a money-spending operation.

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

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

For a destructive, irreversible money-spending tool with no output schema, the description covers prerequisites, preview/confirm flow, retry safety, and downstream usage of purchased channels. An agent has everything needed to call it correctly without accidental double purchases.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value beyond the schema by explaining why country_iso exists (fail fast before any charge) and reinforcing the capacity_pool_id source. The confirmation_token two-call semantics are covered richly in the description, though mostly duplicating the schema text.

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

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

States a specific verb (purchase/add channels) and resource (Capacity Pools via an Order), and distinguishes itself from siblings like buy_did and list_capacity_pools. An agent immediately understands this is a capacity-purchase operation.

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

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

Provides clear context: the pool_id comes from list_capacity_pools, qty is the number to add, and country_iso is an optional fail-fast pre-check for mismatched pools. It does not explicitly name alternatives or exclusions, but the workflow and preconditions are well-telegraphed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: the token-less call charges nothing, confirmation executes the purchase and constitutes acceptance of restrictions, the balance is charged, out-of-stock defaults to a charged back-order, and async allocation/registration cases are spelled out. 'This spends real money' is a clear final warning.

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 layered edge cases in a logical order, closing on the money warning. Long but every sentence carries distinct behavioral information an agent needs before spending funds.

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, yet the description previews the return shape (location/type, channels, prices, balance impact, restrictions, confirmation_token, purchased ids/numbers) and covers the async and registration branches. Nothing essential to 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 coverage is 100%, so baseline is 3, but the description adds genuine cross-field meaning: it warns sku_id is the SKU UUID and NOT group_id, explains confirmation_token as empty-then-execute, and clarifies allow_back_ordering's default semantics. It stops short of restating qty/description, which the schema already covers.

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

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

Opens with a precise verb+resource: 'Purchase one or more DIDs by creating an Order.' This distinguishes it cleanly from siblings like buy_capacity_channels and from read tools such as get_did/search_coverage.

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

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

Explicitly routes the agent to search_coverage for the sku_id, prescribes the two-step token flow, and states when to act on pending DIDs (tell user, then list_dids) and registration_required (follow next_steps). It also names the condition for passing allow_back_ordering=false.

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

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

Goes well beyond the annotations (destructive/not idempotent) by disclosing concrete side effects: the email link stops working, no notification email is sent, and only pending invites are eligible. It also explains that re-inviting requires a new call, which the annotations cannot convey.

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

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

Three sentences, all front-loaded and free of filler, with the core action first and caveats after. Slightly dense with parenthetical cross-references, but every clause carries routing or behavioral 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 destructive mutation with no output schema, it fully covers eligibility constraints, side effects, unavailable alternatives, and the re-invite path. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and already documents the id as a UUID from list_invite_requests, so the description's restatement adds little. Basline would be 3, but referencing the discovery tool in prose gives marginal routing 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 specific verb (revoke) and resource (a PENDING invitation) with the qualifying state front-loaded. It cites list_invite_requests as the source of the id, so an agent can distinguish it from create_invite_request and list_invite_requests at a glance.

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

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

Explicitly names when not to use it: accepted invitations are now user access and cannot be revoked via MCP, directing the agent to the DIDWW panel. It also points to list_invite_requests for discovery and create_invite_request for re-inviting, covering the full decision path.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds the meaningful behavioral detail that is not in annotations: the three possible outcomes (pending/completed/expired) and what 'completed' carries. It does not mention polling/retry behavior, which 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?

Front-loaded with the core action, then token sourcing, then return states, then the call trigger. Every sentence carries distinct information with no redundancy.

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

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

No output schema exists, and the description compensates by enumerating the return states and their meaning, including what to do on 'expired'. For a single-parameter read tool this is complete.

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

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

Schema coverage is 100% and the single token parameter is fully described in the schema. The description restates the token source, adding no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource (check upload link status) and immediately ties it to the two sibling tools that produce the token, so an agent can distinguish it from create_* and list_* siblings without opening the schema.

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

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

Gives an explicit trigger ('Call it when the user says they are done uploading') and, for the expired case, routes the agent to the alternative ('issue a fresh link with the tool that issued this one'). When-to-use and the alternative path are both spelled out.

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

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

Annotations already cover the safety profile (write, non-idempotent, closed-world, non-destructive), and the description adds real value on top: the requirement_id pre-check returns warnings instead of failing later, the country normally must match the DID country, and address data must never be invented. It still does not say what happens on duplicate submissions or describe auth/rate constraints, so it stops short of a 5.

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

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

Front-loaded with purpose and flow position, and nearly every sentence carries actionable guidance (sequencing, pre-check, data-integrity rule). It is on the long side for a create tool, but the density is justified rather than 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?

With no output schema, the description still explains the return behavior (warnings from the requirement pre-check) and covers prerequisites, ordering, and constraints an agent needs to invoke it correctly in the DID flow.

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 a constraint the schema does not state — country_iso usually must match the DID country from the requirement — and reinforces the pre-check semantics of requirement_id.

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

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

States a specific verb (create) plus the exact resource (a regulation address under an existing identity of the authenticated customer) and situates it as step 4 of the DID registration flow. This cleanly distinguishes it from update_address, delete_address and validate_address 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?

Explicitly sequences the tool: comes after list_requirements, create_identity and proof upload via create_regulation_upload_link, and must be followed by create_regulation_upload_link and create_address_verification. It also names the fallback (ask the user for real data) and clarifies the end-customer case is normal, not an exception.

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

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

Annotations already mark this as a non-read-only, idempotent=false, non-destructive write. The description adds real context beyond them: the verification starts in status New and is processed asynchronously, and the call returns a verification id plus status. It does not state permission/authorization requirements or what happens to already-linked DIDs, so it stops short of a 5.

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

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

Front-loaded with the action and its flow position, then the gating condition and the return behavior. Every sentence carries information, though the parenthetical flow chain and the doubled service_description guidance make it denser than needed.

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 write tool with no output schema, the description covers prerequisites (documents uploaded, no pending one-time document), the alternative path, the optional-field trigger, and the asynchronous outcome/status model. An agent has everything required to call it correctly.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the service_description_required condition. The description repeats the same conditional guidance without adding format, batch-limit, or cross-parameter constraints beyond the schema's 'same country and DID Group type' note. 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 ('Submit DIDs ... for verification against a regulation address') and pins its position in the DID registration flow. It also contrasts itself with the sibling create_regulation_upload_link, so the agent can distinguish the two without reading 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?

Explicit when-to-use ('ONLY when all required identity and address proof documents are already uploaded') and an explicit when-not with the named alternative ('if such a document is required, use create_regulation_upload_link with the did_ids instead'). Prerequisite state is spelled out rather than 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 flag destructiveHint=true and idempotentHint=false; the description goes well beyond by explaining WHY (metered channels bill per use in USD, hence confirmation-gated), the allocation-vs-purchase distinction for shared channels, the preview-then-confirm mechanism, and the country-coverage validation that runs before creation. This is exactly the behavioral context an agent needs for a billing-affecting mutation.

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

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

Front-loaded with the core action, then layers the constraint, billing rationale, and coverage pre-check in a logical order; every sentence carries information. It is a dense paragraph and slightly long, but no sentence is filler.

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

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

With no output schema, the description still states the return ('created group id and key attributes, or a readable error'), covers all six parameters' semantics, the confirmation flow, and the billing/destructive implications. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the interaction constraint that at least one of shared/metered must be > 0, that amounts are in USD, and that country_iso triggers a pre-creation coverage check. The 'count not boolean' semantics are in the schema, so this is additive but not exhaustive.

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 Shared Capacity Group') and scopes it precisely ('inside one of the customer's Capacity Pools'). This clearly distinguishes it from create/update/delete/assign siblings like update_capacity_group and assign_did_to_capacity_group 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?

Gives explicit preconditions (provide name + capacity_pool_id, at least one channel count > 0), describes the confirmation-gated two-step flow, and routes the agent to list_capacity_pools for covered_country_isos and to the existing-group update path ('raising metered_channels_count on an existing group has the same effect'). When and how to use it is fully specified.

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 give a coarse safety profile (readOnlyHint=false, destructiveHint=true, non-idempotent), while the description discloses the consequential traits: new-service mode is a PAID monthly per-number subscription billed at staff activation, the two-call confirmation gating that submits nothing on the first call, that resubmit is free and ungated, and that zero assigned numbers auto-cancels the service. It also explains token retry safety, none of which the annotations convey.

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

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

Purpose and mode selection are front-loaded, then billing, gating and prerequisites follow in a logical order. It is dense rather than padded, though the length is substantial for a single tool and a few billing/auto-cancel details 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 billing-affecting mutation with no output schema, the description covers what an agent needs: prerequisites, mode selection, cost implications, the confirmation round-trip, and the return contract ('pending verification id, or a readable error when validation fails'). Nothing material is left for the agent to guess.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by stating the cross-parameter mode constraint and adding a qualifier the schema omits — DIDs must be 'of the same country and DID group type as the emergency requirement'. It also frames confirmation_token as a preview-then-confirm handshake rather than just a field.

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

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

The first sentence states a specific verb and resource ('Submit an emergency verification for staff review'), then splits the tool's two distinct modes (new service vs. resubmit) with the exact parameters that select each. An agent can distinguish this from siblings like create_address_verification or create_regulation_upload_link without opening any schema.

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

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

Explicit when-to-use for each mode, including status preconditions ('allowed when the service is in new, changes required or active status') and mandatory pre-steps ('BEFORE calling, run list_emergency_requirements ... fill any missing identity fields with update_identity'). It also names the alternative route when proofs are missing (create_regulation_upload_link with purpose "emergency"), which is genuine 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 only declare the safety profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds the behavior that actually matters here: the export runs in the background for up to ~5 minutes, date ranges are limited to the current and 2 previous months, future date_to is silently clamped (surfaced as date_to_clamped_to) while a future date_from is an error, and the final output is a download link. This is substantial disclosure 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?

Front-loaded with the purpose, then ordered by enum semantics, date rules, and polling workflow, with no filler sentences. It is a dense single block without visual breaks, which slightly hurts scanability for a description this long, but every sentence carries load-bearing 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?

With no output schema, the description carries the return-value burden and does so: it promises an export_id, warns about the date_to_clamped_to field, and explains the terminal download link. Combined with the polling instruction and per-type date rules, an agent has everything needed to call this correctly and handle 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%, so the baseline is 3, but the description genuinely adds meaning the schema lacks: the semantics of every export_type enum value (including the deprecated legacy view and its row-granularity distinction), the current-plus-2-months window that appears nowhere in the schema, and the error/clamp asymmetry between date_from and date_to. Some date-requirement text duplicates the schema, which keeps this from a 5.

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

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

Opens with a specific verb+resource+format+scope: "Start an asynchronous CSV export of the authenticated customer's data." An agent can immediately separate this from siblings like get_export (poll status) and list_exports (enumerate existing exports), both of which are named or implied.

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

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

Gives explicit when-to-use guidance per export_type, states which types require/accept/forbid date ranges, deprecates legacy_inbound_sms in favor of inbound_sms, and names the follow-up tool and workflow: "poll get_export with the returned export_id until it is completed." Nothing about selection 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 cover mutation/safety hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds non-obvious behavioral context: the identity subject is routinely the caller's own end customer, first_name/last_name denote the authorized representative for business identities, and requirement_id returns warnings instead of failing later. It does not cover permissions or duplicate-creation behavior, but this is well beyond the annotation baseline.

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

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

Front-loads the core purpose and workflow, then layers conditional rules and the subject/representative caveat. It is longer than typical but each block earns its place; minor redundancy with the schema on phone_number digits and business-only fields keeps it from a 5.

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 14-parameter mutation tool with no output schema, the description supplies the full workflow, conditional field rules, data-authenticity guidance, and what requirement_id returns (warnings). Enough for an agent to call it correctly, though it could say more about the created-identity response fields.

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 parameters are already documented (including company_name requirement for business and digits-only phone). The description adds cross-field conditional context (company_name needed for business, mandatory fields from the requirement) and the requirement_id pre-check effect, but largely restates what the schema already carries. 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 (create a regulation identity) and positions it precisely in the DID registration flow as step 2 after list_requirements, which distinguishes it from sibling creation tools like create_address and create_regulation_upload_link.

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

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

Gives explicit sequencing (after list_requirements, then create_regulation_upload_link, then create_address), tells when to use identity_type values per the requirement, and explains the optional requirement_id pre-check. Alternatives and ordering are unambiguously 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?

Beyond the annotations, the description discloses that confirming SENDS AN EMAIL, explains the two-step confirmation_token flow (first call returns a preview and sends nothing), and states that retrying the confirming call with the same token never emails twice. These are exactly the side-effect and retry semantics an agent needs and are not derivable from the annotations alone.

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 purpose, then the email side effect, then lifecycle, then return shape — a logical order. It is somewhat dense with the lifecycle chain, but every sentence carries information an agent needs, so only minor trimming is possible.

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 (id, email, name, roles, status, created_at), and it covers the destructive/email side effect and the token flow. Nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents email, name, roles, and confirmation_token. The description largely restates what the schema provides (role names, confirmation flow), adding no syntax or format detail beyond it; baseline 3 applies.

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

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

The description states a specific verb and resource ('Invite a new user by email to access the authenticated customer account with a chosen set of panel roles') and immediately disambiguates from siblings by naming list_invite_requests and cancel_invite_request. An agent can distinguish it from every other create_* 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?

It lays out the full invite lifecycle and explicitly routes the agent to list_invite_requests for pending invites and cancel_invite_request for revocation, so the surrounding context is clear. It stops short of stating a hard when-not-to-use condition, but there is no competing invitation-creation tool to exclude.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write. The description adds real value beyond that: the feature-gate precondition and its failure mode ('error is returned and nothing is created'), and that no host/destination is required. It stops short of noting that a non-idempotent create with a unique name can fail on retry.

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: purpose first, then the precondition, then the 'no host/destination' clarification, then routing alternatives, then return value. No filler, and the constraints 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?

Despite 11 parameters and no output schema, the description covers precondition behavior, siblings, and return shape ('created trunk id and key attributes'), while the schema handles all field semantics. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so every parameter including enums, ranges, defaults and patterns is already documented in the schema. The description only adds the negative fact that no host or destination parameter is needed. 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 phone.systems™ Voice IN Trunk') and clarifies the routing scope (assigned DIDs' inbound calls to the customer's cloud PBX). It explicitly distinguishes itself from create_sip_trunk and create_pstn_trunk, so an agent can pick it without opening sibling 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?

Names both alternative tools and the condition that selects them, and adds an explicit when-not: the phone.systems™ feature must be enabled or nothing is created. This is exactly the routing guidance an agent needs.

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 cover the safety profile (not read-only, not destructive, not idempotent), and the description adds substantial behavior beyond that: one-time link, browser-side encryption with the server never seeing plaintext, account-specific lifetime that must be read from expires_in_minutes rather than assumed, and automatic replacement of an existing proof. This is exactly the kind of context annotations cannot carry.

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

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

Purpose is front-loaded in the first sentence, and most sentences carry operational weight (QR delivery, lifetime, follow-up call). It is dense and long, with several sentences devoted to client-specific rendering warnings, but those warnings are actionable rather than filler.

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

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

There is no output schema, so the description carries the burden of describing returns — it does so explicitly (upload_url, qr_code_url, and qr_svg when requested) and tells the agent which value to prioritize. Combined with the sibling routing and follow-up call, nothing needed to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns a bump by restating and contextualizing the exclusivity rule (exactly one of identity_id/address_id plus proof_types) and the replacement semantics of proof_types within the workflow. It does not add syntax-level detail the schema lacks, so it falls short of a 5.

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

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

States a specific verb and resource — generate a one-time browser link (URL + QR code) for uploading proof documents — and immediately scopes it to explicitly chosen proof types on one identity or address. It also names the sibling it is not (create_regulation_upload_link), so an agent can route between them 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?

Explicit when-to-use (voluntary/preventive uploads, replacing an existing document), when-not (documents a requirement still demands → create_regulation_upload_link), and the follow-up step (call check_upload_status with the returned token once the user is done). It even pre-empts the delete_proof detour by explaining replacement is automatic.

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

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

Annotations only flag destructiveHint/idempotentHint, but the description goes well beyond them: per-minute billing, a confirmation-gated two-step flow where the first call creates nothing and returns a rate preview plus token, and USD-denominated amounts. It also discloses a failure mode (no rate = no trunk), which the annotations cannot express.

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

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

Front-loaded with the action and its effect, then billing/gating, then failure condition, then sibling routing. Every sentence carries new information; nothing is repeated from the schema or annotations.

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

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

For a 13-parameter mutation tool with no output schema, the description covers the workflow, cost implications, preconditions, and sibling routing well. It stops short of describing what a successful creation returns (trunk ID/handle) or any authorization requirements, which leaves a small gap for a creation tool.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds genuine meaning on top: the destination format is restated with a concrete example, and confirmation_token's 'leave empty on first call' semantics are explained in workflow terms rather than field terms. It does not explain the routing parameters (priority, weight, pop, ringing_timeout), but those are already fully documented in 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 ('Create a PSTN / call-forwarding Voice IN Trunk') and immediately scopes the behavior (inbound calls to assigned DIDs are forwarded to `destination`). It explicitly distinguishes itself from the two nearest siblings, create_sip_trunk and create_phone_systems_trunk, so an agent can route correctly without opening any schema.

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

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

Names both alternatives with their selection conditions ('For a SIP trunk use create_sip_trunk; for a phone.systems™ trunk use create_phone_systems_trunk') and states a hard precondition ('If the destination has no rate, the trunk cannot be created'). It also prescribes the two-call confirmation workflow, which is exactly the when-to-use guidance an agent needs.

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 (readOnly=false, idempotent=false, destructive=false): one-time link, browser-side encryption so the server never sees plaintext, account-specific lifetime with an instruction to quote expires_in_minutes rather than assume a fixed value, and the side effect that did_ids auto-creates the verification on submission. That is meaningful mutation-behavior context annotations alone 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?

Front-loaded with purpose, then params, then return values, then an explicit 'Priority #1' rendering instruction — the structure is deliberate. It is long and includes client-specific QR/markdown-image guidance that borders on verbose, but each block is operational and earns its place for an agent handling link delivery.

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

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

With no output schema, the description fully documents the return values (upload_url, qr_code_url, and qr_svg when qr:'svg'), and it covers all 7 parameters plus the follow-up tool call. Nothing an agent needs to invoke and then use the result correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds combination logic the per-field schema text does not: the interplay of identity_id/address_id/requirement_id, how did_ids plus purpose ('registration' vs 'emergency') selects which verification is created, and when emergency_calling_service_id substitutes for did_ids. Useful cross-parameter meaning beyond the schema's field-by-field descriptions.

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

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

States a specific verb+resource ('Generate a one-time browser link (URL + QR code) for encrypted document upload') and immediately distinguishes itself from create_proof_upload_link, create_address_verification, and create_emergency_verification. An agent can pick this tool apart from its closest siblings without opening any schema.

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

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

Explicit conditional routing: pass identity_id/address_id/requirement_id to collect missing proofs, 'If nothing is missing, skip the link and call create_address_verification / create_emergency_verification directly,' use create_proof_upload_link for voluntary uploads, and call check_upload_status after the user finishes. Both the when and the when-not are stated with named 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 it is a non-readOnly, non-destructive, non-idempotent mutation. The description adds context beyond that: registration credentials are generated server-side and returned masked, omitted fields keep panel defaults, and an invalid configuration yields a readable error. It does not mention auth scopes or rate limits, keeping it just short of a 5.

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

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

Front-loaded with the core purpose, then scope guidance, the registration variant, sibling alternatives, and return behavior. Four sentences, each doing work, though the sibling-routing and registration details make it slightly dense for a single paragraph.

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 48-parameter creation tool with no output schema, the description covers the essential edges: minimal viable call, registration-mode constraint, defaults behavior, sibling alternatives, and return/error format. The schema handles the exhaustive parameter detail, so the description is appropriately complete without being redundant.

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% across all 48 parameters, so the schema already carries full parameter semantics. The description reinforces a few key meanings (host as R-URI host, minimal required fields, registration mode) but adds little beyond what the schema documents, so the baseline of 3 applies.

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

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

States a specific verb ('Create') and resource ('SIP Voice IN Trunk (inbound voice trunk)') for the authenticated customer. It explicitly distinguishes itself from sibling creators by naming create_pstn_trunk and create_phone_systems_trunk, so an agent can route correctly without opening schemas.

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

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

Provides clear when-to-use guidance ('minimal trunk only needs name and host'), an explicit guardrail ('Set ONLY the parameters the user explicitly asked for and never invent values'), and names the alternative tools for PSTN forwarding and phone.systems trunks. It also explains the registration-mode branch (set enabled_sip_registration true and omit host/port).

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

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

With annotations covering the safety profile, the description adds substantial behavioral detail: what each type does, default methods/values, placeholder substitution rules, and that it returns the created trunk id or a readable error. No contradiction with annotations.

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

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

Purpose and mode selection are front-loaded, and the dense paragraph avoids fluff. It is long for a single paragraph, but the length is justified by two delivery modes and 14 parameters.

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

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

Given 14 parameters, two modes, nested objects, and no output schema, the description covers the critical setup paths, defaults, placeholders, and return/error behavior. Minor fields like priority and blocked are left to the schema, which is reasonable.

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 still adds cross-parameter mode conditions (http_in uses url/body/http_method; smtp uses send_to/subject/message) and the full placeholder list that applies across query_parameters, headers, and body.

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

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

States a specific verb and resource ('Create an inbound SMS destination trunk') and scopes it to the authenticated customer. It distinguishes the tool from the related routing sibling assign_did_to_sms_trunk and explains the two delivery modes.

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

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

Explicitly says to route a DID afterward with assign_did_to_sms_trunk and gives clear conditions for choosing type http_in vs smtp. It does not explicitly exclude create_sms_trunk_group or state when not to use this tool, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is covered structurally. The description adds real context beyond that: membership validation rules, the no-nesting constraint, and the return shape ('returns the created group with its member trunks, or a readable error'). It does not discuss whether a duplicate group name fails or whether the call is retry-safe, which is the remaining gap given idempotentHint=false and the schema's uniqueness note.

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

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

Front-loaded with the core action and the concept, then constraints, then lifecycle alternatives and return value — a sensible ordering. It is dense, and the membership-rule sentence is long, but essentially every clause carries distinct information.

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

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

No output schema exists, so the description correctly explains the return payload and error behavior itself. Combined with the membership constraints and pointers to the update/delete siblings, an agent has everything needed to call this correctly and to plan follow-up operations.

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 both parameters are already documented with types and constraints, so the baseline is 3. The description restates name/sms_trunk_ids and points at list_sms_trunks as the id source, but adds no format or syntax detail the schema does not already carry.

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

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

States a specific verb+resource (create an SMS trunk group) and immediately defines what the resource is: a bundle of inbound SMS trunks feeding one routing destination. This distinguishes it from create_sms_trunk, create_trunk_group, and list_sms_trunks without opening any schema.

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

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

Explicitly routes the agent: manage membership later with update_sms_trunk_group, delete with delete_sms_trunk (with a warning attached). It also gives preconditions for the member ids (must be inbound-capable HTTP IN/SMTP/SMSC/ESME, not nested, no MSGP/OTP). It does not, however, say when to prefer this over create_trunk_group or create_sms_trunk, so it stops short of full when/when-not coverage.

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 flag this as destructive/non-idempotent, and the description goes well beyond them: it discloses the 10-member cap, the no-nested-group rule, and the important side effect that a member already in another group is moved. It also states atomicity ('nothing is created' on invalid config), which is exactly the kind of behavior an agent needs before calling a mutating tool.

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

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

Single dense paragraph that is well front-loaded with the action and resource. Every clause carries information (routing rule, member rules, constraints, return/error behavior), though the block is long enough that an agent must parse carefully.

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 states the return value (created group with members in routing order) and the failure mode (readable error, nothing created). Constraints on members and routing are fully covered, so nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the routing semantics of priority (lowest tried first) and weight (higher preferred among equal priorities, which together imply failover vs. load-balancing intent), plus the source of trunk_id values. It does not cover capacity_limit, which is left to the schema.

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

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

States a specific verb+resource ('Create a Voice IN Trunk Group') and immediately defines it as a failover/load-balancing container of existing trunks, including the routing rule. This clearly distinguishes it from siblings like create_sip_trunk, create_sms_trunk_group, or create_capacity_group.

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

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

Gives clear operational context: pass `members` to add existing trunks by id from list_trunks, with the explicit constraint that a group cannot contain another group and holds at most 10 members. It names no exclusion against sibling tools (e.g., when to prefer create_sms_trunk_group), so it stops short of 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?

Adds substantial behavior beyond annotations: the atomicity guarantee ('returns... or a readable error, in which case nothing is created'), the no-normalization storage rule, and the crucial warning that creation alone is inert until attached to a trunk. Annotations only cover the safety profile, so this contextual disclosure is valuable.

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 long and dense, but it is front-loaded with the definition and every sentence carries distinct, non-redundant information (mode, default_action, numbers, numbers_action, attachment requirement, return behavior). No filler, though the single dense paragraph is heavier than strictly necessary.

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

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

No output schema exists, and the description compensates by stating what is returned (the created list or a readable error and the resulting no-op). With annotations covering safety and the schema covering every parameter, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters and the default-3 baseline applies. The description nonetheless adds conceptual meaning the schema doesn't carry — the deny-list/allow-list framing for default_action and the rule that numbers carry the opposite action by default.

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

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

States a specific verb (create) and resource (Voice IN Number List) and immediately defines what the resource is: a caller-ID/source-number filter for inbound calls. It is clearly differentiated from the sibling trunk tools, which are named as the place where the list is actually attached.

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 explains when this tool is and isn't sufficient: creating a list does NOT filter anything on its own, and routes the agent to create_sip_trunk / create_pstn_trunk / update_sip_trunk / update_pstn_trunk via src_number_list_id. The mode and default_action choices come with the conditions that select each option.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful authorization context beyond that: it reveals the roles held on the account and the set of tools the session may NOT call, which tells the agent how permissions are scoped.

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 identifies the resource first and enumerates its contents without filler. Every clause earns its place.

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

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

With no output schema, the description must convey the return shape, and it does name the three things returned (customer, roles, disallowed tools). It omits return formatting/pagination details, but for a zero-parameter read-only introspection tool that is a minor gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No misleading parameter hints are present.

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 ('Show') and resource ('the DIDWW account (customer) the session is currently acting as'), plus the exact contents returned (customer, roles, disallowed tools). The phrase 'currently acting as' implicitly separates it from list_accounts (all accounts) and switch_account (change account), so an agent can distinguish it without reading another 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 implies the 'when' through 'the session is currently acting as', but never states explicitly when to call this instead of list_accounts or switch_account, nor any prerequisite. Usage is inferable rather than spelled out.

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

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

Beyond the annotations, the description discloses that deletion cannot be undone, that proof documents are removed too, the exact blocker categories that prevent deletion, and what happens to already-registered numbers. It also describes the confirmation-token retry behavior, which is valuable operational context not captured by destructiveHint alone.

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 resource, then efficiently layers in destructive scope, blockers, side effects, and return behavior. Every sentence carries operational weight 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?

Given the rich schema, destructive annotations, and absence of an output schema, the description is complete. It covers safety, prerequisites, failure modes, post-deletion effects, and the success response, leaving no critical ambiguity for an agent.

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

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

Schema description coverage is 100%, so both parameters are already well documented in the input schema. The description adds only marginal parameter meaning, mainly reinforcing that deletion is by id and affects associated documents, 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?

The description states a specific verb and resource: delete an authenticated customer's regulation address by id, along with its proof documents. It clearly distinguishes this destructive removal from neighboring tools like update_address, list_addresses, and delete_proof.

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

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

It gives clear context for when deletion is possible and enumerates several blockers that cause the operation to fail. It does not explicitly route the agent to alternatives such as update_address or delete_proof, but the usage context is strong enough to avoid confusion.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds material context beyond them: deletion is irreversible, the hard DIDs-assigned prerequisite, and the side effect that reserved shared channels return to the Capacity Pool as free channels. This is exactly the behavioral detail annotations cannot express.

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 purpose and id source, then the destructiveness, the prerequisite, the side effect, and the return. Every sentence earns its place with no redundancy.

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

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

For a destructive tool with no output schema, the definition covers prerequisite state, irreversibility, side effects, and even the confirmation return. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100% and both parameters (id, confirmation_token) are fully documented in the schema, including the two-phase confirmation flow. The description echoes the id provenance (list_capacity_groups) already stated in the schema but adds no new parameter-level syntax or format detail. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb (Delete) and resource (Shared Capacity Group), notes it operates by id sourced from list_capacity_groups, and is clearly distinguishable from sibling operations like create_capacity_group, update_capacity_group, or unassign_did_from_capacity_group. An agent can identify 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 explicit preconditions and routing: a group with DIDs assigned cannot be deleted, so the agent must first use unassign_did_from_capacity_group or move DIDs to another group. It also points to list_capacity_groups as the id source. When/why-to-use is fully covered.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: releases the number, inbound calls/SMS stop immediately, ~35-day restore_did window before it returns to public stock, pending-order DIDs cancelled with refund, and Bulk Order DIDs cannot be terminated. It also discloses the confirmation-gating behavior.

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

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

Front-loads the action, then the alternative, then consequences, then edge cases. Every sentence carries decision-relevant content, though the block is dense and slightly long for a two-parameter 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 annotations covering the safety profile and a 100%-covered schema, the description fills the remaining gaps: recovery window, immediate service impact, refund behavior, and non-terminable cases. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so both did_id and confirmation_token are already documented in the schema, including the two-call preview-then-confirm flow. The description adds the 'confirmation-gated' framing but no syntax or format beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Terminate (cancel) one of the authenticated customer's DIDs by id') and explicitly distinguishes the action from its softer sibling update_did and its reversal sibling restore_did. An agent can identify exactly what this tool does and how it differs from the surrounding tools.

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

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

Explicit when/when-not routing: 'PREFER THE SOFTER ALTERNATIVE FIRST... call update_did with billing_cycles_count: 0 instead' versus 'Only terminate when the user explicitly wants the number gone NOW.' Names the alternative tool, the parameter to use, and the decision condition, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: it names exactly what is destroyed (all addresses, uploaded proof documents, permanent supporting documents), states the action is irreversible, lists the blockers that prevent it, and discloses an authorization constraint tied to permanent supporting documents.

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 destructive action and cascade, then blockers, then permission caveat. Dense and every sentence carries information, though the single long paragraph is somewhat run-on and could be broken up.

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

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

For a destructive, non-idempotent tool with no output schema, the description covers side effects, irreversibility, precondition blockers, permission requirements, and the success return ('confirmation message'), leaving nothing material for the agent to infer.

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 identity_id and confirmation_token are already fully documented, including the two-phase confirmation flow. The description adds no additional parameter meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (regulation identity by id) and enumerates the cascade of dependent resources destroyed with it. It is clearly distinguishable from siblings like delete_did, delete_address and delete_proof.

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

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

Gives explicit when-not conditions: deletion is blocked while the identity is linked to DIDs, has New/Pending address verifications, unfinished emergency calling services or SMS campaigns, or is the system identity. It also names a permission prerequisite (regulation rule vs porting_manage). It does not, however, point to any alternative tool for the blocked cases, only that the error names the blocker.

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 only destructiveHint=true and idempotentHint=false; the description adds far more: soft-delete semantics, irreversibility ('cannot be undone'), the blocked-deletion precondition, the two-phase confirmation_token preview flow with safe-retry-on-lost-response semantics, and the success return shape. The retry guidance concerns the confirming call, not delete idempotency, so it does not contradict idempotentHint=false.

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

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

Front-loads the core action and scope in the first clause, then layers id sourcing, the replace workflow, the destructive warning, the precondition, and the return value in descending order of importance. Every sentence carries distinct operational information; 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?

Despite having no output schema, the description states what a successful call returns (deleted proof info) and documents the confirmation-token response behavior. Combined with the precondition and workflow, an agent has everything needed to invoke this destructive tool 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 baseline is 3; the description still adds value by telling the agent where proof_id values originate (list_identities / list_addresses) and by framing confirmation_token as a two-step preview-then-confirm handshake rather than an ordinary input. It does not add format details, but the schema already supplies the UUID type and description.

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

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

States a specific verb and resource ('Delete (soft-delete) ... regulation proof documents by id') and scopes it to the authenticated customer's uploads. The parenthetical 'soft-delete' immediately distinguishes the operation's nature from a hard delete performed by sibling tools like delete_did or delete_identity.

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 sibling tools that supply ids (list_identities / list_addresses) and prescribes the replace workflow: delete first, then call create_regulation_upload_link. It also states a hard precondition (a proof tied to a pending address verification cannot be deleted), which is exactly the kind of when-not guidance that prevents failed calls.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further: it warns the action cannot be undone, discloses the cascade behavior for group trunks, and states the DID-routing blocker that will cause failure. These are behavioral traits the agent cannot derive from 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?

Four tight sentences ordered by importance: what it does, that it is irreversible, what blocks it and how to unblock, then the cascade caveat and return value. No filler.

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

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

For a destructive, non-idempotent tool with no output schema, the description covers safety, preconditions, alternatives, cascade semantics, and the success response. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents both id and the two-step confirmation_token flow. The description's restatement of the uuid source adds little beyond the schema, 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 (delete) and resource (SMS trunk), scoped to the authenticated customer and identified by the uuid from list_sms_trunks. It also distinguishes itself from the nearby delete_trunk and delete_sms_trunk_group siblings by explaining that deleting a GROUP trunk cascades to member trunks.

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 (a trunk with DIDs still routing SMS cannot be deleted) and names the remedy with the exact alternative call: assign_did_to_sms_trunk with a null sms_trunk_id, or rerouting to another trunk. This is when-to-use and when-not-to-use guidance with the alternative 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 flag destructiveHint=true, so the safety profile is covered; the description adds valuable context — irreversibility ('cannot be undone'), the DID-assignment precondition, and a return indication. It omits any mention of the two-phase confirmation_token workflow, but that is documented in the 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?

Three sentences, front-loaded with the action and identifier, then the destructive warning and precondition. Efficient overall, though the trailing 'Returns a confirmation message on success' is thin and slightly at odds with the two-step flow described in the schema.

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

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

For a destructive no-output-schema tool, the description covers identity, irreversibility, and the DID precondition. It does not surface the non-obvious two-call confirmation flow, which an agent must infer from the schema, leaving a modest gap.

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

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

Schema description coverage is 100%, so both id and confirmation_token are fully documented in the schema itself, including the two-phase confirm/retry semantics. The description adds nothing beyond 'by id', 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+resource: delete a Voice IN Trunk (inbound voice trunk) by id. It explicitly scopes the resource type, distinguishing it from sibling deleters like delete_sms_trunk and delete_trunk_group, and names the identifier used to target it.

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 precondition for use: trunks still assigned to DIDs cannot be deleted, implying the caller must unassign first. It does not, however, name an alternative tool or describe the unassign path, so it stops short of full when/when-not routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, yet the description adds substantial context beyond them: irreversibility, the DID-routing precondition, the default detach-vs-delete behavior for member trunks, the refusal condition when a member still carries DIDs, and the two-step confirmation_token flow. This is exactly the extra behavioral detail annotations cannot convey.

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

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

Five tight sentences, front-loaded with the destructive warning and identity of the resource; each remaining sentence carries a distinct constraint or default 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 needed (return value is described as a confirmation message on success), the description covers everything required to invoke safely: target identification, precondition checks, default member-trunk behavior, and the confirmation-token round trip.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks — notably that delete_member_trunks=true is refused if any member trunk still carries DIDs, and that confirmation_token is a preview-then-confirm safety gate.

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+resource ('Delete ... Voice IN Trunk Groups by id') and scopes it to the authenticated customer's own groups, which cleanly separates it from siblings like delete_trunk, delete_sms_trunk, and delete_capacity_group.

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

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

Gives explicit preconditions and when-not conditions: a group with DIDs routed to it cannot be deleted until those DIDs are re-routed, and member trunks are only detached by default. It does not name a sibling alternative explicitly, but the gating conditions are 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 declare destructiveHint=true, but the description goes well beyond them: it says all entries are destroyed with the list, that the action cannot be undone, that failures name the blocking trunks, and that a lost confirm response is safe to retry with the same token. This is exactly the extra behavioral context annotations cannot convey.

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

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

Four tight sentences, front-loaded with what is deleted and its destructive nature, then the precondition, then the recovery path. No sentence is filler; each adds an operational fact.

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, and the description compensates by stating the return value ('a confirmation message on success') plus the two-phase preview/confirm protocol. Combined with the annotations and full schema coverage, nothing an agent needs is missing.

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

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

Schema description coverage is 100% and both parameters are fully documented in the schema, including the confirmation_token protocol and the provenance of 'id'. The description adds no syntax or format detail beyond that, 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+resource ('Delete ... Voice IN Number Lists') and disambiguates the resource itself as 'caller-ID filters for inbound calls', which separates it cleanly from the sibling delete_trunk / delete_sms_trunk / delete_did tools.

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

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

Explicitly states the blocking condition (a list still attached to Voice IN Trunks cannot be deleted), names the fix and the exact alternative tools (update_sip_trunk / update_pstn_trunk with src_number_list_id set to null), and describes the required two-call confirmation flow. An agent has everything needed to decide and proceed.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety bar is covered. The description goes well beyond them by defining the semantics of each returned value (credit as allowed negative balance, available_balance as balance + credit, debt, is_debtor, last_activity) and noting the USD denomination. That is real behavioral context an agent would otherwise have to discover.

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

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

Two sentences, front-loaded with the purpose before the field enumeration. The second sentence is dense but every clause defines a distinct returned field, which is warranted given there is no output schema. Slightly list-like but no waste.

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 full burden of documenting the response, and it does so field by field, including units and edge conditions (debt 0 when none). Combined with annotations covering the safety profile, nothing an agent needs to call and interpret this tool is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly adds no parameter guidance because none is needed, and instead spends its words on output semantics.

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

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

States a specific verb and resource with scope: 'Get the authenticated customer's current prepaid account balance and billing standing.' An agent immediately knows what it retrieves. It does not, however, differentiate itself from potentially overlapping siblings such as current_account, get_dashboard, or get_invoice.

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

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

The phrase 'authenticated customer's' implies the context in which it applies, but there is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives like current_account or get_dashboard. Usage is inferable for a zero-parameter read, but nothing is spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description goes beyond them by disclosing the authorization filter ('cells the customer is allowed to see'), the cell shape (name + value, currency attached to amounts), and the USD normalization — genuinely useful behavioral context.

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

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

Front-loaded with the purpose in the first sentence, then a structured enumeration of returned cells and amount semantics. Slightly dense in the cell listing, but every clause carries information an agent would otherwise have to guess.

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, so the description must carry the return contract, and it does so reasonably well by naming the cell set, the name/value pair shape, and currency rules. Missing only the container structure and whether absent cells are omitted versus null.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies; the description correctly spends its space on the return payload instead of inventing parameter detail.

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

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

States a specific verb and resource ('Get the authenticated customer's account summary / dashboard') and enumerates the cell types returned, so the agent knows exactly what this yields. It does not distinguish itself from similar siblings like current_account, get_balance, or list_invoices, which is the only gap.

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 never says when to reach for this tool versus alternatives such as current_account, get_balance, get_invoice, or list_payments, all of which live in the same domain. Usage is only implied by the word 'dashboard'.

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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds substantial content-level transparency: the returned field groups, that E911/CNAM are included, that all amounts are USD, and critically that related entities come back as id+name only. That last point is a genuine behavioral trait an agent could not infer.

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, but it is front-loaded with the operation and then groups the return fields logically (number/location, status, routing, capacity, billing, regulation, E911/CNAM). Given the absence of an output schema, the length is justified, though the run-on structure could be broken into clauses.

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 entire contract for return values, and it does so exhaustively — enumerating every field group plus the id+name abbreviation rule for related entities. Nothing an agent needs to invoke or interpret this read 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 coverage is 100%; the schema already states it is the DID UUID from list_dids. The description's parenthetical repeats that verbatim, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (return full details) and resource (one DID) plus the lookup key (id from list_dids). It is immediately distinguishable from list_dids (enumerate), get_did_history (history), and update_did (mutation).

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

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

Names the id source (the uuid returned by list_dids) and explicitly routes the agent elsewhere for nested entities ('use the dedicated list tools for their full details'), which prevents the common mistake of expecting full related objects. It does not, however, contrast this tool with get_did_history, 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: a 90-day hard retention limit with the explicit instruction to 'say so instead of implying completeness', a 200-entry cap, newest-first ordering, and per-entry fields (action, timestamp, channel, from/to values). This is exactly the behavioral context an agent needs.

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

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

Front-loaded with the core purpose, then detail, with the critical 'HARD LIMIT' constraint emphasized mid-text. It's on the denser side and repeats the action list already in the enum, but nearly every sentence carries operational value.

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

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

With no output schema, the description fully compensates by describing the return shape (entry fields, ordering, channel values, from/to for billing_cycles_count changes), the entry cap, and the retention window. Nothing needed to call or interpret the result is missing.

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

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

Schema coverage is 100%, and the schema already documents both `number` (full DID digits) and the `action` enum with all six values. The description largely restates the action list in prose and repeats the number's origin, adding little parameter meaning beyond what the schema provides, 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 ('Return the billing/lifecycle history of one DID') and enumerates exactly what the history contains, so an agent can distinguish it from get_did (current state) and list_dids (enumeration) without opening any schema.

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

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

It tells the agent where to get the required `number` (from list_dids / get_did) and clarifies that it returns history rather than current state, which routes usage implicitly. It stops short of explicitly naming an alternative for 'when not to use' or stating prerequisites, so it's clear context without exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds real behavioral depth beyond them: it states that NO file content is returned, that download_url opens a signed-in browser session, and that include_signed_url yields SENSITIVE credential-bearing data to be surfaced only on explicit user request. This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the returned fields, then polling guidance, then the size caveat and the signed-URL warning. Dense but every clause carries operational information; the one long sensitivity sentence is slightly heavy but justified.

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

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

With no output schema, the description fully carries the return-value burden: it names every field, explains download_url semantics, and clarifies that file content is absent. Nothing needed to call or interpret this tool is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it frames signed_download_url as login-less sensitive data and gives an explicit policy for when to request and repeat it, plus the null-when-too-large behavior tied to export contents.

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 ('Show a single export created with create_export') and immediately enumerates the fields returned (status, name, filters, timestamps, download_url). An agent can distinguish it from list_exports and create_export 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 operational context: poll again while pending/processing with a stated ~5 minute expectation, and route to create_export with a narrower date range when the slice is too large. It does not explicitly name list_exports as the alternative for enumerating exports, but the single-export scoping makes the boundary inferable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond them: ownership scoping to the authenticated customer, the error-on-missing/unauthorized behavior, and the USD currency normalization for all amounts.

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

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

Front-loaded with the action and scope, then a compact enumeration of returned fields. The field list is somewhat long, but it earns its place because there is no output schema, so it is not 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?

With no output schema, the description usefully spells out the returned fields (id, name, billing period, subtotal/VAT/total, currency, status) and the currency unit, plus the error case. An agent has enough to call and interpret the result, though it does not describe the error shape or id format beyond 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?

With a single parameter and 100% schema description coverage ('The invoice id (uuid)'), the schema already carries the parameter semantics. The description reinforces the ownership scoping of the id but adds no format or lookup detail beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get the details of a single invoice') plus the scoping dimension (belonging to the authenticated customer, by its id). This clearly distinguishes it from the sibling list_invoices.

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 use: retrieve one invoice by id for the authenticated customer, with an explicit failure condition ('returns an error if no invoice with that id belongs to the customer'). It does not, however, explicitly name list_invoices as the alternative for browsing multiple invoices, so the routing guidance is implied rather than stated.

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

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

Annotations already establish the safe read-only, idempotent profile, and the description adds genuinely useful context beyond them: what fields come back, that passwords are never returned, and that a boolean '<field>_set' signals password presence. This security detail is not derivable from 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?

Front-loaded with the core purpose and the id source, then the return details. It is dense but each clause earns its place given there is no output schema; the long parenthetical field enumeration is borderline but justified.

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 summarizing the returned fields, including type-specific configuration and the password-redaction behavior. An agent has everything needed to call it and interpret the response.

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

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

Schema description coverage is 100% on a single required 'id' parameter, so the schema already carries the semantics; the description only restates that the id is the uuid from list_sms_trunks. Baseline 3 applies when the schema does the work.

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 full details) and resource (SMS trunk) scoped to a single id, and explicitly names list_sms_trunks as the source of that id, which cleanly separates it from the list sibling and from create/update/delete_sms_trunk.

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

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

The parenthetical '(the uuid returned by list_sms_trunks)' tells the agent how to obtain the argument, giving clear usage context. It stops short of explicit when-not guidance or naming the alternative getters (get_trunk, get_did_had) it should not be confused with.

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

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

The annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond annotations by disclosing that password values are never returned and that boolean <field>_set fields indicate whether secrets are configured.

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

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

The description is front-loaded with the core action, then enumerates returned fields that matter because no output schema exists. It uses two sentences with no filler and places the password-disclosure note at the end where it is easy to find.

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, so the description carries the return-value burden and does so thoroughly: it lists the main fields plus type-specific configuration and clarifies password handling. Combined with annotations covering safety and idempotency, the definition is complete for correct invocation.

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

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

Schema description coverage is 100%, and the single id parameter is fully documented in the schema. The description repeats that the id is the uuid returned by list_trunks, but adds no syntax, format, or validation detail beyond what the schema already provides.

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

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

The description names a specific verb and resource: returning full details of a single Voice IN Trunk by id. It also distinguishes itself from the list operation by noting the id is the uuid returned by list_trunks.

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

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

It clearly implies when to use this tool: when an agent already has a trunk id and needs full details. It references list_trunks as the source of that id, but stops short of explicitly stating when not to use it or how it differs from other get_* 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 establish readOnly/idempotent/non-destructive, so the description is free to add return-shape context: the exact response fields (name, mode, default_action, items_count, attached_trunks_count with up to 10 named trunks, pagination meta) and the constraint that entries are never returned wholesale. That is meaningful added behavior beyond the safety hints, though it does not discuss permissions or failure modes.

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

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

Front-loaded with the core action, then the return contents, then pagination guidance. Three dense sentences with no filler, though the enumeration of response fields is slightly long for a description that could lean on a 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?

With no output schema, the description compensates by enumerating the returned fields, the exact-value guarantee, the allow/reject action, and the pagination model. An agent has everything needed to call this tool and interpret the response.

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

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

Schema coverage is 100%, so all three parameters (id, page, page_size) are already documented with defaults and bounds. The description reinforces their purpose ('page/page_size to walk large lists') and notes where the id comes from, but adds no syntax or format detail beyond the schema, so the baseline 3 is correct.

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 (Show) and resource (one Voice IN Number List including its stored entries) with scope ('one of the authenticated customer's'), plus a parenthetical that explains what a Voice IN Number List is. This cleanly distinguishes it from the sibling list_voice_in_number_lists, which enumerates lists rather than returning one list's contents.

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

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

It names a concrete downstream use case (entries are needed character-for-character by update_voice_in_number_list remove_numbers) and gives pagination guidance ('Use page/page_size to walk large lists — entries are never returned wholesale'). It does not explicitly contrast with the sibling list tool or state 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful extra behavior: the payload is permission-scoped (it reports tools the account may NOT call, with an explicit 'everything else is allowed' rule) and flags the currently active account. It omits any auth/permission prerequisites for the caller.

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

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

Two tight sentences with zero filler. The resource and scope come first, and the alternative-tool routing is placed last as an actionable follow-up.

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 a trivial input schema, the description carries the full burden and discharges it by enumerating the returned data (accounts, roles, denied tools, active account). Nothing an agent needs to call or interpret this tool is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The schema is an empty, fully-described object consistent with the description.

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

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

States a specific verb and resource ('List every DIDWW account (customer) the authenticated user can act as') and enumerates the returned facts: roles held, tools not callable, and which account is active. This clearly distinguishes it from siblings like current_account and switch_account 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?

Explicitly routes the mutation case to a named alternative: 'Use switch_account to change the active account.' It gives clear context for reading accounts, but does not directly contrast with current_account, which is the most confusable sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: that passing country_iso causes every record to be checked against the requirement and each one then carries `eligible`, `blocking_errors` and `remediation` when it cannot be used. That conditional side-effect is real added value beyond the annotations, though pagination/ordering behavior is left implicit.

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 resource and scope, then the conditional eligibility behavior, then routing to sibling tools. It is dense but every clause earns its place; the only minor cost is a long enumerated list of return fields packed into a single sentence.

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, so enumerating the returned fields (address id, identity, country ISO, city, postal code, street, verified flag, proof summary) is exactly what the description should supply, and it does. Combined with the eligibility behavior and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so a 3 would be the baseline, but the description goes further by explaining where country_iso's value comes from ('straight from a DID's registration_required block') and clarifying the emergency/regulation semantics of requirement_type beyond the enum labels. It gives practical sourcing guidance the schema does not.

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

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

States a specific verb+resource ('List the authenticated customer's regulation addresses') and immediately delimits scope to the caller's own addresses with proof documents. It is clearly distinguishable from siblings like list_address_verifications and list_requirements by naming the resource precisely.

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 how to use the optional parameters ('Pass country_iso (+ did_group_type) — straight from a DID's registration_required block') and adds the alternate condition ('or with requirement_type "emergency" to pick the address for an E911 calling service'). It also routes downstream usage ('Use an address id with create_address_verification or create_regulation_upload_link') and the fallback ('If no suitable address exists, create one with create_address'), giving full when/when-not/alternative coverage.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds meaningful context beyond them: it discloses that rejected verifications carry the staff reject_comment and reject reasons while the address object itself only shows verified: false. It doesn't discuss pagination or result ordering, so it stops short of a 5.

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

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

Three tightly packed sentences, front-loaded with the resource and statuses, then the diagnostic value, then the filters. No filler, though the parenthetical gloss of 'address verifications' is slightly redundant with 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?

No output schema exists, so the description carries the return-shape burden and does so by naming the status values and the rejection fields (reject_comment, reject reasons) an agent will see. Combined with the full schema coverage, nothing needed to call or interpret this tool correctly is missing.

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

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

Schema coverage is 100%, so every parameter (page, number, status, page_size, address_id) is already documented in the schema with defaults and bounds. The description restates the filterable fields and the 'and/or' combinability, which adds only marginal information beyond the structured data — 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 ('List the authenticated customer's address verifications') and clarifies the domain with the parenthetical '(end-user / number registration reviews)' plus the enumerated statuses. An agent can distinguish this from list_addresses, create_address_verification, and validate_address without opening any other schema.

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

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

Gives explicit symptom-driven triggers: 'Check here when a DID stays in awaiting_registration or an address stays unverified.' It also frames the tool as the diagnostic surface for rejections, which tells the agent when this is the right call versus simply reading the address record or the DID record.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description adds useful behavior beyond them by disclosing that results are paginated and enumerating the returned fields (id, name, channel counts, assigned DIDs, pool id/name, pagination meta). It stops short of stating default page size or rate limits, which the schema covers for defaults.

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?

Effectively two sentences, front-loaded with the resource and scope, then the return contents. Dense but every clause (filter, pagination, returned fields) carries information; minor density is the only cost.

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 return payload and noting pagination, and it acknowledges the optional filter for the one non-pagination parameter. Nothing an agent needs to call this list tool correctly is missing.

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

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

Schema description coverage is 100%, so page, page_size, and capacity_pool_id are already documented with defaults and bounds in the schema. The description only echoes the capacity_pool_id filter concept without adding syntax or format detail beyond it, which matches the baseline-3 case when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List the authenticated customer's Shared Capacity Groups') and disambiguates the resource from the similarly named list_capacity_pools by clarifying these are capacity groups, each tied to a Capacity Pool. An agent can distinguish this from the pool-listing sibling 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?

Usage is implied by 'optionally filtered by Capacity Pool,' which tells the agent the filter exists but not when to prefer this tool over list_capacity_pools or other list_* tools. No explicit when-to-use, prerequisites, or exclusions are given, leaving usage 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 (readOnly, idempotent, non-destructive). The description adds real value beyond them: pagination behavior, scoping to the authenticated customer, and semantics of key fields like metered_rate variability and USD-only amounts. No rate limits or auth details, so not a 5.

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

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

Front-loads the core purpose and then enumerates return fields in a single dense paragraph. The parenthetical asides (metered-rate orders of magnitude, DID country coverage) earn their place, but the run-on structure is heavy and would scan better split into shorter sentences.

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

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

With no output schema, the description carries the full burden of describing return values and does so comprehensively: id, name, channel counts, pricing, currency, dates, covered_country_isos, and pagination meta. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema description coverage is 100%, so page and page_size are fully documented in the schema and the description adds no syntax beyond 'Results are paginated.' Baseline 3 is appropriate when the schema carries the 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 (List) and resource (Capacity Pools), then defines the domain concept and what a pool contains, distinguishing it from the sibling list_capacity_groups. An agent knows exactly what this returns and how it differs from adjacent tools.

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

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

Embeds actionable usage context: check covered_country_isos before creating a group for a country, and weigh metered_rate alongside monthly_price when choosing a pool. This is clear guidance, though it never explicitly names an alternative sibling or an exclusion condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond annotations: only masked fields are returned, no full card number or secret is exposed, results are ordered most recent first, and the response is paginated.

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

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

The description is a single tight paragraph, front-loads the resource and safety constraint, then gives returned fields and pagination behavior. Every sentence earns its place and there is no filler.

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

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

There is no output schema, so the description appropriately lists the returned fields, explains masking/security, states ordering, and notes pagination. Annotations cover the safety profile and the input schema fully documents parameters.

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

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

Schema description coverage is 100%, so the schema already documents page and page_size. The description only notes that results are paginated, adding no parameter-level meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: list the authenticated customer's saved credit cards. No sibling tool covers credit cards, so it is clearly distinguishable from the surrounding telecom/DID/trunk tools.

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

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

Usage is implied by the tool name and description, but there is no explicit when-to-use, when-not-to-use, or alternative routing guidance. For this tool family, the intended context is reasonably inferable but not 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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds real value on top: it declares pagination, enumerates the returned fields, and clarifies the multi-condition semantics of the features filter ('ALL listed must be supported').

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?

Single front-loaded paragraph with the core action first and filters grouped by theme (routing, capacity, status). It is long but every clause maps to a real parameter; only the dense parenthetical listing hurts readability slightly.

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

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

With no output schema, the description compensates by enumerating returned fields (id, number, country_iso, channels, status flags, billing_cycles_count, description, expires_at) and pagination meta. Combined with 19 fully documented params, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all 19 parameters, setting a baseline of 3. The description adds meaning beyond it by spelling out AND-semantics for features and the routing/capacity interpretation of flags, though it mostly parallels the schema text.

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

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

Opens with a specific verb+resource ('List the authenticated customer's DIDs') and immediately scopes it with the filter dimensions. It is trivially distinguishable from get_did, delete_did, and update_did without opening any schema.

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

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

The description explains what each filter accomplishes (e.g. has_trunk/has_sms_trunk false surfaces numbers 'routed NOWHERE', is_configured means 'routed AND with channels'), which is effectively usage guidance. It stops short of naming alternatives like get_did for a singleton lookup or the assign_* tools for non-list operations.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real value: the full set of status values, the per-number billing formula (monthly_price × DID count, setup_price one-time, USD), and the last-verification status enum. It doesn't mention rate limits or pagination defaults (those live in 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?

Purpose is front-loaded in the first sentence, followed by a dense field enumeration and a useful billing sentence. The long return-field list is heavy but earns its place given there is no output schema. Minor verbosity, but no waste.

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 present, the description compensates by enumerating the returned fields and statuses, and explains billing so the agent can interpret costs. Combined with annotations covering the safety profile, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% for both page and page_size, so the schema fully documents pagination. The description only notes 'plus pagination meta' without adding syntax 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+resource ('List the authenticated customer's Emergency Calling Services') with clear scope (authenticated customer). Easily distinguished from siblings like list_emergency_requirements or create_emergency_verification.

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

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

Explicitly routes the agent to create_emergency_verification for services in 'changes required' status. It also clarifies billing semantics, giving useful context. However, it does not state when not to use this tool versus list_emergency_requirements, so it stops short of the 5 bar.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, idempotent), but the description adds substantial behavior beyond them: per-DID billing semantics (monthly_price times attached numbers plus one-time setup_price, in USD), empty-list meaning, and the fact that only plan-priced requirements are returned. It does not mention pagination page limits, but the billing and empty-result semantics are unusually rich disclosure.

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

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

The key point (check before creating) is front-loaded and every clause carries information, but the billing and empty-list discussion is dense and delivered in one long paragraph with heavy dashes and semicolons. It is informative rather than wasteful, though a little sprawling for a list 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 the burden of return semantics and does so: it names the requirement fields, the pricing fields, and what an empty list means. Nothing an agent needs to call and interpret this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: filtering by country_iso and/or did_group_type is optional and omitting them returns every plan-priced requirement, paginated. That clarifies the default behavior of the two filter parameters beyond their field-level docs.

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 ('Check what an emergency verification needs BEFORE creating') and enumerates the returned content: identity type, mandatory identity/address fields, and area levels. An agent can distinguish it from create_emergency_verification and list_requirements from the text alone.

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

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

It explicitly positions the tool before creation, names the follow-up tools for each gap (update_identity to fill identity/address fields, create_regulation_upload_link with purpose 'emergency' to upload proofs), and describes filter vs. no-filter behavior. This is genuinely actionable 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 cover the safety profile (read-only, idempotent), but the description adds substantial behavior the annotations cannot: newest-first ordering, pagination, the fact that download_url only works in a signed-in browser session, and the constraint that anonymous links must be fetched individually elsewhere. This is real operational context beyond 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?

Front-loaded with purpose and filters, then return fields, then the signed-URL caveat — a logical order with no filler sentences. It is fairly dense, but every clause carries information an agent needs.

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

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

With no output schema, the description enumerates the returned fields (id, export_type, status, name, filters, created_at, completed_at, download_url, download_expires_at) and their conditional availability, and covers pagination and the download-link caveat. Nothing needed to call or interpret it is missing.

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

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

Schema description coverage is 100%, so the schema already documents page, page_size, status and export_type. The description restates the two filterable fields and inlines the status values, which adds marginal reinforcement but no syntax or format 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 ('List the authenticated customer's recent exports'), plus ordering ('newest first') and scope ('the authenticated customer's'). It explicitly distinguishes itself from the sibling get_export for the signed-URL case.

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 (get_export with include_signed_url) and the precise condition that selects it ('only when the user asked for one'), and states that login-free links are never returned here. Both the when and the when-not are explicit.

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

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

Annotations already mark it read-only, idempotent, non-destructive, and closed-world, but the description adds crucial behavioral detail beyond them: passing country_iso triggers a per-record eligibility check that attaches `eligible`, `blocking_errors`, and `remediation`. It also enumerates the returned fields, which is valuable since there is no 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-loaded with purpose and return shape, then eligibility behavior, then sibling links. It is dense and slightly list-heavy in the return-field enumeration, but every clause carries actionable information with no filler.

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

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

With no output schema, the description compensates fully by enumerating the returned fields and the conditional eligibility/remediation fields, plus the correct follow-up tools. An agent has everything needed to call and use the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: country_iso is sourced 'straight from a DID's registration_required block' (via buy_did) and requirement_type switches the rule set between regulation and E911 emergency requirements.

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

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

States a specific verb and resource ('List the authenticated customer's regulation identities with their uploaded proof documents') and immediately scopes it to the caller's account. It is clearly distinguishable from create_identity, update_identity, and delete_identity 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?

Explicitly states when to pass country_iso/did_group_type and requirement_type 'emergency' for E911, and routes the agent to concrete next tools ('Use an identity id with create_address / update_identity / create_regulation_upload_link. If no suitable identity exists, create one with create_identity').

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real behavioral context: ordering (most recent first), that status is always Pending, that revoke/decline removes rows, and that pagination meta is returned. It does not mention rate limits or result caps, but no contradiction exists.

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

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

Purpose is front-loaded and the long return-field enumeration plus lifecycle chain earn their space given there is no output schema. Slightly dense, but 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?

With no output schema, the description compensates by enumerating returned fields (id, email, name, roles, status, created_at, pagination meta) and ordering, and the lifecycle chain makes the tool's place in the invite flow unambiguous. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% — both page and page_size carry their own defaults and bounds in the schema — so this is the baseline 3. The description only references pagination meta generally and adds no format or syntax detail beyond the schema.

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