topup

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

With no annotations provided, the description carries the full disclosure burden and succeeds emphatically: it corrects the misleading 'buy' name by stating the server 'holds no wallet' and 'does NOT spend your money.' It also discloses what is returned (amount, asset, payTo, facilitator) and the required follow-up step, which is exactly the high-risk behavioral context an agent needs.

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

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

Three sentences, front-loaded with the core purpose before the safety clarification. The second sentence is long, but every clause carries necessary information about the returned fields and the payment flow. 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?

For a one-parameter tool with no output schema and no annotations, the description covers the purpose, the exact returned values, the cardinal safety property, and the next step in the workflow. The only notable absence is explicit quoteId semantics; everything an agent needs to invoke and continue after the call is otherwise 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?

Schema description coverage is 0%, so the description must compensate for the undocumented quoteId parameter, but it never mentions the parameter by name or states where its value comes from. The phrase 'for a quote' implies quoteId references a previously created quote, but format, source, and validation are left to inference. For a single-param tool this is a noticeable but not severe 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—'Get the x402 payment challenge for a quote'—which clearly distinguishes this from sibling tools like quote (which creates the quote) and order_status (which tracks it). It goes well beyond the bare name 'buy' by stating exactly what is returned and where the operation sits in the payment 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 gives a clear precondition—'Requires prior human confirmation of the quote'—and maps the workflow position: fetch the challenge here, pay from your own wallet, then POST the quote again with the payment signature. It doesn't explicitly name alternative tools or give when-not-to-use conditions, so it falls 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 carries the behavioral burden. It discloses key traits: the agent never holds a key, results appear on the page, the link is free, top-up links can be paid by anyone, and eSIM links deliver to the payer. It does not mention the API return value or error behavior, but the provided traits go beyond the schema.

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 relatively long but every sentence adds value: purpose, use case, security trait, delivery semantics, cost, and referral benefit. It front-loads the core purpose and usage condition, though some marketing phrasing like 'send it to family' could be trimmed.

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 tool with 8 parameters, no annotations, and no output schema, the description should clearly state what the tool returns to the caller. It describes the payer's experience (result appears on the page) but does not explicitly say the tool returns a checkout URL or link. This gap leaves the agent uncertain about the direct response, making 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?

Schema coverage is 75%, so the description adds meaningful context beyond the schema. It explains `ref` as an Algorand address for referral earnings, and maps `type` values (topup/esim) to payment and delivery behavior. However, `offerId` remains unexplained, so it doesn't fully compensate for the undocumented parameter.

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

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

The description clearly states the tool creates a checkout link where a human pays from their own Algorand wallet, which is a specific verb, resource, and payment model. It distinguishes from likely sibling 'buy' by emphasizing 'no wallet' and self-payment, though it does not name the sibling explicitly.

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

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

It gives explicit when-to-use guidance: 'Use this when you have no wallet, or when the person should approve and pay themselves.' It also clarifies delivery semantics for top-up vs. eSIM links, but does not state when not to use or explicitly name alternatives, so it falls 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does usefully state that the rate is at the sale price and that the quote is binding, but it does not reveal whether the call commits funds, expires, requires authentication, or has side effects. The wording 'indicative' alongside 'binding' also creates ambiguity about the actual commitment level.

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 directional rate information. Each sentence earns its place, and the binding-price caveat is brief but important. No filler or redundant restatement of the schema exists.

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 annotations and no output schema, the description leaves significant gaps: no return-value description, no quote expiry or commitment details, and no differentiation from the sibling 'quote' tool. The binding-price note helps, but an agent cannot fully determine invocation consequences or expected output from this description alone.

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 67%, with 'to' and 'type' already described, leaving 'amount' undocumented. The description partially compensates by saying the tool gives 'an estimate for an amount', but it does not clarify units, optionality beyond the schema, or how the estimate is computed. This is adequate but not thorough.

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 and purpose: an indicative USDC-to-local-currency rate at the sale price, with an amount estimate. It also adds a distinguishing trait by stating the quote is binding. However, it lacks an explicit verb like 'get' or 'retrieve', and it does not directly differentiate itself from the sibling tool 'quote', so it stops short of a 5.

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 guidance is given about when to use this tool versus the sibling alternatives such as 'quote', 'buy', or 'list_offers'. The description does not mention conditions, exclusions, or scenarios that should route an agent to a different tool. This is essentially a no-guidance case.

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 of behavioral disclosure. 'Public' usefully signals no auth, and the ledger framing suggests a read-only informational call, but the description does not explicitly confirm side-effect-free behavior or describe output/pagination. It is clear but not deeply transparent.

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 front-loads the tool's identity and packs the content categories after a colon with no filler. Every phrase adds 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?

For a zero-argument informational tool, the description covers what data is available and that access is public, which is enough to invoke it. It omits output shape (single summary object vs list) and any note on how 'recent orders' is defined, but the low complexity limits the gap.

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 the description has no parameter semantics to clarify; the schema already encodes the complete parameter surface. Baseline 4 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 identifies a public delivery ledger and enumerates its contents (totals, delivered-or-refunded %, volume, countries, recent orders), so an agent knows what data the tool exposes. It lacks an action verb and does not explicitly contrast it with siblings like order_status or list_offers, so it falls short of a top 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?

The description implies the tool is for retrieving aggregate delivery statistics rather than individual orders or actions, distinguishing it by subject matter from siblings like buy, quote, or order_status. It does not explicitly state when to choose it over alternatives or note any exclusions, leaving use-case routing mostly 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?

With no annotations, the description carries the behavioral disclosure burden. It adds valuable traits: the call is free, prices are indicative rather than final, and the quote operation is what fixes them. It does not mention pagination or return format, but 'browse' sufficiently implies a read-only listing operation.

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 filler. It front-loads the core purpose and offer-type enumeration, then adds the free cost and indicative-price caveat concisely. 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 read-only browse tool, the description plus schema covers the offer categories, country filtering, pagination semantics, and the key pricing caveat. No output schema exists, but the offset parameter's schema description already references next_offset. A minor gap is the lack of an explicit return format, but it is not critical for calling this 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 80%, so the schema already documents most parameters. The description mirrors the type enum by listing categories but adds little beyond it, and the undocumented 'brand' parameter is not clarified in the description either. Baseline 3 is appropriate because the schema does most of the work.

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 ('Browse') with a clear resource ('purchasable offers') and enumerates the four offer categories: mobile top-ups, travel eSIMs, prepaid bills, and international payment corridors. It also distinguishes itself from transactional siblings by noting that shown prices are indicative and that the quote tool fixes them.

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 discovery before a purchase/quote and notes the call is free, but it never explicitly names alternatives or states when not to use this tool. The contrast with quote is only implicit through 'the quote fixes them,' so the agent must infer the routing decision.

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 and delivers substantial behavioral disclosure: the operator is a DETECTED guess from the number range, MVNOs resolve to their host network, and buying a voucher for the wrong network delivers successfully but cannot be redeemed or refunded. It also mentions the correction path via other_brands and that the tool is free, which are material beyond the schema.

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, then concisely adds the free status, the detection caveat, and the critical purchase-confirmation workflow. Every sentence carries distinct information with no filler or repetition.

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

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

The description covers purpose, uncertainty of operator detection, the need for human confirmation, correction via other_brands, and the failure mode of a wrong-network purchase. It does not describe the structure of the returned top-up offers or how other_brands appears in the response, but the operational guidance is strong for a tool with no 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 single parameter is already fully documented in the schema as an E.164 phone string with an example, so the description does not need to duplicate that. The description adds context about the purpose of the phone number but no additional constraints, formats, or parameter-specific guidance.

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 identifies the country and mobile operator of a phone number and lists top-up offers, which goes well beyond the tool name. It does not explicitly differentiate itself from the sibling tool list_offers, so sibling distinction is incomplete.

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 establishes a clear pre-purchase workflow by instructing the agent to read the detected brand back to the human and have it confirmed before buying. However, it does not explicitly state when to use this tool over list_offers or other siblings, leaving the tool-selection context implicit.

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 disclosure burden and does well: it reveals that this is a polling operation (not one-shot), the ~3s cadence, the `terminal` condition, and the payload content of each terminal state (confirmation + signed receipt, refund txid + signed receipt). It falls short of a 5 by not covering timeout behavior, non-terminal response shape, or failure/error cases.

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 purpose, then a dense second sentence carrying the polling cadence and terminal-state contract. Every word earns its place; 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 one-parameter status tool with no output schema, the description covers the critical contract: the polling loop, the stop condition, and the three terminal outcomes. The notable gap is guidance on what to do if `terminal` never becomes true or an error occurs, but the core invocation knowledge 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?

Schema description coverage is 0%, so the description must compensate. 'Check an order' confirms that orderId identifies the order being polled, which is a minimal semantic contribution, but it adds no format, origin, or validation guidance for the parameter.

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

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

The description states a specific verb and resource ('Check an order') and adds concrete scope via the terminal states: delivered, refunded, refund_failed. It is clearly distinct from siblings like buy, quote, and verify_receipt, though it never names a sibling explicitly, so it stops short of a 5.

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 operational guidance: 'Poll every ~3 s until `terminal` is true' and specifies the exact stop conditions. This is clear context for how to use the tool, but it does not mention when not to use it or point to alternatives like verify_receipt.

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 a 10-minute price lock, states it is free, and describes the return content. It also instructs the agent to always show the price and recipient to the human, which is behavioral guidance. However, it does not mention side effects, error behavior, or any prerequisites (e.g., authentication). It provides useful context but lacks comprehensive behavioral disclosure.

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 with zero waste. The core action and time limit are front-loaded, followed by the output and a critical safety instruction. Every sentence earns its place, and the structure is clear and efficient.

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

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

This is a complex tool with 9 parameters, nested objects, and no output schema. The description is minimal, covering only the high-level purpose and one safety instruction. It does not explain how to construct requests, handle nested fields, or interpret results. While the schema covers parameter semantics, the description lacks operational context, making it incomplete for an agent to use correctly without additional guidance.

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 78%, so the schema already documents most parameters. The description does not add any parameter-specific meaning; it only mentions 'one purchase' without elaborating on fields. The baseline for high coverage is 3, and the description adds no extra value beyond that.

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: 'Lock a price (10 minutes) for one purchase.' It also specifies the key outputs (quoteId, exact USDC price, what will be delivered). This is a specific verb-resource pair and distinguishes it from 'buy' by focusing on price locking rather than execution. However, it does not explicitly contrast with sibling tools, so it lacks full differentiation.

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 before buying ('ALWAYS show the human the price... before buying') but does not explicitly state when to use quote versus buy or other siblings. No exclusions or alternative tool references are provided. The guidance is implicit, not explicit, so the agent must infer the 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?

With no annotations, the description carries the burden of behavioral disclosure. It explains the on-chain verification behavior and the onChain:false caveat, which is valuable. However, it does not disclose return format, error behavior, or side effects (e.g., network dependencies), leaving some uncertainty for an agent.

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-loaded with the core verification action, and each clause adds a distinct piece of information. It avoids repetition and is easy to parse quickly.

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 verification tool with no output schema, the description covers the input modes and the on-chain nuance well. However, it does not specify what the tool returns (e.g., boolean, receipt details, or error reasons), which is important for an agent to interpret the result. This leaves a moderate completeness gap.

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. The description adds meaningful semantics beyond the schema by explaining the relationship between orderId and receipt, and by clarifying that onChain:false disables both txid checks. This extra context justifies a higher score.

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: verify an ed25519-signed receipt, its signature, and optionally the txids against an Algorand indexer. It also distinguishes two use cases (orderId vs receipt object), which separates it clearly from sibling tools like order_status or quote.

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: use orderId to verify this service's own orders, or pass a receipt object to verify any receipt in the format, including from another server. It does not explicitly mention when not to use the tool relative to siblings, but the sibling set is distinct enough that no exclusion is necessary.

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