402MCP.org — HTTP 402 & Agent Payment Registry

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: it identifies the scheme, returns exact headers needed to pay and retry, and warns that all 402 fields are server-controlled and flagged untrusted — a real input-trust caveat the annotations do not convey.

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

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

Three sentences, front-loaded with the trigger condition, then the effect, then the argument form and trust caveat. Every sentence carries distinct information with no repetition of the title or schema.

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?

An output schema exists, so return structure need not be explained, yet the description still summarizes what comes back (scheme, decoded artifacts, retry steps). Trigger, inputs, and output nature are all covered for this narrow decode tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a routing rule the schema does not state as such: pass either `raw_response`, or `status` plus `headers` (with `body` only for x402 v1). That tells the agent which combinations are valid rather than leaving it to infer from four optional params.

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

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

States a specific trigger (HTTP 402 response or WWW-Authenticate / PAYMENT-REQUIRED headers) and a specific action (identify payment scheme, decode invoice/macaroon/payment requirements, return pay-and-retry steps). This clearly distinguishes it from siblings like probe_402_support and get_scheme_reference.

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?

Gives explicit triggering conditions — 'whenever an HTTP response has status 402, or carries a WWW-Authenticate (L402, LSAT or Payment) or PAYMENT-REQUIRED header' — and tells the agent which argument combination to use. It does not explicitly exclude sibling alternatives, which is why it falls short of a 5.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real behavioral context: rank 1 is a composite-score artifact rather than an endorsement, which warns the agent against over-trusting the result. It stops short of disclosing anything about freshness or rate limits, but the caveat is genuinely useful beyond structured fields.

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 tight sentences with zero filler; the core behavior comes first and the routing caveat second. 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?

An output schema exists, so return-value detail is not needed, and the description still summarizes the payload shape. Combined with a fully documented single optional parameter, the definition is nearly complete; only minor gaps (result freshness / stability of the ranking) remain.

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% and there is a single optional parameter, so the schema already explains that use_case is an optional echo field. The description adds no parameter-level meaning at all, which is acceptable here but 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?

States a specific verb and resource ('Return whichever solution currently holds rank 1 on 402MCP.org') plus the payload ('full breakdown, install commands and code'). It explicitly contrasts itself with the sibling recommend_payment_rail, so an agent can distinguish it without opening either schema.

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?

Gives both the use condition (you want the current rank-1 solution) and the exclusion with a named alternative ('for a choice that fits specific requirements, call recommend_payment_rail instead'). This is explicit when/when-not routing rather than 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only the nature of the content returned (headers, encodings, flow, links), not permission requirements, rate limits, or caching 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?

Two dense sentences: the content inventory leads, the usage trigger follows. No filler, and nothing is buried.

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?

Output schema exists, so return values need no explanation, and annotations cover the safety profile; purpose, scope and usage trigger are all present. The only gap is sibling disambiguation for an agent choosing among seven related 402 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?

With one parameter at 100% schema coverage plus an enum, the schema already carries the semantics; the description restates the three accepted values (L402, x402, MPP) but adds no format or selection guidance beyond them. Baseline 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?

Names the resource precisely (protocol reference for L402/x402/MPP) and enumerates the payload: challenge, credential and receipt headers, encodings, request/response flow, example, spec links. That makes the deliverable unambiguous, though it never contrasts itself with siblings like decode_402_challenge or probe_402_support.

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?

"Use when implementing a client or server" gives a clear context for invoking it. It does not name when to prefer an alternative sibling (e.g. decode_402_challenge for a concrete challenge), so there are no 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, idempotentHint, destructiveHint false, and openWorldHint false, so the safety profile is covered. The description adds that the returned data includes verified code samples and a last-verified date, which is useful provenance context, but it does not disclose auth needs, rate limits, or error behavior. With rich annotations and an existing output schema, this is adequate but not exceptional.

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 tightly structured sentence, front-loaded with the core action and followed by a clear enumeration of the returned fields. Every clause serves to describe the full record and no space is wasted.

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-by-id tool with full schema coverage, rich annotations, and an output schema, the description is complete enough to tell an agent what it returns and that it retrieves one full entry. The only gap is explicit routing guidance versus sibling search and recommendation tools, which is implied but not stated.

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

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

The single parameter has 100% schema description coverage, so the schema already explains that the id comes from search or recommend results. The description adds no additional meaning about the id format, allowed values, or how to obtain it. Baseline 3 is correct when the schema fully documents the parameter.

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

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

The description gives a specific verb ('Return') and resource ('one solution in full') and enumerates exactly what the full entry contains. The phrase 'one solution in full' distinguishes it from list/search and recommendation siblings, so an agent can tell it is a detail-retrieval tool without opening the schema.

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?

Usage is implied: fetch the complete record for a solution id. The description does not state when to use this tool versus search_402_solutions or recommend_payment_rail, and it does not name exclusions. The schema parameter does say the id comes from search or recommend results, but that guidance is not in the description itself.

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?

Adds concrete behavior not covered by annotations: exactly one request, HEAD/GET choice, redirects are reported rather than followed, private and local addresses are refused (SSRF guard), and it never pays. These are operationally significant constraints an agent could not infer from readOnlyHint/idempotentHint alone.

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?

Four tight sentences, front-loaded with the action and the reported output, then the safety constraints. No filler or repetition of the title.

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?

An output schema exists, so return values need no further explanation, and the description still summarizes what is reported. For a two-parameter probe with full annotation and schema coverage, nothing an agent needs to call it correctly is missing.

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% and both parameters are documented there (url as absolute http(s), method defaulting to GET), so the schema does the heavy lifting. The description only echoes the GET/HEAD choice without adding format or default nuance beyond the schema.

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

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

States a concrete operation ("Make one GET (or HEAD) request to a public URL") plus exactly what it returns: 402 presence, scheme, and decoded terms. An agent can distinguish this probing tool from siblings like decode_402_challenge or get_scheme_reference without opening any schema.

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?

Usage is implied by "probe a public URL for 402 support," but the description never names an alternative or states when to prefer this over decode_402_challenge or get_best_payment_solution. Acceptable context, but routing between siblings is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral detail beyond that: results are ranked with reasons and trade-offs, and excluded entries are returned with explanations — non-obvious output behavior worth disclosing.

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 with the core differentiator front-loaded and no filler. The long filter enumeration is justified since it defines scope, though it is slightly list-heavy.

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

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

With an output schema present, the description needn't explain return values, yet it helpfully notes reasons, trade-offs, and exclusions. Combined with 100% schema coverage and rich annotations, an agent has everything needed to invoke it correctly; only the missing sibling reference keeps it from a 5.

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% with self-documenting enums, so the baseline is 3. The description goes further by explaining the weighting consequence of a parameter — 'sub-cent amounts weight settlement cost heavily' — which maps typical_amount_usd to an observable effect the schema does not convey.

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

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

States a specific verb (choose/recommend) and resource (HTTP 402 payment rail) and explicitly frames it as requirements-driven rather than rank-driven, which distinguishes it from get_best_payment_solution. It also enumerates the filter dimensions and the re-weighting behavior, so an agent knows exactly what the tool computes.

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 phrase 'from requirements rather than from rank' clearly signals when to pick this over a ranking-based sibling, and the filter list implies the context of use. However, it never names the alternative tool explicitly, so the routing guidance is clear but not fully prescriptive.

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, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are returned in published rank order and carry scores, schemes, roles, custody and maturity. It does not mention result caps or pagination behavior, though the limit parameter hints at the former.

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 tight sentences with no filler; the core purpose leads, the result-shape detail follows, and the no-argument behavior is last. Every clause carries information the agent can act on.

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?

An output schema exists, so the description needn't spell out return structure, and rich annotations cover the safety profile. The main gap is filter semantics across the six undocumented parameters, but for a zero-required-argument search tool with self-describing enums this is close to 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 only 13% (only the query parameter is documented), so the description carries real weight here. It says 'Free-text query plus filters' and names schemes and custody/maturity as result facets, which loosely maps to the scheme and self_custodial_only filters, but it never explains kind, role, limit, mcp_native_only, or production_only. The enum values are largely self-describing, which keeps this at a baseline 3.

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 ('Search the 402MCP.org registry of HTTP 402 payment solutions') and scopes it to concrete schemes (L402, x402, MPP), so the agent knows exactly what is being queried. It only implicitly distinguishes itself from siblings like get_solution or get_best_payment_solution by noting that results come back ranked as a list rather than as a single pick.

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

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

It gives one concrete usage cue ('Call with no arguments to list the whole registry') and states that free-text query works alongside filters, so basic usage is implied. It never says when to prefer this tool over recommend_payment_rail, get_best_payment_solution, or get_solution, which are the closest alternatives.

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