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?

Goes well beyond readOnlyHint/idempotentHint by explaining the pending→paid/underpaid/expired lifecycle, partial credit behavior, and the need to poll for network confirmations. No contradiction with annotations.

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

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

Three short, information-dense sentences pack status semantics, timing guidance, and a required input into a compact definition. No filler or repetition of schema/annotations.

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 a read-only, idempotent, single-parameter tool and an output schema available, the description covers all practical decision points: status meanings, polling cadence, confirmation delays, and the required wallet code. Nothing critical 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 0%, so the description must compensate for the bare token property. It says the lookup is 'by its token' and that the wallet code is needed, which gives partial meaning, but it does not explain the token's format or where to obtain it.

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

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

Description states a specific operation: retrieve one deposit for a wallet by token, and enumerates the expected status values. This clearly differentiates it from sibling tools like create_deposit or list_topups.

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

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

Provides clear usage context: call after sending a deposit, poll every ~30 seconds, and allow time for crypto confirmations. It does not name alternatives or explicitly state when not to use, but the context is sufficient.

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

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

Beyond readOnlyHint and idempotentHint, the description reveals the full status transition graph, the ready-state behavior with esim.activation_code as an LPA string, and associated fields iccid, smdp, and matching_id. It also sets polling and delivery-time expectations that annotations do not provide.

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

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

The description is three tightly scoped sentences: purpose, status state machine, ready-state payload, then polling guidance. Every sentence adds necessary information and there is no redundant boilerplate or repetition of annotation values.

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 can carry the return-shape detail, so the description is free to cover status semantics, key fields, and timing. An agent has enough context to call this tool correctly and interpret readiness without additional information.

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 one required token parameter and 0% schema description coverage, the description compensates by identifying token as the order identifier. It does not specify the token's format or provenance, but for a single obvious parameter this is sufficient for correct invocation.

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 this tool returns an order by its token and adds the order status lifecycle, clearly distinguishing it from sibling get_* tools like get_deposit, get_wallet, and get_usage. 'An order by its token' plus the status flow makes the resource and scope unambiguous.

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

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

The description gives concrete usage context: after payment, poll every ~10 seconds and expect delivery usually under a minute. It does not explicitly name alternatives or when-not-to-use, but the polling guidance clearly routes the agent to use get_order for post-payment status checks.

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.