eSIM Tabby

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

The description goes far beyond the annotations. It discloses the refund behavior for card vs. USDC payments, explains the 'refund_pending' state, and warns about the error after installation. This is highly informative and adds context the annotations don't cover.

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

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

The description is four sentences but each sentence is essential: purpose, condition, failure behavior, and refund nuance. It is front-loaded with the core action and efficiently structured with no fluff.

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 tool has complex behavior (conditional cancellation, refund differences, error paths) and the description covers all key edge cases. The output schema exists, and the description complements it with the procedural context needed to use the 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 input schema already fully describes the only parameter `order_id` with 100% coverage. The description doesn't add new meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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 states the tool's verb ('Cancel') and resource ('an order'), and specifies that it also refunds. This distinguishes it from sibling tools like get_order_status or pay_order, making its purpose obvious.

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

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

Explicitly states a precondition ('Only possible while the eSIM is uninstalled') and a clear exclusion ('Once the profile has been installed... this returns an error instead — send the user to support'). This tells the agent when to use and when not to use the tool, and even where to redirect the user.

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 a critical non-obvious behavior: payment details are never accepted—cards go to a hosted page and wallets sign for themselves. This adds meaning beyond the annotations, which only indicate write behavior and non-idempotency. It effectively clarifies the payment flow and output location.

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: the first states the purpose and output, the second adds an essential constraint about payment details. Every word earns its place, and the most important information 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?

Given the tool's simplicity (2 params, 1 required, output schema present, annotations provided), the description covers the core purpose, output, and a key behavioral constraint. It doesn't address usage context relative to siblings, but that gap is minor for a tool of this complexity and is partially covered by the 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 input schema already provides 100% parameter documentation, including a detailed explanation of pay_with with its enum values and behavior. The description adds little beyond referencing the 'rail', which the schema already elaborates. Baseline 3 is appropriate since the schema carries the semantic load.

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 states the action ('Start a purchase') and adds the result ('Returns where to pay'), specifying the scope of the tool. However, it does not explicitly distinguish itself from sibling tools like create_topup_checkout or pay_order, so it falls short of a perfect score.

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?

No explicit guidance is given on when to use this tool versus alternatives. The description focuses on behavioral constraints ('Never accepts payment details') but does not mention prerequisites, follow-up steps, or contrasts with similar tools such as create_topup_checkout or pay_order.

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

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

Annotations already declare readOnlyHint=false, so agents know it's a write operation. The description adds valuable behavioral context: it never accepts payment details directly, and a hosted page or wallet handles the actual payment. This goes beyond what annotations provide and helps set expectations for the transaction flow.

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, front-loaded with the primary purpose and output, followed by a key safety note. There is no wasted wording or redundant 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?

The description addresses the core context: existing eSIM, the two possible payment rails, and that payment details are never handled directly. With a robust schema and an output schema present, nothing critical is missing for an agent to correctly select and invoke the tool.

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 all parameters including plan_id, order_id, and pay_with having descriptions. The tool description mentions 'rail' but does not add meaning beyond what the schema already provides for pay_with. Baseline 3 is appropriate given the schema's thoroughness.

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 action ('Buy more data') on a clearly defined resource ('an existing eSIM') and indicates the output ('Returns where to pay'). This distinguishes it from siblings like create_checkout, which would be for new 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 clearly implies the use case: topping up an existing eSIM. The detailed pay_with parameter schema gives explicit guidance on choosing between 'card' and 'x402', including when not to choose x402 ('only choose it if you have a wallet'), but the tool description itself does not explicitly mention alternatives like create_checkout for new purchases.

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 goes beyond annotations by explaining that the operation is not read-only and can change the order's state by advancing it if not ready. This is a non-obvious behavioral trait not captured by readOnlyHint=false, adding real value.

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 two short sentences with no filler. The main purpose is front-loaded, and the critical caveat about side effects is placed clearly without excess wording.

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 tool with an output schema and complete annotations, the description fully covers what the agent needs: what it does, the side-effect warning, and the input type. No critical information 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 description coverage is 100% for the single order_id parameter, which already states 'order_id of a fulfilled order'. The description adds no additional semantic detail beyond the schema's text, so it stays 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 clearly states it retrieves 'the QR code and activation details for a purchased eSIM'. This is a specific verb+resource combination that distinguishes it from sibling tools like get_esim_usage and get_order_status.

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 context: states the tool is not read-only and can advance an order's state, comparing it to get_order_status. This informs when to use it and warns about side effects, though it doesn't explicitly list alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, providing a safe read profile. The description adds useful behavioral context: it specifically notes 'active eSIM', implying it will not work for inactive eSIMs, and clarifies that it returns both used and remaining data. This goes beyond the structured annotations and adds meaningful constraint information.

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: 'How much data an active eSIM has used, and how much is left.' It is front-loaded with the core query, contains zero filler, and every word contributes to the meaning. This is an exemplary level of conciseness.

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 (one parameter, read-only, with output schema), the description is adequate. It clearly states what the tool returns (used and remaining data) and the condition ('active eSIM'). No additional information like error handling or return format is strictly necessary, as the output schema exists. A minor gap is the lack of mention of what happens if the eSIM is not active, but this is a small omission for an otherwise complete description.

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 already provides full coverage (100%) for the single required parameter, order_id, with the description 'order_id of a fulfilled order'. The tool description adds no additional meaning about the parameter, so it does not improve upon the schema's documentation. This aligns with the baseline score for high schema coverage.

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 explains the tool's purpose: showing how much data an active eSIM has used and how much remains. It distinguishes this from sibling tools like get_order_status and get_plan_details by focusing specifically on data usage. While it lacks an explicit verb, the title 'Check data usage' and the description together convey the action clearly.

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 implies this tool should be used to query data usage for an active eSIM, but it does not explicitly state when to use it over alternatives. No exclusions or alternative tool names are mentioned, leaving the agent to infer the appropriate context from the description and sibling tool names.

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 a critical non-obvious behavior: the tool is not read-only, and it advances the order by confirming payment and placing/collecting the provider order. This adds significant context beyond the readOnlyHint=false annotation and clarifies the side effects. It is consistent with all 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 description is two concise sentences, front-loaded with the purpose and immediately followed by usage timing and the critical behavioral warning. Every sentence adds value with no filler or redundancy.

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

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

The tool is simple with one parameter, has an output schema, and annotations cover safety traits. The description supplies the key missing context about the state-changing effect, making it complete for invocation. No critical information is absent.

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

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

The input schema has one parameter with a clear description ('order_id from create_checkout'), giving 100% schema coverage. The tool description does not add any parameter-specific information beyond what the schema already provides, so the baseline score of 3 is justified.

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 states the tool checks an order and gives the specific context of payment confirmation. This distinguishes it from list_my_orders, but it does not explicitly name sibling alternatives, so it falls short of the highest score.

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

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

Explicitly instructs to call the tool after the user says they've paid, which is a clear usage trigger. It also warns about the state-changing nature. However, it does not mention when not to use it or reference alternative tools, so a score of 4 is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the context that it returns 'current price', but it does not disclose other behavioral aspects like response size, error conditions, or freshness guarantees. With annotations present, this meets the minimum viable bar.

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

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

The description is a single, efficient sentence with no wasted words. It is front-loaded with the key action ('Full details') and the object ('one eSIM plan'), making it immediately scannable.

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?

This is a simple, read-only get-details tool with one well-documented parameter, an output schema to describe return values, and annotations declaring its non-destructive nature. The description, combined with structured data, provides enough context for an AI agent to select and invoke 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 schema provides 100% coverage for the single parameter, identifying plan_id and instructing that it comes from search_esim_plans. The description's phrase 'one eSIM plan' loosely reinforces the singular nature of the parameter, but adds no substantive meaning beyond what the schema already gives. Baseline 3 is appropriate.

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 'Full details of one eSIM plan, including current price' clearly identifies the action (retrieve full details), the resource (eSIM plan), and the scope (one plan). It is specific enough to distinguish from sibling tools like search_esim_plans, which lists plans rather than returning details for a single one.

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 implies the tool is for fetching details of a specific plan, and the schema's plan_id description ('plan_id from search_esim_plans') provides a useful prerequisite by indicating where to obtain the identifier. However, it does not explicitly state when not to use this tool or name alternatives.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, so the safety profile is known. The description adds valuable behavior beyond annotations by specifying the ordering ('newest first') and the account scoping, which helps the agent understand what to expect.

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, clear sentence that front-loads the main action and resource, with no filler or redundant information. It earns its place entirely.

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

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

For a simple, read-only list tool with no parameters and an output schema present, the description fully covers what the tool does. It includes scope and ordering, which is complete for the tool's complexity.

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

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

There are zero parameters, so the schema trivially covers everything. The description adds no parameter detail because none is needed. The baseline of 4 for zero-parameter tools applies here.

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 states the verb 'List', the resource ('eSIM orders'), and the scope ('this account's'), plus the ordering ('newest first'). It effectively distinguishes from siblings like get_order_status (which implies a single order) and list_topup_options (which lists topup options).

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 context that this lists all orders for the account, but it does not explicitly state when to use this versus alternatives like get_order_status. No exclusions or alternative tool mentions are provided, leaving the usage to be implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by explaining top-up semantics (extends existing eSIM, same QR code, no re-install) and the edge case that not all plans are reloadable, resulting in an empty list. This goes beyond the safety 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 description is two concise sentences, front-loaded with the core purpose and followed by valuable behavioral context. No redundant information or fluff.

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 listing tool with an output schema and safety annotations, the description covers the core concept, the meaning of a top-up, and the empty-result edge case. It does not mention error handling for invalid order_id, but that is not critical given the 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 coverage is 100%, and the parameter description already specifies 'order_id of a fulfilled eSIM'. The description adds no new syntax or format details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb (list) and resource (data top-ups for an existing eSIM), distinguishing it from sibling tools like create_topup_checkout by focusing on available options. It also clarifies scope by stating top-ups extend the existing eSIM and that the list may be empty.

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?

Clear usage context: use when you need to see top-up options for an already-owned eSIM. It implicitly differentiates from create_topup_checkout (which likely creates the purchase) but does not explicitly state when to prefer this tool over 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?

The description reveals the non-trivial two-phase behavior (call once for payment requirements, repeat with signed payment to settle) and the limitation about not being able to act on behalf of a wallet tool. This adds context beyond the annotations, which already indicate a write operation (readOnlyHint=false) and non-idempotency (idempotentHint=false). 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 description is front-loaded with the purpose in the first sentence, followed by concise, necessary instructions. Every sentence contributes to understanding the tool's unique workflow, with no wasted words.

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 complexity and lack of output schema, the description covers the essential usage flow, alternatives, and constraints. However, it doesn't specify what the first response (payment requirements) contains or the exact return values, leaving a minor gap. Overall, quite complete for the primary use case.

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

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

Schema coverage is 100% for the single order_id parameter, which is described as 'order_id from create_checkout'. The tool description doesn't add extra meaning to the parameter, but the schema already provides sufficient context, so a baseline score of 3 is appropriate.

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 states the tool's function with a specific verb and resource: 'Pay for an order in USDC over x402, without opening a browser.' It distinguishes from sibling tools (e.g., create_checkout, cancel_order) by focusing on the payment action and the x402 mechanism.

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

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

Explicitly specifies when to use the tool ('Only for an MCP client that signs x402 payments itself') and provides an alternative for other cases ('If your wallet is a separate tool, make an x402 request to the order's x402_url instead'). Also outlines the two-step call pattern, offering clear context and 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds little beyond the purpose—no mention of result ordering, pagination, or filtering behavior. It simply restates the search scope, which provides some context but not rich behavioral detail.

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 that immediately conveys the tool's purpose. No wasted words, perfect front-loading.

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

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

With an output schema present and full schema documentation for parameters, the description is largely complete for a search tool. However, it could have added a note about what constitutes a 'destination' (e.g., country name or code) or how results are ordered, but the schema already covers the country format. Overall, sufficient but not exhaustive.

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%; all three parameters (country, min_data_mb, max_duration_days) have descriptive text. The tool description does not add extra parameter semantics beyond what the schema already provides, so the baseline 3 is appropriate.

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 states the action (Find), the resource (travel eSIM data plans), and the scope (available for a destination). This distinguishes it from sibling tools like get_plan_details, which focuses on a single plan's 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 implies usage: when you need to find plans for a destination. However, it does not explicitly mention when not to use it or provide alternatives, such as using get_plan_details for a specific plan's details. The context is clear but the guidance is not fully explicit.

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