Coal — Payments for AI agents

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds valuable behavioral context: 'The server holds NO long-lived keys — every payment is signed per-request.' It also discloses the header-based auto-resolution behavior. This enriches the agent's understanding of the tool's security model and invocation 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 three sentences, each earning its place: the first states the core purpose, the second explains address resolution via header or parameters, and the third provides a security assurance. No fluff or redundancy, and the main action is front-loaded in the first sentence.

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 balance-checking tool with optional parameters, the description is complete. It covers authentication methods, the scope of addresses that can be checked, and a security note. There is no output schema, but the return value is self-evident for a balance check. The annotations already declare safety properties, and the description fills in the remaining context.

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 schema already documents both parameters. The description adds context by connecting them to the header logic ('Otherwise pass `address` or `agentPrivateKey`'), but it doesn't provide new format or syntax details beyond the schema. This matches the baseline of 3 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 states a specific verb+resource: 'Check the USDC balance for your agent wallet (or any address).' This clearly distinguishes the tool from sibling tools like check_paywall, get_checkout_status, and verify_receipt, which focus on payments, checkouts, and receipts rather than wallet balances.

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 explicit usage guidance on how to specify the address: if `X-Coal-Agent-Key` is set in the header, it auto-resolves; otherwise pass `address` or `agentPrivateKey`. While it does not explicitly name alternatives or exclusions, it clearly explains prerequisites and the two valid invocation patterns, which is more than most tool descriptions offer.

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, openWorldHint, and idempotentHint, which cover safety and side-effect expectations. The description adds valuable context by explaining the conditional return behavior: pricing info if not paid, content access status if paid. This goes beyond what annotations provide and gives a clear picture of what the tool will do.

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 sentence that front-loads the main purpose and includes the key outcome detail. It is concise, clear, and free of unnecessary words. Every word contributes to understanding the tool's behavior.

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 low complexity (two parameters, no nested objects, no output schema), the description is largely complete. It explains the return scenarios and the core function. However, it does not explicitly mention that the address is optional or describe possible errors/edge cases, so it is not fully comprehensive, but it is adequate for a simple read-only 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?

The schema describes both parameters (address and paywallId) with 100% coverage. The description does not add much detail beyond the schema; it mentions the address and specific paywall but does not explain formats or any parameter interactions. Since schema coverage is high, the baseline is 3, and the description neither improves nor degrades it.

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

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

The description clearly states the tool's function: checking if an address has paid for an x402 paywall. It specifies the resource (paywall access) and the action (check), and it differentiates the outcome between pricing info and content access status. However, it does not explicitly distinguish itself from sibling tools like verify_receipt or get_checkout_status, so it loses one point for lacking that 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 the tool is used to check paywall payment status, which gives some context. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any prerequisites or exclusions. The usage context is clear enough to infer, but there is no direct guidance on selection among sibling tools.

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 API key requirements (header or per-call), settlement network and time (~2s), and the fact that it returns a checkout URL. These traits go beyond the annotations, which only indicate read-only/idempotent/destructive hints, providing critical operational context.

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

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

The description is three focused sentences covering purpose, behavior, and authentication. No redundant content, each sentence adds value, and key 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 complexity (5 params, no output schema), the description covers purpose, output, settlement details, and API key setup. It lacks edge-case guidance (e.g., product vs amount precedence) but is generally complete for an AI agent to invoke 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 provides descriptions for all 5 parameters (100% coverage), so the description adds little parameter-specific detail. It does clarify that payment can be for a product or amount, aligning with productId and amount, but this is marginal. 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 'Create a Coal checkout session to pay for a product or amount,' specifying the verb and resource. It distinguishes from siblings like pay_merchant and get_checkout_status by focusing on session creation and returning a checkout URL.

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: it is for initiating a checkout, settles in USDC on Base, and requires an API key. However, it does not explicitly mention when to use this tool over alternatives like pay_merchant, so it slightly lacks explicit 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, openWorldHint, and idempotentHint. The description adds valuable behavioral context: the returned Markdown format includes inline images, prices, and payout addresses, and notes the funded wallet via X-Coal-Agent-Key. This goes beyond the annotations without contradicting them.

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 well-structured and front-loaded with the key directive. It is slightly repetitive with the three 'BEFORE' clauses, but each adds emphasis on priority. Overall, it is concise for the amount of guidance it provides.

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

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

The description fully covers the tool's role in the purchasing workflow, its return value (Markdown grid with key details), and the next step (pay_merchant). Even without an output schema, the return format is adequately described, and the annotations cover safety. Completeness is high.

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 schema coverage is 100% by default. The description adds no parameter-specific details, but with no parameters to document, the baseline of 4 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 explicitly states it is the default first call for browsing/buying, lists numerous synonymous verbs (buy, get, fetch, etc.), and clarifies that it returns a Markdown product grid with images, prices, and payout addresses. It distinguishes itself from payment tools by directing users to pay_merchant after picking a match.

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 explicit usage guidance: 'THE DEFAULT FIRST CALL' and instructs to call it before asking the user, searching the web, or claiming inability to purchase. Clearly indicates when not to use alternatives and sets the agent's role to 'find the right product and confirm the spend.'

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 readOnlyHint, openWorldHint, and idempotentHint annotations covering safety, the description adds useful context: prerequisite of payment, return of a verified download URL, and supported product slugs. It does not mention edge cases like URL expiration, but only a minor gap.

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, each adding distinct value: action and prerequisite, authentication methods, and return type/product support. No redundant wording or filler.

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

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

The description covers the core prerequisites (paid, product slug, auth identifiers), return value (verified download URL), and supported products. With no output schema, the only missing piece is explicit error/edge-case behavior, but the description is largely complete for its straightforward purpose.

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 descriptions already cover all three parameters (100% coverage). The description adds meaning by explaining the source and preferred flow for each identifier ('On-chain txHash from pay_merchant (preferred for agent flows)', 'Coal checkout sessionId'), and lists the exact product slug with price.

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 ('Retrieve / download / get the file') for a clear resource ('digital product after the user paid for it'). It distinguishes itself from siblings like pay_merchant by requiring prior payment and from check_paywall by returning a download URL.

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 use 'after pay_merchant succeeds' for digital goods, and provides two authentication identifiers (txHash from pay_merchant, sessionId from Coal checkout) with preferences. This clearly defines when to use the tool versus 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 indicate a read-only, idempotent, open-world operation. The description adds specific behavioral context by naming the 5 components and emphasizing 'live' status, implying real-time data. This goes beyond the annotations without contradicting them.

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, front-loaded sentence with no wasted words. It conveys all essential information efficiently.

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 low complexity (no parameters, no output schema), the description fully covers what the agent needs: what components are checked and that the status is live. No additional context is necessary.

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 no parameters, so the baseline is 4. The description appropriately focuses on the tool's action and scope, requiring no parameter explanation.

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 live status of all 5 0G components (Storage, Chain, Compute, KV, DA), using a specific verb and resource. This distinguishes it from sibling tools which are all commerce/payment related.

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 tool's purpose is self-evident as a health check, and the sibling context shows no overlapping tools. However, it does not explicitly state when to use it or mention alternatives/exclusions, so it earns a 4 rather than 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?

Annotations already state readOnlyHint, openWorldHint, and idempotentHint. The description adds value by listing the possible status values, which informs the agent about expected return states without contradicting the 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 a single concise sentence, front-loaded with the verb 'check' and resource, and efficiently lists statuses. Every word contributes to clarity with no 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?

For a simple read-only tool with one parameter and no output schema, the description provides sufficient context: it states what the tool does and enumerates the possible return statuses, which act as the expected output. Annotations cover safety and idempotency concerns.

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 covers the only parameter 'sessionId' with a clear description ('Checkout session ID'), achieving 100% schema description coverage. The tool description does not add further parameter semantics beyond the schema, so 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 uses a specific verb 'check' and identifies the resource 'payment status of a checkout session'. It also enumerates possible statuses (pending, verifying, confirmed, expired, failed), making the tool's purpose unambiguous and distinct from siblings like create_checkout or pay_merchant.

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 when-to-use or alternative guidance is provided. The description implies usage (checking payment status) but does not contrast with related tools like verify_receipt or check_paywall, so the agent must infer appropriate usage from context.

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

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

The description discloses the return format ('rendered Markdown') and the specific data fields included, which goes beyond the readOnlyHint and idempotentHint annotations. It does not cover error handling or not-found scenarios, but the annotations already establish the safe, read-only nature, so the added context is valuable.

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: the first lists what is retrieved, the second states the output format. It is front-loaded with the primary action and avoids unnecessary 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 single-parameter read-only operation with clear annotations and no output schema, the description sufficiently captures the tool's purpose, contents, and return format. It is complete for an agent to select and invoke 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?

Schema coverage is 100%, and the description adds no additional meaning beyond the schema's definition of merchantId as 'Coal merchant ID'. The parameter is simple and self-explanatory, so the baseline score 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 uses a specific verb ('Get') and resource ('full profile of a Coal merchant'), enumerating the specific data included (products, paywalls, networks/tokens, 0G proof). This clearly defines the tool's function and distinguishes it from sibling tools like discover_merchants or search_products by focusing on a single merchant's comprehensive profile.

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: to retrieve a complete profile for a known merchant ID, but it does not explicitly state when to use this over alternatives or mention any prerequisites. No exclusions or alternative tool references are provided, leaving the agent to infer based on the tool name and sibling list.

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 adds significant context beyond the annotations: it's a real payment ('sends real USDC'), has a max amount ($5), is gasless (Coal pays gas), automatically uses the X-Coal-Agent-Key header, and returns an on-chain tx hash. It also implies external side effects aligned with `openWorldHint` and `destructiveHint`. 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 longer than typical but every sentence earns its place, covering purpose, usage trigger, gas details, key handling, limits, and follow-up. It's front-loaded with the core action and then supplies necessary constraints. Slight verbosity keeps it from a 5, but it remains efficiently structured.

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?

Despite no output schema, the description states the return value (tx hash) and the necessary follow-up (`download_product`). It covers prerequisites (key from header), limits (max $5), and the real-world nature of the transaction. For a payment tool with annotations and a clear schema, this is complete enough for an agent to operate effectively.

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 has 100% coverage, so baseline is 3. However, the description adds crucial disambiguation: `to` is the merchant payout address, not merchantId, and clarifies that `amount` is capped at $5. It also explains `agentPrivateKey` is optional if the header is set, which is not immediately obvious from the schema alone.

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 specifies the exact action ('Send USDC on Base to any merchant payout address') and explicitly distinguishes the target field (`payoutAddress`, NOT `merchantId`), making it clear this tool handles real payments. It differentiates from sibling tools like `discover_merchants` by saying the address comes from that tool's output, so the agent knows exactly when to use this 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?

Explicit usage trigger is given: 'Use this whenever the user has confirmed they want to buy, purchase, pay, or send money for something.' It also provides a post-condition ('After this succeeds for a digital product, immediately call download_product with the returned tx hash') and clarifies key handling ('no need to ask the user for a key'), giving clear when-to-use and follow-up 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 and openWorldHint, but the description adds important context: the requirement of a Coal API key (with header vs per-call options) and the use of 0G Compute with Sealed Inference (TEE). This goes beyond the annotations and helps the agent understand authentication and privacy/execution context.

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

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

The description is three sentences, front-loaded with the purpose. The API key setup is necessary but could be more concise. The mention of 'Powered by 0G Compute with Sealed Inference (TEE)' is slightly promotional but does provide transparency about the underlying service. Overall, it is reasonably 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?

The tool has no output schema, so the description should clarify what the response looks like. It implies a natural language answer but does not explicitly say so. However, the authentication instructions and purpose are clear, and the annotations cover read-only/open-world behavior. For a query tool, this is mostly sufficient.

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 parameters are well-described in the schema. The description adds extra value for coalApiKey by explaining how to provide it (header or per-call) and where to obtain one, which is not in the schema. The merchantId and question parameters are already clear from their schema descriptions.

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

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

The description clearly states the tool's function: ask a natural language question about a merchant's products, policies, or catalog. It uses a specific verb ('ask') and resource ('merchant's products/policies/catalog'), which distinguishes it from sibling tools like search_products or get_merchant_profile.

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 indicates the use case ('natural language question') but does not explicitly contrast with alternatives or state when not to use it. The setup instructions for the API key add operational context, but there is no mention of sibling tools like search_products or discover_merchants.

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, openWorldHint, and idempotentHint, covering the safety profile. The description adds valuable behavioral context by specifying the return format (Markdown product grid with images), which is not evident from the schema or annotations. It does not contradict annotations.

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

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

Three short sentences, each earning its place: what it does, return format, and a usage example. No redundancy or filler.

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

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

For a read-only search tool with no required parameters and no output schema, the description covers the core behavior, filters, return format, and a usage case. It could mention potential limits or pagination, but the simplicity and annotations make it sufficiently 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 100%, so the schema already fully documents all three parameters. The description repeats the filters (name, max price, tag) but adds little beyond the schema. It aligns with the baseline for complete 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's function: searching products across all Coal merchants, with specific filter options. It distinguishes from siblings like discover_merchants by focusing on products rather than merchants or other entities.

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 an explicit use case: 'Use this when looking for something specific like "find a figurine under $1"'. This gives clear context for when to use it, though it doesn't explicitly mention alternatives or when not to use it, which would make it 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description's 'Print' verb aligns with these. The description adds behavioral context about the tool being a first-step diagnostic for authentication issues, which is helpful beyond the bare annotation flags. No contradictions 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 two sentences, front-loaded with the action ('Print step-by-step instructions') and includes a clear usage trigger. Every word earns its place; there is no fluff 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?

For a tool with no parameters, no output schema, and a simple purpose, the description is fully complete. It explains what the tool does, when to use it, and what context it addresses (authentication/credentials). There are no missing pieces given the tool's simplicity.

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 and the schema is empty, so schema coverage is effectively 100%. The description adds no parameter information, but none is needed. With zero params, the baseline of 4 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 and resource: 'Print step-by-step instructions for using Coal MCP' from multiple clients. It clearly distinguishes itself from sibling tools like pay_merchant or create_checkout by being a meta-level setup guide focused on authentication and usage setup.

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 when-to-use guidance: 'Run this FIRST if you are unsure how to authenticate or which credentials to provide.' It does not explicitly state when not to use it or name alternatives, but the conditional 'if unsure' implies a clear boundary, and the tool has no direct sibling 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 indicate read-only, idempotent behavior, so the bar is lowered. The description adds value by disclosing the output structure (Base TX, 0G Storage receipt, 0G Chain anchor), which goes beyond the annotations. It doesn't cover failure behavior or state prerequisites, but for a read-only verification tool this is acceptable.

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 one focused sentence that front-loads the action and resource, then concisely lists the proof trail elements. Every word earns its place with no 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 (one parameter, no output schema), and the description provides both purpose and the key output components. It could be slightly stronger by stating that this is for completed payments or that verification may fail, but given the tool's scope and annotations, it is largely 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 coverage is 100% – the single parameter sessionId is already described in the schema as 'Checkout session ID'. The description does not add any extra meaning beyond the schema, 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 has a specific verb ('verify') and resource ('payment receipt'), and goes further to explain the exact output: a 3-step proof trail. This clearly distinguishes it from siblings like get_checkout_status, which would focus on status rather than proof of payment.

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 strongly implies when to use the tool (when you need to verify a receipt and view its proof trail), but it does not explicitly state alternatives or when-not-to-use cases. The presence of sibling tools like get_checkout_status creates potential confusion that is not addressed.

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