Dialyne

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

Beyond the annotations it discloses a lot: a pre-send refusal policy for prohibited answers, the ~45 second timing window, the one-minute hold extension requiring callee consent, callback retention behavior, and the wrong_call_state failure mode. What it leaves implicit is the irreversibility implied by destructiveHint=true — that a spoken answer cannot be retracted — and there is mild tension with idempotentHint=false when it says re-sending the same answer after a callback is harmless, though that claim is scoped to the ended-call case.

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 action and the usage gate are front-loaded in the opening two sentences, and every subsequent sentence carries operational content (compliance, secrets, timing, hold, callback, error). It is dense and long for a three-parameter tool, with the compliance clause folded into the first sentence rather than separated, which slightly hurts scanability.

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

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

An output schema exists, so return values need no explanation, and the description covers the remaining risk surface: preconditions, refusal policy, sensitive-data handling, timing pressure, escalation paths, and the post-call state. An agent has everything needed to decide whether to call and how to phrase the answer.

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 already 100%, yet the description adds real semantics: the answer must be the user's actual information or decision rather than invented content, must not ask the callee for codes or card details, and can encode sensitive values as [secret: value] so transcripts mask them. It also ties question_id to pending_question.question_id from get_call, which is behaviourally more informative than the schema's 'omit to answer the question currently pending'.

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

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

The first sentence states a specific verb and resource — send the user's answer to a pending question and return confirmation of relay — and anchors it to a concrete signal ('pending_question' from get_call). This makes it immediately distinguishable from hold_call_question, transfer_call_to_user, cancel_call, and get_call.

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

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

It states the enabling condition ('Use it only when get_call shows a pending_question'), then routes to alternatives by situation: ask the human and use hold_call_question if time is short, or transfer_call_to_user if the callee wants to speak to the user. It also names the terminal follow-up ('Then continue with get_call') and clarifies the callback-after-end case where the tool still applies.

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

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

Annotations already mark it destructive, idempotent, and mutating, and the description adds substance beyond that: it is irreversible, it stops any further attempt to the number for this call, billing is limited to time already spoken, and reserved credit is released. It also reconciles with idempotentHint=true by noting that re-cancelling is a no-op rather than implying reversibility.

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

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

The core action and scope lead the description, and the when-to-use and precondition sentences are short and purposeful. The billing point is stated twice ("nothing is charged beyond the time already spoken" and again in the live-call sentence), and the "Compliance:" fragment is slightly clipped, but neither obscures 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?

An output schema exists, so return values need no prose, and the description still signals that cancelled status comes back. For a one-parameter mutation it covers irreversibility, per-state behavior (live vs. scheduled), idempotency, and billing/compliance consequences, leaving nothing an agent needs before calling it.

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

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

The single call_id parameter is fully documented in the schema (100% coverage), so the schema carries the weight. The description adds only that the identifier may refer to a scheduled or live call, which is marginal over the field description already present.

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

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

States a specific verb (cancel) and resource (a scheduled or live call), and explicitly enumerates what counts as cancellable: scheduled calls, in-progress calls, scheduled callbacks, and automatic retries. No sibling tool performs cancellation, so no disambiguation from siblings is required, and the note that the cancelled status is returned rounds out a complete picture of the operation.

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

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

Gives a positive trigger ("Use it when the user changes their mind or the task is no longer needed") as well as explicit exclusions: cancelling an already-cancelled call has no further effect, and a call that already ended cannot be cancelled. There is no sibling alternative that competes with this tool, so the missing "use X instead" clause is not 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses the two-step responsibility-acceptance flow, the error code responsibility_acceptance_required, the fact that the first attempt changes nothing, that acceptance is logged with a timestamp, hard refusals (human-impersonation, police/government/bank), and account-wide side effects with scheduled calls retaining their identity. The only minor gap is that annotation-level claims like idempotency are restated rather than expanded, but the compliance workflow is far richer than the annotations.

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

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

Front-loaded with purpose, then compliance context, then invocation mechanics, then when/when-not and side effects — a logical progression with no filler sentences. It runs long, and the compliance paragraph could be tightened, but nearly every clause carries operational information the agent needs.

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

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

For a 9-parameter mutation tool with compliance implications, the description covers read mode output (current identity, preview, warning), the acceptance handshake, refusal cases, and side-effect scope. An output schema exists, yet it still explains what the no-argument call returns, so 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 100% schema coverage the baseline is 3, but the description adds workflow meaning the schema alone does not convey: which parameters are free (name, tone) versus deviations, and the required pairing of the same changes with accept_responsibility=true plus warning_version on retry. It reinforces reset_to_recommended keeping name and tone, though it does not restate each parameter individually.

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 pair (read/change) and resource (how the voice agent introduces itself), then enumerates the exact editable facets: name, tone, opening line, 'who is calling?' answer, introduction, AI mention. It is unmistakably distinct from siblings like place_phone_call or transfer_call_to_user.

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' (rename the agent, change introduction or tone) and an explicit 'When not to use' that names the alternative: a one-off greeting belongs in place_phone_call's task. It also tells the agent how to invoke read mode (no argument).

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, and the description reinforces that with a remediation path: credit cannot be added from here, so the agent must redirect the user to the web app. That 'what to do instead' detail is genuine added value beyond the structured fields, though it doesn't cover freshness or staleness of the reported balance.

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 content is front-loaded and useful, but the text repeats itself: 'read-only' appears twice, and the 'credit cannot be added here / tell the user to add credit in the web app' instruction is stated twice in near-identical wording. Trimming the duplicate clause would tighten it without losing information.

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

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

With an output schema present, the description needn't explain return formatting, and it doesn't try to. Given zero parameters and strong annotation coverage, the definition supplies everything needed — purpose, triggers, and the follow-up action — for an agent to call it correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a no-parameter tool applies, and the description correctly spends its words on return-content scope instead of inventing argument semantics.

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

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

The description names a specific verb ('Read') and resource ('remaining call time on this account') and enumerates exactly what is returned: minutes left on prepaid credit with expiry date, plus account limits (simultaneous calls, calls per day). No sibling tool in the list queries balance, so an agent can immediately see this is not a call-control 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?

It states two concrete trigger conditions: before a long call (explicitly, one with a long hold) and after place_phone_call fails for insufficient credit. It also states the boundary action — tell the user to top up in the web app rather than trying to do it here — so the agent knows what to do next, not just when to call this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds a scope constraint beyond the annotations — results are limited to this account's own batches — which is genuinely useful for an agent reasoning about visibility. It does not add pagination, latency or staleness behavior, so not a 5.

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

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

Front-loaded with the return contents, then sequencing, then alternatives — a sensible order. Minor waste: read-only is stated twice (in the compliance line and again as a standalone 'Read-only.'), and the trailing alternative-routing sentences could be tightened. Still well under the length where it becomes costly.

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

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

An output schema exists, so return values need not be fully specified, yet the description still summarizes them usefully. For a single-parameter read tool with full annotation coverage, nothing an agent needs in order to call it correctly — sequencing, scope, alternatives — is missing.

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

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

Schema coverage is 100% and the single batch_id parameter is documented with its origin and an example format ('lot_…'), so the schema does the heavy lifting. The description mentions the batch only implicitly via its relationship to place_batch_calls and adds no format or edge-case detail (e.g. invalid or expired batch_id) beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource (get progress/results of a batch of calls) and enumerates exactly what comes back: status counts, successes, refused numbers, plus per-call call_id, status, outcome and summary. An agent can distinguish it from get_call or list_calls without opening the schema.

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

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

Gives explicit sequencing ('use it after place_batch_calls to report results to the user') and names two alternatives with the conditions that select them: get_call with response_format='detailed' for a transcript, cancel_call to stop a single call. This is exactly the when/when-not/alternative guidance the dimension rewards.

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

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

Beyond the read-only/idempotent annotations, the description discloses non-obvious behavior: automatic retry with status retry_scheduled, the exception for lines requiring a new user request, transcript retention of 90 days, text-only transcripts with no audio, and that callee_objected deletes the transcript and blocks the number.

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 when-to-use guidance is front-loaded and valuable, but the Returns paragraph enumerates status, outcome and event fields that the output schema already carries, making the definition longer than necessary without adding proportional value.

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

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

For a polling tool, the definition covers the complete loop an agent needs: how to poll, when to stop, how to consume events via last_event_id, how retries surface, and the exceptional terminal states. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so call_id, wait_seconds, after_event_id and response_format are already fully documented with ranges, defaults and examples. The description only adds light context ('optionally waiting for news', 'transcript on request') that maps loosely to wait_seconds and response_format, so baseline 3 applies.

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

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

The opening sentence names a specific verb and resource (get the status and written result of a call) and ties it to the originating tool place_phone_call, making the relationship to siblings like list_calls or place_phone_call 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?

It states concrete usage patterns: poll repeatedly until done=true to follow a call in progress, check pending_question, and read the final outcome. It also sets explicit boundaries ('it never places, changes or ends a call') and explains what to do on event callback_suggested and on callee_objected.

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 coarse profile (not read-only, not idempotent, open-world), while the description supplies the real behavior: the request is relayed through the voice agent to the callee, the extension is conditional on consent, it is allowed once per question, seconds_left grows by 60, and total wait per question is capped at 2 minutes. It also discloses the failure/branch outcomes (accepted, callee_prefers_callback, not_possible) and that a callback reschedules when the answer is delivered.

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

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

Front-loaded with the purpose, then trigger, then mechanics, then exclusions — a sensible order. It is somewhat long and repeats the relay idea ('the request is passed to the voice agent, which asks the callee' then later quoting the agent's phrasing), but almost every sentence carries operational 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?

For a two-parameter mutation with annotations and an output schema, the description covers trigger, sequencing, consent semantics, the size and limit of the extension, and the follow-up event to look for. Nothing an agent needs in order to call it correctly at the right moment is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds that call_id must reference a live call whose agent is waiting and that question_id ties the hold to a single pending_question from get_call (hence the once-per-question limit). Those constraints on valid values go slightly beyond the schema text.

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

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

The description names the specific action (extend the answer window by one minute) applied to the specific resource (the voice agent's pending question on a live call), and distinguishes it from answer_call_question and get_call by role in the workflow. An agent can tell from the first sentence alone what this does and what it does not do.

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

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

It gives a concrete trigger ('as soon as get_call shows a pending_question you cannot answer yourself'), an explicit sequence (call hold_call_question first, then ask your human, then answer_call_question), and negative cases ('not for a finished call, nor when you already know the answer — just answer'). The alternative path when the callee prefers a callback is also 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 destructiveHint=false, yet the description still adds real context: account-scoping, newest-first ordering, and the 90-day transcript retention window that limits what the transcript search can reach. It does not explain pagination behavior (no cursor/offset exists, limit caps at 50), which an agent retrieving many calls would need to know.

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

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

Front-loaded with scope, ordering and returned fields, then use cases, then the alternative — a sensible information order. It wastes some space by asserting read-only twice ("Compliance: read-only" and a trailing "Read-only."), both redundant with the 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?

An output schema exists, so the field list is supporting rather than load-bearing, and the description still covers scope, retention limits, ordering, use cases and the detailed alternative. For a read-only, non-paginated listing tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so limit, query and outcome are already fully documented in the schema, and the baseline applies. The description adds only an oblique hint about text search via the "garage" question example; it adds no syntax, default, or interaction details beyond the schema.

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

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

States a specific verb and resource ("List this account's calls"), specifies ordering ("newest first") and enumerates the returned fields (call_id, phone number, status, outcome, task, summary). It also names the sibling it is not — "For the full result and transcript of one call, use get_call" — so an agent can distinguish it without opening the schema.

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

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

Gives three concrete use cases (find a call_id, check whether a number was already called recently, answer "what happened with my call to the garage?") and routes single-call detail work to get_call with a specific parameter value. It does not address the close sibling get_batch_calls or state when this tool should be avoided, so the exclusions are incomplete.

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

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

Annotations already flag this as destructive, open-world and non-idempotent, yet the description still adds substantial operational context: the AI disclosure is always made, per-number anti-harassment limits, a simultaneous-call limit with queueing, refusal when exceeding the 24-hour quota, retry and 15-minute-wait behavior inside the 08:00-21:00 window, and per-call billing. What it does not clarify is the partial-failure semantics of a batch beyond pointing to a 'refused' list, 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?

Purpose and return value are front-loaded, and nearly every sentence carries operational fact rather than filler. The compliance and timing sentences are dense and slightly run-on (the 15-minute/08:00-21:00 clause is hard to parse on first read), which costs a point but does not obscure the core instruction.

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 high-stakes bulk outbound-calling tool with six parameters and an output schema, the definition covers purpose, legality, quota and concurrency behavior, billing, return handling and plan gating. Since an output schema exists, the description need not enumerate return fields, and nothing an agent needs in order to call this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: task must mirror place_phone_call and never be marketing, phone_numbers are French-only, capped at 100, echoed as given, and duplicates/invalid entries are skipped and returned in 'refused'. That last point is behavioral detail the schema does not convey.

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

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

States a specific verb and resource ('Place the same call to a list of numbers in France') and immediately discloses the return shape (batch_id plus one call_id per number). It also distinguishes itself from the sibling place_phone_call by describing itself as the same task applied to many numbers, so an agent can choose between them without inspecting schemas.

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

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

Gives explicit triggering conditions ('when the user explicitly asks to make the same kind of call to several numbers they provide') with two concrete examples, plus exclusion rules (marketing, prospecting, surveys, mass calling refused) and a recovery path for non-Pro accounts (plan_feature_required). It also names the follow-up tools, get_batch_calls and get_call, closing the loop on what to do next.

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, openWorldHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is partly given. The description still adds substantial non-schema behavior: an irreversible real call once answered, per-second prepaid billing, free retry of busy/unanswered calls after 15 minutes, a 08:00-21:00 window that does not block scheduled calls, background execution returning a call_id within 1-10 minutes, and the 45-second answer window. The apparent tension between destructiveHint/idempotentHint=false and the recommended reuse of idempotency_key is a per-request idempotency semantics point, not a contradiction.

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

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

It is long, but front-loaded with the purpose and organized into clear labeled blocks (Compliance, When to use, When not to use, Codes and payment details, Behavior) that match the decision path of a high-stakes mutation tool. Some content is duplicated with the task parameter description (the refused-payment list appears twice), which is the main thing keeping it from a 5.

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

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

For a destructive, open-world, paid, asynchronous tool with 10 parameters, the description covers authorization (explicit user request), compliance (EU AI Act art. 50), cost, irreversibility, the full async follow-up loop, and retry strategy. An output schema exists, so it does not need to explain return values, and it stays appropriately high-level there.

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

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

Schema description coverage is 100%, so baseline is 3 and the schema already carries voice personality labels, language modes, phone format rules and voice_settings ranges. The description adds cross-cutting semantics the schema cannot: the [secret: value] masking convention, why the AI disclosure default should not be changed, and the requirement to confirm a self-found number before calling.

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 gives a specific verb and resource ("Place a real outbound phone call to a number in France (+33)") plus the return form ("a written result"), and the parenthetical lists concrete tasks (book a table, move an appointment). It is clearly distinguishable from siblings like place_batch_calls and get_call, which the description also names later.

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 are explicit when-to-use criteria (user explicitly asked, number and task confirmed) and explicit when-not-to-use rules (prospecting, surveys, debt collection, impersonation, emergencies, refusing to reveal codes). It also routes the agent to siblings by name: get_call for polling/pending_question, answer_call_question within 45 seconds, hold_call_question, transfer_call_to_user for payments.

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

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

Beyond the annotations' destructive/openWorld flags, it discloses the real-world consequences an agent cannot infer: a real paid call will be placed, limits of 3 callbacks per call within 14 days, a minimum 2-minute and maximum 14-day lead time, no calling-hours window, and a named failure mode 'callbacks_disabled'. It also names cancel_call as the reversal path, which is exactly the context destructiveHint alone does not supply.

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, then compliance, then routing to siblings, then limits — a sensible priority order with no filler. The compliance sentence is dense but all of it is load-bearing; a small trim of the overlapping time-window statements (repeated in the compliance and limits sentences) would tighten it.

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, open-world scheduling mutation with only two parameters, the description covers preconditions, limits, cost, failure mode, and reversal. The output schema handles the returned scheduled time, which the description points at without duplicating.

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 already 100%, including the ISO 8601 format and the Europe/Paris default, so the description need not restate syntax. It still adds binding constraints on callback_at that the schema lacks ('at least 2 minutes from now', 'at most 14 days ahead') and clarifies that the number and task are inherited from call_id rather than passed. Slightly redundant on 'the time is kept as 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?

States a specific verb and resource ('Schedule a new attempt of a finished call (same number, same task)') and immediately distinguishes the two nearest siblings: get_call as a precondition and place_phone_call for a different number or task. An agent can pick it out of the sibling 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?

Gives an explicit precondition ('only after get_call shows done=true'), an explicit alternative ('To call another number or do a different task, use place_phone_call'), and a compliance gate ('only on the user's request'), plus the closing instruction to use cancel_call to undo. When-to-use and when-not-to-use are both covered.

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

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

Annotations flag destructive and open-world, and the description adds behavior beyond that: the precise handover sequence (announce to callee, ring user_phone_number, bridge both sides, then leave), the event lifecycle requested → ringing → connected/failed, and the critical fallback that on failure the voice agent stays on the line.

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

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

Purpose and compliance rationale are front-loaded, and the operational sequence follows logically. It runs slightly long with a trailing line break and some redundancy between the failure clause and the event-progression sentence, but every sentence carries actionable content.

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

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

For a destructive, open-world handover tool with an output schema, this covers preconditions, side effects, failure handling, and post-call monitoring via get_call. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds meaning by tying user_phone_number to the ring step and call_id to 'the live call to hand over'. The French-only number format is left to the schema, which is acceptable given full coverage.

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

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

The first sentence names a specific verb and resource: transferring a live call to the user's own phone so they can talk to the callee. It is unmistakable against siblings like place_phone_call or get_call, which neither transfer an existing live call nor target the user's own number.

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

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

It gives explicit triggers ('recommended whenever a payment or sensitive data is needed'), explicit preconditions ('only when the user asked to take over... and can pick up their phone now'), an explicit failure condition ('Fails if the call is not in progress'), and routes progress-checking to get_call.

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