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

Annotations already mark this read-only, and the description adds useful behavioral context: it is one-shot, does not wait, and conditionally returns a code only if the order has arrived. No side effects or wait behavior are hidden; it does not contradict the readOnlyHint.

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-load the key operational constraint ('one-shot', 'no waiting') before the return behavior. Every phrase earns its place; 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 one-parameter read-only tool with no output schema, the description supplies the essential return semantics — current status and conditional arrival code — and the one-shot nature is explicitly stated. The order_id parameter is already covered by the schema, so nothing required for correct invocation is missing.

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

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

The sole parameter order_id is fully documented in the schema with its provenance ('returned by get_number'), and the description adds no new parameter-level information. With 100% schema coverage, the baseline of 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 uses a specific verb and resource — 'One-shot status check for an order' — and differentiates itself from waiting-style siblings by adding '(no waiting)'. It also states the exact return payload, so an agent can tell it apart from get_number, wait_for_otp, and the other tools.

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

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

It clearly conveys when to use it: for an immediate, one-shot status check, not a blocking wait. However, it never explicitly names wait_for_otp as the alternative or says 'use X instead', leaving the routing slightly 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 disclose readOnlyHint=true and openWorldHint=true, so the safety profile is established. The description adds context beyond annotations by clarifying that the balance is current and represents spendable funds on numbers, which is helpful. 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 description is a single, front-loaded sentence with a useful parenthetical clarification. Every word contributes meaning, and there is no repetition of the title or schema fields.

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 parameterless, read-only tool with no output schema, the description fully covers what an agent needs: what the tool returns and what the value represents. No further behavioral or return-format details are necessary 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?

The input schema has zero parameters and schema coverage is 100%, so there is no parameter information for the description to add. A baseline of 4 is appropriate when the schema carries no parameter burden.

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 ('Return') and names the exact resource ('reseller account's current balance'), clearly distinguishing it from siblings like get_number, check_order, and list_services. The parenthetical 'what you can spend on numbers' further removes any ambiguity about the meaning of the balance.

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 'what you can spend on numbers' implies when this tool should be used: before spending or ordering, to confirm available funds. No sibling tool overlaps with balance retrieval, so explicit exclusion language is unnecessary, but the description could still state the usage context more directly.

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 report readOnlyHint=false and idempotentHint=false, but the description adds the critical side effect: 'THIS CHARGES the reseller balance immediately (pay-per-code).' It also discloses the 20-minute auto-refund and early-release refund behavior, giving the agent a clear picture of cost and reversion semantics before calling.

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 three sentences: action first, then the charge warning, then the follow-up workflow. Every sentence carries necessary information, and it does not waste tokens repeating schema details.

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 the full purchase workflow, including charging, refunds, and polling via order_id. Because there is no output schema, a more explicit statement of the exact return shape (e.g., an object containing phone_number and order_id) would make it fully complete, but the current wording provides enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description only generically references service and country and does not add per-parameter meaning, so the baseline 3 is appropriate.

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

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

The description opens with a concrete action: 'Buy a phone number for a service in a country and return it.' This clearly distinguishes the tool from siblings like get_balance, check_order, and wait_for_otp, even though the title 'Get a number' is vague on its own.

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 gives clear lifecycle guidance: buy the number, then poll with wait_for_otp using the returned order_id, and optionally release() early for a refund. It does not explicitly state when not to use this tool or name alternative purchase-like siblings, so it stops short of full exclusion 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful context that results reflect current buyable-number availability, but it does not reveal additional behavioral traits such as result ordering, pagination behavior, or the meaning of an empty response.

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 states the core purpose and the optional filter with no wasted words. It is concise and structured effectively for quick agent comprehension.

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

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

For a simple read-only list tool with 100% schema coverage and readOnly/openWorld annotations, the description plus schema provide sufficient context. The only minor gap is not explicitly directing users to list_services for service codes, though the 'service' schema example partly mitigates this.

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%, with both 'limit' and 'service' documented. The description only reiterates the optional service filter without adding meaning beyond the schema, so the baseline score of 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 uses a specific verb ('List'), a clear resource ('countries'), and a meaningful qualifier ('that currently have buyable numbers'). It also distinguishes itself from siblings like list_services by focusing on countries and availability.

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 its usage: call it when you need available countries, and optionally narrow by service. However, it does not explicitly state when to prefer an alternative or mention related tools like list_services for resolving service codes.

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

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

Annotations already mark this as read-only and open-world, so the safety profile is covered. The description adds valuable behavioral context: results are live, include price/stock, and the unfiltered response can be very large, which meaningfully informs how an agent should invoke the tool.

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

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

Three short sentences, each earning its place. The most important guidance (filter to avoid huge result sets) is front-loaded, and no redundant phrasing is present.

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 the key invocation requirements, including parameter semantics, filtering preference, and result expectations. There is no output schema, so the exact return shape is not fully specified, but the mention of live price and stock gives an agent a sufficient mental model.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining what the codes mean ('tg' for Telegram, '6' for a country code) and by reinforcing the filtering purpose of the optional 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 clearly states a specific action ('List buyable services') and adds distinguishing details: live price and stock. It is easy to tell apart from sibling list_countries because it operates on buyable services rather than static country codes.

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 gives clear operational guidance by strongly recommending filtering by service and/or country due to the large unfiltered catalog. It does not explicitly discuss when to choose this tool over a sibling, but the domain is distinct enough that no exclusions are necessary.

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/non-read-only. The description adds meaningful detail beyond annotations: the refund is immediate, and if the code has already arrived, nothing is refunded and the code is returned. This conditional behavior helps the agent predict outcomes. No contradiction with idempotentHint or openWorldHint.

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 main action is stated first, and the conditional exception follows naturally without unnecessary elaboration.

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 one fully documented parameter and annotations covering destructiveness and idempotence, the description covers the core behavior and an important edge case. The absence of an output schema means the return shape is unspecified, but the mention of 'the code is returned' partially addresses this.

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 fully documents the only parameter as 'The order_id to release,' so schema coverage is 100%. The description's reference to 'an order' aligns with order_id but adds no extra format or semantic detail, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Cancel'), a resource (an order), and the accompanying refund action, making the tool's purpose unambiguous. It is clearly distinct from sibling read-status tools like get_number, check_order, and wait_for_otp.

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 gives clear context: use this to cancel an order and process an immediate refund, with an explicit conditional branch when the code has already arrived. It does not name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already mark this as read-only, and the description adds meaningful behavior beyond that: polling semantics, code expiry, timeout behavior, and the note that the number remains active on timeout. This gives the agent a realistic model of what happens during the wait without contradicting the readOnlyHint.

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, no filler. The core polling behavior is front-loaded, the return condition is stated, and the timeout fallback guidance is included. 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?

The description explains what the tool returns ('the code when delivered') and what to do on timeout, which is critical since there is no output schema. It also covers the major outcome paths: delivered, expired, and timed out. Minor gaps like exact behavior on expiry are not explained, but the core calling scenario is complete.

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

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

Schema coverage is 100%, with both timeout_seconds and poll_interval_seconds already documented with defaults and bounds. The description adds context about timeout behavior but does not add parameter-level detail beyond the schema. This matches the baseline of 3 for fully documented schema 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 ('Poll an order'), a clear resource (the order), and a precise termination condition ('code arrives, expires, or timeout'). It also states the key return value ('Returns the code when delivered'), making the tool's purpose unambiguous and distinct from siblings like check_order and release.

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 gives clear context on when to call: poll until a code arrives or times out. It also provides post-timeout guidance, explicitly saying to call again or use release() to refund. It doesn't explicitly contrast with check_order or explain when not to use this tool, but the polling semantics and timeout behavior are well covered.

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