Request number (purchase)

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

With no annotations provided, the description carries the full burden and does so admirably. It discloses the critical side effect (immediate wallet spend), a prerequisite (API key), and the idempotency behavior (identical calls replayed without charging, distinct tokens for new orders). This covers the primary risks an agent needs to know before invoking a purchase 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 compact and front-loaded with the most critical warning (wallet spend). Each sentence earns its place: the purpose, the prerequisite, the retry guard, and the intentional second-order scenario. No fluff or redundancy.

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

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

For a transactional tool with no output schema, the description covers the action, prerequisites, side effects, and retry semantics. It doesn't describe the response format (e.g., the number returned) or potential error conditions like insufficient balance, but these are not strictly required for a correct call, and the description adequately equips an agent to make the request.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: it tells the agent to source serviceCode from list_services and countryIso from get_service_countries, and it explains the semantics of idempotency_token beyond the schema's basic description. This adds value beyond the raw parameter definitions.

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 the action ('Reserve a virtual number') and the resource (for SMS verification). It distinguishes this from sibling tools like list_services (which list services) and get_status (which checks status) by implying an order/purchase action. The immediate wallet-spend warning further differentiates it as a transactional 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?

Explicitly instructs the agent to use list_services / get_service_countries first to select serviceCode and countryIso, establishing clear prerequisites. It also explains the retry guard and how to intentionally order a second number via a distinct idempotency_token. While it doesn't explicitly state when NOT to use it (e.g., use get_balance to check funds), the purpose is clear enough that an agent can infer the appropriate context.

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