402xAgent is the check an agent calls before paying any x402 endpoint. It probes the endpoint's 402 without paying and returns a pay / skip / recheck verdict with a reason. Every check leaves a public receipt. It never pays the target.
Scored across 10 tools
Most tools have clearly distinct purposes, and the descriptions explicitly cross-reference when to prefer lookup, search_catalog, get_service, or endpoint_spot_check. There is still some residual overlap among discover, search_catalog, lookup, and get_service since all help find endpoint/service information, but the boundaries are mostly clear.
All names use snake_case, which is consistent, but the naming patterns are mixed: bare verbs (discover, lookup), verb_noun (get_receipt, search_catalog), noun phrases (endpoint_spot_check, payment_status), and a product-specific name (get_overnight_cos_pack). It remains readable but not predictably patterned.
Ten tools is well within a reasonable range and each appears to earn its place across discovery, verification, reporting, receipts, payment status, hygiene scoring, and a paid pack download. The set is scoped rather than bloated.
The surface covers the main x402 workflow: discovering services, checking endpoints, reading receipts, viewing catalog records, ranking options, checking payment status, assessing hygiene, and buying a specific pack. Minor gaps may exist around generic payment execution or broader account management, but core workflows are covered.
Free discovery of x402 pay-per-call endpoints from 402xAgent's weekly crawl. Returns up to 20 endpoints matching the words in q (URL or source list), each with the verified (quoted) price, network, last_checked, stale flag, verdict pay|skip|recheck with its reason, and a receipt. Skips are included by default; pass verdict to filter. A result older than 36 h is stale; a pay older than 7 days is returned as recheck. Run endpoint_spot_check right before paying. Read-only, no auth, 60 calls per minute.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Optional. 2-100 chars; space-separated words that must all appear, e.g. "weather" or "crypto price". | |
| limit | No | ||
| verdict | No | Optional filter on the (freshness-adjusted) verdict. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, but the description adds substantial context beyond them: no auth required, a 60 calls/minute rate limit, staleness rules (36 h = stale, a 7-day-old 'pay' downgraded to 'recheck'), and the default inclusion of skips. These are exactly the behavioral traits an agent needs before calling.
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-dense and front-loaded with what the tool returns, followed by filtering, freshness rules, and the safety caveat. Every clause carries meaning, though the long single paragraph could be broken up for faster scanning.
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 no output schema, the description carries the full burden and does so: it enumerates returned fields (price, network, last_checked, stale flag, verdict with reason, receipt) plus rate limits and auth posture. 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 67%, with q and verdict documented in the schema but limit only carrying default/min/max. The description compensates by stating the 'up to 20 endpoints' cap and clarifying that verdict filters on the freshness-adjusted verdict, adding nuance the enum alone 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+resource ('discovery of x402 pay-per-call endpoints') and scopes it to '402xAgent's weekly crawl', which clearly differentiates it from siblings like search_catalog or lookup. An agent can tell what this returns 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?
Gives clear operational context: skips are included by default, verdict filters them, and it explicitly routes the agent to endpoint_spot_check 'right before paying'. It does not, however, distinguish this tool from the other search-like siblings (search_catalog, lookup), 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.
Paid ($0.05 USDC on Base via x402, no free tier): the exact committed snapshots behind endpoint_spot_check's locked teasers: which payment terms changed in the last 30 days, when, from what to what, and the full hygiene checks. Pass the url and the commitment_ref from the free answer's locked_commitments; verify each revealed {snapshot, nonce} against its sha256 digest (docs: https://402xagent.com/docs#endpoint-report).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | the endpoint URL you checked, e.g. https://api.402rates.com/v1/ping | |
| commitment_ref | No | locked_commitments.ref from the free check, e.g. cm-0123456789abcdef | |
| include_current | No | also return today's stored data under current (not covered by the commitment) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnly, openWorld, non-destructive, non-idempotent); the description goes well beyond by disclosing the price ($0.05 USDC on Base via x402, no free tier), the payment/auth mechanism, and the post-call verification obligation against the sha256 digest with a docs link. Payment-per-call context also explains the non-idempotent/read-only annotation pairing rather than contradicting it.
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 price and the value proposition, then the invocation instruction. It is dense but every clause carries information; the deeply nested first sentence and long docs URL slightly reduce scannability.
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 no output schema, the description carries the burden and does it: it names the returned artifacts (revealed {snapshot, nonce}, diffs of payment terms with from/to values, full hygiene checks). Combined with the annotations and 100%-covered schema, an agent has everything needed to invoke and interpret the result.
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 all three parameters are already documented, including where commitment_ref originates ('locked_commitments.ref from the free check'). The description reinforces the linkage as part of a workflow but adds no syntax, format, or validation detail beyond the schema, 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 concrete resource and scope: the exact committed snapshots behind endpoint_spot_check's locked teasers, covering which payment terms changed in the last 30 days, when, from what to what, plus full hygiene checks. It explicitly positions itself against the sibling endpoint_spot_check, so an agent can distinguish paid reveal from free teaser 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 a clear prerequisite workflow: pass the url and the commitment_ref taken from the free answer's locked_commitments, implying endpoint_spot_check must run first. It also warns there is no free tier, which affects tool choice via cost. No explicit when-not-to-use case or fallback alternative is stated, so 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.
Decision-shaped 402xAgent check of a public URL (private, loopback and link-local addresses blocked on every redirect hop) for an x402 PAYMENT-REQUIRED / 402 challenge. Every answer has reason_code (stable code) and confidence (high|medium|low); rules: https://402xagent.com/rules.json. History: stable_for_days, last_changed, drift. Free: verdict (pay|skip|recheck), a plain-words reason, payment_terms_sha256 (hash of the approved payment), and access. Paid: verdict, reason code, quoted/claimed price, pay_to, network, asset, and payment = the exact {network, asset, amount_atomic, amount_usd, pay_to} a router may sign (verdict pay only), plus access with the settlement tx. No 402 terms is skip/no_paywall (recheck/free_trial_active when the target sends x-free-trial headers); recheck only for timeouts, 5xx and network errors; wrong or unsupported network, non-canonical USDC or a pay_to that differs from the listing is skip. The same normalized URL + method reuses one probe for 5 min, so consecutive calls agree. mode=dry-run: free dry run (nothing signed or paid, stored as a public receipt, no approval hash, 50/caller/day). Never pays the target (probe GET only). 5 free checks per client per UTC day (at most 25 per network) (client=vc-mcp), then $0.02 USDC a check on Base via x402. Unpaid after free quota: payment instructions. Forward PAYMENT-SIGNATURE for a paid check.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | optional attribution tag stored on the receipt (dry-run-<caller> sets mode=dry-run) | |
| url | Yes | public http(s) URL to probe | |
| mode | No | optional: dry-run = free dry run: one unpaid probe, nothing signed or paid, always stored as a public receipt (check_type dry-run). Returns the free-tier shape with payment_terms_sha256 null (never an approval). 50 per caller (ref, else client, else IP) per UTC day. ref=dry-run-<caller> also sets it | |
| task | No | optional task label (ignored in decision output) | |
| method | No | optional: probe the target with POST (empty JSON body) for POST-only endpoints | |
| pay_to | No | optional: the wallet you expect to pay (from your listing) | |
| network | No | optional: the CAIP-2 network you expect, e.g. eip155:8453 | |
| claimed_price | No | optional claimed USD price to compare vs quoted |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it states the target is never paid (probe GET only), that results are cached per normalized URL+method for 5 minutes, that dry-run creates a public receipt with no approval hash, and it gives exact rate limits (5 free/client/day, 25/network, 50/caller/day dry-run) and price ($0.02 USDC on Base). Blocked address classes and the free-vs-paid response shapes are disclosed too.
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 dense paragraph of ~200 words with no line breaks, mixing purpose, verdict taxonomy, output fields, caching, pricing and quota. Every element is useful, but the verdict-rules and payment mechanics crowd the core 'what this does', so it is informative rather than 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?
There is no output schema, and the description compensates fully by enumerating the free-tier return (verdict, plain-words reason, payment_terms_sha256, access) and the paid return (price, pay_to, network, asset, signable payment object, settlement tx). For an 8-parameter, no-annotation tool, an agent has everything needed to call it and interpret the reply.
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 reinforces a few parameters (mode=dry-run behavior, ref as attribution tag, the pay_to-vs-listing skip rule) but adds no syntax or format detail that the schema does not already provide for the remaining params (task, method, network, claimed_price).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first clause names a specific verb and resource: a check of a public URL for an x402 PAYMENT-REQUIRED / 402 challenge, with the probe scope (blocked private/loopback/link-local, redirect-hop checks) spelled out. That is far more specific than the sibling names discover or lookup imply, but the description never explicitly contrasts itself with endpoint_report or get_receipt, so sibling differentiation is left to inference.
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 conditions are unusually concrete: recheck only for timeouts/5xx/network errors, skip for wrong network or non-canonical USDC, mode=dry-run for a free unpaid probe, forward PAYMENT-SIGNATURE for a paid check. What is missing is tool-level routing – nothing says when to prefer this over endpoint_report or x402_hygiene.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Buy and download the Overnight Chief of Staff Setup Pack ($9 USDC on Base via x402): 5 ready-to-paste bot prompts, an HTML morning-briefing template, and a PDF setup guide. Always paid — no free quota. Call without PAYMENT-SIGNATURE to receive payment requirements and the HTTP endpoint URL. Agents pay by retrying the HTTP endpoint (or this MCP call) with a PAYMENT-SIGNATURE header holding a signed USDC EIP-3009 authorization.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: it discloses the exact price ($9 USDC on Base via x402), that the resource is 'Always paid — no free quota', and the complete auth handshake (PAYMENT-SIGNATURE header with a signed USDC EIP-3009 authorization). This is exactly the cost/auth/rate-limit context the dimension rewards.
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 offering and price before the payment mechanics. Sentences are dense but each earns its place; the third sentence on EIP-3009 authorization is the only mildly overlapping one relative to the preceding sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param, no-output-schema purchase tool, the description covers purpose, cost, contents, and the two-step payment protocol adequately. It stops short of describing what the successful response delivers (e.g., download links), which an agent might need to complete the transaction.
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 has zero parameters, so the baseline is 4. The description adds useful meaning about an out-of-band header (PAYMENT-SIGNATURE) that governs behavior, though it does not formalize it as a callable 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?
States a specific verb ('Buy and download') and named resource ('Overnight Chief of Staff Setup Pack'), then enumerates the deliverables (5 bot prompts, HTML template, PDF guide). The product specificity makes it trivially distinguishable from generic siblings like lookup or search_catalog.
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 details how to invoke the payment flow (call without PAYMENT-SIGNATURE to get requirements, retry with the header), but never states when an agent should choose this tool over search_catalog or lookup, nor any prerequisites for wanting the pack. Usage mechanics are covered; routing guidance is not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free: read a public 402xAgent receipt. Give id (sc-... from endpoint_spot_check's receipt_id, or a 10-hex crawl id) or url (latest live + crawl receipt for that URL). Receipts hold the listing URL, the live 402 terms, verdict, reason, reason_code, confidence, history summary, timestamp, and a status-badge embed snippet (badge.markdown / badge.html). Does not run a fresh check (use endpoint_spot_check for that).
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | receipt id | |
| url | No | endpoint URL exactly as checked |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds context annotations cannot express: that the call is free, that it is a cached read rather than a fresh check, and what the receipt payload contains. It does not mention pagination or failure modes, but for a read-only lookup that is minor.
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 front-loaded: the core action and 'Free' lead, followed by parameter guidance, then the payload, then the exclusion. Every sentence carries information, though the return-field list makes it run a bit long.
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?
No output schema exists, so the description compensates by enumerating the returned fields (listing URL, terms, verdict, reason, reason_code, confidence, history, timestamp, badge snippets). Both parameters are explained and the alternative tool is named, leaving nothing an agent needs to call it 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%, so the baseline is 3, but the description goes beyond the terse schema by explaining the id format (sc-... from endpoint_spot_check's receipt_id, or a 10-hex crawl id) and what url selects (latest live plus crawl receipt). That provenance and format detail is genuine added value over 'receipt id'.
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 ('read a public 402xAgent receipt') and immediately scopes it as free and read-only. It distinguishes itself from the sibling that performs checks by explicitly naming endpoint_spot_check as the tool that does fresh checks.
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 covers both invocation modes (id vs url) and what each returns, and gives the exclusion: 'Does not run a fresh check (use endpoint_spot_check for that).' This is exactly the when/when-not/alternative guidance the dimension asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the complete catalog record for one known service id (e.g. from search_catalog or lookup results). Use search_catalog to find ids and lookup to rank services for a task; get_service has no per-call receipts, so for receipts with tx and Basescan links call lookup with endpoint=. Read-only. No auth or API key; free, no quota (reads the same catalog snapshot as search_catalog). Returns the record as published: id, name, provider, category, description, endpoint, advertised_price (USD, atomic, asset, network), sample_request, tasks, quality_test (known-answer test, facts_only flag and reason), paid_receipts (count), latest (full last check incl. x402_challenge, error, raw_log_url), history_summary and page_url. Unknown or missing id: error "no service with id ...".
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Exact, case-sensitive catalog service id as returned by search_catalog or lookup, e.g. "exa-search", "x402tap-weather", "onesource-erc20-balance". |
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), and the description adds genuinely new context: no auth/API key, free with no quota, reads the same snapshot as search_catalog, and the exact error for an unknown id. It also discloses the full shape of the returned record.
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 and sibling routing are front-loaded in the first two sentences, and the remaining text earns its place given there is no output schema. The return-field enumeration is long and reads as a dense run-on, which slightly hurts scannability.
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 no output schema, the description fully compensates by enumerating the returned fields (id, provider, category, advertised_price, quality_test, paid_receipts, latest, history_summary, page_url) and the error path. Nothing an agent needs to call or interpret this tool 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 schema already documents case-sensitivity and gives examples, so the baseline is 3. The description adds value by pointing to where ids come from (search_catalog or lookup results) and by specifying the failure mode for an unknown/missing id, which the schema does not.
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 ('Fetch the complete catalog record for one known service id') and immediately distinguishes itself from siblings by naming search_catalog (find ids) and lookup (rank services / receipts). An agent can route correctly 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?
Explicit when-to-use routing: search_catalog to find ids, lookup to rank services, and lookup with endpoint=<id> when receipts with tx/Basescan links are needed. This is a textbook when/when-not/alternative statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank x402 endpoints for a known task at or under a price: "which endpoint should I pay for task X at <= $Y?". Prefer it over search_catalog (keyword browsing, unranked) and get_service (one id's raw record). No auth or API key. Calls the hosted lookup service as client=vc-mcp; all MCP users share that client's 5 free lookups per UTC day (reset 00:00 UTC), after which the tool returns an error reporting the HTTP 402 ($0.02 USDC on Base via x402) and never pays. Returns results sorted by known-answer pass_rate over the last n paid calls, then price, each with price_usd, pass_rate, last_check_at, last_check, stale and receipts (time, tx, basescan_url, charged_usd, delivered, quality); seller-broken services come unsorted under facts_only. No match: empty results, matched 0. Needs task or endpoint; invalid params return an error. Payment never changes results.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | Optional. Most recent paid receipts per service used for pass_rate and returned, 1-20 (default 5; out-of-range values are clamped). | |
| task | No | Task name from /v1/tasks, e.g. web-search, crypto-news, news, weather, token-balance, sec-filings, fx-rates, url-check. Case-insensitive; a known name matches exactly, an unknown one falls back to matching every word in service text. Required unless endpoint is given. | |
| limit | No | Optional. Maximum ranked services in results, 1-20 (default 10; clamped). facts_only is not limited. | |
| payer | No | Optional 0x wallet address (40 hex characters), recorded so a later payment from it to a returned vendor can be matched on-chain. Nothing is charged; a malformed address returns an error. | |
| endpoint | No | A catalog service id (e.g. exa-search) or endpoint URL, to get one service's receipts instead of a whole task. Required unless task is given; can be combined with task. | |
| max_price_usd | No | Optional. Only services whose listed price per call is at or below this many USD, e.g. 0.01. Negative values are rejected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: no auth/API key needed, shared client=vc-mcp quota of 5 free lookups per UTC day with a 00:00 UTC reset, the exact failure mode afterwards (HTTP 402, $0.02 USDC on Base via x402) and the crucial guarantee that it never pays and that payment never changes results. It also discloses result ordering, staleness signaling, and the facts_only exception — rich context an agent cannot get from readOnlyHint/openWorldHint 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?
Front-loads the ranked-question framing and the sibling routing in the first two sentences, then packs quota, output shape and edge cases densely with no filler. It is long and information-dense rather than tight prose, which costs it a point, but nearly every clause carries a fact.
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 no output schema, the description fully carries the return-value burden: sort order (pass_rate over last n paid calls, then price), the field list (price_usd, pass_rate, last_check_at, last_check, stale, receipts with tx/basescan_url/charged_usd/delivered/quality), the facts_only case for seller-broken services, and the empty-results behavior (matched 0). Nothing an agent needs to call or interpret this tool 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 params like n, limit and max_price_usd are already fully documented with ranges and clamps, making 3 the baseline. The description does add one genuinely useful constraint the schema lacks (required fields list is empty): 'Needs task or endpoint; invalid params return an error.' Beyond that it adds little parameter detail the schema doesn't already carry.
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 (rank) and resource (x402 endpoints) plus the exact question it answers, and explicitly distinguishes itself from search_catalog (keyword browsing, unranked) and get_service (one id's raw record). An agent can select it 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?
Gives the selection condition (known task at or under a price) and names both alternatives with the reason each is worse, plus a 'prefer it over' directive. 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.
After you pay an x402 endpoint (Base USDC, EIP-3009 exact): did the payment land, and is it safe to sign a new one? Give payment_payload (the base64 PAYMENT-SIGNATURE you sent), or tx_hash, or from + nonce (+ valid_before). Returns status landed|not_landed|pending|canceled|unknown, safe_to_retry_same_payload (always true: a nonce is single-use), safe_to_resign (true only when two independent RPC sources agree the nonce is unused AND validBefore has passed), tx details, terms match, a claim pointer and a signed receipt. Same 5 free per UTC day as endpoint_spot_check (client=vc-mcp), then $0.02 USDC on Base via x402 (forward PAYMENT-SIGNATURE).
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | ||
| nonce | No | ||
| tx_hash | No | ||
| seller_url | No | the URL you paid | |
| valid_before | No | unix seconds (with from + nonce) | |
| payment_payload | No | base64 PAYMENT-SIGNATURE / X-PAYMENT value of the payment you sent |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), it discloses free-tier limits (5 per UTC day) and per-call cost ($0.02 USDC on Base via x402), the required auth mechanism (forward PAYMENT-SIGNATURE), and the exact safety logic behind safe_to_resign (two independent RPC sources agreeing the nonce is unused AND validBefore passed). This is unusually rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the central question and packs inputs, outputs, semantics, and price into a few dense sentences with little waste. The final pricing sentence is long and slightly run-on, but each clause carries necessary 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?
There is no output schema, so the description must cover return values — and it does, enumerating the status values (landed|not_landed|pending|canceled|unknown), the retry/resign flags, and the accompanying tx details, terms match, claim pointer, and signed receipt. Inputs, auth, and cost are all covered, leaving nothing essential 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?
With only 50% schema coverage, the description compensates by explaining that payment_payload is the base64 PAYMENT-SIGNATURE previously sent and that from/nonce/(valid_before) form a combined identifying group, adding meaning the schema omits. It still leaves tx_hash, from, and nonce individually undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise scope: checking whether an x402 payment landed and whether it is safe to sign a new one, with the exact input forms accepted. It is clearly a payment-status tool, but it never explicitly contrasts itself with siblings like get_receipt or endpoint_spot_check (the latter appears only in a pricing aside), so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear triggering context ("After you pay an x402 endpoint") and spells out the three alternative input modes (payment_payload, tx_hash, or from+nonce+valid_before), which is genuine usage guidance. It does not, however, state when not to reach for this tool versus get_receipt or lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse or keyword-search the verified catalog of pay-per-call (x402) agent services. Use it when you don't know the task name or want to see what exists; use lookup to rank endpoints for a known task at a max price, and get_service for one id's full record. Read-only. No auth or API key; free, no quota or per-client limit: it only reads the catalog snapshot (bundled catalog.json in the local server, the published catalog.json on remote /mcp). Returns {count, results, generated_at, note, methodology_url}; results are in catalog order, ungraded, each with id, name, category, endpoint, advertised_price_usd, page_url and latest (checked_at, reachable, http_status, latency_ms, quoted_price_usd, price_matches_listing, charged_price_usd, delivered_valid, raw_log_url). No match: count 0, empty results. A non-numeric max_price_usd or limit returns an error.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Optional. Maximum number of results, 1-100 (default 20). | |
| query | No | Optional. Space-separated words; every word must appear (case-insensitive) in the service id, name, category, description or provider. Omit to list all. Examples: "search", "crypto news". | |
| category | No | Optional. Case-insensitive substring of the service category, e.g. "web search", "news", "on-chain data", "weather", "public records", "utility". | |
| max_price_usd | No | Optional. Keep services whose advertised price per call is at or below this many USD, e.g. 0.01. | |
| reachable_only | No | Optional (default false). If true, keep only services that were reachable in the latest check. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/idempotent profile, but the description adds material context the annotations do not: no auth or API key, no quota or per-client limit, and the actual data source (local bundled catalog.json vs. published catalog.json on remote /mcp). It also discloses the error behavior for non-numeric max_price_usd/limit and the no-match case.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and sibling routing before the detailed return-field enumeration. The field list is long but earns most of its place because no output schema exists; still, the enumeration is denser than needed for a selection decision.
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 no output schema, the description carries the full burden of documenting returns and does so exhaustively ({count, results, generated_at, note, methodology_url}, per-result fields, and the empty-result case), plus the auth/quota envelope. An agent has everything needed to call and interpret it.
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 nonetheless adds edge-case semantics the schema omits, namely that a non-numeric max_price_usd or limit returns an error and that no match yields count 0 with empty results. It does not add syntax guidance beyond the schema examples.
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 verb+resource ('Browse or keyword-search the verified catalog of pay-per-call (x402) agent services') and explicitly distinguishes itself from the siblings lookup and get_service by the condition that selects each. An agent can route correctly 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?
States exactly when to use it ('when you don't know the task name or want to see what exists') and names the two alternatives with their own selection conditions ('lookup to rank endpoints for a known task at a max price, and get_service for one id's full record'). Nothing 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.
Free x402 hygiene score for an endpoint you run: {score, grade, deductions[{code, points, fix}]} from normal unpaid requests (never pays, never sends bad params). 20 per day per network, cached 24 h. Grades are returned only to you.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full http(s) URL of the x402 endpoint. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real value: it never pays, never sends bad params, is rate-limited to 20/day/network, cached 24h, and results are private to the caller. It omits error behavior for non-x402 or unreachable URLs, keeping it short of 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?
Dense and front-loaded: purpose, return shape, behavior guarantees, and limits all arrive in two compact sentences. The trailing 'Grades are returned only to you' is slightly oblique but still earns its place as a privacy note.
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 no output schema, the description usefully sketches the return payload ({score, grade, deductions[{code,points,fix}]}) and states cost, quota, and caching. Reasonably complete for a one-parameter read tool; failure modes and what 'grade' means are the remaining 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?
Schema coverage is 100% with a clear description of the single 'url' parameter, so the schema carries the load. The description adds only the implicit constraint that the endpoint should be one you run; no format or edge-case guidance beyond that. 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: returns a hygiene score with grade and deductions for a given x402 endpoint, and specifies it derives from normal unpaid requests. An agent can tell this is a scoring/diagnostic tool, though it never names how it differs from the closely related endpoint_report or endpoint_spot_check 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?
'for an endpoint you run' implies ownership scope, and the rate/cache limits hint at intended usage, but there is no explicit when-to-use or when-not-to-use versus endpoint_report, endpoint_spot_check, or lookup. The agent must infer selection from the sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
x402_hygieneendpoint_reportdiscoverpayment_statusCheck any x402 endpoint before your AI agent pays it: trust grade, verdict, and hijack checks.
Check an x402 endpoint before your agent pays it: avoid / caution / ok, proven on-chain.
Agent x402 Paywall MCP — Coinbase HTTP 402 protocol + on-chain settlement. Agents pay per-call
Live uptime and source-URL verification for AI agents, with per-call x402/USDC paid endpoints.
Add one secure layer between your agents and this server.
