esimker eSIM store

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

The description discloses important behavior beyond the annotations: every call creates a new unpaid order, retrying is unsafe, the token is a secret, and email delivery is a side effect. It also explains topup semantics and the embargo error. These details meaningfully inform an agent about side effects and non-idempotency, which annotations only partially signal.

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 adds value: purpose, return values, retry warning, parameter clarifications, error meaning, and alternative tool. The most critical constraints are front-loaded, and there is no filler or repetition of schema details.

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 mutation tool with six parameters and complex side effects, the description covers the key operational facts: what is returned, how to use optional parameters, non-idempotency, secret handling, and an alternative path. An output schema exists, so detailed return structure does not need to be duplicated here.

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 0% schema description coverage, the description carries the burden of explaining parameters. It explains period_num (1–365, daily_unlimited only), topup_iccid (with plan_id from list_topups), email (optional eSIM delivery), and lang (order page language). It does not fully clarify payment_method semantics beyond the enum, and lang is only implied, so it is not a perfect 5.

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: 'Create an order for a person to pay.' It explains the distinct artifacts returned (checkout_url, order_url, token) and differentiates itself from purchase_esim, which is the wallet-payment alternative. This clearly distinguishes the tool from its 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?

The description gives explicit usage guidance: confirm the plan and price first, do not retry while a checkout is open, and use purchase_esim for wallet payments. It also flags a 403 as an embargoed jurisdiction, giving the agent actionable context for handling errors and choosing 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 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 annotations (readOnlyHint=false, idempotentHint=true), the description explains the idempotency MECHANISM (client_ref reuse returns existing order without second charge), the 429 rate limit (50 orders/24h per wallet), the 402 error meaning, and the pricing rule (price × days). These are behavioral facts the annotations cannot convey. 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?

Dense but front-loaded and waste-free: the core purpose leads, followed by idempotency, parameter semantics, return flow, error handling, rate limit, and prerequisite. Every sentence carries operational value for a tool with this many behavioral gotchas; nothing is 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 6-parameter mutating tool with idempotency, rate limits, plan-specific pricing, and an error path, the description covers the full call lifecycle: prerequisite (wallet code), action, parameter constraints, response handling (poll get_order), failure handling (402 → create_deposit), and throttling (429). The existence of an output schema relieves it from documenting return shape in detail.

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, and it delivers: client_ref gets length, purpose, and idempotency semantics; period_num gets range, default, applicability (daily_unlimited only), and cost formula; topup_iccid gets its pairing with list_topups that an agent could not derive from the bare schema titles. Minor gaps remain for lang/email and the source of plan_id in the non-topup path, but the semantically critical parameters are fully explained.

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 opening clause 'Charge the wallet and issue an eSIM, no checkout' names a specific action and resource and immediately distinguishes this direct-purchase path from the checkout flow (create_checkout). The purpose is unmistakable even before reading parameter details.

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

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

The description names concrete alternatives with their trigger conditions: 'create_deposit first' on a 402 short-balance, 'plan_id from list_topups' to top up, and 'poll get_order(token)' after purchase. 'No checkout' and 'Needs the wallet code' frame when this tool is and is not the right choice. Nothing is left to inference.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses meaningful behavior: the query is fuzzy across translations, slug, and code; empty query returns all; each result includes specific price fields with definitions. This provides the agent with a full picture of what the tool returns and how it behaves.

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

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

Three tight sentences: one for scope, one for query behavior, one for output format and follow-up. No redundant phrasing, and the most important semantics are front-loaded before the field listing.

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 fully covers the single optional parameter, the result item structure, and the recommended follow-up tool. With an output schema already present and annotations declaring read-only idempotent behavior, there are no meaningful missing details for an agent to call this correctly.

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

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

The schema provides only the parameter name 'query' with a default, so the description carries the full semantic burden. It explains what the query matches (name in 17 languages, slug, ISO code) and that empty query lists everything, which is exactly what an agent needs to invoke the tool correctly.

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 ('search'), the resource ('destinations'), and the scope ('on sale'), and explains exactly what query matches against: name in 17 languages, slug, or ISO code. This clearly distinguishes it from sibling tools like get_plans and create_checkout without needing to inspect their 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?

The description gives clear usage context: empty query lists everything, and query matches certain fields. It also provides a natural next step with 'Continue with get_plans(slug)'. It does not explicitly discuss when not to use this tool or compare it to alternatives, but the workflow guidance makes usage clear.

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