code402

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

The description goes beyond annotations by explaining the payment flow (x402 paywall, direct wallet payment) and the return payload (listing and paid_endpoint). It suggests both create and update behavior, which aligns with the idempotentHint, but does not detail side effects like overwriting existing entries.

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 well-structured, with two clear sentences covering the operation, endpoint, payload, and return values. It front-loads the primary action and avoids unnecessary elaboration.

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 provides sufficient context for using the tool, including the endpoint, required parameters, and return values. It mentions the seller must be registered, which covers a key prerequisite, but does not discuss error scenarios or idempotency details (though annotations cover idempotency).

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 description restates the parameter list from the schema but adds minimal new meaning. The schema already provides per-parameter descriptions (e.g., 'Price per call'), so the tool description adds little semantic enhancement beyond contextualizing them as part of a paid listing.

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 or updates a paid listing for a registered seller, specifying the exact endpoint and required parameters. It is specific to listing management and distinguishable from sibling tools like registering a seller or querying services.

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 tool is for creating or updating listings but does not explicitly discuss when to use it versus alternatives, such as when a seller needs to be registered first or when a read-only operation is preferred. It implies prerequisites but does not state them as usage guidelines.

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 readOnly, idempotent, openWorld, and non-destructive behavior, so the description doesn't need to repeat that. It adds useful context by naming the endpoint and the response fields (status, service, network), which helps the agent understand exactly what this read-only call returns. 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?

A single, well-structured sentence packs all necessary information: the endpoint, the response shape, and an example of the network value. No fluff or redundancy; it is front-loaded and immediately informative.

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-parameter, read-only health check, the description fully covers what the tool does and what it returns. With annotations already providing safety semantics and no output schema, this description is sufficient for an agent to invoke it correctly without further clarification.

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 no parameters, so the baseline is 4 per guidelines. The description doesn't need to explain parameter meanings, and the 100% schema coverage is trivial for an empty schema. It effectively communicates that no input is 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 the tool checks the gateway's /healthz endpoint and specifies the exact return structure ({ status, service, network }). It is distinct from sibling tools (which focus on listings, sellers, etc.) by naming the specific endpoint and its health-check purpose.

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 usage context is implied: this is for checking gateway health and configuration. It doesn't explicitly mention when not to use it or alternatives, but given the sibling tools, no alternative health check exists, and the description makes its purpose unmistakable. A small gap is the lack of explicit 'use this when you need to know the gateway status or settlement chain.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations with the "(free)" cost disclosure and the exact response structure, giving the agent concrete expectations of the payload. No contradictions; the only minor gap is no mention of data-freshness windows or auth scoping for "own" beyond inference.

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 tightly-scoped sentences with strong front-loading: the first gives the action and endpoint, the second the exact response contract. The compact return type notation is information-dense with zero filler. Every element earns its place; the cost qualifier "(free)" is parenthetically efficient rather than wordy.

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 single-parameter GET tool with strong annotations, the description is nearly complete: it covers what it does, the cost posture, the endpoint, and the exact return shape. Since no output schema exists, the inline return type fills that gap well. Minor absence of notes on result ordering, data freshness, or pagination of by_service are edge omissions for a tool this simple.

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% (the only parameter, sellerId, is documented as a 'Registered seller slug' with a pattern), so the baseline of 3 applies. The description's endpoint URL shows the parameter is path-based but adds little semantic detail beyond the schema's 100% coverage. The description does not meaningfully exceed the schema's parameter documentation—it's consistent, just not additive.

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?

"Fetch a seller's own settlement analytics" uses a specific verb+resource, further grounded by the full endpoint URL (GET /v1/sellers/{sellerId}/analytics). The scope qualifier "own" and the return shape (total_settled_calls, by_service) clearly differentiate it from siblings like code402_get_seller_invoice or code402_list_services. Explicitly identifies the exact resource and operation with no ambiguity.

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 use cases via the "settlement analytics (free)" qualifier and the detailed return shape, which tells the agent what kind of data to expect. However, there is no explicit statement of when to prefer this over get_seller_invoice, list_services, or other siblings, and no exclusions or alternative pointers are given. Usage context is implied rather than stated.

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

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

Annotations already cover read-only, idempotent, and non-destructive aspects, lowering the bar. The description adds meaningful context by specifying the return fields and the USDC integer base units (6 decimals), which clarifies the output format without contradicting 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 concise, packing the API endpoint, purpose, and return fields into two sentences with no redundant content. It is well-structured and 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?

The description explains the core purpose, lists the output fields, and clarifies the unit of amounts, which gives sufficient context for basic usage. It does not delve into fee calculation details or error conditions, but given the schema and annotations, it is reasonably 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?

The schema provides full descriptions for both parameters (sellerId and since), including constraints and units. The description does not add additional meaning beyond what is already in the schema, so it meets the baseline without enhancing understanding.

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: computing a seller's platform-fee invoice from settled receipts. It distinguishes from sibling tools by specifying the invoice calculation and the endpoint, which is specific and 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 implies when to use the tool (when an invoice is needed from settled receipts) but does not explicitly contrast with alternatives like get_seller_analytics or list_services. No direct 'when not to use' guidance is provided, so it relies on implied 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?

Beyond the read-only and idempotent annotations, the description reveals concrete behavior: it returns the same shape as list_services and provides an error with close matches for unknown IDs. This gives the agent a clear expectation of outcomes without relying solely on 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, covering the action, the parameter source, the return shape, and error behavior. There is no redundancy or fluff, making it efficient 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?

For a simple get-by-ID operation, the description covers all essential aspects: what it does, how to identify the resource, what the response looks like, and what happens on failure. The lack of an output schema is mitigated by referencing the shape of list_services, making 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?

The schema already defines serviceId with constraints and an example. The description adds context by indicating the ID should come from list_services, which clarifies the expected value's origin and format, going beyond the schema's type definition.

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 (fetch) and resource (a single service) and distinguishes from siblings like list_services by focusing on a specific serviceId. It also notes the return shape matches list_services, further clarifying its purpose.

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 context by specifying serviceId is 'as returned by code402_list_services', suggesting a typical flow of listing first then fetching. It also mentions error behavior with close matches when the ID is unknown, offering guidance on what to expect. However, it could be more explicit about when to choose this over alternative tools (e.g., list_services or probe_endpoint).

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, idempotentHint, and destructiveHint=false, so the baseline is lower. The description adds valuable context: no account/API key needed, accountless, per-call pricing via x402, and that this tool only discovers, never pays. This goes beyond the annotations and clarifies the tool's non-mutating role in the payment flow. No contradictions found.

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-structured paragraph that front-loads the core purpose ('List services on the code402 gateway storefront') and then efficiently packs essential context: endpoint, data fields, auth model, pricing model, and return format. Every sentence adds value, with no redundancy or filler. It balances detail with brevity.

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 (pagination, filtering, pricing model, accountless design) and the absence of an output schema, the description is notably complete: it includes the full return structure, clarifies the discovery-only nature, and explains the external dependency (x402 client). It covers all necessary aspects for an agent to understand the tool's role and data without additional context. Sibling diversity further justifies this completeness.

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% – each parameter (limit, query, offset) already has a clear description in the schema. The tool description does not add further parameter-level details, but it does reinforce the semantics by mentioning pagination and filtering implicitly. With high schema coverage, a baseline of 3 is appropriate; the description is not required to repeat schema info.

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 lists services on the code402 gateway storefront, specifying GET /v1/services, the resource types (first-party APIs and third-party listings), and the data fields returned. It distinguishes from siblings like code402_get_service (single service) and code402_create_listing (creation) by emphasizing 'List' and 'discovery only'.

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 explicitly says 'this tool only discovers' and explains that actual payment requires an x402-capable HTTP client with the buyer's wallet, setting clear context for when to use this tool (discovery) vs when not (payment). It also notes the accountless nature, which clarifies prerequisites. However, it does not explicitly name alternative sibling tools for discovery vs. retrieval, though the context is sufficient.

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

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

Beyond the annotations (readOnly, non-destructive), the description adds crucial behavioral details: 'No payment is ever sent' and 'Private/internal addresses are rejected.' This informs the agent of limits and outcomes beyond what annotations provide.

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 dense sentences cover action, output, usage, and safety. The information is front-loaded and every sentence adds value 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?

For a tool with a single parameter, no output schema, and clear annotations, the description is complete: it specifies the exact action, output structure, usage scenarios, and constraints. No 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?

The schema already fully describes the URL parameter with a pattern and description. The description adds extra constraint that private/internal addresses are rejected, which is not in the schema but is valuable for parameter handling.

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: sends an unpaid GET to a URL and reports on the x402 challenge and normalized terms. It distinguishes from siblings by focusing on probing rather than listing creation, health checks, or seller operations.

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 indicates when to use: 'Use before budgeting a payment or to liveness-check a listing.' It does not mention alternatives or when-not-to-use, but the intended context is clear and practical.

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?

Discloses key behaviors beyond annotations: non-custodial settlement, wallet immutability, free registration, and fee structure. It also hints at the EIP-191 re-binding requirement, which is valuable context. 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?

Front-loaded with the core action, followed by concise details on endpoint, params, behavior, and fees. The single-paragraph structure is dense but efficient, with no wasted words.

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

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

Despite no output schema, it explicitly lists the return object ({ sellerId, wallet, storefront }). It covers fees, settlement, immutability, and update capability, making it complete for an agent to decide and 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?

Schema already covers all parameter descriptions (100% coverage). The description adds value by explaining the wallet's settlement role and the id format, though it largely reinforces the schema rather than adding entirely new semantics.

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?

Clearly states the action (register a seller or update its name) and resource, with a specific endpoint and payload. It distinguishes from siblings by focusing on seller registration, not listing or analytics.

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 context on when to use (register/update seller) and the immutability caveat. It does not explicitly list alternatives or exclusions, but sibling tools are sufficiently distinct, so the usage is clear.

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