Skysay

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: a 25,000-character cap, per-section total/returned/has_more reporting, omission of items 'too large to preview', and the privacy guarantee that 'SMS message content is never included'.

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

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

Lead clause front-loads the purpose and every subsequent clause carries real value (counts, limits, privacy). It is a single very dense sentence, which slightly hurts readability, but 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?

With no output schema, the description must describe returns itself, and it does so thoroughly: section structure, caps (10 line items, 5 newest), the list_tool escape hatch, and the character limit. Only parameter scoping is left thin.

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

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

Schema coverage is only 50% and the description says nothing about either parameter. project_id is undocumented in both places, and the description does not compensate by explaining what project_id scopes or how it interacts with organization_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?

Uses a specific verb and resource ('Summarize a workspace') and enumerates exactly what the summary contains (wallet balance, usage totals, counts for agents/numbers/calls/SMS). This clearly distinguishes it from the sibling list_* tools, which return complete record sets rather than a bounded overview.

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 implies when to use this tool (a bounded summary) versus the list_tool 'that returns complete records', and notes that tool 'requires its own scope'. However, it never names the actual sibling tools or states an explicit when-to-use/when-not condition, leaving the routing 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 destructive=true, readOnly=false and idempotentHint=false, so the safety profile is covered. The description adds a genuinely new behavioral trait not present in structured fields: duplicates already in the list are silently skipped, which materially affects the outcome of a call. It does not describe partial-failure behavior or permission requirements.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the two constraints. The cap restates maxItems=10000 already in the schema, a minor redundancy, but nothing is padded or buried.

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

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

For a destructive bulk-write tool with no output schema and low parameter coverage, the description covers the batching limit and dedup semantics but omits the shape of each contact object, whether the operation is atomic or partial, and any authorization requirements. Adequate as a minimum, but an agent could still mis-invoke it by sending wrong item structures.

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

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

Schema description coverage is only 33%: contact_list_id and especially the contacts array carry no description, and the array's item type is an untyped object. The description does not compensate — it never explains what fields a contact row must contain, nor clarifies the required list identifier, leaving the most important input structure undocumented.

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

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

The description names a specific verb (append) and resource (rows in an existing contact list), which unambiguously separates it from siblings like create_contact_list and list_contacts. The word 'existing' signals it operates on an already-created list rather than creating one.

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

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

Usage is only implied: the agent can infer this is the tool for adding contacts to an existing list, and the 10,000 cap implies batching constraints. There is no explicit when-to-use statement, no prerequisites (e.g., required scopes or list-must-exist), and no pointer to alternatives such as create_contact_list.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds real behavioral context beyond them: the effect is a persistent, global suppression ('from then on') that every outbound path honors. It stops short of saying what happens on duplicate input or what permissions are needed, so it is additive but not complete.

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

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

Two short sentences, effect front-loaded, zero filler. 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?

There is no output schema, so the description should ideally state what a successful call returns (e.g., count added, duplicates skipped), and the reason parameter is undocumented in both schema and description. The core effect is communicated well, but the picture is incomplete for a destructive, non-idempotent mutation.

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 only 33% schema coverage, one of three parameters has a schema description (organization_id). The description only weakly maps to phone_numbers ('Add numbers') and gives no meaning for the reason parameter, whose 160-char constraint appears nowhere. Partial compensation only.

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

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

States a specific verb and resource: 'Add numbers to the workspace do-not-call register.' The resource is unambiguous and distinct from sibling tools like update_number_rules or authorize_outbound. It does not, however, explicitly contrast itself with any sibling, which is what a 5 would require.

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 context is implied by the register's purpose (suppressing outbound contact) but the description never says when to reach for this tool versus update_number_rules, evaluate_outbound_policy, or check_number_requirements, and gives no exclusions or prerequisites. Adequate but with a clear routing gap.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial context beyond that: gate ordering, the per-org allowlist plus always-on high-risk-country hard block, that the `stage` field identifies which gate answered, and that no reserve, charge, or review row is written. This is exactly the value-add behavioral detail 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 purpose and outcome enum, then details gates and scope limits in a tight sequence. The sentences are dense but every clause carries distinct information (ordering, exclusions, return field). Slightly heavy for a single paragraph, but nothing is wasted.

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

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

With no output schema and 15 params, the description still explains the return states (allowed|blocked|needs_review), the `stage` field, the gate ordering, and the exact scope boundaries of the check. An agent has enough to invoke and interpret it correctly despite the schema's low coverage.

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

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

Schema coverage is only 33%, so the description has to compensate. It maps the key params to gates (country/channel/profile/caps at the capability gate; purpose and user_authorization at the per-call policy gate; caller-number readiness), adding ordering semantics beyond the schema. Several params (metadata, categories, campaign_id, amount_minor, phone_number, relationship) remain unexplained, keeping it 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+resource ('Preflight a call/SMS') and the exact outcome space (allowed|blocked|needs_review), and positions it relative to create_outbound_call ('before placing it'). An agent can distinguish it from create_outbound_call and the policy/number-rule 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?

Clearly frames the usage context ('before placing it') and names create_outbound_call as the action it previews. The 'Not a full admission' sentence explicitly carves out number rules, concurrency, and wallet reserve, steering the agent elsewhere, but it does not name the specific sibling (e.g. check_number_requirements) for those unchecked gates.

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, but the description adds genuine value by specifying exactly what is destroyed or skipped: queued calls are cancelled and remaining contacts are skipped. It stops short of stating reversibility or whether re-cancelling an already-cancelled campaign errors.

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

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

A single sentence that front-loads the action and then the consequence. No filler, nothing to trim.

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

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

The core side effects are conveyed, but for a destructive, non-idempotent mutation with no output schema there is no mention of return shape, error cases, or auth/permission needs, and the required campaign_id is unexplained.

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

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

Schema coverage is only 50%: organization_id is documented in the schema, but campaign_id has no description anywhere. The description adds no parameter information, so it fails to compensate for the undocumented required identifier.

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 ('Cancel a campaign') and even names the concrete effects on queued calls and remaining contacts. It does not, however, differentiate itself from close siblings like pause_campaign or resume_campaign, leaving the cancel-vs-pause distinction to inference.

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

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

There is no guidance on when to cancel versus pause, whether cancellation is appropriate mid-launch, or any precondition (e.g. campaign must be running). The agent must guess which sibling to reach for.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, covering the safety profile. The description adds value by clarifying consequences: finished attempts keep results and no further charges or queuing occur. It does not explain idempotency behavior despite the non-idempotent annotation.

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

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

Two short sentences, front-loaded with the action and scoped effects. Every clause adds 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?

The description covers behavioral consequences well and annotations carry the destructive profile, but the sparse schema (33% coverage) leaves required parameters undocumented and the description does not compensate. For a 3-param destructive mutation tool, this is a noticeable gap.

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

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

Schema coverage is only 33% – only organization_id has a description. The description mentions no parameter names or meanings, leaving agent_id and run_id with no semantic guidance beyond the schema's required list and string types.

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

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

States a specific verb 'Cancel' with the resource 'simulation run' and scope ('queued or running'). It distinguishes from siblings such as start_simulation_run and get_simulation_run by verb, so an agent can select it correctly 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 the core use case ('queued or running') but no explicit when-not conditions or alternatives. It doesn't mention when to prefer get_simulation_run or that already-finished runs cannot be cancelled, leaving routing implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. Beyond that the description adds only the vague "in plain terms," which hints at human-readable output but does not say what is returned, whether results are per-country, or how missing/unknown countries are handled.

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

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

A single short sentence with no filler; the purpose and scope are front-loaded and nothing is wasted.

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

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

This is a simple read-only lookup with no output schema and only two optional params, so the description needn't explain return values. Still, with 0% schema coverage it leaves the accepted input vocabulary (ISO codes? names?) and the meaning of "plain terms" unspecified, which is the minimum an agent would need to call it confidently.

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

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

Schema description coverage is 0%, so the description must carry the burden; it does partially by naming both dimensions ("country" and "number-type"), which maps to the countries and number_types arrays. It gives no format, expected value vocabulary, or behavior for empty/omitted arrays, so compensation is incomplete.

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

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

States a concrete verb ("Return") and a specific resource ("country and number-type onboarding requirements"), so an agent knows this is a read/lookup tool. It does not, however, distinguish itself from adjacent siblings such as get_number_rules, get_number_catalog, or get_coverage, which an agent could easily confuse it with.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With several similarly named number-related siblings (get_number_rules, get_number_catalog, get_coverage, request_number), the absence of routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that: no note on why a create is flagged destructive, whether retries duplicate agents, or what side effects the webhook/audio stream registration has.

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 tight sentence with the key concept ('shortcut for creating an external_audio agent') front-loaded and no filler. It is efficient, though its brevity contributes to the specification gaps noted elsewhere.

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

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

A destructive create operation with 5 parameters, 20% schema coverage, and no output schema needs more than one sentence. The description omits parameter significance, side effects, and any return/identity information, leaving an agent under-informed before a non-idempotent write.

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

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

Schema description coverage is only 20% (just organization_id), so the description must compensate, and it covers only webhook_url and audio_stream_url by name. It says nothing about name, project_id, or the expected URL format, leaving three required-ish fields undocumented.

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

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

States a specific outcome: it creates an external_audio agent preconfigured with webhook and audio stream URLs, and labels itself a shortcut, which implicitly differentiates it from the sibling create_agent. An agent can grasp the resource and scope without opening the schema.

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

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

The word 'shortcut' implies this is the preferred path when the target is an external_audio agent, so usage is implied. However, it never names create_agent as the alternative, states no prerequisites, and gives no when-not guidance.

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

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

Annotations already declare destructive=true, idempotent=false and readOnly=false, so the write profile is covered. The description adds real value beyond that: it discloses that locale overrides stay draft data until an explicit voice-stack publish command, and that language-axis-less engines reject languages/language_profiles/follow_caller with a 400 naming the offending field. Auth requirements and the create-return value remain unstated.

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

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

Three sentences, front-loaded with the core action and modes before the finer behavioral caveats. Dense and slightly jargon-heavy ('has_language_axis false'), but every sentence carries information an agent needs; 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 16-parameter create tool with no output schema and very low schema coverage, the description covers the trickiest semantics (modes, language axis, draft vs publish) but omits what the call returns (e.g. the new agent id) and leaves most optional parameters undocumented. Adequate but with clear gaps.

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

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

Schema description coverage is only 13% across 16 parameters (with nested objects), so the description is expected to compensate. It supplies meaning for mode, languages, language_profiles, and voice_frontend-adjacent engine constraints, but leaves model, voice, transcriber, webhook_url, and the message/prompt fields entirely unexplained. Partial compensation only.

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

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

The description states a specific verb and resource ('Create a first-class Skysay agent') and enumerates the three valid modes (external_audio, external_text, hosted), so the agent knows exactly what operation this is. It does not name update_agent or connect_external_agent explicitly, but the mode enumeration and 'first-class' framing distinguish creation from the sibling update/connect tools implicitly.

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 through the mode descriptions and the hosted-vs-external distinction, but there is no explicit 'use this when X, use update_agent when Y' guidance versus the many sibling agent tools. The engine/language-axis constraint is the closest thing to a precondition, but prerequisites and alternatives are largely left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the mutation profile is covered. The description adds genuinely new behavioral context: the object is created in a non-active draft state and does nothing until launch_campaign is called. It does not explain why destructiveHint is true for a create, nor that repeated calls are non-idempotent, which are the remaining gaps.

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, both dense with signal and zero filler; the core 'Create a draft ...' action is front-loaded and the lifecycle caveat is placed last where it belongs. The parenthetical enumerations are compact rather than wasteful.

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

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

For an 18-parameter, deeply nested mutation tool with no output schema and low schema coverage, the description covers the required-parameter ground and key enums but leaves several optional parameters and the retry_policy object structure undocumented. Adequate as a starting point, but not complete for confident 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 only 22%, so the description must carry weight, and it does partially: it names consent_basis values (existing_customer | explicit_consent) and retry preset names (sales, collections, single_attempt). But many of the 18 parameters (language, ends_at, time_zone_mode, max_concurrency vs reserved_concurrency distinction, the retry_policy object shape) are left entirely 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?

The description names a specific verb and resource ('Create a draft outbound campaign') and enumerates the substantive configuration dimensions (agent, caller-id numbers, contact list, purpose, consent basis, calling windows, retry policy, concurrency, schedule). It also draws a clear boundary against the sibling launch_campaign by stating the campaign stays a draft until launched.

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 draft-versus-launch distinction is explicit and directly routes the agent: use this to stage, use launch_campaign to activate. However, it gives no guidance on when to prefer update_campaign over creating a new campaign, and no prerequisites (e.g. that the agent, contact list and numbers must already exist) are stated.

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

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

Annotations already declare this is a non-read-only, non-idempotent, destructive write, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: a per-row import report is returned and invalid rows are reported rather than failing the whole list, which tells the agent the operation has partial-success semantics.

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

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

Two tight sentences, front-loaded with the action and resource, then the return/failure behavior. No filler or repetition of the title.

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

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

Return behavior is covered despite no output schema, and annotations cover the mutation profile. However, the description omits permission/workspace requirements, behavior on name collision (whether an existing list is overwritten, which matters given destructiveHint=true), and the 10,000-row cap that only exists in the schema.

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

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

Schema description coverage is only 20%, and the description compensates only for the contact-row fields (phone_e164, name, first_name, language, time_zone, external_reference, variables). The required top-level parameters project_id and name, plus source and organization_id, receive no explanation in the description, so the burden is not met.

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?

State a specific verb and resource ('Create a contact list in the workspace') and clarifies that rows are optional. It does not explicitly differentiate itself from the close sibling add_contacts, which also adds contacts, so an agent still has to infer the boundary.

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

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

No when-to-use guidance, no prerequisites, and no named alternative such as add_contacts for appending to an existing list. The only hint at usage is 'optionally with rows', which is a capability statement rather than routing guidance.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false). The description adds genuine value beyond that: it discloses that purpose is never refused, that recipient_type is recorded but never enforced, and that the destination is gated by org capabilities. It still stops short of explaining the destructive consequence (call placement) or idempotency behaviour.

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

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

Three tight sentences, front-loaded with the core action and with zero filler. It packs several distinct behavioural facts without padding, though the semicolon-chain of the trailing clause is slightly dense.

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 15-parameter, nested-object mutation tool with no output schema, the description is only partially sufficient: it adequately covers the policy gate and two salient parameters, but leaves most inputs and the overall calling workflow underspecified given the low schema coverage.

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

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

Schema coverage is only 20% across 15 parameters. The description adds real meaning for purpose (free-form, never refused) and recipient_type (persisted verbatim, not enforced), but then defers to the schema for the catalog rather than restating it, and leaves the majority of parameters (to, from_number_id, project_id, user_authorization, policy, agent_id, etc.) undocumented in either place.

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

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

The description opens with a specific verb + resource ('Create a policy-gated outbound call request'), which is clearly distinct from a plain 'place call'. However, it does not explicitly differentiate itself from neighbouring authorizers such as authorize_outbound or evaluate_outbound_policy, so an agent must still infer which one to choose.

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 'policy-gated' framing and the note that the destination country is authorized against workspace capabilities imply a prerequisite workflow, which is useful contextual guidance. But there is no explicit when-to-use/when-not, and no named alternative for the authorization or policy-evaluation steps.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the mutation/repeatability profile is covered. The description adds useful context that a dry-run verification path exists, but says nothing about what the server creation entails, whether existing servers are affected, or permission requirements.

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

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

Two short sentences with zero filler, and the core purpose is front-loaded before the verification hint. 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 7 parameters, 14% schema coverage, no output schema and no parameter documentation in the description, an agent has almost nothing to reason about for port, transport, or allowed_sip_ips. The description is too thin for the tool's complexity, even accounting for annotations that cover the safety profile.

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

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

Schema description coverage is only 14% (only organization_id is documented), and the description contributes no parameter meaning at all — port, transport, allowed_sip_ips and server_address are unexplained in both places. For a 7-parameter tool with one documented field, the description should compensate but 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?

The description states a specific verb and resource ('Create a customer phone server for self-hosted media/calling'), which clearly distinguishes it from list_phone_servers and identifies test_phone_server as the dry-run counterpart. It is clear and actionable, though the differentiation from the create-side siblings (create_agent, create_campaign) relies only on the resource noun.

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

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

The mention that 'test_phone_server dry-run verifies it' implies a sensible pre-creation workflow, but the description never states when to use this tool versus the dry-run or when creation is appropriate. Usage is inferable rather than explicit, with no exclusions or prerequisites.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotence, so the safety profile is covered. The description adds genuinely non-obvious behavior: per-runner runtime admission gates, the language requirement for adaptive_voice, and the explicit disambiguation that caller_environment is synthetic caller-input noise, not the agent's outgoing ambience. Permission requirements and post-create side effects remain unstated.

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

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

Three sentences, front-loaded with the core action, then runner behavior, then the caller_environment clarification. Dense but mostly earning its place; the caller_environment sentence partially restates the nested schema description.

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

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

For a 7-parameter tool with nested objects, no output schema and low schema coverage, the description covers the trickiest path (scenarios/runners/voice) well but leaves the policy object and snapshot source unexplained, so an agent cannot fully call it without inference.

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 only 29% schema coverage, the description must compensate, and it does for the scenarios array, runner values and caller_environment/noise_level semantics. However it says nothing about `policy`, the `default_snapshot_source` draft/published choice, or the two required fields, so significant parameters remain undocumented on both sides.

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 simulation suite on an AI agent') and adds the framing that a scenario pack becomes a suite via this call. That distinguishes it cleanly from the sibling read tools (get_simulation_suite, list_simulation_suites) and from other create_* 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?

It gives real conditional context -- adaptive_voice is 'admitted only where the voice runtime is on', and offline runners are named -- but never frames when to choose this over an alternative (e.g. creating a suite vs. adding scenarios later, or preview_simulation_run/start_simulation_run). Usage is implied rather than routed.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, so the safety profile is already structured. The description adds useful behavioral context beyond that: the operation is offline, places no phone call, and requires synthetic_only=true, which matches openWorldHint=false and reassures an agent about non-open-world side effects. It does not explain what state gets created or that organization_id must match the auth workspace.

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

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

Two short sentences, zero padding, with the core purpose front-loaded and the non-obvious constraint and retirement note immediately after. 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?

For a destructive mutation tool with six parameters, low schema coverage, and no output schema, the description covers purpose and the synthetic_only constraint but omits what the fixture contains, required relationships among agent_id/project_id/agent_endpoint_id, and any return shape. Adequate but with clear gaps.

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

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

Schema description coverage is only 17%, so the description should compensate for the other five parameters, but it does not. Its only param-level content (synthetic_only must be true) merely restates the schema const, and the PIN remark only hints that pin is obsolete. project_id, agent_id, agent_endpoint_id, and organization_id remain undocumented in both places.

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

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

The description gives a specific verb+resource: creating an offline synthetic trial call fixture. It also clarifies what the tool is NOT ('places no phone call'), which implicitly separates it from create_outbound_call. It stops short of naming a sibling or stating the exact artifact produced, so it lands at clear-but-not-fully-differentiating.

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

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

Usage is only implied: the tool is framed as an offline fixture for synthetic trials. There is no explicit 'use this when...' and no named alternative (e.g., create_outbound_call or start_simulation_run) for agents that actually want a live or simulated call. The retirement note for live PIN trials gives indirect context but not selecting guidance.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuine behavioral context: purpose is never refused for novelty (only emptiness), recipient_type is recorded verbatim, and destination country is governed by workspace capabilities rather than by this evaluation — the last point usefully bounds what the tool actually checks.

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

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

Three tight sentences, front-loaded with the core action and followed by the two behavioral caveats. Minor redundancy with the schema's own purpose/recipient_type descriptions, but no wasted prose.

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

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

For a 9-parameter, nested-object tool with no output schema, the description explains inputs but says nothing about what the evaluation returns (verdict format, allow/deny, error signaling), which is the key missing piece an agent needs. Input-side coverage is adequate; outcome-side is absent.

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

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

Schema coverage is only 44%, and the description adds real meaning for purpose, recipient_type, and country. However, five parameters (to, from_number_id, policy, categories, user_authorization) — including the nested policy object — are undocumented in both schema and description, so the gap is not fully compensated.

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

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

States a specific verb and resource ('Evaluate outbound voice/SMS policy') and anchors it in the workflow ('before creating a call'). It is clearly distinct from create_outbound_call, but it never contrasts itself with the closer sibling authorize_outbound (mentioned only inside a schema property), so sibling differentiation is incomplete.

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?

'before creating a call' implies the timing of use, which is useful, but the description never explicitly names authorize_outbound or check_number_requirements or says when this evaluation is required versus optional. Usage must be inferred 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 declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description's only added claims are 'authenticated-workspace' scoping and 'same safe REST agent projection', which are vague jargon that disclose nothing concrete (no error/not-found behavior, no consistency guarantees clarified).

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

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

A single short sentence with the verb+resource front-loaded, so it is not bloated. The trailing clause 'using the same safe REST agent projection' is cryptic filler that does not earn 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 and no schema parameter descriptions, the definition should explain what an 'agent' record contains and how to supply agent_id. Neither is present, so an agent cannot confidently invoke or interpret this call.

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

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

There is one required parameter with 0% schema description coverage, so the description carries the full burden. It says nothing about agent_id's format, provenance, or where the caller obtains a valid value, leaving the single parameter effectively undocumented.

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

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

States a specific verb ('Get') and resource ('agent') with a singular scope ('one'), which distinguishes it from list_agents. However, the qualifier 'the same safe REST agent projection' refers to an antecedent not present in this description and does not clarify the purpose, nor does it separate this tool from get_agent_variables, get_agent_voice_stack, or get_agent_catalog.

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

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

No when-to-use guidance is given. The description never explains when to call get_agent versus list_agents, get_agent_catalog, or the more specific get_agent_variables/get_agent_voice_stack siblings. The agent must infer routing entirely from names.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the lower bar applies, yet the description still adds required permissions (agents:read or coverage:read) and describes the returned data shape (cost, latency, languages, streaming, runnability, conversation_engines). The only gap is pagination/size behavior in a presumably large catalog.

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

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

The lead sentence front-loads the purpose and filters, but the middle clause about has_language_axis, per-language overrides, and 'Follow the caller' is dense and hard to parse. Structure is otherwise linear and mostly waste-free.

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 return fields, conversation_engines values, and auth requirements for a moderately complex catalog tool. The awkward has_language_axis passage leaves some ambiguity about the per-language override rows, but nothing critical to invoking the 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 0%, so the description carries the burden, and it delivers: it names component, language with two worked examples showing filter semantics, and metered_only. It does not fully explain what metered_only excludes or the accepted form of component beyond the enum, but the semantics are largely covered.

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 ('selectable STT/LLM/TTS voice-stack providers') and enumerates the returned attributes (cost, latency, languages, streaming, runnability) plus conversation_engines. This distinguishes it clearly from siblings such as get_agent_voice_stack (a specific agent's stack) and get_capabilities.

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

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

It states an auth prerequisite and gives concrete filter usage examples (language=et, language=si), which implies the discovery use case. However, it never explicitly says when to reach for this catalog versus get_agent_voice_stack or list_audio_environments, so alternative 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 already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds genuine value beyond that: it discloses the returned contents and, importantly, that the payload carries the revision required by a write and the schema_hash a call admitted now carries. It omits auth or pagination details, preventing a 5.

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

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

Two sentences, front-loaded with verb and resource, with the field enumeration in a parenthetical and the endpoint equivalence at the end. Efficient, though the last sentence is a mapping convenience rather than essential 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 readOnly tool with no output schema and only two parameters, the description adequately explains what is returned and why the revision/schema_hash matter. An agent can call this correctly with the information given, though the revision semantics could be expanded.

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

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

Schema coverage is 50%: organization_id is documented inline, agent_id is not. The description only reinforces agent_id via the GET path template and adds no syntax or format guidance. With the schema doing half the work, this is a baseline 3.

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

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

States a specific verb (Read) and resource (an AI agent's call variables config), then enumerates the contained fields: declared variables, SMS templates, SMS mode, caller lookup. This clearly separates it from get_agent and from the write counterpart. It stops short of naming sibling tools explicitly, so it falls just under a 5.

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

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

Usage is implied rather than stated: the mention of 'the revision a write must name' hints that this read feeds the set_agent_variables write, and the REST endpoint mapping grounds it. But there is no explicit 'use this when' or when-not guidance, so an agent must infer the workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds two useful behavioral facts: results are scoped to the authenticated workspace and the language profiles returned are 'sparse' (partial). It does not describe the response shape, but with no output schema that gap is minor for a simple getter.

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

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

One sentence with the resource and scope front-loaded; no padding. The only minor weakness is the trailing 'REST voice-stack projection' jargon, which costs a small amount of clarity without adding actionable 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 read-only single-parameter getter whose annotations already carry the safety profile, this is close to adequate. The 'sparse language profiles' phrase helps set return expectations, but with no output schema the description could say more about what a 'selected stack' contains.

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

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

Schema coverage is 0% and the single agent_id parameter has no schema description. The phrase 'one authenticated-workspace agent's' implies a single specific agent identifier rather than a list, adding marginal meaning, but it does not clarify accepted ID format or source.

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

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

The description names a specific verb and resource: 'Get one authenticated-workspace agent's selected stack and sparse language profiles.' This distinguishes it from set_agent_voice_stack (the mutating counterpart) and from get_agent. The trailing 'REST voice-stack projection' adds jargon that slightly clouds rather than clarifies.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The use case (read an existing agent's voice configuration) is only implied by the verb and resource.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description then adds behavior beyond that: it tells the agent what the payload actually conveys (status, recording state, workflow outcome, interrupts taken, settled), which matters because there is no output schema. It stops short of stating what happens when the call_id is unknown.

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

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

One sentence, front-loaded with the verb and the primary object, followed by a compact parenthetical of the returned facets. No filler, no repetition of the title.

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

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

With no output schema, the description carries the burden of explaining the response and does so reasonably by listing the fields the agent will receive. It does not mention error behavior for an invalid or expired call_id, which is the main remaining gap for a single-resource getter.

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

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

Schema description coverage is 0%, so the schema contributes nothing beyond the name 'call_id'. The description also says nothing about the parameter. It is a single, self-evident identifier for the call being fetched, so the ambiguity is low, but the description does no work here — baseline 3 fits.

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?

Names a specific verb (Get) and resource (call) and enumerates the facets returned: status, recording state, and workflow end state (outcome, interrupts, settled). This is clear, but it does not explicitly differentiate itself from siblings such as get_call_recording, get_call_transcript, or list_calls — 'recording state' in particular sits close to get_call_recording without saying which one to reach for.

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

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

Usage is only implied: a single call look-up keyed by call_id. There is no explicit 'use this when you have a call_id and need status' or 'use list_calls to enumerate calls' guidance despite several near-neighbor retrieval siblings. Minimum viable but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a small piece of behavioral context by noting 'disclosure state,' which hints at recording-consent output, but says nothing about what the metadata contains or whether a recording may be absent.

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

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

A single front-loaded sentence with no filler. It is efficient, though its brevity is part of why coverage gaps remain rather than being a virtue in itself.

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

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

With no output schema, the description should characterize the return value, and 'metadata and disclosure state' is a partial answer. For a single-ID read tool this is minimally adequate but leaves the agent guessing at payload structure and failure modes.

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

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

Schema description coverage is 0%, so the description carries the full burden for call_id and provides nothing — no format, no source, no relation to the call identifiers used by sibling tools. The parameter is a self-evident ID, which keeps this from being a 1, but the gap is real.

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 ('Get recording metadata and disclosure state'), which is concrete and more specific than the bare title. It does not, however, differentiate itself from adjacent siblings such as get_call, get_call_transcript, or get_call_translations, so an agent must infer which call artifact this returns.

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

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

There is no guidance on when to use this tool versus get_call, get_call_transcript, or list_calls. No prerequisites are stated, and no condition selects this tool over its 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine behavioral context about the `events` field and pre-empts a likely misinterpretation ('an empty events never means the other party was silent'), which is valuable for interpreting results.

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

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

Two tightly written sentences, front-loaded with the core action, and every clause does work. Nothing extraneous, though the second sentence is dense rather than clearly separated.

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's explanation of `events` is useful, but with four parameters at 0% schema coverage it omits pagination and translation semantics entirely. For a paginated, translatable retrieval tool this leaves material gaps.

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

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

Schema description coverage is 0% for all four parameters, so the description carries the full burden, yet it addresses none of them. It says nothing about call_id, the limit/cursor pagination pair, or translation_language, so an agent must guess at paging and translation behavior.

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

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

The description states a specific verb+resource ('Get call transcript turns'), which is concrete and unambiguous. However, it never distinguishes itself from close siblings such as get_call, get_call_recording, or get_call_translations, leaving the agent to infer which retrieval tool applies.

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

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

There is no explicit when-to-use guidance and no mention of alternatives among the many get_* siblings. The agent gets what the tool returns but not when to prefer it over get_call or get_call_translations.

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 readOnly, idempotent, and non-destructive semantics, so the bar is lower. The description still adds real behavioral context beyond them: 'cached' signals it only returns existing translations and will not generate new ones, and 'No paid work is created' conveys a cost/authorization trait the annotations do not 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?

Two short sentences, no filler, and the core purpose plus the cost constraint are front-loaded. Every sentence earns its place.

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

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

For a 4-parameter read tool with zero schema descriptions and no output schema, the definition is too thin. It never explains target_language filtering, pagination via limit/cursor, or what happens when no cached translation exists, so an agent lacks enough to invoke it confidently.

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

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

Schema description coverage is 0% and there are 4 parameters. The phrase 'for a call' loosely maps to call_id, but target_language, limit, and cursor are entirely unexplained in both the schema and the description, leaving key filtering and pagination semantics undocumented.

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

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

The description states a specific verb and resource: 'Read cached machine translations for a call.' The phrases 'cached' and 'No paid work is created' implicitly distinguish it from the sibling request_call_translation tool, but no sibling is named explicitly, which keeps it short of a 5.

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

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

'No paid work is created' hints at when to prefer this over a generation/request tool, but the description never explicitly names the alternative or states the condition (e.g., 'use request_call_translation if no cached translation exists'). Usage is implied, not 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 readOnlyHint, idempotentHint and non-destructive, so safety is covered without the description. The description does add return-shape context ('latest run and contact counters'), but says nothing about not-found behavior, workspace scoping failure modes, or permissions.

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

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

A single short sentence, front-loaded with the verb and the record scope, with no filler. It is efficient, though the brevity is partly what leaves the guidance gaps above.

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

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

For a simple read tool with strong annotations and no output schema, the description usefully hints at the return contents. It is still thin on the one undocumented parameter and on error/empty-result behavior, which an agent fetching by id would want.

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

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

Schema description coverage is only 50%: organization_id is documented in the schema, but campaign_id carries no description anywhere. The description never clarifies that campaign_id is the lookup key or what form it takes, so it fails to compensate for the coverage gap.

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

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

States a specific verb ('Read') and resource ('one campaign') and even scopes the payload to a single record with its latest run and counters. It does not, however, name or contrast itself with list_campaigns, the obvious sibling an agent might confuse it with.

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

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

There is no when-to-use guidance, no mention of how to obtain a campaign_id, and no pointer to list_campaigns for discovery or to launch_campaign/update_campaign for lifecycle actions. Usage is only inferred from the word 'one'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description's only added behavioral note is that the payload includes live usage measured against caps, which is useful but thin given the annotation coverage.

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

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

A single sentence with no wasted words, and the primary return (the capabilities record) is front-loaded ahead of the supporting payloads. It is efficient, though it stops short of the optimal front-loading that would name scope or role up front.

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

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

With no output schema, the description carries the burden of describing returns, and it does list the three major payload groups. It stops short of describing the shape of the capabilities record or the usage-vs-caps structure, but it is adequate for a single-parameter read tool.

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

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

There is a single optional parameter and schema description coverage is 100%, so the schema already explains the organization_id default and constraint. The description adds nothing about the parameter, which is the expected baseline here.

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

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

States a specific verb+resource (return the workspace capabilities record) and enumerates the payload: use-case profiles and live usage vs caps. This is clear, but it does not distinguish itself from siblings such as request_capabilities or get_coverage, leaving ambiguity about which to select.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The presence of request_capabilities and get_coverage in the sibling list makes the absence of routing guidance a real gap, not a minor one.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds useful substance beyond that by naming the payload (REST record plus row_count), which partially compensates for the missing output schema; it still says nothing about not-found/error 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?

Two short sentences, zero filler, with the core purpose front-loaded and the disambiguation pointer second. Every clause earns its place.

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

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

For a two-parameter read tool with no output schema, the description covers purpose, the reference-by-id model, and a partial view of the return shape. What remains thin is the meaning of contact_list_id and any error/not-found semantics, but an agent has enough to invoke it correctly.

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

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

Schema coverage is 50%: organization_id is documented in the schema but contact_list_id is not. The phrase 'by id' hints at the required identifier but adds no format, source, or constraint detail beyond the schema, so 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 precise verb (read), resource (one contact list), and scope (of the workspace, by id), which cleanly separates it from the sibling list_contact_lists. It also clarifies the record is the REST contact-list record including row_count, so an agent knows exactly which object it gets back.

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 routes the row-reading use case to a named alternative (list_contacts), which is genuine when-to-use guidance. It does not explicitly contrast with list_contact_lists, though 'one ... by id' implicitly implies that distinction.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds value by naming the returned coverage dimensions, but says nothing about pagination, filtering behavior, or result size, which is modest additional context given the low-complexity read.

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

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

A single front-loaded sentence with no filler; the resource and returned fields come first. It is appropriately terse for a simple lookup tool.

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

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

For a low-complexity read-only listing with no output schema, the description conveys the core purpose and return dimensions. The gap is the unexplained 'countries' parameter, which leaves the agent guessing about filtering behavior.

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

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

Schema description coverage is 0% and the single 'countries' parameter is undocumented in both schema and description. The description does not explain whether passing countries filters the list, is required to scope results, or what string format is expected, so the key semantic is missing.

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

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

States a specific verb (List) and resource (supported countries) and enumerates the data dimensions returned (voice, SMS, registration, onboarding speed). It is clear what the tool does, though it does not explicitly differentiate itself from overlapping siblings such as get_capabilities or get_number_catalog.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives, despite several catalog-style siblings that could overlap. The agent must infer the selection criteria entirely on its own.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds two things annotations do not: results come from a cache (potentially stale or incomplete), and no billing/paid work is incurred. That billing and caching context is genuinely useful for an agent deciding whether to call it.

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

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

Two short sentences, no filler, with the core action front-loaded and the cost guarantee immediately after. 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?

For a simple read tool with strong annotations and no output schema, the description covers purpose and cost behavior adequately. It is incomplete on the input side, though: target_language's optionality and effect are undocumented in both schema and description, leaving meaningful ambiguity about what a call returns.

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

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

Schema description coverage is 0% for two parameters, so the description carries the full burden and does not meet it. It never explains what message_id identifies or what target_language does, nor whether omitting target_language returns all available languages or a default. No syntax or format hints are given.

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

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

'Read cached machine translations for an SMS' names a specific verb (read) and resource (SMS translations), and the word 'cached' plus 'No paid work is created' functionally separates it from the sibling request_message_translation. It stops short of naming that sibling explicitly, so the distinction relies on inference rather than direct routing.

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 cost note implies the when: use this when cached translations suffice and you don't want to trigger paid work. However, it never names request_message_translation as the alternative for generating fresh translations, so the agent must infer the fork from the tool name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that results carry pricing and onboarding terms, which is useful context, but says nothing about pagination, result volume, or how the limit behaves.

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 efficient sentence with the resource stated first and the return contents front-loaded. Nothing is wasted, though the brevity comes at the cost of the missing usage and parameter detail.

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 6 undocumented parameters, no output schema, and only a one-line description, an agent cannot confidently construct a filtered query or know what a result looks like. The definition is adequate as a purpose statement but insufficient for correct invocation.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the full burden. It gestures at capabilities and onboarding terms but never explains the filtering semantics of countries, number_types, available_only, or limit, leaving most parameters opaque.

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

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

The description gives a specific verb (list) and resource (available number offerings) and enumerates the returned data (setup/monthly prices, capabilities, onboarding terms), which distinguishes it from a plain inventory list like list_numbers. However, it never explicitly contrasts itself with siblings such as list_numbers or get_number_rules, leaving the boundary to inference.

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

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

There is no indication of when to use this catalog versus list_numbers, get_number_rules, check_number_requirements, or request_number. No prerequisites, no exclusions, and no 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds essentially nothing beyond them — the phrase "customer-facing" hints at a scope qualifier but is never explained, and there is no note on permissions, rate limits, or what an empty result means.

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

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

One short, front-loaded sentence with no filler. It is efficient, though the terseness contributes to the under-specification noted elsewhere.

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

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

No output schema exists, so the description carries the burden of explaining what comes back — yet it never says what the rules contain, their structure, or whether an empty list is possible. Combined with 0% parameter coverage, an agent is left with meaningful gaps for a lookup tool.

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

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

Schema description coverage is 0% for the single required parameter number_id. The description says "for one phone number," which suggests the value is a phone number, yet the parameter is named number_id, leaving real ambiguity about whether an internal identifier or an E.164 number is expected.

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 ... Number rules") scoped to a single phone number, which naturally distinguishes it from the sibling update_number_rules. However, "customer-facing Number rules" is not defined, so the agent must infer what a "Number rule" actually is.

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

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

No when-to-use guidance and no named alternatives. The agent gets no signal about how this differs from check_number_requirements, get_number_catalog, or list_numbers, all of which touch numbers and could plausibly be chosen instead.

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 and non-destructive, so the safety bar is met structurally. The description adds real behavioral context beyond them: the required `agents:read` scope, the conditional inclusion of transcripts/recordings/conversation evidence only under `recordings:read`, and that results are paginated over attempts.

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

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

Three tight sentences: content first, pagination scope second, permissions last. No filler, and the most decision-relevant information (what you get back) is front-loaded.

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

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

With no output schema, the description correctly takes on the burden of describing return contents and permission-gated fields, which it does well. It stops short of covering cursor/limit behavior details or failure modes, but nothing essential for a correct call 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 only 20% (just organization_id documented), so the description carries most of the burden. "Paginated over attempts" does clarify the scope of limit/cursor, which is genuine added meaning, but run_id, agent_id, limit and cursor formats or defaults are never explained.

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 and enumerates what the run payload contains (status, attempts, per-scenario verdicts, assertion results, recognition facts, transcripts). It is clear on its own, but it does not distinguish itself from the sibling get_simulation_run_results, whose name suggests overlapping content, leaving a routing ambiguity an agent must resolve elsewhere.

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 read-only framing and the required permission scopes, and the conditional recordings:read note hints at when extra data appears. However, there is no explicit when-to-use versus get_simulation_run_results, preview_simulation_run, or start_simulation_run, and no stated prerequisites beyond scopes.

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 read-only/idempotent/no-side-effects, yet the description adds genuinely useful behavior: exactly what is redacted (no transcript, no recording reference, no rubric rationale) and the minimal permission scope required (simulation_suites:read). 'Read-only' repeats the annotation, but the redaction and permission disclosures go well beyond it.

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

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

Opens with the core purpose and output shape, then the permission/CI rationale, then a terse safety note. Tightly constructed with little waste, though the CI-gating explanation is somewhat elaborate relative to the rest.

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-value burden and does so well, enumerating the projected fields and what is withheld. The remaining gap is parameter-level guidance (pagination, cursor), which is left undocumented.

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

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

Schema coverage is only 20% (only organization_id documented), so the description is expected to compensate, and it does not -- limit, cursor, run_id and agent_id semantics are unaddressed. 'The same run' faintly implies run_id/agent_id identify the run, but pagination and cursor behavior are never explained.

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 resource (a simulation run) and a precise output shape (redacted pass/fail projection: per-case status, error codes, failed assertions, evidence kind). The phrase 'The same run as a redacted... projection' implicitly distinguishes it from the fuller run sibling, but does not name get_simulation_run directly, so sibling differentiation is only 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 a clear use context -- a build server / CI job gating a deploy -- which explains when this narrow projection is preferable. It stops short of explicitly naming the alternative (get_simulation_run for the full transcript-bearing view) or stating when-not to use it.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false, non-destructive), so the redundant 'Read-only' adds little. However, the description does add real behavioral context beyond annotations: what the response comprises, and that starting a run with an unsupported runner is refused with a 422.

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 sentence followed by a two-word tag; the payload contents are front-loaded and every clause carries information (scenarios, policy, history, run_setup, 422). Slightly packed but free of 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 correctly carries the burden of describing the return: scenarios/runners, policy, run history, and run_setup with supported_runners. It is thin on parameter semantics and omits behaviors like not-found handling, but for a simple read tool it is nearly complete.

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

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

Schema description coverage is only 33%: organization_id is documented in the schema while agent_id and suite_id are bare strings. The description says nothing about any parameter, not even the optional workspace override or id formats, so it fails to compensate for the coverage gap.

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

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

The description names the exact resource ('One simulation suite') and enumerates its contents (scenarios and runners, policy, run history, run_setup), which makes it clearly distinguishable from siblings like list_simulation_suites or get_simulation_run. It is specific but never explicitly contrasts itself with those 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?

Usage is only implied: by exposing run_setup's supported_runners and the 422 refusal, it hints that this call is how you discover which runners are admissible before starting a run. There is no explicit when-to-use or when-to-prefer-an-alternative statement (e.g., versus get_simulation_run).

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

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

The description is otherwise unusually rich - it discloses that the tool returns immediately, never reports the call as ended, that the media worker tears the call down, and that the call reaches its terminal event via the ordinary path. However, it states 'Repeating the request is idempotent and returns the original timestamp', which directly conflicts with the annotation idempotentHint=false. That inconsistency is a serious behavioral disclosure problem even though the destructive/openWorld hints are consistent with the described teardown.

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

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

Three tight sentences, front-loaded with the action, then the return/async contract, then idempotency and the refusal condition. No sentence is padding.

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

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

With no output schema, the description supplies the return value (hangup_requested_at), the asynchronous teardown path, the terminal-event behavior, and the refusal case. An agent has everything needed to call it and interpret the result, aside from the idempotency inconsistency.

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

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

Schema description coverage is 0% for the single call_id parameter, so the description carries the burden. It does add meaning by stating the referenced call must be live and not merely queued for origination, but it never says what form call_id takes or where to obtain it, leaving part of the semantics implicit.

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

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

States a specific verb and resource ('ask a call that is already live to hang up') and immediately bounds the scope to live calls, distinguishing it from get_call, create_outbound_call, and the campaign control tools. An agent can identify the operation without opening the schema.

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

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

Gives a clear applicability condition (the call must already be live) and an explicit exclusion ('a call still queued for origination is refused'), plus the repeat-call behavior. It does not name a sibling alternative for the queued case (e.g. cancel_campaign), so it stops just short of full routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral detail: the tool both authorizes and starts, launch is conditional on list type and workspace capabilities, and the returned result carries an authorization decision rather than a guaranteed launch. It still omits what side effects (real outbound calls) occur and what happens on denial.

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

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

Two sentences, front-loaded with the core action, and no filler. The second sentence packs the conditional launch behavior and the return-value caveat efficiently, though the 'Existing-customer / consented lists' phrasing is dense enough to slow parsing.

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, open-world tool with no output schema, the description should carry more of the return and failure story. It does explain that the result carries the authorization decision, but leaves unclear what happens when authorization is denied, whether the action is reversible, and what downstream effects the launch triggers.

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

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

Schema coverage is 50%: organization_id is documented in-schema (defaults to authenticated workspace, must match it), while campaign_id has no schema description. The description supplies the key implicit constraint that the target must be a draft campaign, partly compensating, but adds no format or identity details for campaign_id. 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 compound verb (authorize and start) and a precise resource scope (a draft campaign), which cleanly separates it from create_campaign, pause_campaign, and resume_campaign. It does not explicitly name a sibling or contrast itself with resume_campaign, so it falls short of a 5.

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

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

The conditional clause 'Existing-customer / consented lists on active workspace capabilities start immediately' implies when a launch is immediately effective versus when it stalls for authorization, which hints at usage context. But it never says when to prefer this over resume_campaign/pause_campaign, nor does it state the prerequisite that the campaign must already be a draft.

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

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

Annotations already declare a safe read-only idempotent operation, and the description adds substantial non-obvious behavior: pages are bounded by both a count (limit) and 25,000 characters, may hold fewer, and oversized agents are surfaced in pagination.omitted. This is real 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?

Three dense sentences, front-loaded with what the tool returns before pagination caveats. Every sentence carries information, though the character-bound and omission details make it 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?

With no output schema, the description steps in to describe the return: the safe agent item DTO, pagination metadata, next_cursor, has_more, and pagination.omitted. An agent has enough to call it and consume 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 50%; cursor semantics are reinforced (

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 workspace's agents') and adds distinguishing scope: bounded, newest-first, paginated. An agent can separate it from get_agent or list_calls 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?

Clearly explains that next_cursor continues the listing and is only meaningful while has_more is true, which tells the agent how to iterate. It stops short of explicitly naming alternatives (e.g. get_agent for a single agent, or 'the tool that reads it' for omitted agents is left unnamed).

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 bar is lower, but the description adds real context: the catalogue is immutable and version-pinned, no provider is contacted, and no selection is mutated. The volume vs noise_level note further clarifies how fields differ between callers, exceeding what 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?

Three tight sentences with no filler, front-loaded with the core verb+resource and followed by only value-adding constraints. Every sentence earns its place.

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

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

For a zero-parameter, no-output-schema read tool, the description supplies the catalogue's content shape (Off option, version-pinned presets) and hints at relevant fields (volume, noise_level), which partially compensates for the absence of an output schema. It stops short of enumerating the returned fields fully.

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 zero parameters the baseline is 4; the description adds no parameter detail because there are none to describe.

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 (immutable, provider-independent audio-environment catalogue), and adds scope detail: it contains an explicit Off option and version-pinned ambience presets. The resource is unique among siblings, so confusion is unlikely, but it does not explicitly contrast itself with any alternative listing tool.

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 a discovery use case (list the catalogue, no selection changed) but gives no explicit when-to-use or when-not-to-use guidance, and names no alternative. Usage is inferable rather than stated.

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

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

Annotations already declare the safe read-only profile, and the description adds substantial beyond-schema behavior: newest-first ordering, per-item trimming of runtime_config, a hard character cap (25,000) that can make pages shorter than limit, and a named pagination.omitted case for oversized calls. This is exactly the kind of operational detail the structured fields 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?

Four dense sentences, front-loaded with the tool's purpose and scope, with zero filler. Each sentence carries distinct information (trimming, page bounds, pagination continuation, omission).

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 shape well, describing item contents and the pagination object's next_cursor, has_more, and omitted fields. The only shortfall is that project_id and full organization_id semantics remain thin, but for a paginated list tool this is close to complete.

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

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

Schema description coverage is 50%, and the description adds meaning for limit (page bounded by both count and characters) and cursor (continues listing, valid only while has_more). However project_id is undocumented in both schema and description, and organization_id's workspace-default behavior is left to the schema alone, so it only partially compensates for the coverage gap.

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

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

States a specific verb (List), resource (workspace's calls), and scope (one bounded, newest-first page). It further disambiguates from the sibling get_call by noting the record is returned without runtime_config while get_call returns the full record. An agent can distinguish this from other list_* tools without opening any schema.

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

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

It routes the agent toward get_call for the full record and explains pagination continuation via next_cursor/has_more, giving clear context for how to iterate. It stops short of an explicit 'use this when... / not when...' statement against the broader sibling set (e.g. get_call_transcript), so it earns a 4 rather than 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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond the annotations: the result is a workspace-scoped, bounded page that includes each campaign's latest run and counters.

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

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

A single sentence with no filler, front-loading the core action and resource while packing in scope, return content, and pagination constraint. Every phrase earns its place.

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

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

For a simple read-only list with rich annotations but no output schema, the description does mention return content and pagination. However, it leaves project_id and the limit/offset mechanics unexplained, which is a meaningful gap given the low schema description coverage.

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

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

Schema description coverage is only 25% (only organization_id is described in the schema). The description does not explain what limit, offset, or project_id do, nor does it clarify pagination semantics beyond the vague phrase 'bounded page', so it fails to compensate for the undocumented 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?

The description states a specific verb ('List') and resource ('campaigns') and adds scope ('in the workspace') plus return content ('latest run and counters', 'bounded page'). It does not explicitly differentiate from siblings like get_campaign or other list_* tools, but the core purpose is unmistakable.

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 implies use for enumerating campaigns in a workspace but gives no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as get_campaign for a single campaign. Pagination parameters exist but the description offers no guidance on when or how to page.

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 a read-only, idempotent, non-destructive, non-open-world operation, so the safety profile is covered. The description adds real value beyond that: newest-first ordering, a per-page cap of both limit lists and 25,000 characters, and the condition under which the cursor is meaningful. It omits permission/auth requirements, 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?

Purpose is front-loaded in the first clause, with pagination invariants in a tight second sentence. It is dense but every clause carries information; the phrase 'using the REST contact-list record' is the only slightly loose element.

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 enumerates returned fields (id, name, project, source, row_count, timestamps) and the pagination envelope. Annotations cover safety, but the unexplained project_id filter leaves a small gap for a 4-parameter list 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 only 50% – project_id and limit carry no schema description. The description compensates for limit ('a page holds at most limit lists') and for cursor (via the pagination.next_cursor explanation), but says nothing about what project_id filters or how organization_id scoping behaves, so half the parameters remain underspecified.

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 workspace's contact lists'), and adds scope detail (one bounded, newest-first page) plus the fields returned. This clearly separates it from get_contact_list (single record), create_contact_list (write), and list_contacts (a different resource).

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 invocation: it lists the workspace's lists, not another workspace's, and explains that next_cursor only continues while has_more is true. It stops short of naming alternatives (get_contact_list, list_contacts) or stating when not to use it, so no explicit exclusion guidance is present.

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 safe read-only, idempotent profile, and the description adds substantial non-derivable behavior: a page holds at most limit contacts AND at most 25,000 characters, so it may return fewer than requested; pagination.next_cursor/has_more drive continuation; and oversized contacts appear in pagination.omitted.

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

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

Front-loads verb and scope, then layers pagination and edge-case behavior in one dense but well-ordered sentence. The parenthetical field enumeration earns its place given there is no output schema, though the sentence is long.

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 available, the description covers the return shape (enumerated fields), page-size limits, continuation mechanics, and the omitted-contact edge case, giving the agent everything needed to call and consume the tool correctly.

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

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

Schema coverage is only 50%, but the description compensates by explaining what limit actually bounds (contacts and characters per page) and how cursor relates to pagination.next_cursor. contact_list_id semantics remain only implied, and organization_id relies on 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 ('List one bounded page of a contact list's contacts') and clarifies scope with fields, ordering ('import order'), and record source ('using the REST contact record'). It is clearly distinguishable from list_contact_lists and get_contact_list 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?

Usage is implied by the scoping to a single contact_list_id, and the pagination narrative tells the agent how to continue, but no alternative tool is named and there is no explicit when/when-not guidance. Adequate but not routing-grade.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no scoping behavior, no default ordering, no pagination or volume characteristics for the list operation.

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

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

A single short sentence is maximally compact, but here brevity reflects under-specification rather than efficient communication. It is front-loaded but carries almost no 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 two-parameter list tool with no output schema and incomplete parameter documentation, the description should explain what the returned conversations represent and how scope is determined. It omits all of this, leaving real gaps an agent cannot resolve from structured 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 description coverage is only 50%: organization_id is documented but project_id has no description at all. The description text provides zero compensating information about either parameter or their relationship (e.g., whether project_id scopes the listing).

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

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

"List SMS conversations" simply restates the tool name and title verbatim with no additional specificity. It does not distinguish this tool from siblings like list_calls, list_campaigns, or list_contacts, nor clarify what a 'conversation' contains versus a call or message.

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

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

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, filtering, or pagination. An agent must infer usage entirely from the name.

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 still adds substantial behavior: newest-first ordering, an explicit page ceiling of 'at most 25,000 characters' (so a page may return fewer than limit), the rule that next_cursor is meaningful only while has_more is true, and the existence of pagination.omitted for oversized numbers. These are non-obvious traits an agent cannot get from structured fields.

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

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

Three sentences, none wasted, with the bounded-pagination constraint front-loaded before cursor semantics. It is dense but every clause carries operational information; a slightly shorter phrasing of the 25,000-character rule could tighten it further.

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 documents the return envelope (pagination.next_cursor, has_more, omitted) that the agent must read to page correctly. The remaining gap is project_id and any scoping behavior beyond organization_id, which is only partially covered in the schema.

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

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

Schema coverage is only 50%, but the description compensates by clarifying that limit is a true upper bound rather than a guaranteed count, and by tying cursor to pagination.next_cursor. project_id remains completely undocumented in both the schema and the description, leaving one gap.

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

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

Names a specific verb and resource ('List one bounded, newest-first page of the workspace's phone numbers with registration status'), and the possessive 'workspace's' implicitly distinguishes owned numbers from the catalog tool. It never names a sibling explicitly, so an agent must still infer the boundary versus get_number_catalog or list_phone_servers.

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 pagination mechanics but gives no when-to-use, when-not-to-use, or alternative-tool guidance. An agent is not told how this list differs from get_number_catalog or get_number_rules, which is the primary routing decision for this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the 'self-hosted media/calling' scope, which is useful domain context, but does not mention pagination, filtering, or return format.

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

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

A single, efficient sentence with the verb and scope front-loaded. Nothing is wasted, though it is minimal.

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

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

For a simple read-only list tool with annotations covering safety, the description is adequate but thin: it omits any hint of pagination, result shape, or the meaning of the two scope 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 coverage is 50%; organization_id is documented in the schema but project_id is not. The description adds no parameter guidance at all. Baseline 3 applies given partial schema coverage and the tool having zero required 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?

The description states a specific verb (List) and resource (customer phone servers), scoping it to self-hosted media/calling. It is distinguishable from create_phone_server and test_phone_server by verb, though it doesn't explicitly name those 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?

Usage is implied by the 'List' verb and the 'customer phone servers' scope, but there is no explicit when-to-use guidance or exclusion criteria relative to siblings like test_phone_server.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' is redundant repetition with no added credit. The description does add one genuinely useful behavioral fact not in structured data: results include the health of each suite's latest run. Pagination behavior for limit/cursor is unaddressed.

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

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

Two tight sentences, front-loaded with the resource and scope; nothing is buried. Minor waste in the trailing 'Read-only' already covered by 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?

No output schema exists, so the description carries the return-value burden and does partially address it (health of latest run). However, for a paged list tool with limit/cursor parameters, the absence of any pagination or result-shape detail leaves a real gap. Safety semantics are covered by annotations.

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

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

Schema description coverage is only 25% (just organization_id). The description implies agent scoping via 'an AI agent's simulation suites', but says nothing about the limit/cursor pagination controls or the organization_id default-and-must-match constraint that the schema alone covers. With low coverage the description should compensate more than it does.

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

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

Specific verb (List) plus resource (simulation suites) plus scope (an AI agent's) plus the value-added 'health of each one's latest run'. It clearly distinguishes itself from the singular sibling get_simulation_suite and from start/cancel_simulation_run without needing 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?

No when-to-use vs. alternatives guidance. It never names get_simulation_suite for a single suite or explains when an agent should list suites vs. inspect a specific run. Usage must be inferred from the name alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=false. The description adds genuinely useful behavioral context beyond those annotations: it explains that the pause is temporary and prevents new attempts until resumption, which helps an agent understand the mutation's scope and reversibility.

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

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

A single front-loaded sentence with no wasted words. The core action and its effect are stated immediately and efficiently.

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

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

For a simple mutation tool with annotations covering the safety profile and no output schema, the description is minimally adequate. It omits parameter guidance and does not route the agent among close siblings like cancel_campaign and resume_campaign, which leaves meaningful gaps.

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

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

The description provides no information about either parameter. With schema description coverage at only 50%, campaign_id is undocumented in both the schema and the description, and the description does nothing to compensate for that gap.

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

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

States a specific verb+resource ('Pause a running campaign') and clarifies the effect ('no new attempts are placed until it is resumed'), which implicitly distinguishes it from permanent alternatives like cancel_campaign. However, it does not explicitly name siblings such as resume_campaign or cancel_campaign, so the routing value is slightly below the top band.

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

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

The phrase 'a running campaign' implies a precondition, and 'until it is resumed' signals that the action is temporary. But there is no explicit when-to-use guidance, no exclusions, and no pointer to alternatives like cancel_campaign or resume_campaign.

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 read-only/idempotent/non-destructive profile, but the description adds substantial behavior beyond them: exactly which values come back, that nothing is created, queued, or budget-reserved, and that the estimate is an upper bound over the whole suite rather than a precise figure. That cost-model nuance is real context an agent could not 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?

Three sentences, front-loaded with the returned values, then scope semantics, then the safety statement. Every clause earns its place and there is no restatement of the name or 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?

There is no output schema, so the description carries the burden of describing returns and it does so explicitly. For a simple three-parameter read-only tool it covers purpose, scope, side-effect profile, and return shape, leaving nothing an agent needs in order 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 only 33%; organization_id is documented but agent_id and suite_id are bare with no format, default, or scoping semantics supplied by the description. Worse, the only parameter-like name it mentions (scenario_ids) is not a parameter of this tool at all, so it does not compensate for the coverage gap and may send the agent looking for a non-existent field.

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

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

States a specific verb (preview) and resource (a simulation run) and enumerates the concrete outputs: attempt counts, estimated spend, model-call ceiling, and supported_runners. It also implicitly separates itself from start_simulation_run by emphasizing that no run is created, so an agent can distinguish it from the write 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?

Gives clear context for when this is the right call (a pre-flight cost/feasibility check) and explains the whole-suite upper-bound semantics versus a scenario_ids-confined run. It never names start_simulation_run as the alternative or states an explicit 'do not use when', so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description goes well beyond them: it discloses that a managed provider may be contacted, that BYOK validation occurs, that preview-rate and voice-availability state can be written, that credentials have no platform fallback, and that audio is bounded in-memory WAV. That is exactly the extra context needed for a non-idempotent, destructive, open-world call.

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

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

Three tight sentences with zero filler, and the most decision-relevant facts (bounded/rate-limited preview, state writes, not read-only or free) are front-loaded before the size limits. Slightly dense but every clause carries weight.

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

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

For an 11-parameter, nested-object tool with no output schema, the description covers side effects, credential behavior, and the return shape (bounded in-memory WAV) well. Remaining gaps are modest: rate-limit magnitudes, failure/fallback behavior, and the interaction between the required provider/model combo and the optional credential_id.

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

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

Schema coverage is 55%, so the schema already documents several optional params (credential_id, organization_id, delivery, agent_id, audio_environment). The description restates the 200-character text bound and adds the return format, but says nothing new about the five required params or how delivery/language interact, so it neither compensates for the coverage gap nor adds much beyond the schema.

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

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

The first sentence names a specific verb and resource ('Render ... TTS preview'), qualifies it with real scope modifiers (bounded, rate-limited, provider-backed, authenticated workspace), and no sibling tool overlaps it. An agent can distinguish this from get_agent_voice_stack or preview_simulation_run 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?

It conveys real usage context ('validate BYOK', 'exact pinned managed voice retry' via agent_id) and warns that this is not a free/read-only probe, which implicitly tells the agent when not to call it casually. But it never names an alternative tool or states the precondition under which this preview should be preferred over set_agent_voice_stack or test_phone_server, leaving routing 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 idempotentHint=true; the description adds genuinely new context: it is a paid operation ($0.02/1,000 words, $0.01 minimum), it only applies to an 'eligible new call', and already-ready or matching-language text is free. It leaves 'eligible' undefined and does not say whether the charge is immediate or what the call returns.

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 compact, front-loaded sentences that lead with the action and then layer the cost model efficiently. Slightly dense pricing phrasing ('per target') costs it the top mark, but nothing is wasted.

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

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

For a simple two-parameter mutation with annotations covering the safety profile, the description is adequate on cost and eligibility but omits what the call returns or whether translation is synchronous or queued. With no output schema, that gap is noticeable though not severe.

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

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

Schema description coverage is 0%, so the description carries the burden for both parameters, yet it never explains call_id or the expected format of target_language (e.g., BCP-47 code). Only the oblique phrase 'per target' and 'matching-language text' hint at target_language semantics, which is insufficient compensation.

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 ('request paid stored-text translation for an eligible new call') and clarifies the key nuance that it works even when automatic translation is off. It does not name the read counterpart (get_call_translations) or the message-level sibling (request_message_translation), so sibling differentiation is only partial.

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 condition for use ('even with automatic translation off') and hints that existing ready results should be checked first because they cost nothing. It stops short of explicitly naming alternatives such as get_call_translations or request_message_translation, so the routing guidance is implied rather than enumerated.

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 mutating, non-idempotent, destructive write, so the bar is lower. The description adds real behavioral value beyond that: refusal semantics ('a missing choice, an empty list or an unrecognized code is refused and nothing is stored') and the KYB-gated auto-approval vs. review routing. It does not say whether an existing policy is overwritten, which matters given destructiveHint=true.

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

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

Three tight sentences, front-loaded with the mandatory destination choice before the approval-flow detail. Dense but every clause carries information; the ISO code enumeration is the only slightly heavy phrase.

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 six parameters, one required, no output schema, and 50% schema coverage, the definition covers the destination/refusal path well but leaves the required profiles parameter and the channels/policy_version semantics unaddressed. An agent could invoke it correctly on the destination axis but not confidently on the payload axis.

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

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

Schema coverage is 50%: countries and all_countries are thoroughly described in the schema (largely duplicating the description), but channels, policy_version, and — critically — the REQUIRED profiles parameter are undocumented in both places. The description only gestures at these ('capabilities profiles/channels/destinations') without explaining what values profiles accepts. Baseline 3 fits given the partial coverage.

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

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

The description states specific verbs and resources ('Select capabilities profiles/channels/destinations and accept the outbound policy'), which clearly separates this write operation from the read-only sibling get_capabilities. It stops short of naming that sibling explicitly or otherwise differentiating itself from evaluate_outbound_policy or authorize_outbound.

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 establishes the conditions under which the call succeeds (destination choice required; auto-approve within default caps once KYB is approved, otherwise review), which is useful conditional context. However, it never says when to reach for this tool versus get_capabilities, evaluate_outbound_policy, or authorize_outbound, so the agent must infer the 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 flag readOnly=false, destructive=true, idempotent=true and openWorld=true, so the safety profile is covered. The description goes further by disclosing the monetary cost ($0.02 per 1,000 words, $0.01 minimum) and the free cached-read behavior, which is exactly the consequence an agent needs before calling a destructive, billed 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?

Three short sentences, front-loaded with the action and followed by cost and caching facts; each sentence earns its place. Slightly abrupt with no closing note on behavior after invocation.

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, no-output-schema tool with only hint-level annotations, the description covers cost and caching well but leaves 'eligible' undefined, gives no parameter guidance, and does not indicate what the caller receives or what happens on an ineligible/invalid request.

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

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

Schema description coverage is 0% for both required parameters, so the description carries the full burden, yet it says nothing about message_id format or what target_language accepts (locale code? language name?). The only hint is the bare word 'target' in the pricing sentence.

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

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

Specific verb (request) plus resource (paid stored-text translation) and scope (an eligible new SMS), which separates it from the read-only get_message_translations sibling. It never names that sibling explicitly, so the differentiation is inferable rather than stated.

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

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

'Explicitly request paid ... translation for an eligible new SMS' combined with 'Cached reads never charge' implies the tool is for triggering new translations rather than fetching existing ones, but the when-not condition and the meaning of 'eligible' are never 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 destructiveHint=true and idempotentHint=false, but the description adds real context beyond them: this creates a *request* record, not a live number, and provider ordering/assignment requires operator approval. That materially changes agent expectations about the effect of a 'destructive' call. It stops short of explaining permissions, rate limits, or what the returned request looks like.

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

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

A single efficient sentence with the core action front-loaded and the caveat trailing. It is appropriately sized, though the phrase 'managed phone-number request' is somewhat jargon-dependent for an unfamiliar agent.

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

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

For a 10-parameter, non-idempotent, destructive creation tool with 10% schema coverage and no output schema, the description is thin. It does not explain parameter expectations or how to follow up on the request (e.g., checking status or listing numbers), leaving substantial gaps an agent must guess at.

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

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

Schema description coverage is only 10% across 10 parameters, so the description carries the burden — and it provides zero parameter guidance (no mention of country, project_id, number_type, capabilities, or the org-scoping rule encoded only in organization_id). Adding only a high-level noun phrase leaves most parameters semantically opaque.

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

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

The description gives a specific verb+resource: 'Create a managed phone-number request.' An agent can distinguish this from read-oriented siblings like get_number_catalog or list_numbers, since it clearly creates a request entity. However, it does not differentiate itself from adjacent siblings such as check_number_requirements or get_coverage, which also sit in the number-provisioning space.

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

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

There is no explicit when-to-use guidance and no named alternatives. The clause about operator approval describes a downstream process, not when an agent should choose this tool over check_number_requirements or get_number_catalog. Usage must be inferred entirely.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known. The description adds nothing beyond the name: it doesn't say what resuming actually triggers (outbound dialing resuming, which contacts get called, whether it can be undone) or that repeated calls are not idempotent.

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

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

A single short sentence with zero waste and the action front-loaded. It is appropriately sized for what it contains, though the extreme brevity reflects under-specification rather than disciplined conciseness.

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?

This is a state-changing, non-idempotent operation with no output schema and one undocumented parameter, so the description carries real explanatory burden. It omits the required campaign state, side effects of resuming, and error conditions (e.g., resuming an already-running campaign), leaving the agent under-informed.

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

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

Schema description coverage is only 50%. The organization_id parameter is well documented in the schema, but campaign_id has no description anywhere, and the description text supplies no parameter meaning at all. With half the parameters undocumented, the description fails to compensate for the coverage gap.

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

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

States a specific verb (resume) and resource (campaign) with the precondition implied by 'paused'. It is clear, but it does not differentiate itself from the very similar launch_campaign sibling, which an agent must choose between when a campaign is not already paused.

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 'paused campaign' implies a precondition, but there is no explicit when-to-use guidance and no mention of launch_campaign or pause_campaign as alternatives. The agent must infer which sibling applies from names alone.

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