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

Annotations declare a non-read, non-idempotent, non-destructive mutation, and the description adds material context beyond them: it discloses the return value ('proxy credentials and remaining balance') and the non-obvious trait that country_code is 'only a soft preference for provisioning,' which prevents agents from assuming geo-guaranteed allocation. It does not contradict annotations, though it stops short of describing billing/failure edge cases for a purchase action.

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 tight sentences with zero filler: the core action and return value lead, followed by two routing sentences that each name a specific sibling tool. Every sentence earns its place, and it stays compact despite the API having 40 siblings.

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 wisely states what the call returns (proxy credentials and remaining balance), and it resolves sibling ambiguity by naming the two related tools and the sequencing between them. It could additionally flag explicit billing/payment side effects or failure behavior, but the mutating nature of a purchase is already visible via annotations and the title.

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 baseline is 3 and the schema already documents all four parameters. The description earns a 4 by adding the crucial semantic nuance that country_code is a soft preference only, which materially changes how an agent treats that parameter, and by framing gb as the traffic volume being added within the purchase.

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 the action precisely — 'Purchase proxy traffic (GB) for a selected pool type' — with a clear resource (GB in a pool) and a specific verb. It differentiates itself from closely related siblings by pointing to virtualsms_generate_proxy_endpoint and virtualsms_set_proxy_targeting for related-but-different actions, so an agent can tell them apart 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?

Explicitly names alternatives and the conditions that select them: use virtualsms_generate_proxy_endpoint for per-connection targeting (country/state/city/zip/asn) or a ready-to-use connection string, and virtualsms_set_proxy_targeting to persist a default targeting. The phrase 'after buying' also establishes the correct call ordering. This is the strongest possible routing guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's job is lighter. It adds value by specifying return values ('number of orders cancelled plus any failures'), which informs the agent of the outcome. It could mention the irreversible nature, but overall it adds useful context.

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 two sentences, front-loaded with the action, and includes a usage hint. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description compensates by mentioning return values. Annotations cover destruction. It could mention what happens to other resources or confirmation steps, but it is mostly complete for a zero-parameter bulk action.

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 has zero parameters, so per guidelines the baseline is 4. The description rightly includes no parameter details, and the schema covers everything.

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: 'Bulk-cancel every currently active order in your account.' It uses a specific verb ('bulk-cancel') and resource ('every active order'), and distinguishes itself from the sibling tool 'virtualsms_cancel_order' which cancels a single 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?

The description provides context for when to use this tool: 'Useful for quick cleanup after a batch run or test session.' While it doesn't explicitly exclude other scenarios or name alternatives, the sibling tools (e.g., 'virtualsms_cancel_order') imply the singular use case, and the context is sufficient.

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 signal destructiveness and idempotence. The description adds valuable context: cancellation only allowed before SMS reception, a cooldown mechanism, and that premature calls result in a local error without backend impact. No contradiction with annotations.

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

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

The description is three sentences with no extraneous information. It front-loads the core action and constraints, each sentence serves a distinct purpose: purpose, usage, and behavioral 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 simple cancellation tool, the description covers key constraints (no SMS received, cooldown, error behavior). It lacks any mention of the success response or refund specifics, but given no output schema, this is 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?

The only parameter 'order_id' is fully described in the schema (100% coverage). The description does not add semantic detail beyond what the schema provides, meriting the baseline score.

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

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

The description clearly states 'Cancel an order and request a refund' and specifies the condition 'Only works if no SMS has been received yet.' This distinctively differentiates it from siblings like 'virtualsms_cancel_all_orders' which cancels multiple orders.

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 explicitly provides when to use the tool: 'if the service is taking too long or you want to try a different number.' It also details a crucial prerequisite: check 'cancel_available_at' to respect a 120-second cooldown, and warns that early calls return a specific error.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds context beyond that: full refund, time window, and SMS condition. It does not contradict any annotation. The added specificity about refund and eligibility is valuable, though it doesn't mention failure modes or exact return shape, which is minor given the simple operation.

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, front-loaded with the core action and outcome, then adds eligibility constraints. Every sentence carries essential information, and there is no fluff. It is concise and well-structured.

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 mutation tool without an output schema, the description provides enough context: what it does, when it's valid, and what the result is (full refund). The annotations cover the destructive nature. No critical information is missing for an agent 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?

The schema has one parameter (rental_id) with a clear description, and schema coverage is 100%. The tool description adds no additional parameter-specific detail, such as format or validation. Per the rubric, with high schema coverage, a 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 clearly states the action (cancel), the resource (a rental), and the outcome (full refund). It also includes specific eligibility conditions, distinguishing it from sibling tools like cancel_order or cancel_all_orders by focusing on rentals. This is a specific, unambiguous purpose statement.

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 explicitly states when to use the tool (within 20 minutes, before SMS received) and when not to use it (past that window, it runs to expiry). It also notes it works for either tier, giving clear context. No alternative tools are named, but the when/when-not guidance is sufficient.

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 cover readOnly, idempotent, open-world, and non-destructive behavior explaining. The description adds useful behavioral context beyond those annotations by emphasizing that the lookup is 'public' and requires no API key, plus it implies the output includes carrier, line type, and spam risk. No contradictions exist.

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 entire description is one compact sentence that front-loads the core purpose and then adds key access context ('No API key required'). No filler or redundant restatement of the tool name or title.

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

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

For a simple, single-parameter, low-complexity lookup tool with rich annotations, the description plus schema fully covers what an agent needs to select and invoke it correctly. Return-format details are not explicitly described, but the description already names the result dimensions (carrier, line type, spam risk), which is adequate without an output schema.

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

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

Schema coverage is 100% and the parameter description already explains E.164 format with an example. The description adds value by calling the number 'arbitrary,' clarifying that any public number can be checked regardless of account association, and by mentioning the specific categories the lookup covers.

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 identifies a specific verb-resource pair: a public carrier and line-type lookup for an E.164 phone number. It also specifies the data categories returned (mobile/landline/VoIP, spam risk), which makes the tool's purpose unmistakable and distinct from the many sibling 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 states that this is a public lookup requiring no API key, which signals when it can be used independently from account-bound tools. It does not explicitly name an alternative or exclusion, but no sibling appears to be a competing number-lookup tool, so the context is sufficient.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the agent knows this is a mutating, non-idempotent call. The description adds valuable timing context ('Codes typically arrive within ~10-60 seconds'), which annotations don't cover. No contradiction with annotations. Missing disclosure of the financial/cost aspect of a purchase.

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

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

Three sentences with zero waste: purpose and returns first, timing second, follow-up routing third. Every sentence earns its place and the most decision-relevant information (what it does, what it returns) is front-loaded.

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

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

For a simple 2-parameter purchase tool with no output schema, the description covers purpose, returns, timing, and next steps — nearly complete. The main gap is that it doesn't disclose that this is a paid operation with financial implications, which would be helpful context for an 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?

Schema description coverage is 100% — both service and country have descriptive text in the schema, so the baseline is 3. The description doesn't add parameter-level detail beyond the schema (e.g., it doesn't hint at service code formats or provide examples of common codes), but it doesn't need to since the schema is already complete.

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 (Purchase) and resource (virtual phone number) with a clear purpose (SMS verification), and explicitly names the return values (order_id and phone_number). This distinguishes it from siblings like virtualsms_list_orders (listing) and virtualsms_get_order (retrieval).

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?

Provides explicit post-purchase routing: 'Use get_sms to poll for the verification code, or use wait_for_sms to block until it arrives.' This tells the agent what to do next with named sibling tools. However, it does not state when to prefer a rental (create_rental family) over a one-time purchase, or mention cancel_order as a recourse.

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

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

Goes well beyond the annotations by disclosing the difference between full-access and platform sourcing, the service-locking behavior, the 1/3/7-day duration restriction, and the refund terms. These are operational traits an agent cannot infer from readOnly/destructive hints alone.

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

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

Three dense sentences with no filler; the core distinction and prerequisites are front-loaded before the refund detail. Every sentence carries operational 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 mutating create operation with no output schema, it covers selection, prerequisites, tier constraints, and refund conditions well. The only notable gap is that it doesn't describe the return value or how to identify the newly created rental afterward, which would make it fully 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 already 100%, but the description adds tier-specific meaning, clarifies that platform is locked to one chosen service, and restates the allowed platform durations. It doesn't explain auto_renew behavior beyond the schema, but the added tier semantics justify above baseline.

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 uses a specific verb-resource pair ('Rent a phone number') and immediately distinguishes this tool from the one-off create_order sibling by contrasting extended rentals with single-use orders. It also defines the two tiers, so an agent knows exactly what operation this performs.

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 names create_order as the alternative for one-off numbers and states the preconditions: check rentals_available and rentals_price/rentals_pricing first. This leaves no ambiguity about when this tool should be selected over its closest sibling.

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 show this is a mutating, non-idempotent operation. The description adds an important behavioral and financial disclosure: it charges the user's balance at the current catalog price, which is not visible in the schema.

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

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

Two concise sentences with no filler. The primary action is front-loaded and the billing consequence follows immediately, making the description easy to parse.

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 mutating tool with no output schema, the description covers the action, the active-rental prerequisite, and the key financial side effect. It does not describe return values, but that is not essential for tool selection or 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 descriptions already cover both parameters (100% coverage), so the baseline is 3. The description adds meaning by clarifying that rental_id must reference an active rental and that duration_hours results in a balance charge at current pricing.

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?

Clearly states the action ('extend'), the target ('an active rental'), and the change ('additional duration'). The 'active' qualifier and the billing effect distinguish it from create/cancel/get/list rental siblings.

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

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

Explains the precondition that the rental must be active, which tells an agent when this tool is applicable. It does not explicitly name alternatives or when-not-to-use conditions, but the context is clear among the rental sibling tools.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral detail: 'Returns available countries with prices and stock levels' and 'sorted by price,' which beyond the annotations. No 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?

Two sentences with no wasted words. The main purpose is front-loaded, and each sentence adds value: first states action, second describes output. Perfectly concise.

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?

Despite no output schema, the description covers input (service, limit), operation (sort by price), and output shape (countries with prices and stock levels). This is complete for a simple search tool, providing what an agent needs to use 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%, so baseline is 3. The description does not add new parameter-specific meaning beyond what the schema already provides (e.g., service examples and limit default). It repeats the core idea but adds no extra 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 clearly states the purpose: 'Find the cheapest countries for a given service, sorted by price.' It specifies the verb (find) and resource (cheapest countries), and distinguishes from similar tools like virtualsms_get_price by focusing on cheapest across countries.

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 when to use (for a given service, looking for cheapest), but does not explicitly state when not to use or mention alternative tools. It provides context but lacks exclusions or comparisons.

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 idempotentHint=true. The description adds a valuable behavioral nuance: sub-country targeting bills at 2x GB on non-premium pools, free on residential_premium. This cost implication is beyond the annotations and helps agents anticipate side effects.

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

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

Two sentences, front-loaded with the core function and scope. It packs essential details (targeting, session, protocol, formats, read-only nature) without fluff, and the billing caveat is placed at the end to avoid distraction.

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

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

Given 9 parameters, 4 enums, and no output schema, the description covers the key points: what it builds, that it is read-only, the billing implication, and the dashboard compatibility. It doesn't describe output structure, but since no output schema exists, the description could hypothetically add that; however, the examples are in the parameter values and the format enum, so it's reasonably complete.

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

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

Schema description coverage is 100%, so all 9 parameters are documented in the schema. The description largely restates these options (formats, targeting levels) without adding new semantic details beyond what's in 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 clearly states the tool composes proxy connection strings with specific options (targeting, session, protocol, format). It explicitly clarifies it does not purchase or change anything server-side, distinguishing it from siblings like buy_proxy or set_proxy_targeting.

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

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

The description provides clear context: it is for generating endpoint strings for an owned proxy, and it states it does not alter server state. However, it does not explicitly name alternative tools or say when not to use it, though the distinction from set_proxy_targeting is implied by the read-only nature.

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

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

The description adds the important behavioral note that the tool requires an API key, which is beyond what annotations provide (readOnlyHint, idempotentHint). It correctly implies a safe, non-destructive operation. No contradiction with annotations.

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

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

The description is two sentences long with no unnecessary words. It front-loads the core purpose and follows with a critical requirement. 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?

Given the simplicity of the tool (one optional parameter, no output schema) and rich annotations, the description is mostly complete. However, it does not hint at the return format, but the tool name and context imply a numeric balance value. A minor gap but not critical.

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 100% coverage for its single optional parameter 'currency', so the description does not need to add extra meaning. The baseline score of 3 is appropriate as the description ignores the parameter entirely.

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 verb 'Check' and the resource 'account balance in USD', which immediately distinguishes this tool from siblings like get_price or get_profile. The resource is specific and easy to understand.

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 mentions a prerequisite (VIRTUALSMS_API_KEY) but does not provide guidance on when to use this tool versus alternatives. The context of sibling tools suggests it is for balance inquiry, but no explicit when-to-use or when-not-to-use advice is 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, idempotent, non-destructive behavior. The description adds that the tool returns the latest state and includes received SMS content, which is useful behavioral context beyond what annotations convey.

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

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

Two sentences carry the purpose, scope, returned fields, and tool routing with no filler. The key information about the latest state is front-loaded.

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

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

For a simple single-parameter read operation, the description is complete: it states inputs, outputs, scope, and relationship to a sibling tool. The safety profile is already covered by annotations, and no output schema is needed to call the tool correctly.

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

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

The single parameter order_id is already fully described in the schema at 100% coverage. The description restates the need for an order_id without adding format, source, or validation semantics, so it meets the baseline but adds no schema-independent value.

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

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

The description names a specific action and resource ('get the full details of a specific order') and enumerates the returned fields (status, phone number, service, country, timestamps, SMS code/text). It also differentiates from get_sms by saying it returns beyond what that tool provides, making it clear among many siblings.

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

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

It gives an explicit trigger condition ('Use this when you have an order_id and need the latest state') and names the relevant alternative (get_sms), indicating what that alternative does not cover. This is sufficient routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, fully conveying the safe, non-destructive nature. The description adds no new behavioral traits beyond reinforcing that it checks price/availability. No contradiction 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?

The description is two sentences with zero wasted words. It front-loads the action and necessary context, making it easy to parse quickly. Every sentence provides 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 simple price-check tool with no output schema, the description covers the core purpose but lacks detail about the return format (e.g., price, currency, availability status). Given the low complexity, it is adequate but could benefit from stating what the output contains.

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

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

Both parameters have schema descriptions (service code string, country ISO code) that are clear and sufficient. The description does not add extra meaning beyond what the schema already provides. Baseline score 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 clearly states the action 'Check the price and availability for a specific service + country combination.' It uses a specific verb 'check' and distinct resource (price/availability), differentiating it from siblings like get_balance or get_order. The additional guidance to 'always check price before buying' reinforces its purpose.

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 explicitly advises to use this tool before buying, giving clear context for when to invoke it. However, it does not mention alternatives or when not to use it, though siblings like virtualsms_find_cheapest may serve a different purpose. The guidance is straightforward and helpful.

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 provide readOnlyHint, destructiveHint=false, idempotentHint. Description adds no behavioral context beyond field listing, such as side effects or response handling.

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?

Single sentence efficiently lists all returned fields with no redundancy. Front-loaded with 'Full account profile'.

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

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

Given zero parameters, no output schema, and rich annotations, the description sufficiently explains what the tool returns. It covers all relevant aspects for using the tool.

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

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

No parameters exist, so description does not need to add meaning. Baseline of 4 applies as there is no param info to supplement.

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 specifies that the tool retrieves the full account profile, listing specific fields like email, balance, orders, etc. It distinguishes itself from siblings that handle orders, balance, or SMS operations.

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

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

No explicit guidance on when to use this tool versus alternatives. The description implies it is for viewing account profile, but does not state exclusions or mention sibling tools.

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

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

The annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already cover safety, but the description adds important behavior: it does not make an upstream call, returns cached data, and refreshes every ~5 minutes. This is value beyond annotations and sets agent expectations correctly.

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, each earning its place. The first states the kernel and the second adds critical behavioral context (cached, cheap, refresh time). Effective front-loading.

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 tool is simple (1 param, no output schema, simple scalar return) and the description fully explains its behavior. Nothing missing 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 schema provides 100% coverage: proxy_id is described as 'Proxy ID returned by list_proxies or buy_proxy'. The description adds no additional parameter semantics, which is acceptable given full schema coverage. 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 ('Get cached GB used/remaining and request count') and the resource ('one proxy'), which is clear. It distinguishes from siblings like virtualsms_get_proxy_usage_history by focusing on 'cached' and 'for one proxy', but does not explicitly name that sibling.

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 clearly indicates it returns cached data, refreshing every ~5 minutes, which implies when to use it (quick checks) versus a live/historical call. It does not explicitly mention alternatives, but the context of 'cached' and 'cheap' gives clear usage signals.

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, covering the safety profile comprehensively. The description adds the temporal scope (per-day series over 7/30 days) and the type of data (traffic in GB and request count), which is useful context beyond the annotations. However, it does not disclose response format, pagination, or error behavior, so it adds only moderate value beyond the structured metadata.

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, concise sentence that front-loads the action ('Get') and scope ('per-day traffic and request-count series'). It contains zero fluff and efficiently conveys the essential information.

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

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

For a simple read-only tool with 2 parameters, the description is mostly adequate. However, it does not clarify how it differs from virtualsms_get_proxy_usage, which could lead an agent to select the wrong tool for a given task. No output format is described, but given the absence of an output schema and the read-only nature, this is a minor gap. The description covers the core functionality but lacks sibling differentiation.

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 fully describes both parameters: proxy_id is the proxy identifier and range is an enum with 7d/30d and a default. Schema description coverage is 100%, so the description adds no new meaning beyond restating the time window. Baseline 3 is appropriate when the schema handles parameter documentation.

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 specifies a per-day traffic (GB) and request-count series for a single proxy over a 7 or 30-day window. It uses a specific verb 'Get' and resource 'proxy usage history', making the action unambiguous. However, it does not explicitly differentiate itself from the sibling virtualsms_get_proxy_usage, relying solely on the name 'history' to imply distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of conditions, exclusions, or references to sibling tools. Given the existence of virtualsms_get_proxy_usage, the description fails to clarify which tool is appropriate for current usage versus historical series, leaving the agent to infer without explicit direction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat that. It adds value by disclosing the exact response contents (including received SMS), which is helpful context not present in the schema or annotations. It does not contradict any 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?

Two sentences with zero waste. The first sentence front-loads the purpose and response details; the second gives actionable usage guidance. 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 simple single-parameter read-only tool, the description is complete: it lists the response fields, states the prerequisite for the ID, and the annotations cover safety semantics. 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?

The schema already fully documents rental_id ('Rental ID to retrieve') with 100% coverage. The description adds no extra meaning beyond that, other than implying the ID comes from list_rentals. Baseline 3 is appropriate because the schema does the heavy lifting and the description offers no additional parameter-level detail.

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 (get) and the specific resource (a rental by ID), then enumerates the concrete fields returned (tier, phone number, country, service lock, status, expiry, and any received SMS). It also differentiates from list_rentals by noting the prerequisite, making the tool's role unambiguous.

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

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

The description explicitly tells the agent when to use this tool versus the alternative: 'Use list_rentals first if you do not have the rental_id.' This is a direct, actionable usage guideline that names the sibling and the condition that selects between them.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations by disclosing the return contents (status, phone_number, messages[] array, extracted code) and the recommended polling cadence. The description 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?

Two sentences carry purpose, return shape, polling guidance, and sibling routing with zero filler. The core statement ('Check if an SMS verification code has been received for an order') is front-loaded, and every subsequent clause adds 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 one-parameter, read-only, idempotent polling tool, the description covers everything needed to invoke it correctly: what it does, what it returns, when to poll, and when to choose the alternative. Although there is no output schema, the description compensates by listing the returned fields, making the tool self-contained.

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 single parameter order_id is already fully documented as 'Order ID returned from create_order'. The description adds no extra parameter detail beyond the schema, which warrants the baseline 3 for high coverage. No compensation needed.

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 ('Check') and resource ('SMS verification code for an order'), making the tool's function clear. It also differentiates from the sibling tool wait_for_sms by explicitly naming it as the blocking alternative. An agent can immediately identify this as the non-blocking polling variant.

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 explicit when-to-use guidance: 'Poll this every 5-10 seconds after buying a number'. It also names the alternative ('wait_for_sms') and the condition that selects it ('to block until delivery'). This is model usage guidance for a polling 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=true and idempotentHint=true. The description confirms it is a read operation by stating it aggregated from order history, but it does not add further behavioral context beyond listing the output fields. It does not contradict annotations.

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

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

The description is a single, well-structured sentence that starts with the core purpose and lists specific data points returned. It is concise without unnecessary words, earning its place efficiently.

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?

Despite no output schema, the description lists key elements returned (total orders, success rate, total spend, top services/countries, status breakdown), providing a clear picture of the output. It does not specify format or units, but it is reasonably complete for a stats tool with a single optional input parameter.

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

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

The only parameter 'since_days' is fully described in the input schema (default 30, window in days). The description mentions a 'configurable lookback window' but does not add semantic value beyond the schema. With 100% schema coverage, 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 clearly states the tool returns aggregated usage stats including total orders, success rate, total spend, top services/countries, and status breakdown over a configurable lookback window. It distinguishes itself from sibling tools that handle individual orders, balances, or other specific operations.

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

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

The description implies usage for getting an overview of account activity, but it does not explicitly state when to use this tool vs alternatives like listing orders or checking balance. No explicit usage conditions or exclusions are provided, leaving the agent to infer context.

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 carry the safety profile (readOnlyHint, idempotentHint, destructiveHint false), and the description adds only the existence of optional filters without deeper behavioral details like pagination policy or result ordering. It is consistent with annotations but not additive.

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 delivers its purpose in one compact sentence and adds a second sentence for the type enum. It is front-loaded and free of filler, though the type list is redundant with 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 simple read-only list operation with full schema descriptions and optional parameters, the description provides sufficient context for a correct invocation. Without an output schema, some return-format detail is missing, but the tool is straightforward enough to remain complete.

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

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

Schema description coverage is 100%, so the description adds no real meaning beyond the structured fields. The phrase 'type, date range, and pagination' only paraphrases the schema, and the listed type values are already present in the enum.

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?

Description states the resource ('transaction history') and identifies the transaction types that distinguish it from order or usage history siblings. It lacks a standalone verb, but the title and context 'history for the account' make the retrieval intent clear.

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

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

No guidance is given on when to call this tool vs siblings such as virtualsms_order_history, virtualsms_get_proxy_usage_history, or virtualsms_get_balance. The description does not mention exclusions or preferences, leaving the choice to the agent's inference.

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

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

Annotations already provide comprehensive safety and idempotency hints. The description adds that it returns country codes and implies non-destructive, read-only behavior, but does not significantly extend beyond 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?

Two concise sentences with no wasted words. Front-loads purpose and usage. Every sentence is informative.

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 tool with one optional parameter and no output schema, the description adequately explains purpose, usage, and expected output (country codes). No gaps.

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

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

Schema coverage is 100% with one optional parameter. The description does not add meaning beyond the schema parameter description; it only mentions country codes. Per guidelines, 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?

Description clearly states 'Get all available countries for SMS verification.' It uses a specific verb and resource, and distinguishes from sibling tools like order and service listings.

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 explicitly advises using it to discover country codes before buying a number, providing clear contextual guidance. It does not specify when not to use or compare to alternatives, but the context is clear.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the description does not need to cover that ground again. It usefully adds that the tool surfaces pending orders and phone numbers, but it does not disclose ordering, limits, or whether the status filter changes the response shape. No contradiction with annotations.

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

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

Three short sentences, each earning its place: the primary action, the key use case, and the recommended follow-up tool. The most important information is front-loaded and there is no filler.

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

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

Given the low complexity, one optional parameter, rich annotations, and no output schema, the description provides enough context for an agent to select and call the tool. The only notable gap is the lack of explicit guidance on when to prefer order_history or get_order instead, but that is a minor omission.

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 optional status parameter is explicitly documented in the schema. The description adds no additional parameter meaning, but with full 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 clearly states a verb and resource — 'List your active orders' — and adds a concrete recovery use case. However, 'active' is not precisely defined relative to the status filter, which also includes cancelled and completed statuses. It also does not explicitly distinguish itself from the order_history sibling.

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 explicit context for when to use this tool: after a session interruption, to find pending orders and their phone numbers, followed by get_sms. It does not, however, state when not to use it or mention alternatives like order_history for historical lookups.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the content of the response (remaining GB, login credentials, proxy_id usage), but does not add further behavioral details such as pagination or auth requirements. This meets the lower bar set by rich 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?

Two sentences with no filler. The first sentence states the core purpose, the second lists downstream tools that consume the returned proxy_id, which is immediately useful. 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 tool is simple with no parameters, annotations cover safety, and the description explicitly mentions the output fields (remaining GB, login credentials) and role of proxy_id. The absence of an output schema is compensated by the description's clear statement of what is returned. 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?

The tool has zero parameters, so schema coverage is 100% and the description need not compensate. The description adds meaning by stating that it lists all proxies on the account, which clarifies the scope without any parameter-specific gaps.

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

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

The description states a specific verb ('List') and resource ('all proxies on your account') with details (remaining GB and login credentials). It also distinguishes itself from siblings like list_proxy_catalog and list_proxy_locations by specifying 'your account' and the downstream use of proxy_id.

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 clearly implies when to use the tool: to get proxy_id values for use with get_proxy_usage, rotate_proxy, set_proxy_targeting, and generate_proxy_endpoint. It gives clear context without explicitly saying when not to use alternatives like list_proxy_catalog, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds minor context about the contents of the catalog but does not disclose details like response format or whether data is live/static. No contradictions with 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?

Two short sentences with no filler. The main listing purpose is front-loaded, and the usage guidance is placed immediately after. Every word contributes.

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

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

Given the tool has no parameters, rich annotations, and a simple informational purpose, the description is complete. It states the content of the catalog and the recommended usage context, which is all an agent needs 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?

The tool has zero parameters, so parameter-level documentation is unnecessary. The description meaningfully indicates what will be returned (pool types, countries, price-per-GB), which is the only semantic context needed for a parameterless tool.

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

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

The description uses a specific verb ('List') and a clear resource ('available proxy pool types, countries, and price-per-GB'), which uniquely distinguishes this tool from siblings like list_proxies, list_proxy_locations, and list_services. It conveys exactly what information the catalog provides.

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 instruction 'Use this before buying proxy traffic' gives clear, actionable context for when to invoke the tool. It does not explicitly name excluded alternatives or contrast with buy_proxy/list_proxies, but the intended placement in the workflow is evident.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond annotations by stating 'Public endpoint, no purchase required' and the pool_type limitation ('Not available for residential_premium'). These are behavioral traits not covered by annotations, so the description enriches the agent's understanding. No contradictions found.

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 two sentences, with the primary purpose front-loaded in the first sentence and usage context/constraints in the second. There is no wasted wording, and it efficiently conveys the essential information an agent needs. It is appropriately sized for the tool's complexity.

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 tool has no output schema, but the description explains what it returns conceptually (cities, states, ASNs, ZIP codes for a given pool type + country) and why it is used. It also mentions the availability constraint. Given the moderate complexity and the annotations covering read-only/idempotent behavior, the description is complete enough for correct invocation. A minor gap is the lack of an explicit note about the output format, but that is not critical.

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 all three parameters (kind, country, pool_type) are documented in the schema. The description does not add parameter-specific details beyond what the schema provides, but it does clarify the purpose of the output (discovering location_code values), which implicitly ties to the parameters. Since the schema covers semantics, 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 ('List') and the resource ('available cities, states, ASNs, or ZIP codes') scoped by pool type and country. It explicitly distinguishes its purpose from siblings by noting it is for discovering valid location_code values before other tools like virtualsms_generate_proxy_endpoint and virtualsms_set_proxy_targeting. This is clear and unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use this to discover valid location_code values before calling virtualsms_generate_proxy_endpoint or virtualsms_set_proxy_targeting with sub-country targeting.' It also states a key constraint ('Not available for residential_premium'), which helps the agent decide when not to use it. This is explicit and actionable.

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, so the description does not need to restate safety. It adds behavioral value by clarifying that this is a summary list (specific fields) rather than full rental detail, and by noting the 'both tiers' scope. Pagination and ordering are not mentioned, but those are minor gaps for a simple list 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 two sentences with no filler: purpose, optional filter, returned fields, and sibling pointer are all included efficiently. The core action is front-loaded, making it easy to scan.

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 list tool with one optional, fully documented parameter and safety annotations, the description is complete. It states what the tool returns, how to filter, and where to go for full detail. No critical information needed 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?

Schema description coverage is 100%; the schema already defines status as an optional filter with allowed values and a default of 'active'. The description only restates 'optionally filtered by status' without adding new meaning, 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 and resource ('List your rentals'), states scope ('across both tiers'), and enumerates the returned fields. It also explicitly contrasts itself with get_rental ('Use get_rental for full detail on one'), making the tool's purpose unambiguous and distinguishable from its closest sibling.

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 names the key alternative, get_rental, and tells the agent to use that tool when full detail is needed. It also mentions the optional status filter. It does not enumerate exclusions for other sibling list tools like list_orders, but the main routing decision is 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 already provide readOnly, idempotent, and non-destructive hints. Description adds no additional behavioral traits beyond listing services, which is already clear from the name.

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 concise sentences, no verbose language, front-loads the core purpose with examples. Every word is useful.

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

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

Given the tool has only one optional parameter and no output schema, the description fully covers the necessary context: what it does and how to use 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?

Schema covers 100% of parameters with descriptions. The tool description does not add new semantic meaning beyond what the schema already provides for the 'search' parameter.

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?

Description clearly states it lists all available SMS verification services and provides examples (Telegram, WhatsApp, Google). It distinguishes from sibling 'search_services' by implying it returns all services without filters.

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?

Description explicitly tells when to use ('before buying a number') and hints at usage context, but does not contrast with sibling 'search_services' or specify when 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 indicate read-only, non-destructive, idempotent. The description adds valuable behavioral details: server cap of 50 orders and most-recent-first ordering. No contradictions.

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

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

Two sentences, front-loaded with purpose and filters, then limit and ordering. Every sentence is necessary and efficient.

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 filters and limit but does not specify the return structure of orders. Since there is no output schema, the agent may need to know what fields each order contains (e.g., order id, status, etc.). A more complete description would mention typical fields.

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

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

Schema description coverage is 100%, so baseline is 3. The description only summarizes the filters (status, service, country, since_days, limit) without adding new meaning beyond what's 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?

The description clearly states the tool lists past orders with optional filters, and mentions the server cap and ordering. However, it does not differentiate from the sibling tool 'virtualsms_list_orders', which may have a similar purpose, thus lacking sibling differentiation.

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 does not provide guidance on when to use this tool vs alternatives (e.g., virtualsms_get_order for a single order). It states optional filters but no when-not-to-use or explicit context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. It adds valuable context about what data is provided (available counts, pricing, per-country service counts) and how tier affects the data source (local vs. global supplier network). This goes beyond the annotations, though it could mention that the response is a list or that it may be empty, but the current level is sufficient.

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 two sentences, with the core purpose and key behavior front-loaded. It is efficient, but the second sentence could be seen as slightly dense with details (e.g., 'with per-country service counts and popular services'), though it's still concise. No waste, but the sentence structure is a bit packed. Still, it earns a 4.

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

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

Given the tool's moderate complexity, the description covers the main entry point (tier) and usage context ('before creating a rental'). The annotations cover safety and idempotency, and the schema covers parameters. There is no output schema, but the description explains what the tool returns (list of countries with stock, counts, pricing) so expectations are set. Some might argue it could mention that the output is a list, but it's clear enough. It's complete for an internal directory-like tool.

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

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

The schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning for the 'tier' parameter by explaining the difference between full_access and platform, which is not fully captured in the schema's terse 'Which tier to list'. For other parameters like 'type', 'country', and 'service', the description does not add further detail, but the schema covers them. Baseline 3 is appropriate since the schema carries the load.

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 'List countries with rental stock, available counts, and pricing,' which is a specific verb and resource. It also differentiates between the two tiers with distinct inventory sources, making it distinguishable from siblings like virtualsms_list_countries or virtualsms_rentals_pricing. The title is descriptive, and the description adds crucial details about what each tier returns.

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

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

The description provides clear guidance on when to use this tool ('Use this before creating a rental') and explains the meaning of the tier parameter choices ('full_access (default) shows local-SIM inventory; tier=platform shows countries available via our global supplier network'). It does not explicitly state when NOT to use it versus alternatives, but the context of 'before creating a rental' is helpful, and the sibling resolution is aided by the distinct purpose.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'catalog-driven retail price' context, which clarifies that the price comes from a catalog rather than a live quote. However, it doesn't disclose whether the price is guaranteed, whether it includes taxes/fees, or what happens if the combo is invalid. With annotations covering safety, a 3 is appropriate.

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

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

One sentence with zero waste. The core purpose is front-loaded, and the parenthetical parameter list is efficient. 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 simple read-only price lookup with 100% schema coverage and safety annotations, the description is mostly complete. However, it doesn't explain what 'platform-tier' means or how this differs from the sibling virtualsms_rentals_pricing tool. An agent might need to open sibling schemas to disambiguate. The lack of an output schema means the return format is unknown, but for a price lookup that's 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 description coverage is 100%, so the schema already documents all three parameters. The description adds the concept of a 'platform-tier rental combo' but doesn't add syntax or format details beyond what the schema provides. Baseline 3 is correct when schema does the heavy lifting.

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 ('Get') and resource ('catalog-driven retail price for a (service, country, duration) platform-tier rental combo'). It clearly distinguishes this from the sibling tools like virtualsms_rentals_pricing and virtualsms_get_price by specifying the platform-tier rental combo context. However, it doesn't explicitly name a sibling alternative, so it loses a point for not fully differentiating from similar pricing tools.

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

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

The description implies usage context: it's for getting a retail price for a rental combo, which is distinct from other pricing tools. However, it doesn't explicitly state when to use this tool versus alternatives like virtualsms_rentals_pricing or virtualsms_get_price. The context signals show many sibling tools, but the description provides no explicit when/when-not 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?

Beyond the annotations' readOnlyHint and idempotentHint, the description adds a critical behavioral caveat: the output is a raw catalog dump that may include non-purchasable rows and is not authoritative. This warns the agent not to treat the results as actionable inventory, which is exactly the kind of behavioral nuance annotations cannot convey.

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

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

Three compact sentences front-load the purpose, then provide the essential caveat, and finally route to alternatives. There is no filler or repetition; every sentence earns its place.

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

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

For a parameterless, read-only catalog tool with no output schema, the description covers everything an agent needs: what the tool returns, how reliable that data is, what to do before creating a rental, and which sibling tool to use for different pricing needs.

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 has zero parameters, so the baseline is 4. The description adds meaning by explaining what the returned catalog contains (local SIM inventory, durations, prices), even though there is no input schema to elaborate on.

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 all active rental pricing tiers,' and clarifies the content as local SIM inventory, durations, and prices for the Full Access tier. It also differentiates itself from the sibling tools by explicitly naming rentals_price and rentals_available as alternatives, making the tool's scope unmistakable.

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

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

The description gives explicit when-not-to-trust guidance: 'This is a raw catalog dump and may list rows that are not purchasable today, so confirm against rentals_available... before creating a rental.' It also directs agents to rentals_price for platform-tier per-country pricing, leaving no ambiguity about which sibling to use in which scenario.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful domain constraint beyond annotations — that platform-tier rentals are locked to ONE chosen service per number — which is material behavioral context. Consistent with calibration for annotation-covered read tools, a 3 is appropriate.

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

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

Three tight sentences with zero filler. The primary purpose and returned data are front-loaded in the first sentence, the critical lock constraint follows, and the usage directive closes it. 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?

Despite having no output schema, the description compensates by naming the returned data (physical stock counts and retail price) and explaining the platform-tier lock constraint. Combined with 100% schema coverage and rich annotations, an agent has what it needs to call this correctly. Only a more explicit return-format note would push it higher.

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 both parameters (country_code as ISO-2, duration_hours defaulting to 24) are already documented. The description only echoes the country scope ('in a given country') and adds nothing about format, syntax, or valid values beyond what the schema provides. Baseline 3 is correct when the schema carries the parameter documentation load.

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

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

States a specific verb ('List'), a precise resource ('services available for platform-tier rental'), and a scope ('in a given country'). It distinguishes itself from the sibling virtualsms_list_services by qualifying the platform-tier rental subtype and adds concrete detail about what is returned (physical stock counts and retail price). An agent can tell it apart from related rental tools without opening any schema.

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

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

The phrasing 'Use this to pick a valid service code before creating one' gives implicit workflow guidance that this precedes rental creation. However, it does not explicitly name alternative siblings (e.g., virtualsms_list_services for non-platform rentals, or virtualsms_rentals_available for available numbers) or state when NOT to use it, so the differentiation is inferred rather than explicit.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description doesn't need to restate those. The description adds valuable behavioral context: the order must be in waiting/created status, not all order types support retry, and some providers only support swap_number. This goes beyond the annotations and helps the agent anticipate failure modes.

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 carrying distinct information: the action, the precondition, and the alternative. No filler or redundancy. The most important constraint (same phone number) is front-loaded.

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

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

For a single-parameter tool with no output schema, the description covers the action, precondition, and alternative. It doesn't describe the response format, but with no output schema and a simple order_id parameter, this is a minor gap. The description is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% (order_id is described as 'Order ID to retry'), so the schema already documents the parameter. The description adds context about the order status requirement but doesn't add new parameter-level detail beyond what the schema provides. 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 clearly states the action ('Ask the provider to resend the SMS'), the target resource ('existing order'), and the key constraint ('to the SAME phone number'). It also distinguishes itself from the sibling tool virtualsms_swap_number, which returns a NEW number, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool: when the order is in waiting/created status and the goal is to resend to the same number. It also provides an explicit alternative: 'Some providers only support swap_number instead, which returns a NEW number.' This gives clear routing guidance.

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

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

Annotations already indicate this is a mutating, non-idempotent operation (readOnlyHint=false, idempotentHint=false). The description adds the behavioral context that it requests a fresh IP, implying the old IP is replaced. It doesn't disclose details like whether the old IP is permanently lost or if there are rate limits, but the annotations cover the core safety profile.

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 with no wasted words. The core action is front-loaded, and the use case is stated in the second sentence. 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 simple 2-parameter tool with full schema coverage and annotations covering the mutation profile, the description is nearly complete. It could mention what the response contains (e.g., new IP) but no output schema exists, so a brief note on return value would be a minor improvement.

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 both parameters. The description adds the context that proxy_id comes from list_proxies or buy_proxy, which is helpful, but doesn't add meaning beyond what the schema provides. 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 clearly states the action ('Request a fresh IP'), the resource ('an existing proxy'), and the use case ('when an endpoint flags the current exit IP'). It distinguishes itself from sibling tools like buy_proxy or list_proxies by focusing on rotation of an existing proxy.

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 a clear context for use ('when an endpoint flags the current exit IP'), which implies the tool is for remediation of blocked IPs. It doesn't explicitly state when not to use it or name alternatives, but the context is specific enough for an agent to select it appropriately.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds value by stating it returns 'matching services with similarity scores', which provides behavioral context beyond the annotations. No 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?

Two sentences, zero wasted words. The purpose is front-loaded, and every sentence contributes meaning. Excellent for its length.

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

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

Given the tool's simplicity (one param, no output schema), the description is complete: it explains what the tool does, when to use it, and what the response contains (matching services with scores). No gaps.

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

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

Schema coverage is 100% with a single parameter 'query' well-described as 'Natural language search query'. The description reinforces this but adds no new semantic information. 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 clearly states the tool's purpose: 'Find the right service code using natural language.' It uses a specific verb ('search') and resource ('service code'), and distinguishes from siblings like virtualsms_list_services by focusing on name-based search.

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 explicitly advises using the tool when the exact code is unknown, with examples like 'uber', 'binance', 'steam'. It does not explicitly list alternatives or when not to use, but the context of sibling tools (e.g., list_services, find_cheapest) provides implicit differentiation. A clear 'when-not' would improve this.

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 (non-read-only, idempotent), the description discloses that this changes the STORED default—a persistent side effect—and explains the billing implications (2x on own allocation vs included on residential_premium). This is exactly the behavioral context an agent needs beyond the structured annotations.

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

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

Three sentences, zero filler. The core action is front-loaded, followed by billing nuance, then the key persistence warning and routing to the sibling tool. 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 covers what the tool does, the persistent side effect, billing impact, and the alternative for one-off use. There is no output schema, but nothing essential for correctly selecting or invoking the tool is missing.

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

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

Schema coverage is 100%, so schema already documents each parameter clearly. The description adds value by explaining the billing consequences of cities/ASNs versus country-only, and by noting that state/zip targeting is only available via the alternative tool, which helps an agent decide what to pass.

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 ('Persist') and resource ('default geo-targeting on an existing proxy sub-user'), making the action unmistakable. It also distinguishes itself by contrasting with virtualsms_generate_proxy_endpoint, which is the one-off connection-string 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 explicitly states when to use this tool (persisting a stored default) and when not to ('For a one-off connection string ... use virtualsms_generate_proxy_endpoint instead'). It also gives billing context that affects whether this tool is the right choice depending on the pool type.

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?

Adds access constraints (Beta, invite-only), explains that this starts a browser the user can watch and drive via an authenticated viewer_url, and clarifies that agent-driven navigation is not part of this call. The annotations already signal mutating/open-world behavior, and the description adds live-viewer semantics without contradicting them. It could mention session lifecycle or cleanup, but this is substantial added context.

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

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

Three sentences, front-loaded with the essential start action and deliverable, followed by routing guidance and a pairing tip. There is no filler or repetition of schema fields. The first sentence is dense and could be parsed more cleanly, but each sentence earns its place.

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

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

For a 9-parameter tool with no output schema, the description covers the core purpose, output link, and relationship to create_order, but leaves gaps around session lifecycle, how to use viewer_url, and the semantics of attach vs fresh mode. Those gaps matter for correct invocation, so the description is adequate but not fully 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?

The input schema covers all 9 parameters with descriptions and enums, so the baseline is 3. The description enriches 'country' with country-matched proxy logic and hints at order_id relevance via optional order phone number and timeline, but it does not explain mode attach/fresh, run_prep, or prep_preset beyond the schema. Thus it offers only a small increment over the structured data.

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—starting a country-matched cloud browser for manual takeover—and names the key deliverable, viewer_url. It also distinguishes itself from agent-driven navigation tools and positions itself relative to create_order. There is no ambiguity about what this tool does.

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

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

Clearly frames manual takeover as the intended use case and tells the agent that agent-driven navigation belongs to separate opt-in session tools, establishing a when-to-use boundary. Pairing guidance with create_order gives a concrete invocation context. However, it does not name the session sibling tools explicitly or explain attach vs fresh selection, so the guidance is strong but not exhaustive.

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 indicate a non-read-only, non-destructive mutation, and the description adds meaningful behavioral context: the 120-second cooldown, the cooldown_active error returned locally, the no-additional-charge guarantee, and the no-backend-round-trip detail. No contradiction with 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?

Four well-structured sentences, front-loaded with the core action and outcome, followed by a bolded cooldown warning and error behavior. Every sentence earns its place with no fluff.

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

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

For a low-complexity, one-parameter mutation tool, the description covers use case, preconditions, cost implication, cooldown, and error behavior. The only minor gap is that it doesn't explicitly state what happens to the old number or what a successful response contains, but the operation's effect is reasonably implied.

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 order_id parameter is already described with its status requirement. The description adds no parameter-specific meaning 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?

The description uses a specific verb and resource ('Swap a phone number on an existing order') and explains the concrete outcome ('Gets a new number for the same service and country without additional charge'). This clearly distinguishes it from sibling tools like create_order, retry_order, and cancel_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 explicitly states when to use the tool ('Use when the current number isn't receiving SMS') and gives a concrete precondition ('Check swap_available_at on the order before calling'). It does not name alternative tools or when-not-to-use scenarios, so it stops 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?

Beyond the annotations, the description discloses that the tool 'Consumes a small amount of the proxy's GB allocation' and is 'Rate-limited to about once per 20 seconds per proxy.' These are useful behavioral traits not captured by the schema or annotations.

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

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

The description is three sentences with no wasted words. The primary action and result are front-loaded, and the behavioral caveats are stated compactly at the end.

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

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

There is no output schema, so the description appropriately lists the expected report fields: exit IP, country, city, ISP, and latency. It also covers resource consumption and rate limiting, making the tool sufficiently understandable 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 fully documents all four parameters. The description adds no additional parameter-level guidance, keeping it at the baseline.

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: 'Make one request through a proxy and report the exit IP, country, city, ISP, and latency.' This clearly identifies the tool's function and scope, distinguishing it from sibling tools like rotate_proxy or buy_proxy.

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 states clear usage context: 'Proves the proxy works and which country it exits from.' This tells an agent when to use the tool, though it does not explicitly name alternatives or exclusion conditions.

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

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

Goes well beyond annotations: warns this call BLOCKS for up to timeout_seconds, gives typical delivery latency (~10-60s), and discloses the WebSocket + polling-fallback delivery mechanism. readOnlyHint/idempotentHint already cover safety; description adds operational 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?

Description is compact and front-loaded with the blocking behavior and timeout, then mechanism and usage. A slight redundancy between 'Wait (block)' and the later 'BLOCKS' sentence is minor.

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 blocking wait tool with rich annotations and fully documented params, it covers what the call does, how long it may block, and how delivery is detected. The one gap is no statement about what is returned on timeout, which matters since no output schema exists.

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

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

Schema covers both parameters with descriptions, defaults, min/max (100% coverage), so baseline applies. Description mostly restates timeout bounds and the order_id origin already in schema, adding no new parameter 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?

States a specific operation: wait/blocks on an existing order_id until SMS arrives or timeout. The resource and behavior are unmistakable, though it stops short of explicitly differentiating from the get_sms sibling (e.g., 'if you only need to read once, use get_sms').

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 to pass an order_id from create_order and describes the buy-and-wait workflow ('call create_order then this tool'). It gives clear context and prerequisites, but no when-not-to-use guidance versus get_sms/retry_order.

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