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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), and the description adds genuinely useful behavior beyond them: the 10,000-row per-call batch limit and the fact that duplicates within the list are skipped. It still omits what happens on failure or partial success, but that is a modest gap against 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?

Two short sentences, zero filler, with the core action and its most important constraint (the batch cap) front-loaded. 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 non-destructive mutation with annotations and no output schema, the description covers the action, the size limit, and dedup behavior. However, with 33% schema coverage and an undocumented nested contacts object, an agent still lacks enough detail to construct valid payloads 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 only 33% and only organization_id carries a description. The description states the 10,000 cap, which merely restates the schema's maxItems, and says nothing about the contacts item shape (which is an undocumented bare object) or the contact_list_id semantics. It does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Append rows to an existing contact list'), and the word 'existing' distinguishes it from the sibling create_contact_list. An agent can tell at a glance that this adds to a 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?

The phrase 'existing contact list' implies the list must already exist, which is useful context, but there is no explicit when-to-use guidance, no conditions or prerequisites, and no routing to siblings such as create_contact_list or list_contacts. Usage is only implied.

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

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing the exact gate sequence (workspace capabilities, then per-call policy, then Number rules when from_number_id is set), the always-on high-risk-country hard block, and the negative guarantees: no reserve, charge, or review row is written. The explicit 'not checked' list (allowed_agents, concurrency, wallet reserve) is exactly the kind of scope boundary an agent needs to avoid over-trusting a positive result.

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

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

Front-loads the purpose and verdict in the first sentence, then layers gate order and exclusions, so the most decision-relevant content comes first. The middle sentences are dense and parenthetical-heavy, and the dangling 'stage outbound_number_rules' fragment reads awkwardly, but little of the content is genuinely redundant.

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

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

For a 15-parameter tool with no output schema, the description does well on the gate model and read-only guarantees, but it leaves the return shape underspecified beyond the three verdicts and the meaning of `stage` — no indication of what reason/detail fields accompany a block. The missing routing guidance relative to evaluate_outbound_policy is also a real gap given that sibling exists.

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

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

With only 33% schema description coverage across 15 parameters, the description carries real weight: it explains that from_number_id triggers the Number's own rules stage and that channel selects the voice-vs-SMS gate path, plus what `stage` means in the result. It still says nothing about to, phone_number, categories, campaign_id, amount_minor, relationship, or user_requested, so several parameters 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?

States a specific verb (preflight) and resource (call/SMS against pre-dial gates) and names the concrete decision space (allowed|blocked|needs_review), which distinguishes it from create_outbound_call by making clear it answers rather than performs. An agent can tell what it returns without opening the schema.

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

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

Explicitly frames this as a check to run 'before placing' the call and ties it to create_outbound_call's questions in order, which gives clear when-to-use context. It also scopes itself with 'Not a full admission' and lists what is not checked, but it never mentions the closely related siblings evaluate_outbound_policy or check_number_requirements, leaving the agent to guess which preflight tool to pick.

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 state readOnly=false, destructive=false, idempotent=false, so the safety profile is partly covered. The description adds real behavioral context: canceling does not touch carrier settings, purchase numbers, or place calls, and verification depends on linked call evidence. It still does not say what state the setup or attempt ends in.

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

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

It is short, but the lead sentence is vague filler ('canonical service') and the actual verb is buried. The scope disclaimer and the call-evidence sentence are useful, yet the whole thing could be recast to put cancellation first.

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 mutating tool with no output schema and zero parameter documentation, so the description must do heavy lifting. It omits the resulting state after cancellation, whether the test can be restarted, and any prerequisites, leaving an agent without 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% across three parameters, so the description carries the full burden and mostly fails it: setup_id, attempt_id, and project_id are never explained. Only the phrase 'linked call evidence' faintly hints at what attempt_id refers to, which is not enough.

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 says the tool will "Manage an existing-number forwarding setup," which is broader and vaguer than the name/title 'Cancel forwarding test' and never states the cancel action. An agent reading only the description would not know this tool stops a forwarding test, nor how it differs from start_forwarding_test or get_forwarding_test.

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

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

No indication of when to use this versus start_forwarding_test, get_forwarding_test, or update_forwarding_setup. The negative scope ("No carrier settings change, number purchase or phone call occurs") is a useful exclusion but is not usage routing.

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

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

Annotations already declare destructiveHint=true, 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 establish readOnly, idempotent and non-destructive behavior, so the bar is lower. The description nonetheless adds a genuine behavioral nuance beyond the annotations: this check does not reserve the deletion and results can be stale, since delete_agent performs an atomic re-check. It omits what the returned dependency data looks like, which matters given there is no output schema.

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

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

Two short sentences, with the core action front-loaded and the non-reservation caveat immediately following. No filler and nothing that could be trimmed without losing meaning.

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

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

For a single-parameter read-only check with no output schema, the description covers the essential call-correctness concerns: purpose and the non-atomic/racy nature of the result. The main gap is that it does not indicate the shape or meaning of the returned dependencies (e.g. whether it lists agents, campaigns, or contacts), which an agent would need to interpret the result.

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, agent_id, with 0% schema description coverage, so the schema adds no meaning. The description never mentions the parameter; it is only inferable from the tool's subject matter. Adequate but no added semantic value.

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

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

States a specific verb and resource ('Read the current dependencies preventing deletion'), which an agent can immediately map to a pre-deletion inspection step. It explicitly names the sibling it complements (delete_agent), making the distinction between the two operations unambiguous.

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

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

The description defines the usage context clearly: run this to see what blocks deletion, and note that it is non-binding because delete_agent re-checks atomically. It does not spell out an explicit 'when not to call this' case (e.g. that calling it is optional since delete_agent performs its own check), 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 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=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds that this bundles a webhook URL and an audio stream URL, but doesn't disclose the shortcut's preset defaults or what happens if required URLs are unreachable. Given annotations, a 3 is appropriate.

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

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

A single tight sentence with the core concept front-loaded. No wasted words, though brevity here comes at the cost of the missing detail 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?

This is a mutation that creates an agent, with no output schema and thin parameter documentation. The description should explain the shortcut's implied defaults, what gets created, and the required URLs' roles; instead it leaves most of that to 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?

Schema coverage is only 33% across 6 parameters with a nested call_summary object. The description only gestures at two of them (webhook_url, audio_stream_url) without format or semantics, and says nothing about name, project_id, or the optional organization_id default. It does not compensate for the low schema coverage.

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

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

States a specific action (create) and a specific resource variant (external_audio agent) plus the distinguishing payload (webhook and audio stream URLs). It's clear what the tool builds, though it never explicitly contrasts itself with the sibling create_agent, leaving the relationship to be inferred.

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?

Calling itself a 'shortcut' hints that it is an alternative to create_agent, but there is no explicit when-to-use / when-not-to-use guidance or statement of which defaults the shortcut applies. An agent must guess whether to route here or through create_agent.

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

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

Annotations already declare non-read-only, non-idempotent, closed-world, and the description adds genuinely non-derivable behavior: language fields are rejected with a 400 naming the field when the engine has has_language_axis false, and locale overrides stay draft until an explicit publish step. It does not state what the response contains (e.g., the new agent's id) or whether creation is atomic across the nested objects.

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 purpose, and no filler. However, terms like 'first-class', 'shared stack', and 'explicit voice-stack publish command' are used without definition and add density without clarity.

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 17-parameter creation tool with nested objects and no output schema, the description is thin: it never says what is returned, what defaults apply, or how the many optional fields interact. It covers the highest-risk validation rule well, which keeps it at minimum-viable rather than inadequate.

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 18% across 17 parameters, so the description must compensate and largely does not: model, voice, transcriber, webhook_url, begin_message, first_message, system_prompt, audio_stream_url and the required project_id/name are never explained. It does add real cross-parameter semantics for languages and language_profiles via the engine capability gate and the draft/publish lifecycle, but that covers a small fraction of the surface.

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 Skysay agent) and enumerates the three mutually exclusive modes, so the agent knows exactly what the call produces. It does not distinguish itself from siblings that also create agents (connect_external_agent, duplicate_agent) or from update_agent.

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

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

Usage is implied through the mode enumeration and the note that hosted mode is the one that accepts stacks and languages, but there is no explicit statement of when to choose this tool over connect_external_agent or duplicate_agent. The mention that locale overrides need a later publish command is a useful sequencing hint but is phrased as a fact rather than 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 non-read-only, non-destructive, non-idempotent, so the safety profile is covered; the description adds genuinely new behavioral context by establishing that creation yields an inert draft and that outbound activity requires a separate launch. It does not disclose validation behavior, whether creation can fail on number/consent mismatches, or permission requirements, which keeps it from 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?

The purpose and the critical launch caveat are front-loaded, and the whole definition is two sentences with no filler. The middle sentence is a long comma-run list that is dense to parse but each element carries information.

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

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

For a 7-required-parameter mutation with nested objects, 22% schema coverage and no output schema, the description covers the conceptual surface but leaves real gaps: it never says what is returned (presumably a campaign id needed for launch_campaign) or how concurrency/reserved_concurrency and time_zone_mode interact. Adequate to attempt a call, not complete enough to call confidently without opening the schema.

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

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

With only 22% schema coverage across 18 parameters and nested objects, the description usefully names the major configuration groups and spells out the consent_basis values and the three retry_policy presets. However, it says nothing about the distinction between max_concurrency and reserved_concurrency, time_zone_mode, language, ends_at, organization_id scoping, or the shape of retry_policy — leaving several parameters 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 opens with a specific verb+resource+state ('Create a draft outbound campaign') and then enumerates exactly what the draft configures: agent, caller-id numbers, contact list, purpose, consent basis, calling windows, retry policy, concurrency, schedule. This is clearly distinct from launch_campaign, update_campaign, and get_campaign in the sibling set.

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

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

It explicitly states the lifecycle boundary: the campaign does not run until 'launched with launch_campaign,' which routes the agent to the correct follow-up tool. It gives no guidance on when to prefer update_campaign for an existing campaign or on prerequisite policy checks (evaluate_outbound_policy / authorize_outbound), so it stops short of full alternative coverage.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: a partial-failure model where invalid rows are reported in a per-row import report and 'never fail the list.' It omits auth/permission requirements, but the partial-import contract is the most valuable fact here.

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, no filler, with the core action and the optional payload front-loaded and the return/error behavior trailing. Efficient, though the parenthetical field list is dense filler that the schema already carries.

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

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

For a 5-parameter creation tool with no output schema, the description covers what an agent most needs: it creates a list, rows are optional, and the return is a per-row import report. Gaps remain around duplicate/already-existing list behavior, project_id meaning, and list-size limits, but the essential calling contract is present.

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

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

Schema description coverage is only 20%, so the description must carry weight. It enumerates the contact fields (phone_e164, name, first_name, language, time_zone, external_reference, variables), which largely restates the nested schema, and it omits consent_basis, the source enum, the 10,000-row cap and the 28-variable limit. It adds some mapping value but does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Create a contact list in the workspace') plus the optional payload ('optionally with rows'), so the agent knows exactly what is produced. It does not, however, distinguish itself from the sibling add_contacts, which an agent could easily confuse with row insertion.

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 phrase 'optionally with rows' hints that this tool can create an empty list that contacts are later added to, but the description never states when to pick this over add_contacts or when a list already exists. No exclusions or alternatives are 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=false, destructiveHint=false, openWorldHint=false, so the safety profile is partially covered. The description genuinely adds beyond them by stating what does NOT happen (no carrier settings change, no number purchase, no phone call), which is useful scope-limiting context for a write tool. It still omits permissions/auth needs, what is actually created, and the multi-step workflow implied by the `step` enum.

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

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

Three short sentences with no filler, and the negative-scope statement is placed early. The wording is tight, though the leading "Manage" verb creates ambiguity rather than earning 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 10-parameter mutation tool with no output schema and only 30% schema coverage, the description leaves major gaps: the step-based workflow, the required idempotency key, what the call returns, and whether the setup must be completed across multiple invocations. What is present is accurate but far from sufficient.

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

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

Only 30% of the 10 parameters carry schema descriptions, so the description is expected to compensate and it does not — no parameter is mentioned by name. Critical semantics such as the required `idempotency_key`, the `step` lifecycle, and the relationship between `source_number`, `number_id`, and `project_id` are left entirely to the sparse 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?

"Manage an existing-number forwarding setup" identifies the resource (existing-number forwarding) and scopes it away from carrier/number-purchase actions, but the verb "Manage" conflicts with the tool name "create" and with the existence of a sibling `update_forwarding_setup`. An agent cannot tell from the description whether this creates a new setup or mutates an existing 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?

There is no when-to-use guidance, no routing to `update_forwarding_setup`, `get_forwarding_setup`, `start_forwarding_test`, or `record_forwarding_instructions`, and no explanation of when the `step` values (setup/line/connect/test/manage) should be used. The only conditional hint is "Test verification requires linked call evidence," which is too fragmentary to guide invocation.

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, open-world, and non-idempotent behavior, so the description is credited for adding semantics beyond that: fields are 'recorded, never enforced,' no approval gate exists, and destination country is checked against workspace capabilities. It still omits practical consequences such as whether the call is actually dialed immediately or cost/quota implications.

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

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

The description is a single front-loaded paragraph that leads with the action and then layers scoping facts. It is dense but every clause carries information; the parenthetical pointer to the purpose property is slightly redundant given the schema already holds the catalog.

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 destructive mutation with nested runtime_config and no output schema, the description leaves too much unexplained – most parameters, the distinction from trial calls, and what the returned call object will contain. The behavioral notes it does include are useful, but they don't cover the tool's full complexity.

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% across 15 parameters, so the description must compensate and largely does not. It clarifies purpose, user_authorization, and recipient_type (and the purpose catalog actually lives in the schema, not here), but says nothing about to, policy, agent_id, categories, campaign_id, relationship, runtime_config, user_requested, organization_id, or agent_endpoint_id.

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

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

The description opens with a specific verb and resource ('Create an outbound call request') and adds scope ('A workspace that holds a number calls out'), which separates it from read/lookup siblings. It does not explicitly name adjacent siblings like create_trial_call, authorize_outbound, or evaluate_outbound_policy, though the 'no approval step' line implicitly distances it from the authorization tools.

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

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

Usage is only implied: 'no approval step' hints that authorization isn't required first, and the country-capability line hints at a prerequisite check. There is no explicit statement of when to choose this over create_trial_call, authorize_outbound, or evaluate_outbound_policy, so the agent must infer 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds a genuinely non-obvious behavioral fact beyond the annotations — the password is returned only once and is unrecoverable afterward — which is exactly the kind of disclosure that prevents agent misuse. It omits any note that repeat calls create duplicate keys.

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 effect of the call front-loaded before the storage warning. 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 lack of an output schema is mostly compensated by explaining the one-time password return. But with no annotations covering inputs and 0% schema coverage on two required parameters, the description leaves the agent_id semantics and duplicate-creation behavior 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 description coverage is 0%, so the description carries the full burden, yet it only hints at `name` ('named PBX key') and says nothing at all about `agent_id` — the more consequential parameter, whose accepted format and scope are entirely undocumented.

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

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

States a specific verb and resource (create a PBX key) plus a meaningful qualifier, 'independently revocable named'. It is distinguishable from sibling list_pbx_keys/revoke_pbx_key/rotate_pbx_key, though the description never explicitly names those alternatives.

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 'independently revocable' implicitly hints at when to use this versus rotate_pbx_key or revoke_pbx_key, but there is no explicit when-to-use, when-not, or prerequisite guidance (e.g. that agent_id must reference an existing agent).

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, idempotentHint=false and destructiveHint=false, so the agent knows this is a non-idempotent write that won't destroy data. The description adds meaningful context by pointing to the dry-run verification tool, but says nothing about permissions, side effects of provisioning a server, or failure modes — gaps that matter for a multi-param mutation.

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

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

Two short sentences with zero filler, and the core action is stated first with the verification hint following. Every clause carries information.

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

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

For a 7-parameter, non-idempotent creation tool with no output schema and near-zero schema descriptions, the description does far too little — it never explains required configuration, what a created server looks like, or how failures surface. The only compensating element is the dry-run pointer, which is not enough.

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%: of seven parameters, only organization_id carries a description, and the description text explains none of them. Critical fields like server_address (required), port, transport, and allowed_sip_ips are left entirely for the agent to infer, which is a real gap for a provisioning tool.

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

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

States a specific verb and resource ('Create a customer phone server') with a scoping qualifier ('for self-hosted media/calling') that tells the agent this provisions infrastructure, not a call or campaign. It also names the related sibling test_phone_server, though it doesn't distinguish itself from the many other create_* tools beyond 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 clause 'test_phone_server dry-run verifies it' implies a recommended workflow of validating before creating, which is useful. However, there is no explicit statement of when to use this tool versus alternatives, no prerequisites (e.g. required project or org context), and no when-not-to-use guidance.

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

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

Annotations only declare the mutation profile (readOnly false, destructive false, idempotent false, openWorld false); the description goes beyond that by explaining runner behavior (deterministic/adaptive_chat run offline, adaptive_voice requires the voice runtime), admission conditions, and a semantic distinction for caller_environment versus agent ambience. This is meaningful context a caller would not get from the annotations alone.

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

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

The core purpose is front-loaded in the first clause, and the remaining sentences each add distinct operational detail (runner admission, caller_environment semantics). Dense but every sentence earns its place, with no filler.

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

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

For a mutating tool with 7 parameters, nested objects, and no output schema, the description covers the scenario/runner and caller_environment territory well but omits guidance on other top-level inputs such as policy, default_snapshot_source, organization_id, and what the call returns. It is adequate but leaves 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 low (29%), so the description must carry weight. It adds valuable semantics for the `scenarios` array (runner, language requirements for adaptive_voice) and for caller_environment/noise_level, but leaves several top-level parameters (name, policy, description, organization_id, default_snapshot_source) unexplained, so compensation is only partial.

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 (create) and resource (simulation suite) scoped to an AI agent, and clarifies the distinctive behavior that a whole scenario list can be submitted in one call, i.e. 'this is how a scenario pack becomes a suite.' It does not explicitly name the sibling read tools (get_simulation_suite, list_simulation_suites), but the create semantics are unambiguous.

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

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

Usage is implied via 'this is how a scenario pack becomes a suite' and the runner admission rules, which tell the caller when a given runner is valid. However, it never explicitly states when to choose this tool over alternatives like preview_simulation_run or start_simulation_run, 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 declare it is a non-readOnly, non-destructive, non-openWorld operation. The description adds meaningful context beyond those hints: no actual phone call is placed, the operation is synthetic/offline, and the live trial path is retired, which helps set expectations about side effects.

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 the most important constraint (synthetic_only must be true). Every clause earns its place and there is no filler.

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

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

For a mutation tool with six parameters, low schema description coverage, and no output schema, the description does not provide enough parameter guidance or alternative-tool routing. It explains what the tool does well, but an agent still lacks the detail needed to confidently populate the non-obvious optional 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 17%, so the description should compensate for undocumented parameters, but it only mentions synthetic_only (already enforced as a const in the schema) and says nothing about pin, agent_id, project_id, or agent_endpoint_id. It leaves most parameter meaning to inference.

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

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

States a specific verb (Create) and a tightly scoped resource (offline synthetic trial call fixture), and immediately distinguishes itself from live call creation by noting it places no phone call and that live shared-number PIN trials are retired. An agent can tell this apart from create_outbound_call 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 use: synthetic_only must be true, the fixture is offline, and it places no phone call. It also implicitly excludes live PIN trial usage by saying those are retired, but it does not explicitly name alternatives such as create_outbound_call or simulation tools.

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

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

Annotations already flag destructive=true and idempotent=true, so the safety profile is partly covered, but the description adds substantial non-obvious context: never request card numbers/CVC/passwords/OTPs, pending checkout is not credit, only the signed Stripe webhook credits funds, retry with the same key, and native card support is host-dependent. It does not contradict any 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?

The purpose is front-loaded and most sentences carry behavioral or security value, but the text is dense and repetitive: the 'not native UI/MCP elicitation' point is made twice, and several statements restate schema descriptions. Tighter editing would preserve the content in fewer sentences.

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

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

There is no output schema, so the description must carry return semantics, and it does: card_checkout returns a Stripe hosted-checkout URL, request_challenge returns approval metadata, and the 402 payload carries amount/currency/seller profile. For a payment mutation with annotations, nothing essential is missing.

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

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

With 86% schema coverage the baseline is 3, but the description goes beyond the per-field schema text by explaining cross-parameter workflow: when payment_approved is legitimate, when to omit shared_payment_token and use request_challenge, and that request_challenge returns 402 metadata rather than elicitation. This adds genuine inter-parameter meaning.

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

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

The opening sentence states a specific verb and resource ('Request purchased Skysay calling credit for the authenticated workspace') and the title reinforces it. No sibling tool covers wallet top-ups, so there is no ambiguity to resolve, and the description names account_overview as the prerequisite read.

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 says to read the wallet currency via account_overview first, that owner approval of the exact amount/currency/purpose must precede payment_approved, and that OAuth scope consent is not purchase approval. It also distinguishes the two methods (card_checkout vs shared_payment_token) with the conditions for each.

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?

While annotations mark the operation as destructive, the description adds significant behavioral depth by detailing the side effects: it retains historical calls, transcripts, and billing, and explicitly avoids canceling numbers or modifying sibling agents. This provides essential context beyond the structured hints.

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

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

The text is highly efficient. It front-loads the primary function and quickly follows up with critical context (what is retained, what is excluded), ensuring no sentence is unnecessary.

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

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

Given the single-parameter input and the destructive nature of the task, the description is complete. It covers the scope of deletion, necessary user interaction, and the resulting state of the surrounding system components.

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

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

The schema coverage is 0%, meaning the description must compensate for the input parameter definition. However, the description does not provide any semantic meaning or constraints for the required 'agent_id' parameter, so it stays at the minimum viable score.

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

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

The description clearly and specifically states the tool's purpose: 'Permanently remove one unused AI agent.' It also defines the boundaries of the operation by stating what it does not affect, helping distinguish it from other agent management 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?

The description provides crucial usage guidance by setting preconditions and workflow constraints. It specifies that the agent must be 'unused,' and explicitly instructs the agent to 'Ask the user to confirm before calling,' preventing accidental destructive action.

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

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

Annotations already declare destructiveHint=true, but the description adds substantive context beyond them: what is removed (campaign leaves listings) versus retained (calls, recordings, transcripts, billing records), the 409 conflict, and the 404 on retry. This is exactly the retention-vs-destruction detail an agent needs before a destructive call.

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

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

Three compact sentences, front-loaded with the eligible states, then side effects, then error semantics and the confirmation prompt. No redundant restatement of the title or annotations.

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

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

No output schema exists, yet the description covers side effects, retention, failure modes (409/404), and the human-in-the-loop requirement. For a two-parameter destructive tool this leaves nothing material unspecified.

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 carries no description. The description implies campaign_id is the identifier of a deletable campaign but adds no format or lookup guidance, so it neither compensates for nor worsens the gap.

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

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

States a specific verb (delete) and resource (campaign), and goes further by enumerating the eligible statuses (draft, held, blocked, completed, cancelled). An agent can distinguish this from cancel_campaign because the description explicitly routes active campaigns there.

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 exact precondition for use (campaign must be in a deletable state), names the alternative path (cancel first for launching/scheduled/running/paused), states the error on violation (409 campaign_active), and prescribes asking the user to confirm. Near-complete 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?

The destructive annotation is already present, and the description adds important context: deletion is permanent, it requires the current revision, and suites with run history must not use this path. This adds real behavioral substance beyond the structured 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 short sentences, each carrying necessary information, with the destructive precondition and alternative path front-loaded. 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?

For a destructive tool with no output schema, the description covers the key preconditions and the alternative path well. It does not mention the optional organization_id behavior, but the schema already documents that parameter.

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

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

Schema description coverage is low at 25%, and the description only clarifies that the revision must be current. It does not explain agent_id or suite_id, though those are fairly self-evident from the resource and required fields.

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

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

The description states a specific verb and resource: permanently delete a simulation suite. It also scopes the action to suites that have never had a run, distinguishing it from archival or general suite operations.

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 an explicit when-to-use condition (suite has never had a run) and a when-not-to-use condition (suites with run history must be archived through the suite API instead). This is exactly the routing guidance an agent needs.

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

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

Annotations already declare a non-read-only, idempotent, non-destructive mutation, so the bar is lower; the description adds meaningful context by specifying that the copy is 'stopped', omits publication/execution history, and will not expose connection secrets. This goes beyond the annotations, though it does not mention permission requirements or rate limits.

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

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

Three sentences with zero filler: purpose first, then retry guidance, then the secrets caveat. The most important information is front-loaded and each sentence earns its place.

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

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

For a mutation tool with annotations and no output schema, the description covers the operation's effect (stopped copy, no history), idempotent retry, and what is not returned. It is close to complete, with the only gap being the unexplained agent_id parameter.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It mentions request_key and name only in passing (reuse after an uncertain result) and never explains agent_id or any format, length, or constraint details, leaving most parameter 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 gives a specific verb and resource ('Create an independent stopped copy of the latest saved authoring configuration') and distinguishes it from create_agent by specifying that the copy excludes publication and execution history. An agent can tell this apart from siblings without opening the schema.

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

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

It provides a concrete retry guideline ('Reuse request_key and name after an uncertain result'), which is useful for idempotent recovery. However, it never states when to choose duplicate_agent over create_agent or update_agent, and gives no exclusions or prerequisites beyond the retry hint.

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

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

Annotations already establish readOnly/idempotent/non-destructive and closed-world, so safety is covered; the description adds real value beyond that by disclosing what is and isn't judged — purpose, recipient_type and user_authorization are merely recorded, never asserted against. This prevents an agent from treating a rejected result as a judgment on those fields. It still does not describe the shape or verdict semantics of the evaluation response, which matters for a check-only tool with no output schema.

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

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

Three tight sentences with no filler, and the most decision-relevant clause (what is checked, and that it must happen before call creation) is front-loaded. The final sentence about country reads as a deliberate scoping carve-out rather than padding, though it partially duplicates the country parameter's own 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?

With 9 parameters, a nested object, no output schema and only 44% schema coverage, the description carries substantial burden and covers the optional fields well. It leaves the `policy` object and `categories` undocumented and never indicates what the evaluation returns or what an agent should do with a failing verdict, which are material gaps for a pre-flight gate tool.

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

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

Schema coverage is 44%, so the description needs to compensate, and it does explain the optional/never-enforced semantics of purpose, recipient_type and user_authorization plus the country boundary — meaningful meaning beyond the schema. However, `policy` (a nested object) and `categories` are left entirely unexplained in both schema and description, and `to` format is only alluded to via 'destination format'.

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

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

Names a specific verb and resource (evaluate outbound voice/SMS policy) and enumerates the concrete checks performed: suspensions, caller-number registration, destination format. The temporal anchor 'before creating a call' places it in the outbound workflow, though it never names the adjacent siblings authorize_outbound or create_outbound_call, so the agent must infer the boundary itself.

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

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

Gives a clear use condition ('before creating a call') and an explicit exclusion ('destination country is governed by the org's workspace capabilities, not by this evaluation'), which prevents the agent from expecting this tool to gate country eligibility. It stops short of naming which sibling to call instead for country gating, so the alternative is only implied.

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

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

Annotations already declare readOnlyHint, 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 declare readOnly, idempotent and non-destructive behavior, so the description can spend its length elsewhere and it does: it discloses that every field is an AI estimate (not ground truth) and enumerates the status values with their skip reasons (no_conversation, insufficient_transcript). It does not say what happens on a nonexistent call_id or whether results are cached or fresh.

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 that are front-loaded with the core action, and the enumerated status values are compact rather than wasteful. The clause "read with the transcript's scope" is slightly opaque and taxes the reader a little.

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 effectively documents the return shape: summary, follow-up flag, goal-met judgment, sentiment, and the full status enum with skip reasons. With annotations already covering the safety profile, an agent has everything needed to call it correctly.

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

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

There is only one parameter, call_id, and schema coverage is 0%, so the description has to carry it. "Of a call" implies call_id identifies the call, but the description never states the expected format, where to obtain the ID, or what happens with an unknown 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?

It gives a specific verb and resource ("Get the AI summary of a call") and enumerates the returned fields, so it is clearly distinct from get_call and get_call_transcript. It never names those siblings as alternatives, though, so the differentiation must be inferred from the field list 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?

Usage is only implied: an agent can infer it should call this when it wants a condensed AI assessment instead of a raw transcript. There is no explicit "use this when…" guidance, no exclusions, and no mention of what to call for the full transcript or recording.

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 and openWorldHint=false, so the safety profile is covered. The description adds some non-obvious scope constraints (no carrier settings change, no number purchase, no phone call), which is useful, but "Test verification requires linked call evidence" is cryptic and unexplained, and no auth or return behavior is described.

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

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

Three short sentences with no filler, but they are not front-loaded around what the tool does. The final sentence about "linked call evidence" is an opaque fragment that costs space without adding usable guidance.

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

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

There is no output schema and the description does not say what "instructions" contain, which is the core thing an agent needs for a retrieval tool. With both parameters undocumented in the schema and an unexplained test-verification clause, the definition leaves key behavior unaddressed despite the tool's modest complexity.

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 setup_id and project_id, so the description carries the full burden and fails: neither parameter is mentioned. Only the phrase "existing-number forwarding setup" loosely hints at setup_id, leaving project_id entirely unexplained.

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

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

The name promises a retrieval ("get"), but the description opens with the verb "Manage," which is vague and conflicts with the read-only framing. It never says what "forwarding instructions" actually are or what the tool returns, so an agent cannot distinguish it from get_forwarding_setup, update_forwarding_setup, or record_forwarding_instructions.

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

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

There is no statement of when to call this versus the many forwarding siblings (get_forwarding_setup, update_forwarding_setup, start_forwarding_test, record_forwarding_instructions). The sentences describe what does NOT happen rather than when this tool is the right choice.

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 does add non-obvious context — no carrier settings change, no number purchase, no phone call occurs — which reassures an agent this call is side-effect free. However, "Test verification requires linked call evidence" is unexplained jargon and the description says nothing about what the response contains.

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?

At three short sentences it is not bloated, but the opening verb is misleading and the closing sentence about test verification is vague enough to be wasted space. The most useful content (no side effects) is buried in the middle rather than front-loaded.

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

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

For a single-resource read with no output schema and no documented parameters, the description should at minimum say what is returned and what setup_id refers to. Neither is present, and the "Manage" framing leaves the agent unsure whether this tool mutates or reads.

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 largely fails it. The phrase "existing-number forwarding setup" faintly implies setup_id identifies an existing setup, but project_id is never mentioned and no format, scope, or lookup semantics 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?

The verb chosen is "Manage," which does not describe retrieval and actively obscures that this is a read of a single setup. The resource is identifiable ("existing-number forwarding setup"), but nothing distinguishes it from siblings such as list_forwarding_setups, get_forwarding_test, or update_forwarding_setup.

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

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

There is no statement of when to call this versus list_forwarding_setups (all setups) or get_forwarding_test (test state), even though both are direct alternatives. The only conditional sentence ("Test verification requires linked call evidence") is a cryptic precondition 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?

The annotations already establish read-only, idempotent, non-destructive behavior. The description usefully adds that no carrier settings change, number purchase, or phone call is triggered, and notes the linked-call-evidence requirement without contradicting those annotations.

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

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

The three short sentences are economical, and the side-effect limitations are easy to scan. However, the opening uses its prime position on vague "Manage ... canonical service" wording rather than the actual retrieval operation.

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

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

For a lookup with three undocumented parameters and no output schema, the definition leaves essential gaps: what test status or verification information is retrieved, how the required IDs relate, and how linked call evidence affects the result. The safety caveats are helpful but do not make selection and invocation sufficiently 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?

With 0% schema description coverage, none of setup_id, attempt_id, or project_id is explained in the schema. The description does not compensate by mapping the IDs to a setup and test attempt, explaining where to obtain them, or clarifying how project_id scopes the lookup.

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 scopes the domain to an existing-number forwarding setup, but "Manage" does not state that this tool retrieves a specific forwarding test attempt. It therefore fails to distinguish the operation clearly from get_forwarding_setup, start_forwarding_test, or update_forwarding_setup.

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

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

There is no explicit guidance on when to use this lookup instead of start_forwarding_test, cancel_forwarding_test, or get_forwarding_setup. The linked-call-evidence statement hints at a verification prerequisite, but does not explain when to call this tool or what state the test must be in.

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.