topup

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

With no annotations, the description carries the full burden of behavioral disclosure, and it clearly states the most important safety property: the hosted server holds no wallet and does NOT spend money. It also enumerates the returned fields. It omits edge behavior such as challenge expiration or error conditions, which prevents 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?

The purpose is front-loaded in the first sentence, and the safety clarification immediately follows. Each of the three sentences earns its place, though the description is slightly longer than strictly necessary.

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 tool with no output schema, this description is unusually complete: it gives the input context, the exact returned data, the payment flow, and the follow-up action. Minor gaps remain around formal error behavior and challenge expiration 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% and the description never explicitly names quoteId, only referring to 'a quote' and 'prior human confirmation of the quote.' With one required parameter the inference is easy, but the description could have explicitly mapped quoteId to the identifier returned by the quote 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?

States an explicit verb ('Get'), a specific resource ('x402 payment challenge'), and the relationship to a quote. The clarification that it does not spend money distinguishes it from what the name 'buy' would otherwise suggest and from siblings like quote and verify_receipt.

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 a concrete prerequisite: 'Requires prior human confirmation of the quote.' It also positions the tool in a multi-step flow by explaining that the user pays from their own wallet and then POSTs the quote again with a signature. It does not explicitly name alternative sibling tools, so it stops short of a 5.

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?

With no annotations, the description must disclose behavioral traits. It does add meaningful context: the rate is 'indicative' (not a guaranteed final price), but the quote returned is 'binding'. It also indicates the price is at the sale price (a specific pricing policy). However, it does not state whether this operation is read-only, has side effects, requires authentication, or what happens if the amount is omitted. The disclosure is partial but not comprehensive.

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 sentences with no wasted words. The primary purpose is front-loaded, and the key behavioral caveat (binding quote) is placed prominently. It is concise and easy to parse.

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 no output schema, no annotations, and only two parameters with partial schema coverage. The description does not explain what the tool returns (e.g., a rate value, an estimated amount, or a JSON object), nor does it clarify the meaning of 'amount' or what happens when it is omitted. It also fails to mention any constraints like supported currencies or authentication. Given the low commitment from other sources, the description is insufficient for an agent to call this tool correctly without further assumptions.

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 a description for 'to' but not for 'amount'. The description mentions 'with an estimate for an amount', which hints that amount is used to produce an estimate, but it does not clarify whether the amount is in USDC, local currency, or what the estimate represents. It adds some value over the bare schema but fails to fully resolve the ambiguity for the undocumented parameter, especially given the 50% 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 states the tool provides an indicative USDC → local-currency rate at the sale price, with an amount-based estimate, and that the quote is binding. This is a specific verb-resource pairing and distinguishes it from generic 'quote' by emphasizing 'our sale price' and the binding nature. However, it does not explicitly say 'returns a rate' or describe the output format, and it doesn't differentiate from the sibling 'quote' tool directly.

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 offers no guidance on when to use this tool versus siblings like 'quote' or 'buy'. It does not state whether this is a preliminary check before a purchase, if it should be used to fetch a final price, or any exclusions. The agent is left to infer the intended context from the name and description alone.

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?

With no annotations, the description carries the burden of behavioral disclosure. It communicates that the tool is a public read-only-style ledger, which implies no auth or side effects, but it does not explicitly state read-only behavior or any operational constraints such as rate limits or freshness of data.

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 the core identity ('Public delivery ledger') and then efficiently enumerates the returned data. Every phrase contributes information without 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?

Given the tool's simplicity—no parameters, no output schema, no annotations—the description provides a reasonably complete picture: it is a public aggregate view of delivery performance. It could be slightly stronger by explicitly noting that it returns summary metrics rather than detailed order data, but the listed contents largely cover that.

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 there is no parameter documentation burden. The description appropriately focuses on what the result contains rather than input semantics, which is all that is needed 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 identifies a specific resource (public delivery ledger) and names the key data it exposes: totals, delivered-or-refunded percentage, volume, countries, and recent orders. It is clear enough to distinguish from siblings like order_status or list_offers, though it lacks an explicit verb such as 'get' or 'view'.

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 no guidance on when to use this tool versus the sibling tools. It only states that the ledger is public, leaving the agent to infer that it is appropriate for aggregate delivery stats but not for specific order or quote queries.

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?

No annotations are provided, so the description carries the behavioral burden. 'Browse' implies a read-only action, and 'Free' plus 'Prices shown are indicative' add practical context beyond the name. However, it does not explicitly confirm no side effects, authentication requirements, or error behavior, which would be important with no annotation support.

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 sentences, front-loads the purpose and offer categories, and adds a useful pricing caveat. There is no filler or repetition of schema fields.

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 browse tool, the description is close to sufficient: the required `type` is documented in the schema, country scope is stated, and the relationship to `quote` is clear. But with no annotations and no output schema, the undocumented `brand` parameter and the lack of any return-shape or pagination guidance leave meaningful gaps.

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 67%: `type` and `country` are documented, but `brand` is not. The description reinforces the enum categories and the country scope, but it does not clarify what `brand` means or how it interacts with `type` and `country`, leaving a real semantic gap.

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

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

The description opens with a specific verb and resource, 'Browse purchasable offers,' then enumerates the exact offer families: mobile top-ups, travel eSIMs, prepaid bills, and international payment corridors. This clearly separates it from siblings like `buy` and `quote`, especially with the pricing caveat that the quote fixes prices.

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 clear context for when to use the tool: to browse offers for a country, and it explicitly hands off firm pricing to the `quote` tool ('Prices shown are indicative; the quote fixes them'). It does not explicitly list exclusions or when to prefer `buy` or other siblings, but the context is strong.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so excellently. It reveals that the operator is a guess based on number range, that MVNOs resolve to host networks, that confirmation is required before purchase, and that a wrong-network voucher cannot be redeemed or refunded. It also notes the tool is free.

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

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

Every sentence carries essential information: the action, the free aspect, the detection caveat, the MVNO behavior, the required confirmation workflow, and the failure consequence. The description is longer than average but not bloated, and the key caveat is emphasized with clear 'DETECTED' and a direct warning.

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 lookup tool with no output schema, the description covers the core return behavior (country, operator, offers) and even names other_brands as a correction field. It could be more complete by describing the exact output shape or error handling for invalid numbers, but what is present is enough for a capable agent to invoke it correctly and responsibly.

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 documents the single phone parameter with format E.164, giving 100% schema description coverage. The description does not add significant parameter-level detail beyond the schema, which is acceptable but not contributive, so the baseline of 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?

The description opens with a specific action and resource: 'Identify the country and mobile operator of a phone number and list the top-up offers available for it.' This clearly distinguishes the tool from generic list/quote/buy siblings by adding phone-based lookup behavior, and it is not a tautology of the tool name.

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 operational guidance: read the detected brand back to the human, confirm it before buying, and correct it using other_brands. It also explains the risk of buying for the wrong network. It does not explicitly name alternative sibling tools, so it stops short of full when-to-use vs. alternative coverage.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool may not be immediately terminal, requires polling, and details what each terminal state returns (confirmation, signed receipt, refund txid). This is transparent about the expected interaction pattern and response contents.

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 well-organized sentence that front-loads the purpose, then uses a colon and list to convey polling behavior and terminal states. Every word contributes meaning; there is no wasted text 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 has one parameter, no annotations, and no output schema, so the description must cover the essentials. It covers the terminal outcomes and polling interval, but it omits details about non-terminal response shapes, error handling, or what the 'terminal' flag looks like in the response. Some gaps remain for a fully self-sufficient 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 schema has 0% description coverage for the single required parameter 'orderId', so the description must compensate. It only says 'Check an order', which implies orderId identifies the order but provides no format, example, or additional context. For a low-coverage schema, this is insufficient.

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 purpose with a specific verb and resource ('Check an order') and enumerates the three possible terminal outcomes (delivered, refunded, refund_failed), which makes the function of the tool unmistakable. It doesn't explicitly differentiate from the sibling 'verify_receipt', though the focus on order-level status is reasonably distinct.

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: 'Poll every ~3 s until `terminal` is true', which tells the agent exactly how to interact with the tool over time. It doesn't mention when to prefer this over alternatives or provide exclusion criteria, but the polling protocol is concrete and actionable.

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?

With no annotations, the description carries the full burden. It discloses the 10-minute price lock, that the service is free, and what the user receives. It does not mention idempotency, side effects, or failure behavior, but the provided behavioral facts are meaningful and match the tool's purpose.

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, each earning its place: the core action and lock duration, the return payload, and a mandatory UX rule. No filler, fluff, or repetition of schema details. The most critical 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?

The description covers the essential return values and the locking behavior, which is sufficient given the schema's parameter documentation. It lacks explicit linkage to prerequisites (e.g., getting an offerId from list_offers) and does not describe error conditions, but for a pre-purchase quoting tool this is adequate. A slightly richer note on how the quoteId feeds into buy would make it complete.

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

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

Schema description coverage is 75%, so the baseline is 3. The description adds context about outputs (price, deliverables) but does not explain any specific input parameters, nor does it compensate for the 25% of undocumented schema fields. It neither significantly improves nor detracts from what the schema already provides.

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-resource pair ('Lock a price') and scopes it to 'one purchase', clearly distinguishing it from siblings like buy or list_offers. It also states the return values (quoteId, exact USDC price, what will be delivered), leaving no ambiguity about the tool's function.

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's context with 'ALWAYS show the human the price and the recipient before buying', which signals quote's role as a pre-purchase step. It doesn't explicitly name alternatives or exclusions, but the sequential flow (quote before buy) is reasonably clear.

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?

With no annotations provided, the description carries full behavioral burden. It discloses the cryptographic method (ed25519), the verification target (service's public key), and the return content (signature validity and txids). It does not explicitly state read-only behavior, but 'verify' strongly implies it.

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 action and primary resource are front-loaded, and the return values are stated efficiently. Every sentence 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?

For a single-parameter tool with no output schema, the description covers the essential behavior and return values. It lacks explicit error-handling or edge-case details, but the core information needed to invoke the tool correctly is present.

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 only defines orderId as a string with no description. The description implies orderId identifies the order whose receipt to verify, which adds meaning beyond the schema. However, it does not explicitly state the parameter's purpose or expected format, leaving some inference required.

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 a specific verb ('Verify') and resource ('an order's ed25519-signed receipt against the service's published public key'). This is distinct from siblings like order_status or ledger, making the tool's purpose 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 provides clear context: use this tool when you need to verify an order's receipt signature. It does not explicitly mention alternatives or exclusions, but the tool's purpose is distinct enough that no direct competitor exists among the siblings.

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