x402 Doctor

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely new operational facts: zero cost, a 10-calls-per-hour rate limit, that it performs an on-chain existence/success lookup, and that it resolves payer/payee USDC transfers. That is meaningful disclosure beyond the annotation set, though it doesn't explain failure modes for an invalid or unmatched header.

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?

One dense but well-ordered sentence covering cost, when to call, input provenance, and return contents, followed by two short qualifiers for read-only and rate limit. No filler and the key facts are 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?

An output schema exists, so return values needn't be spelled out, yet the description still summarizes them helpfully. Cost, rate limit, input source, and mutation profile are all covered — nothing an agent needs to call this 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 coverage is 100% and the single parameter is already documented as a base64 JSON header value. The description adds provenance and format guidance — which header to grab, the X-PAYMENT-RESPONSE v1 naming — giving it value above the baseline 3 for fully-covered schemas.

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 (check an x402 payment proof) and enumerates exactly what it returns: transaction, network, payer, on-chain existence/success, USDC movement, explorer link. It doesn't explicitly differentiate itself from the closest sibling, verify_receipt, so it falls short of a 5.

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

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

Gives clear triggering context — 'after paying an x402 endpoint, pass the PAYMENT-RESPONSE header it returned' — and notes the v1 header name variant. It offers no explicit exclusion or comparison to alternatives such as verify_receipt, so the when-not guidance is missing.

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 open-world annotations, it explains that validity requires Active status, an agent_uri card matching the on-chain metadata_hash, and presence of the badge on that card. It also discloses the additional CIS-8 registry check and the shared free quota of 10 calls per hour, which are material operational behaviors.

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 purpose is front-loaded, and the alternative-tool guidance and rate limit are easy to locate. However, the second sentence packs numerous return fields and validation conditions into dense prose, some of which duplicates the output schema, while 'Read-only' repeats the annotations.

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

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

For a one-parameter read operation with complete input documentation and an output schema, the description supplies the selection and invocation context an agent needs: identifier choices, precise validity semantics, the relevant sibling alternative, and quota constraints. No material prerequisite or behavioral gap is apparent.

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 already provides the badge example, ccd:<genesis>/cis-2:<address> syntax, length limits, and registry-app Agent ID alternative. The description adds some context about where these identifiers come from, but largely restates the schema without adding validation or error-handling guidance.

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

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

The opening sentence identifies a specific operation and resource: looking up an agent in Concordium's CIS-8004 Agent Registry using a badge, CIS-2 token address, or registry Agent ID. It also distinguishes this lookup from x402_payee_check, making its role clear among the payment-oriented siblings.

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 accepted identifier forms make the intended lookup scenarios explicit. The instruction to use x402_payee_check when checking an x402 endpoint's payTos against its seller's badge provides a concrete condition for selecting the alternative.

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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false; the description adds meaningful context that a person reads every report and nothing is run or changed automatically, clarifying the submission is inert. This is useful beyond the annotations, though it could be read as slightly at odds with the non-readonly hint.

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, front-loaded with what the tool does, followed by cost and behavioral expectations. No 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 simple feedback form with a full output schema and complete param documentation, the description supplies the essential unknowns: cost, human review, and that no automated action occurs. Nothing an agent needs 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 coverage is 100% with descriptions and an enum for type, so parameters are already fully documented. The description adds no per-parameter format or syntax detail beyond calling the report 'structured', so 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?

States a specific verb (report) and resource (a bug, missing feature, or anything else about the service) and the structured nature of the submission. It clearly occupies a distinct role from the sibling security-check tools, none of which share this function.

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?

Makes clear this is the channel for reporting issues and notes it is free with human review, which sets expectations for use. It does not explicitly state when-not to use it or name alternatives, but the sibling set is unrelated so the context is unambiguous.

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 openWorldHint=false, and "Read-only, nothing is stored" largely restates that. The genuinely additive disclosures are the failure semantics ("A changed verdict or receipt fails") and the free/no-cost nature, plus the HTTP endpoint equivalence — useful, but thin beyond what the annotations already imply.

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-loads "Free" and the core action, then the mechanics of what to pass and what comes back, with no filler. The parenthetical tool list is long but earns its place by telling the agent which answers are verifiable.

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?

Covers cost, safety profile, input requirement, return fields, failure condition, and the REST equivalent, which is substantial for a three-parameter tool with an output schema. The main gap is the lack of any routing cue against check_payment_proof, leaving ambiguity in a crowded verification-tool family.

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 all three parameters; the description only adds that route and input together enable the exact-request check, which is a modest but real gain over the schema. Baseline 3 applies since the schema does the heavy lifting.

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 ("check the signed receipt that every paid x402 Doctor answer carries") and enumerates which answer types carry receipts (diagnose, preflight, batch, deep, fix, delivery check; HTTP or MCP). That scope is very clear, but it never distinguishes itself from the verification-oriented sibling check_payment_proof, so an agent still has to infer which verifier applies.

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 a concrete motivating scenario ("to prove later which verdict you got before paying an endpoint") and states the calling convention ("Pass the whole answer as response"). It stops short of explicit when-not guidance or naming an alternative verifier for the cases this one does not cover.

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?

Goes well beyond the annotations: discloses the caller's price ($0.25 across listed chains/RLUSD), that the tool itself spends up to $0.1 from its own wallet, that it returns a job id immediately and is asynchronous, that refusals happen pre-payment, and that a signed EIP-191 receipt bound to the arguments is returned. It also disambiguates that this is a purchase, not a read, which is consistent with readOnlyHint=false and openWorldHint=true.

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?

Dense but well ordered: price, what it does, async handoff, refusal conditions, endpoint equivalent, receipt. The long parenthetical chain list (Solana, Monad, Polygon, Arbitrum, Avalanche, Algorand, Stellar, XRP Ledger) is front-loaded clutter, though it does convey accepted payment rails.

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 an async paid job tool it covers everything an agent needs: cost, prerequisite gating, immediate job-id return, the polling sibling, and the receipt artifact. Since an output schema exists, the description is not obliged to describe return values, and it already names the job id and receipt semantics.

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 two parameters already document the https/third-party/USDC-on-Base constraint on url and the GET-then-POST default for method. The description restates the payment-currency constraint but adds no new syntax or format detail beyond the schema, so the 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?

States a specific, multi-step action on a specific resource: it buys the endpoint once with the listing's example input, validates the answer against the declared output schema, has a judge verdict it, and measures the on-chain charge. It also names the sibling it hands off to (x402_delivery_status) and the prerequisite check, so an agent can separate it from x402_diagnose / x402_preflight without opening schemas.

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 prerequisite conditions explicitly (must get a 'go' from the pre-payment check and be payable in USDC on Base, otherwise refused before payment) and the correct follow-up path (poll x402_delivery_status, free, result in minutes). It stops short of saying when to prefer x402_quick_check or x402_preflight_deep instead, so the alternative-selection guidance is incomplete.

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 openWorldHint=false, so the safety profile is covered. The description adds valuable context beyond that: the call is free, it exposes a state machine (awaiting_payment, queued, done), and on completion returns paid_and_delivered, the outcome, the on-chain measured charge and the transaction. No contradictions.

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-loads the key points (free, status, source tool) and packs the state list efficiently into one sentence. It is dense and slightly run-on, but 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 a single required parameter, an output schema, and read-only annotations, the description covers what an agent needs: the source of the id, the possible states, and what becomes available once done. Polling cadence or retry guidance is not stated, but it is not essential to call 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 schema itself explains the single `id` parameter as 'The job id x402_delivery_check answered with'. The description reinforces where the id comes from but adds no syntax or format details beyond the schema. 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?

States a specific verb and resource: retrieves the status of a delivery check. It distinguishes itself from sibling x402_delivery_check by saying the check was 'ordered with' that tool, and lists the possible states, so an agent can tell exactly what this returns.

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?

Clearly implies when to use it: after ordering a check via x402_delivery_check (or the GET endpoint). It does not explicitly state exclusions or when to prefer another sibling, but the context is unambiguous.

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 only declare readOnlyHint and openWorldHint; the description adds real behavioral context beyond them — that the tool itself costs $0.01 in listed currencies, that the target endpoint is never paid, what the response contains (pass/warn/fail per check plus a fix hint), and that a signed EIP-191 receipt bound to the caller's arguments is returned. It doesn't describe rate limits, latency, or failure behavior for unreachable URLs, which keeps it below a 5.

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 price and currency enumeration is front-loaded, which is useful, but the eight-chain USDC/RLUSD list is verbose and consumes roughly a third of the text before the actual purpose appears. The core sentence is a long run-on that packs checks, audience, alternative, and receipt into one breath instead of structured clauses.

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, return values needn't be explained, and annotations cover the safety profile; the description still covers what is checked, how results are graded, the receipt artifact, and the cost of invocation. Remaining gaps are minor operational details such as behavior on unreachable or non-x402 endpoints.

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 documents url, body, and method, including the body-implies-POST behavior and the openapi.json fallback. The description adds no per-parameter meaning of its own, 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 names a specific verb and resource ("diagnose an x402 endpoint") and immediately defines the scope: it inspects the endpoint the way a paying agent would, without paying it, checking the 402 challenge, accepts[] options, resource URL, settlement readiness, discovery, and paywall. It explicitly distinguishes itself from the sibling x402_preflight by intended audience (endpoint owner vs. prospective payer).

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 states both sides of the routing decision: use this when you own or are debugging the endpoint, use x402_preflight when deciding whether to pay someone else's endpoint. That is explicit when/when-not guidance with a named alternative. It doesn't address the other closely related siblings (x402_quick_check, x402_preflight_deep, x402_delivery_check, x402_fix), so the routing is clear but not exhaustive.

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?

Goes well past the readOnlyHint/openWorldHint annotations: discloses that the call is paid ($0.05 in USDC across nine chains or RLUSD on XRP Ledger), that the result carries an EIP-191 receipt bound to the caller's arguments, and that it mirrors GET /api/v1/fix. That cost and receipt-binding information materially changes how an agent should invoke and trust the call.

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-loads the purpose and the ownership routing well, but the opening parenthetical enumerates nine payment networks, which is bulk that contributes little to a tool-selection decision. The improvement list (ERC-8004, Builder Code, Bazaar schema, etc.) is similarly long, though it does convey useful output scope.

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 four-parameter read-only diagnostic with an output schema, the description supplies everything extra an agent needs: cost, payment rails, what the fix output contains, stack-targeted code, and the receipt guarantee. Return formatting is covered by the output schema, so nothing essential 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%, so url, body, stack and method are already fully documented in the input schema. The description's mention of 'your own payTo, amount, network and route' refers to the generated fix code, not to input parameters, so it adds no new meaning about the arguments. 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?

States a specific verb+resource pair: it diagnoses an x402 endpoint and returns per-problem concrete code changes for the caller's stack. It also distinguishes itself from the sibling x402_diagnose by noting it bundles the diagnosis, so an agent can pick between the two without opening a 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 clear context for when to use it (you own the endpoint and want actionable fixes, not just a verdict) and explicitly names the alternative x402_diagnose plus the reason to skip it. It does not state exclusions, such as what a non-owner should call instead, or when a preflight check is still preferable.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the free quota ('10 calls per hour' shared), that it never triggers payment, and exactly where identity data is sourced from (402's extra.erc8004 or the seller's /.well-known/agent-registration.json, plus agent-card Concordium badge). It does not mention caching, latency, or behavior when the endpoint is unreachable beyond the 'not-read' verdict.

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 core question and the 'free/never pays' constraint are front-loaded, which is good. But the body is one long paragraph that dumps two full verdict enumerations inline, making it heavy to scan and burying the quota note at the very end.

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, yet the description still enumerates the verdict space and the optional concordium block, and covers identity sources, rate limits, and the no-payment guarantee. For a moderately complex read-only verification tool this is close to complete; only error/failure behavior for unreachable endpoints is unaddressed.

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 url/body/method are already fully documented, including the POST implication of body and the GET-then-POST default of method. The description adds no parameter-level meaning beyond the schema, so the 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?

Opens with a concrete question the tool answers ('is every payTo of this x402 endpoint really its seller's?') plus a named standard and the scope of one outcome per payment option. The 'Free' and 'Never pays' framing implicitly separates it from paid/delivery siblings, but no sibling is named, so differentiation is inferred rather than stated.

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 context is implied by 'Free:' and 'Never pays.', which tells the agent this is the non-paying verification step, and the rate limit is disclosed. However, it never says when to choose this over x402_preflight_deep, x402_diagnose or x402_delivery_check, and no prerequisites or exclusions are given.

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 cover the read-only/open-world profile, and the description adds what the annotations cannot: the tool never pays, it checks OFAC SDN listing, HTTPS, token support, advertised vs actual price, budget against max_usd, and a 30-day track record. It also discloses that the response carries an EIP-191 signed receipt bound to the arguments, which is non-obvious 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?

Purpose, price and the core directive are front-loaded before the verdict list and the sibling routing. The prose is dense and the long enumeration of chains and check reasons borders on crowding, but nearly every clause carries usable signal.

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 not be spelled out, yet the description still names the verdict set and the receipt. For a six-parameter preflight tool with sibling alternatives, 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 coverage is 100%, so the baseline is 3; the description still adds decision-level meaning by tying max_usd to the 'over your budget' verdict and explaining that the buyer's check is scoped to one call. Other parameters (method, network, body, client) are left to the schema, so it does not fully compensate beyond baseline.

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 verb and resource ('call this before your agent pays an x402 endpoint') plus the exact output shape ('go, caution or no_go'). It explicitly separates itself from siblings x402_preflight_batch, x402_preflight_deep and x402_diagnose, so an agent can select it without opening a 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 a clear trigger ('before your agent pays an x402 endpoint') and routes to alternatives with conditions: batch for several endpoints, deep above ~$1, diagnose for your own endpoint. When-to-use and when-to-use-something-else are both explicit.

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 only declare readOnlyHint and openWorldHint; the description adds real behavioral context beyond that: the $0.005 price, the accepted chains/assets, and critically 'Never pays the endpoints', which reassures the agent about side effects. It also discloses that the answer includes a signed EIP-191 receipt bound to the caller's arguments, a non-obvious property worth knowing before relying on the result.

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?

Cost and the core purpose are front-loaded in the first clause, and the remainder is dense but purposeful. The long enumeration of eight payment chains in a parenthetical is the one stretch that consumes space relative to its decision value.

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 not be detailed, yet the description still previews the go/caution/no_go verdicts, recommended payment option and totals. Pricing, payment rails and the receipt are all covered; only error behavior for invalid or unreachable URLs is left unspecified.

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 documents urls, client, method, max_usd and network in detail. The description adds no parameter-level meaning beyond repeating the 'up to 10' limit, leaving it at the baseline for a fully documented 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 specific verb and resource: a pre-payment check across up to 10 x402 endpoints in one call, and even names the underlying REST route (GET /api/v1/preflight/batch). The batch scope ('up to 10 at once') implicitly separates it from the single-endpoint x402_preflight, but no sibling is named explicitly.

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

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

'For marketplaces and agents that weigh several services' gives an implied audience/context for use. There is no explicit when-not guidance and no routing to alternatives such as x402_preflight for a single endpoint or x402_preflight_deep for deeper analysis, so the agent must infer the choice.

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 openWorldHint=true, and the description adds real value on top: the $0.01 x402 fee, the accepted currencies/chains, the explicit 'never pays the endpoint' guarantee, and that the reply carries an EIP-191 receipt bound to the caller's arguments. The only shortfall is that rate limits or latency/failure behavior on unreachable endpoints are not mentioned.

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?

Information is front-loaded with the price and use case, then the payoff, then the sibling alternative and the receipt guarantee. The eight-chain enumeration is long but materially useful for deciding whether the caller can pay. A slightly tighter opening sentence would make it a 5.

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 explanation, and the description still summarizes what the verdict payload contains. Combined with full schema coverage, safety annotations, cost, payment rails and alternative routing, an agent has everything needed 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 description coverage is 100%, so every parameter including body, client, method, max_usd and network is already documented in the schema. The description only indirectly touches parameters by listing supported payment chains, which loosely maps to `network` but adds no syntax or selection guidance beyond the schema. 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 a specific action (pre-payment deep verdict) on a specific resource (x402 endpoint) and enumerates the returned content: verdict (go/caution/no_go), full diagnosis, 30-day per-day history, seller's other-endpoint reliability, and domain-move detection. It also states the underlying route (GET /api/v1/preflight/deep) and explicitly separates itself from the cheaper sibling x402_preflight.

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 an explicit decision threshold (worth it before a payment above about $1, for expensive calls) and names the alternative for ordinary calls (x402_preflight is enough). It also rules out an assumption the agent might make by stating it never pays the endpoint, so the cost of invoking it is unambiguous.

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 context annotations do not carry: it is free, rate-limited to 10 calls per hour, and returns a pass/warn/fail verdict with a problem count and the top three problems. Annotations already cover read-only and open-world behavior, so the remaining gap is only that it doesn't say how it verifies (e.g. whether it actually issues requests).

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

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

Two sentences, front-loaded with the free quick-check purpose and the return shape, then the routing. The pricing parentheticals are dense but each earns its place by driving cost-aware selection; slightly compacted phrasing would improve readability.

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, full parameter coverage, and read-only annotations already provided, the description supplies the missing pieces: cost model, rate limit, verdict semantics, and sibling routing. Only the verification mechanics are left implicit, which is a minor gap for an endpoint liveness check.

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 url, body, and method descriptions already explain defaults and fallbacks in detail. The prose adds nothing about parameters, so this sits at the baseline for a fully documented 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 specific verb and resource ('does this x402 endpoint work for a paying agent?') and immediately names the decision output (pass/warn/fail with problem count and top three). This is distinguishable at a glance from siblings like x402_fix or x402_preflight.

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 positions itself as the free entry check and routes to three alternatives by condition and price: x402_diagnose for every check, x402_fix for code changes, x402_preflight before paying third-party endpoints. The 10-calls-per-hour cap further defines when it is appropriate.

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?

Goes well beyond the annotations by disclosing that the record only appears after 'the next daily scan' (asynchronous, not immediate), the 25-endpoints-per-host cap, and the 10-calls-per-hour rate limit. It also explains the payoff — buyers' agents see the record before paying — which the idempotent/destructive hints 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?

Front-loads the free/self-serve framing and packs prerequisites, timing, and limits into three sentences. The seven-registry enumeration is a bit listy and could be trimmed, but each sentence otherwise carries operational information.

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

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

An output schema exists, so return values need not be described; the description covers what remains — cost, eligibility, verification, async timing, and quotas. Nothing an agent needs to decide whether to call this tool or to set expectations 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 coverage is 100% and the single `url` parameter is already documented with an example, so the schema carries most of the load. The description still adds a meaningful constraint: the URL must be a live x402/MPP/L402 endpoint that returns a 402 payment challenge, which is a validation requirement not present in 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?

Opens with a specific verb and resource: adding your own paid endpoint to the x402 Trust Index. It clearly separates itself from the read-only sibling x402_trust_record and from registry-listing tools by framing this as self-registration when nothing else lists the endpoint.

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?

States the exact condition for use ('when no registry lists it yet') and enumerates the registries it complements, which tells an agent when another path already covers the endpoint. It also gives a prerequisite (the endpoint must answer 402 with a payment challenge) so the agent can pre-validate before calling.

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 real context beyond readOnlyHint/openWorldHint: it is free vs the $0.001 preflight, capped at 10 calls per hour, and returns found:false rather than erroring for unknown endpoints. The only minor gap is not saying how stale the daily data can be relative to the current scan.

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?

One dense but front-loaded block leading with 'Free' and the resource, then constraints. Every clause carries information (cost, limit, absence case, alternatives), though the sentence is long enough that the rate limit is buried mid-string rather than set off.

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 an output schema exists, the description needn't document return shape, yet it still summarizes verdict/reasons/price/networks and covers the not-found case, cost, and rate limit — everything needed to call it correctly. Only freshness semantics are left implicit.

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 single url parameter is fully documented with an example, so the schema carries the load. The description reinforces that the target is an x402 or MPP endpoint, but adds no format or normalization guidance (e.g. trailing slash, scheme handling) 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 specific resource (the daily track-record of a paid x402/MPP endpoint from the Trust Index) and enumerates the returned content: uptime across last 30 scanned days, latest verdict and reasons, price and networks. Names the sibling it complements (x402_trust_add for endpoints not indexed) so it is distinguishable without opening schemas.

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 frames the use case (check the historical record) and routes to x402_preflight for a live pre-payment check, plus x402_trust_add when the endpoint is absent. It does not address the other near siblings (x402_quick_check, x402_delivery_check, x402_preflight_deep), so the alternative mapping is not exhaustive.

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