Cypher eSIM

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the state precondition (unpaid only), though it never says whether a cancelled order can be restored or what happens to a paid order if attempted.

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

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

Two short sentences, zero filler, with the positive definition of the operation front-loaded and the restriction immediately after. Every clause carries actionable information.

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

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

It is a simple two-parameter mutation with full schema coverage, rich annotations, and no output schema, so all that is genuinely needed is purpose plus the eligibility rule. Both are present, and nothing else would change how an agent invokes it.

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

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

Schema description coverage is 100% and both required parameters (order_id, order_token) are documented in the schema as values returned by create_order. The description adds no parameter-level meaning such as where tokens expire or whether they are reusable, so baseline 3 applies.

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

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

States a specific verb (cancel) and resource (order) plus the qualifying state (unpaid), which is enough to tell it apart from create_order/get_order without opening a schema. It stops short of naming any sibling explicitly, so it lands just below the top mark.

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?

"Do not cancel after the payment was sent" gives an explicit when-not condition tied to order state, which is the key routing decision for this tool. No alternative tool is named, but there is no competing cancel path among the siblings, so the guidance is effectively complete.

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?

This description provides critical domain knowledge far beyond the structured annotations. It details complex business logic such as plan specificities ('validity starts at installation', 'Europe number is French +33') and financial prerequisites (the user must send 'exactly that amount').

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 extremely dense and runs together without clear formatting or separation. Although it contains immense value, presenting the function, business rules, and multi-step workflow in one continuous, unstructured paragraph makes it difficult for an agent to parse the distinct sections.

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 definition is exceptionally complete. It not only details the creation process but also defines the financial obligations, the expected outputs (order_id, token, amount, address), and the necessary subsequent steps (polling, cancellation), making it highly robust.

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?

Since the input schema coverage is 100%, the schema already dictates the semantics of all 6 parameters. The description adds context regarding the business nature of the parameters (e.g., 'coin' and 'plan_id') but does not provide clarifying meaning beyond the schema's own definitions.

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 and specifically states the tool's function: 'Create a crypto invoice for one new eSIM.' It clearly defines the resource being acted upon (eSIM/crypto invoice) and distinguishes it from other sibling tools like get_order.

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

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

The description provides comprehensive usage guidelines that cover the entire customer lifecycle. It explicitly details the necessary pre-call confirmation steps and outlines the required follow-up workflow, directing the agent to use 'get_order' for polling and 'cancel_order' for cleanup.

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 mutation/idempotency/open-world flags, and the description adds real context beyond them: that installation state is unchanged ('no new QR, nothing to install') and that payment and polling behave like create_order. It stops short of saying what the returned invoice looks like or how long it stays valid, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the effect of the call, then the parameter constraint, then the operational comparison. Nothing is redundant.

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 4-parameter write tool with no output schema, it covers the effect, the key parameter precondition, and where to learn about payment/polling. Minor gap: no mention of how the created invoice is retrieved later (get_order) or its expiry, which an agent may need for follow-up.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint the schema misses: plan_id must come specifically from list_topups for that same ICCID. This resolves an inconsistency with the schema text (which says plan_id comes from list_plans) for the top-up case.

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

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

States a specific verb and resource ('Create a crypto invoice') plus the exact effect ('adds a data plan to an existing eSIM (no new QR, nothing to install)'). The parenthetical immediately separates it from create_order, which sets up a new eSIM.

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 hard prerequisite ('plan_id must come from list_topups for this ICCID') and points to create_order for the payment/polling flow. It doesn't state an explicit 'don't use this when...' rule, but the existing-eSIM framing makes the boundary with create_order inferable.

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 (readOnly, non-destructive), the description adds real value: it enumerates the status lifecycle, describes exactly what is returned when delivered (QR, LPA, ICCID, install links), and discloses a rate limit of once per 5 seconds. These are traits annotations do not convey.

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

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

Dense and front-loaded—status meanings first, then return contents, then the rate limit. No filler sentences, though the status enumeration could be trimmed if brevity were prioritized.

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

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

With no output schema, the description properly compensates by explaining the return payload and status semantics, plus the rate limit. It is largely complete for a read tool whose params and safety profile are already covered by schema and annotations.

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

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

Schema description coverage is 100%, with both order_id and order_token documented as values returned by create_order. The description adds nothing about the parameters, so the baseline 3 is appropriate when the schema carries the full burden.

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 makes clear it retrieves order status and per-eSIM delivery details, with the resource (order) obvious and the semantics of each status spelled out. It does not explicitly state 'retrieves an order by id' or differentiate against siblings like create_order/cancel_order, but the operation 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?

Usage is only implied—an agent infers it should call this to check status or obtain delivered eSIM credentials. There are no explicit when/when-not statements or references to the alternatives (create_order, cancel_order), and the rate-limit line is a constraint rather than usage 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing what is actually returned (install rules, validity start, notes) in the absence of an output schema, plus the instruction to surface notes to the buyer — genuinely non-obvious behavior.

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

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

One dense sentence front-loads the return contents, and a second short imperative delivers the workflow constraint. No filler, no restatement of the title, and the most decision-relevant information (what you get back) comes first.

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-read tool with full annotation coverage and no output schema, the description compensates well by enumerating returned fields and flagging the notes-reading obligation. Only minor gaps remain, such as error behavior for a stale or invalid plan_id.

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 parameter at 100% schema coverage, the schema already documents plan_id including its origin ('plan_id from list_plans'). The description adds nothing about the parameter's format, validity, or what happens with an unknown id, so this sits at the baseline.

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

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

The description states a specific verb-and-resource pair (full details of one plan) and enumerates the exact contents returned: countries, data, days, phone number, install rules, validity start, notes. That is far more precise than the title 'Get plan'. It implies but never explicitly names the list_plans counterpart for the collection-vs-single distinction.

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

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

Gives a concrete workflow rule — read the notes to the person before create_order — which anchors the tool in the order flow and tells the agent this is a pre-purchase inspection step. It stops short of an explicit exclusion such as 'use list_plans to browse candidates first', so the routing is clear but not complete.

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?

While annotations confirm it is a read-only action, the description discloses critical behavioral context: 'Sending on a different network loses the funds.' This is a high-stakes behavioral warning that goes beyond standard 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 extremely concise. The first sentence defines the resource, and the second sentence provides the necessary operational context and use case, making it highly 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?

Given that inputs are empty and the safety profile is covered by annotations, the description is fully complete. It addresses the domain logic (which coins) and the critical failure mode (network mismatch) an agent needs to know before calling it.

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

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

Since there are zero parameters, the baseline is high. The description adds valuable semantics by identifying the two specific data points that the tool provides: 'coins and networks accepted for payment'.

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?

It explicitly states the tool lists accepted coins and networks for payment. By referencing 'create_order' in the same description, it clearly defines its operational purpose relative to the existing workflow.

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 a clear operational usage guideline by linking the tool's output to the 'create_order' input. It also gives a crucial operational warning about network mismatch, which is vital for its intended use.

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

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

Annotations already declare a safe, idempotent, read-only, closed-world operation, yet the description adds substantial context beyond them: validity start rules for data vs number plans, install-timing warnings, the French +33 number for Europe, the UK after-arrival constraint, regional fallback behavior, and final USD pricing with crypto set at create_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 front-loaded with the core purpose and ordering, then layers useful warnings. It runs several dense sentences, but nearly every clause carries decision-relevant information such as install timing and regional fallback.

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 read-only list tool with no output schema, the description covers purpose, type semantics, fallback behavior, and pricing. It does not describe the return shape or pagination, which is a minor gap but not critical 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 coverage is 100%, so baseline is 3, but the description meaningfully expands the type parameter beyond its brief schema description by explaining validity start, phone/SMS capability, and regional number formats. It says less about include_regional and destination, so it does not fully saturate all three parameters.

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

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

The description states a specific verb and resource ('List purchasable plans for a destination') and adds a distinguishing ordering guarantee ('cheapest first'). An agent can tell this apart from the singular get_plan sibling without opening either schema.

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

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

It explains how to choose the plan type and references create_order for crypto pricing, which implies an ordering workflow. However, it never explicitly says when to use this tool versus siblings like get_plan or search_destinations, so usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the call returns both an eligibility determination and a plan list, which is genuinely useful context, but it says nothing about what happens for an ineligible or unknown ICCID.

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

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

A single sentence with no filler, and the eligibility-check purpose is front-loaded ahead of the plan 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?

For a one-parameter, read-only lookup whose annotations cover the safety profile and whose schema covers the parameter, the description is nearly sufficient. The minor gap is that it doesn't say what the eligibility result looks like or what is returned when top-up is not possible.

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

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

Schema coverage is 100% and the single iccid parameter is fully documented in the schema, including length constraints and where to find the value. The description only alludes to it via 'installed eSIM' and adds no format or validation detail beyond the schema, so baseline 3 applies.

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

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

States a specific compound verb (check eligibility + list plans) against a specific resource (top-ups for an installed Cypher eSIM), which an agent can clearly separate from list_plans or create_topup. It stops short of naming those siblings, so the differentiation is implied rather than explicit.

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 'check whether ... can be topped up' framing implies this is the read step preceding create_topup, but the description never says so or names any alternative. An agent must infer when to call this versus create_topup or list_plans.

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

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

Annotations already mark this as read-only, idempotent, non-destructive, and not open-world. The description adds useful behavioral context beyond annotations by describing returned fields, USD starting prices, plan counts, and empty-query behavior.

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

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

The description is front-loaded with the tool purpose, then efficiently covers return values and the empty-query case. Every sentence adds useful information without 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?

For a simple two-parameter search tool with full schema descriptions and safety annotations, the description is complete enough to call it correctly. It explains the result content and empty-query behavior even though no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics for query, including world destinations and code formats like R-EUROPE/WORLD, plus the empty-query rule. Limit behavior is left to the schema.

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

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

The description states a specific verb and resource: find destinations by name or ISO code. It also clarifies the returned destination-code formats and ties them to list_plans, so the agent can distinguish this search tool from list_plans without opening 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?

It clearly explains the main usage pattern—search by country/region name, ISO code, or empty query—and connects results to list_plans. It does not give explicit when-not guidance, but the usage context is clear and sufficient.

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