doctorSIM

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

Beyond annotations, it discloses that PRO creates debit prepaid credits, return order_id/status/credits_used, email confirmation behavior, sandbox fake-order behavior, and checkout display constraints. It also explains idempotency safety and discourages promising an in-chat QR for guests.

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 dense but front-loads the alias and guest/PRO workflow, and most sentences carry operational value. A slightly clearer structural separation between usage, output display, and retry guidance would improve scanability.

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

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

For a financial order-creation tool, it covers guest vs PRO flows, preview behavior, idempotency, error recovery, sandbox behavior, and customer-facing output constraints. With an output schema available, it does not need to restate return structures.

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 only 33%, and the description does not explain the critical required catalog_id or price_token parameters, nor lang/currency usage. It adds some practical context for idempotency_key, but does not compensate for the undocumented required inputs.

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 create action for an eSIM order and explains it is an alias of create_order with type=esim. This clearly distinguishes it from sibling preview/order-status tools while acknowledging its legacy connector role.

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

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

It gives explicit routing: guests can call without Authorization after choosing a plan with optional preview, while PRO OAuth users should preview first then create. It also names fallback siblings list_orders/get_order_status when order_id is missing and warns never to re-create.

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 two distinct account paths (Consumer returns payment_link; PRO debits retail_eur and returns order_id/credits_used), the insufficient-wallet behavior (INSUFFICIENT_CREDITS with no debit), and idempotency semantics (replay does not double-debit). These are the exact traits an agent needs before committing a priced, credit-consuming 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?

Purpose is front-loaded and nearly every sentence carries operational signal; no filler. It is telegraphic and dense ('Fulfilment is is_topup (no new QR)'), which is efficient but slightly reduces scannability.

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

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

With an output schema present, return-value detail is arguably redundant, but the description covers auth, error mode, idempotency, and fulfilment type for a financially consequential mutation. It omits edge cases such as an expired price_token or a non-titular ICCID mismatch.

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?

At 67% schema coverage the schema already documents iccid, catalog_id, price_token and idempotency_key; the description adds provenance constraints on catalog_id/price_token and the no-double-debit meaning of the key. The lang and currency enums remain unexplained in both places, which is the only real gap.

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

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

States a specific verb and resource ('Create an eSIM top-up for a titular-owned ICCID') and implicitly separates itself from create_esim_order / create_order via 'Fulfilment is is_topup (no new QR)'. An agent can distinguish top-up of an existing line from a new order without opening either schema.

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

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

Gives the precondition (ICCID must be titular-owned), the upstream dependency (catalog_id + price_token from get_esim_topup_plans), and the auth requirement (OAuth orders:write). It stops short of an explicit exclusion naming create_esim_order for new lines, so the alternative routing is inferred rather than stated.

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

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

Annotations only say non-readOnly, non-destructive, closed-world; the description adds substantial behavior beyond that — idempotency semantics (same key returns the original order, no second charge), what success returns (order_id, status, credits_used), payment-rail rules (PRO credits beat stripe_link, STRIPE_LINK_DISABLED has no silent fallback), and explicit display prohibitions (never show checkout_hash, only payment_link/order_id). This is exactly the mutation-context an agent needs.

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

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

Front-loaded with the core action and routing rule, then layered with operational constraints. It is dense and slightly sprawling in the middle (payment-gateway warning, display rules, account linking), but nearly every clause carries a decision the agent must make.

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 12-parameter mutation tool with an output schema, this covers the remaining gaps: vertical inference, guest vs PRO flow, retry/ambiguity handling, multi-SKU behavior, and display constraints. Nothing essential to calling it correctly is left unstated.

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 92%, so the baseline is 3. The description still adds real value on top: price_token only for gift cards with no phone and no country_id, and a distinct idempotency_key per SKU — cross-field constraints the schema documents per-property but not jointly.

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+resource ('Place the order') and immediately clarifies scope: one tool covering every vertical, with `type` inferred from price_token/catalog_id. An agent can tell what it does and how vertical routing works without opening the schema.

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

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

Gives concrete when-to-call guidance: guest/consumer calls as soon as the product is chosen (preview optional), OAuth PRO must preview first with the same body. It also covers multi-SKU (N calls, distinct idempotency keys) and the ambiguity fallback to list_orders/get_order_status. It stops short of naming the sibling tools it overlaps with (create_esim_order, create_esim_topup, preview_order), so the agent must infer why those exist alongside this one.

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 this is a read-only, non-destructive, closed-world operation, so the description earns credit for the extras it adds: the required OAuth scope (balance:read), the account-linking precondition, and the EUR denomination. It stops short of saying what happens when preconditions fail (error shape or empty result), which would round out the behavioral picture.

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 with no filler. The eligibility constraint and the negative guardrail are front-loaded before the softer prerequisite 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?

With an output schema present, the description needn't explain return values, and it covers auth scope plus the account-linking requirement. The only meaningful gap is failure behavior when the caller is not PRO or has no linked account, which matters given the explicit guest-flow warning.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify. The description correctly spends no words on argument semantics and instead invests in preconditions.

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

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

States a specific verb and resource ('Returns the authenticated PRO user prepaid credit balance in EUR') and scopes it to a named audience. This is clearly distinguishable from siblings like guest_order_lookup or list_orders, which deal with orders rather than account balance.

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

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

Gives explicit eligibility ('PRO accounts only'), an explicit exclusion ('do NOT call for guest checkout flows'), and the prerequisite (linking a doctorSIM account). An agent has everything needed to decide whether to call this or fall back to another path.

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 read-only, non-destructive annotations already establish the safety profile. The description adds useful scope by naming the three service lines, but it does not disclose pagination, filtering, or return-shape details; an output schema exists, so return values need not be described.

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 efficient sentence that front-loads the verb and resource. No words are wasted, and the service categories are stated compactly.

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 zero parameters, an output schema, and annotations covering read-only behavior, the description is largely complete. It states the tool's scope but leaves a small gap by not clarifying how this country list differs from the eSIM-destination and operator-rate siblings.

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. There are no parameter semantics to explain, and the description correctly does not invent any.

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 clear verb and resource: 'List countries available for top-up, travel eSIM, and gift card services.' It distinguishes the tool's scope from purely eSIM-focused siblings, but it does not explicitly contrast with get_esim_destinations or get_operator_rates, which also return geographic coverage data.

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

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

Usage is implied by the service categories mentioned, but there is no explicit guidance on when to choose this tool over get_esim_destinations, get_operator_rates, or get_giftcard_brands. The agent must infer that this is the broad country-list tool rather than a service-specific lookup.

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 readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that results include starting prices and both country and regional/global coverage, which is moderate additional context. It does not explain pagination, price currency, or result ordering.

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

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

It is short and front-loaded: purpose and output content come first. But the entire second sentence is spent on a parameter that is not in the schema, so part of this brevity is wasted and misleading rather than 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?

With an output schema, read-only annotations, and a single fully described parameter, most of the burden is handled elsewhere. Still, the description leaves unclear what the tool actually returns per destination and how the nonexistent country_iso relates to the real coverage_type filter.

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% for the single coverage_type parameter, so the baseline is 3. But the description instead documents a 'country_iso' parameter that does not exist in the schema, which actively misleads about how to call the tool rather than supplementing 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 verb and resource are specific ('List travel eSIM destinations'), and it distinguishes itself from the get_esim_plans sibling by noting that results carry starting prices. However, the scope is muddied because it describes a country_iso input that this tool does not accept.

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 sentence 'Use it for get_esim_plans' implies this tool is the discovery step before fetching plans, which is useful routing. But the phrasing is vague and never states when not to use it or how coverage_type filtering changes the choice.

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 cover the read-only, non-destructive, closed-world profile, so the bar is lower, and the description still adds real behavior: OAuth requirement, a five-minute provider-refresh throttle, and the fact that the line is identical across devices. It doesn't explain error or not-found behavior, so not a 5.

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

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

Four dense sentences with the core lookup and key constraint front-loaded; no wasted framing. A few phrases ('titular-owned', the parenthetical snapshot list) are slightly jargon-heavy but still 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 two-parameter read tool with an output schema, this covers everything an agent needs: source of the ICCID, auth requirement, refresh semantics, and even a preview of the nested consumption payload. Nothing material is left out.

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 both parameters are already documented, so the baseline is 3. The description echoes the refresh throttle and the ICCID provenance but adds no format or syntax detail the schema lacks.

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 (look up) and resource (remaining data for an eSIM line) keyed by ICCID, and explicitly anchors it to get_order_status as the upstream source. That anchoring distinguishes it from the sibling get_order_status and from the plan/order 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 says where the ICCID must come from (a fulfilled get_order_status) and that OAuth is required, which is genuine usage context. It does not name an explicit when-not-to-use case or a competing alternative, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that the response is the 'full detail' and mentions two fields (price_token, unlimited), which is thin given an output schema 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?

A single front-loaded sentence with no filler. The trailing mention of price_token and unlimited is slightly wasteful since an output schema already describes the return shape.

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, non-destructive lookup with annotations and an output schema, the description covers the essentials. The unlabeled localization parameter (lang) and any error behavior for an unknown catalog_id are left unexplained.

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 50%: catalog_id is already documented in the schema as coming from get_esim_plans, and the description simply restates that keying. The lang parameter (enum en/es) is undocumented in both places, so the description does not compensate for the coverage gap.

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 action (fetch full detail) on a specific resource (one eSIM plan) keyed by catalog_id, which implicitly contrasts with the bulk get_esim_plans sibling. It stops short of naming the sibling explicitly, so an agent must infer the single-vs-list distinction from the wording.

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 'by catalog_id' phrasing implies this is called after listing plans to drill into one entry, but no when-to-use or when-not-to-use guidance is stated and no alternative is named. Usage is inferable rather than instructed.

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 readOnly/openWorld=false and non-destructive, so the safety profile is covered. The description adds non-obvious behavior beyond that: the strict matching rule that silently excludes regional plans, and the default-inclusive filter semantics — both are things an agent would otherwise get wrong.

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 front-loaded sentences with the matching pitfall placed early, where it matters most. The sentence enumerating catalog_id, price_token, and unlimited is partially redundant given an output schema exists, but it is short enough not to be a real cost.

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?

Annotations and an output schema carry much of the burden, and the description covers the highest-risk parameter well. However, for a 5-parameter filtering tool with three enum parameters, leaving coverage_type undocumented and lang/currency undefined is a noticeable gap an agent cannot resolve from the schema alone.

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 40%, so the description must compensate and only partly does. It thoroughly explains country_iso's strict-match behavior and the data_type default ('omit or all returns both'), but lang, currency, and coverage_type receive no mention anywhere — coverage_type in particular is a bare string with no enum and no explanation.

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?

Opens with a specific verb and resource ('List publishable travel eSIM plans for a destination') and scopes the result set with 'publishable'. It implicitly separates itself from get_esim_plan_detail and get_esim_topup_plans via the list-vs-detail distinction, but never names a sibling explicitly.

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

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

Gives actionable routing logic: use ISO-2 for a single country, region slugs (eu, ww, as) for regional or global coverage, and clarify that 'es' will not return EU/global plans. That is a real usage rule most tools lack, though no alternative tool is named for the detail-heavy case.

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 destructiveHint=false, so safety is covered; the description goes further by disclosing the OAuth scope 'orders:read' and that the signed price_token is bound to catalog retail_eur, the same amount PRO credits debit. That is real behavioral context an agent cannot get from the structured fields, though it doesn't cover failure modes or what happens for non-PRO accounts beyond the credits hint.

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 compact sentences, purpose front-loaded, with the ownership constraint and auth requirement following. No filler; every clause (no custom amount, price_token semantics, PRO checkout_mode, OAuth scope) carries information an agent needs.

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

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

An output schema exists so return structure needn't be spelled out, and the description still flags the salient returned fields (catalog_id, signed price_token, checkout_mode). Combined with the auth scope and ownership constraint, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: 'titular-owned' narrows which ICCID is valid (ownership constraint not in the schema's 'original eSIM line'), and it ties price_token to retail_eur, clarifying what the currency parameter actually affects. The lang parameter is left to its enum-only schema description.

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

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

States a specific verb and resource ('List the exact doctorsim.com top-up packs') scoped to a titular-owned eSIM ICCID, which separates it from the generic plan-listing siblings like get_esim_plans and from the purchasing tool create_esim_topup. The '(same order as Mi Cuenta)' note pins down the exact catalog view the agent will get.

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

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

The phrase 'No custom amount' implicitly excludes custom top-ups, and the ICCID requirement implies it is a pre-purchase lookup for an existing line. However, it never explicitly says when to use this instead of get_esim_plans, get_esim_plan_detail, or when to follow with create_esim_topup, so routing must be inferred.

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 destructiveHint=false, so safety is covered. The description adds genuine behavioral value beyond that: the quota-token flow and the constraint against passing a phone number. It does not cover rate limits or pagination, so it stops short of a 5.

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

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

Two dense sentences with zero filler, front-loaded with what the tool returns before the downstream workflow. Every clause carries actionable 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?

An output schema exists so return values needn't be explained, yet the description still summarizes them usefully and completes the picture with the follow-up call pattern and the phone-number restriction. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 67% and the description reinforces the two important linkages: brand_id comes from get_giftcard_brands, and the returned token is the price_token used downstream. It leaves q and lang unaddressed, though those are self-documenting in the schema (lang has an enum, q has its own description).

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?

Names the exact resource (gift card denominations for a brand) and enumerates the return fields — token, service fee, total per price point — so an agent knows precisely what it gets. It is clearly distinguishable from the sibling get_giftcard_brands, which supplies the brand list rather than denominations.

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 tells the agent to source the brand argument from get_giftcard_brands (id_operator) and to chain into preview_order / create_order using price_token only. It also states a hard exclusion: never send a phone for gift cards. This is exactly the when/how/when-not guidance the dimension rewards.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavior the annotations don't: pagination semantics tied to meta.cursor and meta.has_more, and the fact that each result row is an id_operator rather than a self-contained brand.

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-loaded with purpose, then the downstream handoff, then pagination mechanics. No filler or restatement of the tool name.

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

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

An output schema exists, so return-value detail is not required, and the description still flags the two fields an agent actually needs from the response (meta.cursor, meta.has_more). For a paginated read-only list tool this is nearly complete; only minor gaps remain around the uncaptioned lang enum and country format.

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

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

With 80% schema coverage the baseline is 3, and the description earns above that by explaining the pagination loop concretely ('pass cursor=meta.cursor when meta.has_more is true') and by defining what the returned identifier means. It does not clarify the country format or lang values, but the schema covers country and the enum is self-explanatory.

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

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

States a specific verb and resource ('List gift card brands') with the scope ('for a country') and the categorical content (gaming, streaming, retail). It also explicitly differentiates itself from the sibling get_giftcard_brand_products by naming it as the next step, so an agent can route correctly without inspecting schemas.

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

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

Gives a clear use context ('no phone number involved') and an explicit handoff ('pass it to get_giftcard_brand_products for denominations and price tokens'). It does not state when-not-to-use or position itself against search_products, so it stops short of the 5 bar, but the next-step guidance is strong.

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 destructiveHint=false, but the description adds important behavioral context: rates include product_name, description, and a token; totals are indicative; and preview_order must be called for the authoritative breakdown. This goes beyond the safety profile and tells the agent how to interpret and act on the results.

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

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

The description is front-loaded with the core purpose and then provides tightly scoped guidance. Every sentence adds actionable information; there is no restatement of the tool name or schema fields without added 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?

An output schema exists, so return values need not be fully explained. Still, the description usefully mentions the rate fields and token semantics, the indicative-total caveat, and the preview_order dependency, making the definition complete for correct invocation and downstream workflow.

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 75%, so baseline is 3. The description adds useful meaning for operator_id (comes from get_operator_service_types) and q (keyword search on descriptions with an example), though the lang parameter remains unexplained in both schema and description.

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 and resource: 'Get live pricing for an operator.' It clearly distinguishes this tool from sibling operations by noting that returned tokens feed preview_order/create_order and that preview_order is required for authoritative totals.

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 says to use operator_id from get_operator_service_types for the chosen service type, recommends q for description searches with an example, and directs the agent to call preview_order before user confirmation. These are clear when-to-use and when-to-defer instructions involving named alternatives.

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 openWorldHint=false, so safety and closed-world nature are covered structurally. The description adds only the country_id provenance dependency; it says nothing about coverage gaps (country with no operators) or pagination, and an output schema exists so return shape needn't be explained.

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

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

One short sentence, purpose front-loaded, with the dependency and usage trigger packed in without filler. Nothing here is redundant or padded.

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 tool with full schema coverage, an output schema, and annotations carrying the safety profile, the description covers purpose, prerequisite source, and usage trigger. Only edge-case behavior (empty results, whether the list is filtered by country availability) is unaddressed.

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 parameter is already documented as 'id_country from get_countries'. The description merely restates that provenance, adding no syntax, format, or validation detail beyond the schema.

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

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

States a specific verb and resource ('List mobile operators for a country') and ties the scope to a sibling input ('uses id_country from get_countries'), so an agent can distinguish it from get_countries and the rate/service-type siblings without opening a schema.

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

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

Gives an explicit trigger ('use when carrier lookup failed or the user already knows the operator'), which implicitly positions lookup_carrier as the fallback path. It doesn't name that sibling outright or state a when-not-to-use case, so it falls short of a 5.

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

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

Annotations already declare this is a read-only, non-destructive, closed-world lookup, so the description needn't restate safety. It adds meaningful behavioral context by explaining the downstream sequencing and the crucial nuance that each returned service type carries its own id_operator for rate lookup. It doesn't discuss caching or output formatting, but the output schema covers return structure.

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 purpose and sequencing are front-loaded, and the description is short enough to scan. However, the final sentence repeats the get_operator_rates routing already implied by the preceding sentence about each type's own id_operator, adding mild redundancy.

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

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

For a simple read-only lookup with an output schema, the description covers the essential preconditions, downstream routing, and the key id_operator nuance. It is nearly complete, with only minor room for elaboration about the return shape or error cases, which the output schema largely handles.

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 is already fully documented in the schema as the id_operator from lookup_carrier or get_operators. The description reinforces that operator_id is the parent/airtime operator identifier and warns that returned service types have their own id_operator, but the parameter itself is not elaborated beyond the schema.

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

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

The description states a specific verb and resource: list available recharge/service types for an operator after carrier lookup. It explicitly distinguishes the result from sibling tools by explaining that each service type has its own id_operator and that get_operator_rates should be called with the matching 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?

It gives an explicit precondition ('After carrier lookup'), names the follow-up tool (get_operator_rates), and even prescribes the user-facing question to disambiguate airtime, bundles, or data. The workflow from lookup to service-type selection to rates is fully specified.

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?

With readOnly/non-destructive already declared by annotations, the description still adds substantial context: IDs are enumerable without OAuth, the hash is unguessable, idempotency recovery is scoped to 24h on the same account, and provider refresh is throttled when the last check is under five minutes old. Those are behavioral traits no annotation conveys.

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

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

Front-loaded with purpose, then callers, then recovery path, then return payload; sentences are dense and mostly load-bearing. It runs long and the return-value enumeration overlaps with the existing output schema, which slightly dilutes focus.

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 four optional params, full schema coverage, an output schema, and read-only annotations, the description covers everything an agent needs: which key to use, what happens on timeout, and what a fulfilled eSIM/gift card response 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?

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining precedence (payment_link over checkout_hash), the OAuth constraint on order_id, and the timeout-recovery workflow where idempotency_key substitutes for a missing order_id. It doesn't add format specifics but adds real decision logic.

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?

Opens with a specific verb+resource ('Check order or checkout status') and immediately segments the operation by caller identity (guest vs OAuth/PRO). It clearly signals this is a status-read tool distinct from create/preview siblings, though it never acknowledges the sibling 'guest_order_lookup', which could be a competing path for the same guest use case.

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 states which identifier to pass per caller type, marks payment_link as '(preferred)', and gives concrete prohibitions: don't pass sequential order_id without OAuth, don't ask the buyer for the hash, never re-create after a timeout. This is near-complete when/when-not/alternative 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 mark this as a safe read operation, but the description adds meaningful context beyond them: no login is required, both invalid email and invalid ticket return the same generic ORDER_NOT_FOUND error, and a different endpoint still requires OAuth. These details materially help an agent understand auth and error 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?

Four short sentences, front-loaded with the core purpose and followed by usage guidance and behavioral notes. Every sentence contributes useful information with no repetition or 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?

The output schema exists, so return values need no explanation. Annotations cover safety, and the description covers the remaining critical concerns: authentication, error behavior, and when to prefer the sibling tool. The only minor omission is the optional lang parameter, but that is not essential 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 description reinforces the meaning of the required parameters (buyer email and user-visible ticket/order_id), but the schema already documents both. With only 67% schema description coverage, the optional 'lang' parameter (enum en/es) is left unexplained in both schema and description, so the description does not fully compensate for the gap.

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

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

States a specific verb and resource ('Guest order status') and a precise fallback condition ('when checkout_hash is gone'), which clearly distinguishes it from get_order_status. An agent can identify the tool's purpose without opening the schema.

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

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

Explicitly names the preferred alternative ('Prefer get_order_status with payment_link when the hash is still known') and states the no-login condition. It also clarifies that wrong email or ticket both return a generic error, setting expectations for failure modes.

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 readOnly; the description adds real value beyond them — OAuth requirement, no provider call for balance_amount, and what type=esim rows include (iccid, install_url, qr_code_url). Doesn't cover rate limits or pagination, so not a 5.

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

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

Front-loaded with the core action and auth constraint; sentences are dense but mostly earn their place. The final 'decode nested consumption' sentence is somewhat cryptic.

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

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

An output schema exists so return values needn't be explained, yet two of three parameters (limit, delivery_status) remain undocumented in both schema and description. Adequate for the main use case but with clear 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 0%, so the description carries the burden. It explains type=esim enrichment and the balance_amount/list semantics, but leaves the topup/giftcard enum values, limit, and delivery_status undocumented. Partial compensation.

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

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

States a specific verb and resource — list completed or refunded orders for the authenticated user — and the OAuth/guest-checkout constraint implicitly distinguishes it from guest_order_lookup and get_order_status. Clear, though it doesn't name siblings explicitly.

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

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

Specifies the condition (authenticated user, no guest checkout), which routes guest flows to guest_order_lookup. Lacks explicit exclusion wording or direct sibling naming, but 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=true and destructiveHint=false, so safety is covered. The description adds what annotations cannot: the account tier and OAuth scope prerequisites needed before the call will succeed. It doesn't mention pagination or result limits, but the output schema covers return shape.

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

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

Three short sentences, front-loaded with the hardest constraint (PRO-only, scope required). 'Requires OAuth' partially repeats the scope mention, a small redundancy, but nothing is wasted beyond that.

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

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

For a no-argument read tool with full annotations and an output schema, the description covers the main remaining risk: auth and tier prerequisites. It could note pagination behavior or empty-list semantics, but nothing critical for correct invocation is absent.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. No parameter claims are missing or misleading.

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

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

The description names a specific verb and resource ('Lists registered webhook subscriptions'), so an agent can immediately tell this is a webhook-enumeration read. It doesn't need sibling differentiation because no other sibling touches webhooks, but it also doesn't disambiguate beyond the resource name.

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 eligibility constraints (PRO account, webhooks:read OAuth scope) that gate usage, which is genuinely useful routing information. However, it never states when to call this versus other listing tools or any exclusions, so guidance is implied 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it returns id_operator and id_country for downstream steps and tells the agent to ask the user on failure.

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 four short sentences with no wasted text. The primary instruction to call it first for phone-number top-ups 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?

An output schema exists, so the description does not need to fully explain return values, though it helpfully names id_operator and id_country. The only meaningful gap is that lang is not explained anywhere, despite being an enum 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 required phone parameter is documented in the schema with E.164 format and an example, and the description reinforces that format. However, the lang parameter is an enum with no description in the schema or the tool description, leaving half the parameters undocumented.

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: identify the mobile carrier and country from a phone number. It also distinguishes this lookup from sibling listing tools like get_operators and get_countries by tying it directly to a phone-number input and top-up flow.

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

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

It gives explicit sequencing guidance: ALWAYS call this FIRST when the user provides a phone number for a top-up. It also specifies a fallback action if lookup fails, asking the user which carrier/network the number uses.

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 readOnly/non-destructive annotations, it discloses that no credits are deducted, that guests can call it without Authorization, and that sandbox keys (test_*) route to the sandbox catalog. These are non-obvious behavioral traits an agent could not infer from structured fields.

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

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

Front-loads the alias relationship and preconditions in short, purposeful sentences. Slightly dense with parentheticals, but every sentence carries information; 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?

Auth, cost, and sandbox behavior are covered well, and an output schema exists so return values need not be restated. However, with 0% schema description coverage, the description leaves all four input parameters unexplained, which is a material gap 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 0% and the description explains none of the four parameters (catalog_id, price_token, lang, currency). The mention of return fields (data_gb, checkout_mode, unlimited) does not inform input semantics, leaving required catalog_id/price_token meaning undocumented.

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

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

States a specific verb and resource ('Preview a travel eSIM order without placing it') and explicitly frames itself as an alias of preview_order scoped to type=esim. An agent can distinguish it from preview_order and from the mutation sibling create_esim_order without opening any schema.

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

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

Gives clear usage context: callable by guests without Authorization, no credits deducted, and the 'kept for existing connectors' note implies new callers should prefer preview_order with type=esim. It stops short of an explicit when-not/alternative statement, so not a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that ('WITHOUT placing an order'). Beyond the annotations it adds real context: it surfaces the credit debit that a subsequent create_order would incur, and notes the extra travel-eSIM return fields (unlimited, data_gb). It stops short of stating error/expiry behavior for an invalid or stale price_token, which is the main remaining gap.

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 key constraint ('WITHOUT placing an order') is front-loaded and the whole thing is a handful of tight sentences with no filler. It is dense with parentheticals and enum-like asides, which slightly taxes parsing, but every sentence carries decision-relevant information.

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

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

With an output schema present, return values needn't be spelled out, and the description covers the workflow gating, both auth personas, all three verticals and the eSIM-specific extras. What it omits — behavior on expired/invalid tokens or partial failures — is secondary but would help for a tool whose only required input is an opaque token.

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 90%, so the baseline is 3; the description earns a bump by explaining that vertical type is inferred from price_token/catalog_id so the type param is often unnecessary, which is a semantic shortcut the schema only partially conveys. It does not add much on the other nine parameters, which the schema already documents well.

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?

Starts with a precise verb+resource ('Returns the price breakdown') and immediately scopes it ('WITHOUT placing an order'), which separates it from create_order and the other write siblings. It also declares it covers every vertical (top-up, travel eSIM, gift card), so an agent knows this single tool spans cases it might otherwise split across 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?

Explicit conditional routing: required for PRO credits because it shows the debit before create_order, optional for guest/consumer payment_link where guests can create immediately. It ties the decision to concrete states (checkout_mode=payment_link vs credits) rather than leaving the agent to infer, and names the follow-up tool (create_order).

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 readOnly=true, destructive=false and closed-world, so safety is covered. The description adds real behavioral context beyond them: pagination is driven by meta.has_more and cursor=meta.cursor, and the q+operator_id combination silently switches from name search to live rate-description search. It doesn't mention result ordering or rate limits, so not a 5.

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

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

Three dense sentences, front-loaded with purpose, then the anti-pattern with named alternatives, then the mode switch, then pagination. No filler and each sentence changes how the agent would call the tool.

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 an output schema exists, the description needn't document returns, and it covers the two things most likely to cause a bad call: picking this tool for top-ups and mishandling the q+operator_id mode. Minor gap: it doesn't clarify whether service_type or lang still apply in rate-description mode, leaving some parameter interaction to inference.

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 86%, so the baseline is 3; the description earns above that by explaining the non-obvious interaction where q changes meaning when operator_id is present (catalog names vs bundle/data descriptions) and by tying cursor to meta.cursor. Other parameters (limit, lang, service_type) are left entirely to the schema.

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

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

States a specific verb and resource ('Browse the country catalog by operator/brand name') and scopes the content types (gift cards, gaming). It also explicitly separates itself from the mobile top-up flow, so an agent can distinguish it from get_operators, get_operator_rates and the esim siblings without opening a 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?

Names the exclusions and the alternatives in sequence: for phone-number top-ups use lookup_carrier, then get_operator_service_types and get_operator_rates, 'NOT this tool alone'. It also explains the alternate search mode (operator_id + q) so the agent knows which invocation path to pick.

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