esimker eSIM store

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

Annotations already signal non-read-only and non-idempotent behavior, and the description reinforces and expands on this: every call creates a new unpaid order, the token is a secret, a 403 means the caller's jurisdiction is embargoed, and an optional email also receives the eSIM by mail. This adds valuable behavioral context beyond the structured hints.

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?

Every sentence carries essential information: purpose, return values, safety warnings, parameter constraints, error meaning, and alternatives. The critical non-idempotency warning is front-loaded, and there is no fluff or repetition.

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

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

The description covers the full workflow: what to confirm before calling, what the response contains and who receives what, error semantics, top-up usage, and the relevant alternative tool. With an output schema present, the description need not enumerate return fields, making this complete for an agent to invoke 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 0%, so the description must explain parameters, and it does for most: period_num (1–365 and daily_unlimited only), topup_iccid (with plan_id from list_topups), email (also mails the eSIM), and lang (the order page language). It does not explicitly describe payment_method, though its enum values are 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?

The description opens with a specific verb+resource: 'Create an order for a person to pay.' It clarifies the tool's purpose by describing its outputs (token, checkout_url, order_url) and differentiates it from the sibling purchase_esim, which handles wallet payments.

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 usage warnings: confirm the plan and price first, every call creates a new unpaid order, and do not retry while a checkout is open. It also names the alternative for wallet payments ('To pay from a wallet use purchase_esim') and explains the top-up use case via list_topups.

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 carry generic hints, so the description carries the behavioral burden. It reveals this is a state-changing operation, explains amount floors and caps, discloses deposit expiration (~15 minutes), includes network fees, and tells the agent to poll until paid. 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 core purpose, constraints, and payment instructions are front-loaded and organized well. However, the 'every purchase returns 3% cashback' clause is tangential to invoking create_deposit and adds noise, so not every sentence fully 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 thoroughly covers the crypto payment flow, card flow, amount constraints, expiry, and the follow-up polling via get_deposit. The main gap is that 'needs the wallet code' is not tied to any schema parameter or explained in terms of where the agent supplies it, and the source of the polling token is only implicit.

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%, but the description compensates richly: it defines the amount_usd limits, gives the allowed crypto currency list for payment_method 'crypto', and explains how the response carries `pay` details. The only parameter not described, lang, is self-explanatory via its title and default.

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 clear verb and resource: it opens a wallet top-up and returns what is needed to pay it. It also distinguishes itself from siblings by explaining the crypto `pay` flow versus the card `checkout_url` flow, so an agent can tell it apart from tools like get_deposit and create_checkout.

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 concrete when-to-use guidance: when payment_method is crypto, pass a specific currency; when it is card, only checkout_url is returned; and after creating the deposit, poll get_deposit(token). It does not explicitly frame when not to use this tool versus alternatives, but the crypto/card distinction provides clear usage 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?

The description discloses critical behavioral traits beyond the annotations: the secret is returned only once, there is no recovery or identity, the code must be saved immediately and used as a Bearer token, the balance never pays out, accept_terms must be true, and the call is rate-limited/geo-blocked. This is far more than the annotations provide and is essential for safe invocation.

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?

Every sentence earns its place: purpose, secret handling, authorization usage, balance policy, terms requirement, next step, and rate-limit warning. It is dense but not bloated, and the core purpose 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 one-parameter creation tool with an output schema available, the description covers the full lifecycle: what to do with the returned secret, how to authenticate, that there is no recovery, and what to do next (create_deposit). Nothing essential is 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?

Schema description coverage is 0%, so the description carries the full burden. It explicitly explains the sole parameter accept_terms: it 'must be true' and links to the terms. This fully compensates for the missing schema descriptions.

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: 'Mint a prepaid wallet with no account behind it.' It clearly differentiates from sibling tools by stating this is the wallet-creation step and pointing to create_deposit as the funding follow-up. The agent can tell what this tool does and how it differs from related 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 provides explicit workflow context: 'Then create_deposit to fund it,' and notes rate-limiting/geo-blocking parity with checkout. It does not explicitly state when NOT to use the tool or contrast with alternatives, but the workflow direction is clear enough for an agent to select it correctly.

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 readOnly/idempotent/open-world safety, and the description goes beyond them by decoding each status: underpaid means nothing credited yet, payment_held means the processor's compliance check is holding it and the user must contact support rather than pay again. That 'do not pay again' guidance is genuinely useful behavioral context, though it doesn't discuss auth or any output-side caveats.

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 what the tool returns before the status catalogue, and every clause is functional. The pipe-delimited status list is dense but readable and earns its space.

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 need not be explained, and the description uses its space for status interpretation and polling cadence instead. An agent has enough to call it and act on the result; only the token/wallet-code ambiguity leaves a small 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?

There is exactly one parameter and schema description coverage is 0%, so the description must carry it. It says the deposit is fetched 'by its token' and that it 'needs the wallet code', which adds some meaning but is ambiguous about whether the token is the wallet code or a deposit token — a gap the schema does not fill.

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 resource ('one deposit of the wallet') and the key that retrieves it ('by its token'), which cleanly separates it from create_deposit, create_checkout and list_topups. The retrieve verb is only implied rather than stated, and no sibling is named, so it falls just short of a 5.

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

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

Gives a concrete when-to-call instruction: poll every ~30 s after sending, because crypto needs network confirmations. It also implicitly routes the agent away from re-paying on payment_held. It does not contrast itself with get_wallet or list_topups, so no explicit alternatives are given.

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

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

Annotations already declare this as a safe, idempotent read, so the bar is low, yet the description goes well beyond them: it enumerates the full status state machine, explains the payment_held compliance hold (money held, nothing issued), and describes what fields appear once ready. That is the kind of operational context an agent cannot get from annotations or 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?

Dense but economical: statuses, the held-payment edge case, the ready-state fields, and polling cadence each earn their sentence. The opening fragment and the mid-sentence field dump make the structure slightly less scannable than it could be.

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, return fields need no explanation, yet the description still covers the full status lifecycle, the exception path, QR rendering of esim.activation_code, and polling behavior — everything an agent needs to interpret results and act. Only the invalid/unknown-token case 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?

With schema coverage at 0% and one required parameter, the description only implicitly documents the token as the order identifier ('An order by its token'). It does not state where the token comes from (e.g., supplied by create_checkout/purchase_esim) or that it must be the exact order token, so it only partially compensates for the schema 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?

The description identifies the resource and lookup key ('An order by its token'), making it distinguishable from siblings like get_deposit, get_wallet, and list_topups. It lacks an explicit verb ('retrieve/fetch an order'), but the intent is unambiguous in context.

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 concrete usage guidance — poll every ~10 s after payment, delivery usually under a minute — and a clear action rule for the payment_held branch (do not pay again, contact support). It does not compare against sibling lookup tools, but no exclusions are needed here.

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 and idempotentHint, but the description adds meaningful behavior: methods are dynamic ('open right now'), crypto is a hosted invoice, and `gateways` has ordering semantics where unspecified checkouts default to the first provider. This goes well 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 compact and front-loaded with the core purpose, then expands into valuable method and gateway context. The only slight weakness is the final clause 'which is what these tools do,' which is a little ambiguous about which tools are being referred to.

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-parameter, read-only tool with an output schema and safety annotations, the description is complete: it explains each payment method, points to the wallet creation sibling, and clarifies the gateway default behavior. Nothing essential is missing for an agent to call this tool correctly.

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

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

The tool has zero parameters, so parameter documentation is not needed; the schema coverage is trivially complete. The description instead contributes to understanding the output semantics, which is appropriate for a no-argument 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 clearly identifies the tool as returning currently available checkout methods (crypto, card, wallet) and adds provider-level detail via the `gateways` field. This distinguishes it from siblings like get_wallet, since it enumerates payment methods rather than balances or 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 gives practical context by explaining what each method means and points to create_wallet as the relevant sibling for prepaid balances. It does not explicitly state 'use this before create_checkout' or list exclusions, but the usage context is reasonably clear for a zero-parameter read-only 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, covering the safety profile. The description adds meaningful behavioral detail by explaining the meaning of fields such as retail being per-day when daily_unlimited is true, location_codes representing covered countries, and id being the plan_id for an order.

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 and mostly efficient, front-loading the core purpose and then listing the return fields. The field list is presented as a long single sentence with several parenthetical clarifications, which is slightly cumbersome but still compact and free of filler.

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

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

For a one-parameter, read-only, idempotent tool with an output schema, the description covers the essential context: how to obtain the slug, what fields are returned, and specific unit semantics for retail. It does not discuss error behavior or the broader purchase flow, but those are less critical given the annotations and 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?

The schema only says 'Slug' with no description, so the 0% schema coverage puts the burden on the tool description. The description compensates by explaining that slug identifies one destination and that it should come from search_destinations, which is the key semantic an agent needs.

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 the resource (plans) and scope (one destination, identified by slug), and it points to search_destinations as the slug source. It lacks an explicit action verb like 'retrieves' or 'lists', and it does not contrast itself with sibling tools, but the intent is 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 phrase 'slug from search_destinations' gives clear prerequisite context: call search_destinations first to obtain a destination slug, then use this tool. It does not explicitly state when not to use this tool or name alternatives, so it falls short of full explicit 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 and idempotentHint=true, so the safety profile is clear. The description adds a useful scoping detail: it returns only remaining data and status, and only for eSIMs we issued. No additional behavioral detail such as error cases or data freshness is provided, but the annotations lower the burden.

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 with no filler. It front-loads the key result ('Remaining data and status') and then adds the scope ('eSIM we issued'). Every word contributes meaningful 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?

Given the tool's simplicity, the existing output schema, and the read-only annotations, the description covers the essential context. It could be improved by explicitly stating that the iccid is the lookup key, but that is already evident from the input schema. Overall, the description is sufficient for correct invocation.

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

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

The input schema has 0% description coverage, so the description must compensate. It partially does by clarifying that the iccid must refer to an eSIM we issued. However, it does not explain the iccid format, how to obtain it, or any constraints beyond issuer scope.

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 identifies the resource (an eSIM we issued) and the information returned (remaining data and status). This clearly maps to the tool name get_usage, though it lacks an explicit verb like 'retrieves'. It is not a tautology and is reasonably distinguishable from 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?

The phrase 'we issued' implies the tool is for eSIMs provided by this system, giving some usage context. However, there is no explicit guidance about when to prefer this over alternatives, nor any mention of excluded cases. Usage is inferable but not directly 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 already establish read-only and idempotent behavior, so the description does not need to repeat those. It adds meaningful behavioral context beyond the annotations: a 50-transaction limit, the fact that deposit rules are the current applicable rules, and that orders include their tokens. This helps the agent understand what the returned wallet object represents.

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 dense sentence that front-loads a stylistic phrase rather than an action. It contains useful detail, but the long parenthetical list and em-dash construction make it less scannable than a direct 'Gets the wallet for the given wallet code, including...' would be.

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?

Although an output schema exists and annotations cover safety, the description leaves key invocation context unresolved: how to obtain or pass the wallet code, and how this tool relates to sibling get_* tools. For a tool that returns multiple related resources, the missing prerequisite and selection guidance make it incomplete.

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

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

The input schema has zero properties, yet the description states 'Needs the wallet code' without naming an argument or explaining how to supply it. This creates a serious invocation gap: an agent following the schema would call with no arguments, while the description implies a required input. The description must compensate for the empty schema but does not.

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 tool name get_wallet and the enumerated wallet contents (balance, transactions, orders, deposits) make the purpose reasonably clear even though the description never uses a direct retrieval verb. It is not a tautology, but it does not explicitly differentiate itself from sibling tools like get_order or get_deposit.

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 get_wallet versus siblings such as get_order, get_deposit, or create_wallet. The only usage hint is 'Needs the wallet code,' which states a prerequisite but not a selection condition, exclusion, or alternative.

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 the tool as read-only, idempotent, and closed-world. The description adds useful behavioral context by limiting results to eSIMs issued by the service and by showing the intended usage path through create_checkout or purchase_esim.

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 resource, scope, returned fields, and follow-up actions are all stated economically and 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 read-only list tool with an output schema, the description is nearly complete: it gives scope, return fields, and next steps. The only real gap is the under-specified iccid parameter, already counted under parameter semantics.

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 conveys that iccid identifies the eSIM via the 'topup_iccid=iccid' examples, but it never explicitly describes the iccid parameter's format, source, or validation requirements.

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 the resource (top-up plans) and its scope (only eSIMs issued by this service), listing the returned fields. It does not use an explicit verb like 'list', relying on the tool name, and sibling differentiation from get_plans is only implicit.

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

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

The context 'fit an eSIM we issued' implies when to call, and the follow-up calls show how the result can be used. However, it does not explicitly state when to choose this over get_plans or any listing alternatives, nor does it mention prerequisites or exclusions.

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 idempotentHint annotation, the description explains the full idempotency behavior, charging semantics, rate limits, error codes, and prerequisites. It also says what the response contains and how to advance the flow, which is valuable behavioral 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 dense but every sentence earns its place. It front-loads the core purpose and then delivers essential operational details without filler. The flow from idempotency to pricing to topup to error handling is logical 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?

For a paid purchase operation with zero schema descriptions, this definition covers prerequisite wallet code, idempotency, pricing, topup behavior, error handling, rate limits, and post-purchase polling. The output schema handles return shape details, so the description is complete.

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

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

Schema description coverage is 0%, so the description carries the burden. It adds strong semantics for client_ref, period_num, and topup_iccid, including validation ranges and idempotency meaning. However, plan_id, lang, and email are not explicitly described, leaving minor 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+resource: 'Charge the wallet and issue an eSIM, no checkout.' It clearly differentiates itself from sibling tools like create_checkout and create_deposit by positioning purchase_esim as the direct purchase path.

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 guidance on when to use alternatives: use create_deposit on a 402, poll get_order for activation, and use list_topups for topups. It also tells the agent to reuse client_ref on retries, which is a clear procedural rule.

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 and idempotentHint, and the description adds meaningful behavior: matching over 18 languages, slug, or ISO code, empty-query returning all items, and the meaning of each returned field (min_retail, unlimited_from, plan_count). Minor omissions like pagination and ordering are acceptable for a simple search tool.

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

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

Three sentences, each dense with information: listing semantics, query behavior, output fields, and the next-step call. There is no filler or repetition of schema content.

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

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

For a one-parameter, read-only tool with an output schema, the description covers search behavior, return-field semantics, and the natural follow-up call. An agent has everything needed to invoke it correctly and interpret the result, aided by the 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?

The schema has 0% description coverage, so the description fully carries the burden for the single `query` parameter. It explains matching across name, slug, and ISO code, and explicitly states that an empty value lists everything. This is complete semantic coverage for the 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?

The description identifies the resource (destinations) and the search/list behavior: query matches name in 18 languages, slug, or ISO code, and empty query lists everything. The opening phrase 'Destinations on sale' is slightly ambiguous (could be read as discounted items) and the verb is not explicitly stated, though the tool name supplies it. It differentiates from siblings by naming get_plans as the follow-up.

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 a clear usage pattern: pass a query to search, leave empty to list everything, and continue with get_plans(slug). It also provides concrete field-level context. It does not state explicit exclusions or when to prefer siblings over this tool, but the continuation guidance anchors when this tool is the right entry point.

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