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 read-only and idempotent hints, and the description adds valuable behavioral context: the credential is HMAC-signed, expires in 10 minutes, contains a hash-chained outcome ledger with specific fields, and can be verified via a separate endpoint. 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?

Two dense but purposeful sentences: the first states the action and endpoint, the second explains the credential's internal structure and intended use. No fluff, front-loaded with the core operation.

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 GET with no output schema, the description explains the nature of the returned credential, its fields, TTL, and verification path. It does not describe the exact response envelope or error behavior, but it is sufficiently complete for tool selection and basic invocation.

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 only parameter, agent_id, is fully described in the schema with a pattern and 'Atlas agent id'. The description does not add extra meaning beyond restating that it is the agent's credential, so it relies on the schema's 100% coverage. 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 ('Fetch') and identifies the exact resource ('agent's tamper-evident reputation credential') plus the endpoint path. It clearly distinguishes this from sibling tools by naming the unique credential type and its use case in pricing counterparty risk.

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 on when to use the tool ('Sellers use this to price counterparty risk before serving a new agent') but does not explicitly mention alternatives or exclusion criteria. This meets the 'clear context, no exclusions' level.

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?

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description goes further by explaining the accountless nature ('No account or API key exists or is needed'), the payment model (x402, priced per call), and reiterating that this tool 'only discovers'. This adds substantial context beyond the structured annotations, such as the operational requirement for a wallet when actually paying. There is 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 a single, well-structured paragraph of three sentences. It front-loads the core purpose, then provides essential context about accountlessness and payment, and ends with the return structure. Every sentence contributes information without redundancy or filler. It is concise yet comprehensive.

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 listing tool with no output schema, the description covers the essential details: what it lists, the accountless and payment model, and the return shape (including pagination fields like has_more, next_offset). It does not explicitly explain how to paginate iteratively, but the return object implies it. Given the tool's simplicity and the richness of the description, it is nearly complete; a small gap is the lack of any mention of rate limits or error handling, but those are not expected for discovery tools.

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 baseline is 3. The tool description does not add parameter-specific details beyond what the schema provides, but it does offer contextual hints through the example return object (e.g., offset, has_more) that relate to pagination parameters. It does not improve on the schema descriptions, so a 3 is appropriate.

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

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

The description clearly states the tool's function: 'List services on the code402 gateway storefront', with a specific verb ('List') and resource ('services'). It distinguishes itself from siblings by mentioning 'first-party APIs and third-party seller listings' and explicitly says 'this tool only discovers', which sets it apart from payment or creation tools. The GET /v1/services path adds further clarity.

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 usage context by stating this tool is for discovery only ('this tool only discovers') and clarifies that paying for services requires an x402-capable client with the buyer's own wallet. It also notes that no account or API key is needed, which guides the agent on authentication. However, it does not explicitly name alternative tools or specify when not to use it, but the sibling list and the 'only discovers' phrasing give sufficient implicit 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?

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?

Annotations already indicate a write (readOnlyHint=false), safe (destructiveHint=false), and idempotent. The description adds critical context: wallet immutability, non-custodial nature, fees/Pro pricing, and the return structure, which is valuable beyond annotations. 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 dense but each sentence earns its place (registration/update, immutability, payment settlement, fees, Pro, return object, ownership proof). Wording is efficient, though a long single paragraph could be slightly better organized. It remains concise and 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 no output schema, the description compensates by explicitly stating the return object { sellerId, wallet, storefront }. It covers fees, non-custodial nature, and ownership verification, making the tool's behavior sufficiently comprehensible for an agent. Minor gap: no explicit note on idempotency behavior despite the idempotent hint, but the 'or update' implies it. Overall complete for this complexity.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds the endpoint payload format and that wallet receives USDC payments, but does not explain each param beyond schema descriptions. Baseline 3 is appropriate since the schema already carries the meaning.

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 registers a seller on the gateway and can also update the seller's name, specifying the endpoint and primary action. Among siblings (create_listing, check_health, analytics, etc.), it uniquely covers seller registration, making its purpose unambiguous.

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

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

It explains when to use it (to register a seller or update name) and notes key constraints (wallet immutable, re-binding requires proof). It does not explicitly mention alternatives or when not to use it, but the scope is clear from the endpoint and sibling tool names, so guidance is adequate.

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 annotations already convey readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond those flags: evidence is probe-measured, never self-reported, and the return shape includes settlement details when available. It could mention index freshness or empty-result behavior, but no stated contradiction.

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 dense sentences with no filler. It front-loads the action, then the evidence fields, then the return shape; every clause 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?

Given the simple query parameters, no output schema, and clear annotations, the description is complete. It includes purpose, high-level result shape, evidence fields, optional settlement terms, and the payment safety trigger that motivates use.

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 both parameters completely: q has type, length constraints, and examples; limit has min, max, and default. The description adds little to parameter semantics, but that is acceptable since the input schema itself carries the full burden.

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 names a specific verb and resource: query the code402 Atlas index for measured trust evidence on an endpoint or domain. It lists concrete evidence fields and distinguishes this lookup from the sibling code402_probe_endpoint by emphasizing existing probe-verified evidence in an index.

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 instruction 'Use before letting an agent pay any endpoint' is an explicit, actionable trigger. It does not spell out when-not-to-use or name an alternative tool, but the use context is clear and sufficient for tool selection.

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