asms

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds genuinely new context – a 10-minute block window and automatic refund of unfilled orders – but does not say whether an explicit cancel refunds, what error surfaces when called too early, or that the action is irreversible.

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, each load-bearing, and the discouraging verdict ('Rarely needed') is front-loaded before the reasoning. No filler and no repetition of the schema.

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

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

For a single-parameter destructive tool with no output schema, the decision-critical information (don't use it to retry, timing gate, self-refund behavior) is all present. The gap is the post-cancel outcome and error behavior, which an agent would still have to discover empirically.

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?

One parameter with 100% schema description coverage that already tells the agent orderId comes from create_otp_order. The description adds no format, source, or validation detail beyond that, 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 description makes clear this releases/cancels a verification order and explicitly names create_otp_order as the thing an agent should reach for instead when retrying. What it never states plainly is the effect of a successful cancel (whether the held funds are released/refunded), so the resource is identified but the operation's outcome is left implicit.

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

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

Explicit when-not-to-use ('to retry a verification do NOT cancel'), an explicit alternative ('just call create_otp_order again'), a hard precondition (blocked for the first 10 minutes), and the only valid case (release an order you no longer need after the hold). This is close to a model usage section.

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=true, and the description adds genuinely valuable operational context: the 5-120 minute window, the no-SMS precondition, and what happens on failure (the rental runs to its end date rather than being cancelled). It does not say where the refund lands or how quickly, which is the one behavioral detail still missing for a money-moving 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?

Two sentences, the action and refund stated first, then the constraints. Every clause is load-bearing — the time window, the no-SMS rule, and the expiry fallback each change agent behavior.

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

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

For a one-parameter destructive tool with no output schema, this covers the decision-relevant facts well: what it does, when it is legal, and what occurs otherwise. The remaining gap is post-call expectations — refund destination and timing — which matters for a tool whose whole purpose is a refund.

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 parameter already documents the accepted number formats in detail, including ignored characters. The description adds only the phrase "rented number," which carries no formatting or sourcing information beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Cancel a rented number") plus the immediate consequence ("refund it"), which cleanly separates it from rent_number and from cancel_order, which operates on orders rather than rentals. An agent can pick this 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 concrete eligibility windows (5-120 minutes after renting) and a hard exclusion (only if no SMS has been received), so the when-to-use condition is explicit. It stops short of naming a sibling as the alternative for the out-of-window case, leaving the agent to infer that an expired rental simply runs its course.

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

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

Annotations declare destructiveHint=true and non-idempotent, but the description adds far more: wallet debit, automatic refund within 10 minutes for unfilled orders, no penalty for retrying, and an explicit 'this spends real wallet balance' warning. It also corrects a likely wrong agent instinct (do not cancel to retry), which no structured field conveys.

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

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

Front-loaded with the core action and return values, and nearly every sentence carries operational guidance rather than filler. It is dense and slightly long, and the spending warning sits at the end rather than up front where a cost warning would be most salient.

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

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

There is no output schema, and the description compensates by naming the returned fields and describing downstream flow, refund timing, retry policy, and pool selection. An agent has everything needed to call this correctly and handle the failure case.

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

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

Schema description coverage is 100%, so the country and service semantics are already documented, making 3 the baseline. The description goes beyond the schema by advising which pool to choose when a service rejects codes — 'us1 (Non-VoIP AT&T) pool, which has the highest delivery rate' — adding decision-level meaning the schema only partially implies.

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 concrete verb and resource ('Buy a number to receive an OTP'), lists the side effects (allocates a number, debits the wallet), and states the return shape (orderId + phoneNumber). It also names the follow-up sibling poll_sms, so an agent can distinguish the ordering step from the polling step without opening either schema.

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

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

Explicit guidance is given for the full lifecycle: call this, then poll with poll_sms; if no code arrives, do NOT cancel to retry, instead call create_otp_order again. It also states the escalation path (use the us1 pool when a service keeps rejecting codes) and the cost condition (auto-refund within 10 minutes means repeated ordering carries no penalty).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds only the 'authenticated account' scoping and 'current' (live, not cached) nuance; it says nothing about whether multiple currencies/wallets can exist, rate limits, or failure modes when no wallet exists.

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

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

One short, front-loaded sentence with no filler or repetition of the title. Every word 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 read this is nearly sufficient, but with no output schema the return shape is undocumented and the description does not hint at it (single amount vs per-currency balances, units, currency code). That leaves a real interpretation gap for the calling agent.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly signals that no filtering arguments are needed and the account is implicit from auth.

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

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

States a specific verb and resource ('Get the current wallet balance') and scopes it to 'the authenticated account'. It is unambiguous, though no sibling balance tool exists to distinguish from, so 5-level differentiation isn't demonstrated.

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

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

Usage is only implied by the resource name; there is no statement of when to call it versus other data sources (e.g., get_pricing or order totals) or any prerequisite such as authentication being established. Adequate but with a clear 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=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds only that omitting service broadens the result set; it doesn't say whether results are counts versus actual numbers, ordering, or freshness.

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

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

Two sentences, no filler, and the core operation is front-loaded before the optional-parameter note. Every clause carries 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 simple two-parameter read tool with no output schema, the description covers what the tool returns conceptually (a count of in-stock numbers). It stops short of describing the response shape or whether multiple services yield multiple entries, a minor gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema by explaining the behavior of omitting the optional `service` parameter (returns stock across all services) rather than merely restating it.

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

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

States a specific verb ('Get') and resource ('how many numbers are in stock'), scoped by country and optionally service. It is distinguishable from siblings like get_pricing and get_balance by the 'stock' framing, though it doesn't explicitly contrast with them.

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 one guidance offered is 'Omit `service` to list stock for every available service,' which clarifies an optional usage pattern. However, it never says when to prefer this over get_pricing or get_rental_offers/what services are eligible, 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond the schema by explaining that omitting the optional `service` parameter switches the result from a single price to a full price list. It does not mention currency, price freshness, or whether prices are guaranteed at order time.

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, zero waste, with the core purpose front-loaded and the optional-parameter rule immediately after. Nothing needs to be re-read.

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-only lookup with no output schema, the description covers what is priced, the unit (per OTP activation), and the list-vs-single behavior. The only gap is the shape of the returned price data (currency, additional fields), which an agent might want before formatting results.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the semantics of the optional `service` parameter's omission, which the schema only marks as non-required without saying what happens. It adds no interpretation of the `country` pool values, but those are richly documented in the schema.

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

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

States a specific verb and resource with a precise unit: the retail price per OTP activation, for a service in a country. This is clearly distinguishable from inventory/balance siblings in substance, though it never names an alternative tool explicitly.

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

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

Gives one concrete usage rule — omit `service` to list all services — which is genuine when-to-do-what guidance. It offers no guidance on when to call this instead of get_inventory or get_rental_offers, so the cross-tool routing 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 only declare readOnlyHint and openWorldHint; the description adds genuinely new behavioral context — that a rented number is held for the entire period and receives every inbound SMS, contrasted against single-code OTP orders. That semantics-of-what-you-get detail is exactly what annotations can't convey. It doesn't describe the shape of the returned listings, but no output schema exists to lean on.

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

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

Three short sentences, front-loaded with the core action and scope, then the rental-vs-OTP distinction, then the omission behavior. No filler and nothing buried.

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

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

One optional enum parameter, full schema coverage, read-only annotations, and no output schema — a low-complexity tool. The description covers the action, the time-range scope, the product distinction, and the omitted-parameter mode, which is everything needed to invoke it correctly.

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

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

Schema coverage is 100% and the enum values are fully documented, so the baseline is 3. The description earns an extra point by explaining the otherwise undocumented semantic of omitting `country` — that it switches the response to a list of rentable countries, a mode change the schema does not express.

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

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

States a specific verb and resource ('List the rental periods and prices') and bounds the scope with '(1 day to 12 months)'. It explicitly contrasts rentals with OTP orders, which disambiguates it from create_otp_order, but it never addresses the overlapping siblings get_pricing and get_inventory, so an agent can't fully rule those out from the description alone.

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

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

'Omit `country` to list the countries numbers can be rented in' gives concrete calling guidance for the optional-parameter path, and the 'unlike an OTP order' clause tells the agent which scenario this tool serves. It stops short of explicitly saying 'call this before rent_number' or naming any case where another tool is preferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds only the status filter notion ('awaiting a code or already received'); it says nothing about ordering, what 'recent' means, or pagination behavior beyond the schema's limit field.

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 tight sentence with the resource front-loaded and no filler. The only softness is the undefined 'recent', which adds a small ambiguity rather than waste.

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

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

For a read-only list with a fully documented single parameter and annotations covering safety, the essential call information is present. However, with no output schema, the description should indicate what an order record contains or how results are ordered, and it does not.

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

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

Schema description coverage is 100% and the single 'limit' parameter already documents default 50 / max 1000. The description adds no parameter meaning, so the baseline 3 applies.

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

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

The description uses a specific verb+resource ('List recent OTP orders') and scopes it to 'the account', which separates it from create_otp_order and cancel_order by action. It stops short of naming a sibling or explaining how it differs from poll_sms/read_rental_sms, which also surface verification data.

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

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

The parenthetical '(awaiting a code or already received)' implies the status window an agent should expect, giving some usage context. But there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as poll_sms for fetching the actual code.

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 this is a safe read (readOnlyHint=true) with a closed data scope (openWorldHint=false). The description adds genuinely useful behavioral context: ended rentals are excluded by default, which materially affects results. It stops short of describing ordering, pagination, or empty-result 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 with no filler; the core listing behavior and the important default-filter caveat are both 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 single-optional-parameter read tool with annotations covering safety and no output schema, the description gives enough to call it correctly and predicts the shape of results via country/period/end date. Minor gaps remain around result ordering, pagination, and result size limits.

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 only parameter already documents 'Also list rentals that have ended (default false).' The description's 'Ended rentals are left out unless includeEnded is true' conveys the same semantics in context but adds no new detail, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('List the account's rented numbers') and even names the fields returned (country, period, end date), which distinguishes it from mutation siblings like cancel_rental or rent_number. It does not explicitly differentiate from the read-side siblings such as get_inventory or read_rental_sms, leaving the agent to infer the boundary.

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

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

Usage is implied by the includeEnded condition: the default is active rentals, and setting the flag broadens it. However, the description never states when an agent should choose this over sibling tools (e.g., read_rental_sms or get_inventory), and no prerequisites or exclusions are given.

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 and closed-world behavior, and the description adds substantial operational context beyond that: empty-result polling semantics, retry timing, auto-refund within 10 minutes, no charge for ordering again, and charging only for codes that arrive. This is unusually complete for a polling tool.

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

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

The description is front-loaded with the core polling behavior and result semantics, then moves directly into failure handling. Despite covering several operational rules, every sentence is actionable and no sentence is redundant.

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

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

There is no output schema, but the description fully explains the possible return outcomes: the code when it arrives or an empty result requiring another poll. It also supplies the failure workflow, refund behavior, and billing behavior needed to call and recover from this 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 100%, and the single orderId parameter is already documented as coming from create_otp_order. The description does not add format, source, or validation details 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 specific action and resource: check for the SMS/OTP code on an order. It also explains the result shape, returning the code once it arrives or an empty result otherwise, which makes the tool's purpose unambiguous and distinguishable from setup siblings like create_otp_order.

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 polling guidance ('poll again after a few seconds') and a concrete escalation path after one to two minutes: order a fresh number with create_otp_order, prefer the us1 Non-VoIP pool, leave the original to auto-refund, and never cancel just to retry. This directly covers when to use the tool, what to do on failure, and which alternatives not to use.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavior — result ordering (newest first) and the intended polling loop — but says nothing about what an empty response looks like, whether history is truncated, or any rate limiting on repeated polls.

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 scope and ordering front-loaded before the polling hint. Nothing could be cut 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?

For a no-output-schema, single-parameter read tool, the definition covers scope and ordering well enough to call it correctly. The remaining gap is the unresolved relationship with poll_sms and the absence of any note on empty results.

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

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

Only one parameter and schema coverage is 100%; the schema itself explains the accepted number format and that '+', spaces and dashes are ignored. The description adds nothing about the parameter, which is acceptable at full schema coverage but is the baseline, not a contribution.

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 SMS a rented number has received) plus the scope 'during this rental' and the ordering 'newest first'. It does not name or differentiate from the sibling poll_sms, which reads as a near-duplicate purpose, so it stops 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 only usage instruction is 'poll again every few seconds while waiting for a message', which is a cadence hint rather than a when-to-use rule. With a sibling literally named poll_sms, the agent is given no basis for choosing between the two, and no note on what to do if the rental has expired or the number is not rented.

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 openWorldHint=true, but the description adds the crucial business consequence those hints cannot express: it debits the real wallet balance and requires user confirmation. It also discloses what the call returns (the number and rental end time), which no annotation or output schema provides.

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

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

Four short sentences, front-loaded with the action and its required inputs, then the side effect, then the warning. Every sentence carries information the agent needs and nothing is repeated.

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

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

With no output schema, the description still tells the agent what comes back (number and rental end), what the call costs, and how to read messages afterwards. Combined with the fully documented schema and destructive annotation, 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 description coverage is 100% and both enums are fully enumerated with human-readable expansions, so the description's mention of 'country' and 'period' adds nothing new. Its availability caveat ('not every period is on sale in every country') is already stated in the period schema description, so the baseline 3 applies.

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

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

States a specific verb and resource ('Rent a phone number') plus the scoping dimensions (country, period). It is clearly distinguishable from siblings like get_rental_offers (browse) and read_rental_sms (consume), and an agent can identify it without opening the schema.

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

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

Gives an explicit prerequisite ('get the periods and prices from get_rental_offers first') and an explicit confirmation step before spending. It also points to the follow-up tool ('Read its SMS with read_rental_sms'), so both the entry and exit paths of the workflow are named.

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