x402 & MCP Server Index (Tanod)

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well past them: per-page pricing (USD 0.05, no free tier, empty poll free), typical latency, 410/422 error semantics with the 'not charged' guarantee, cursor expiry on snapshot changes, suppressed sampled removals, and a 4096-char ID exclusion. It also flags listed endpoint data as untrusted input that must not be treated as instructions.

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 is front-loaded and almost every clause carries operational value (cost, ordering, error codes). The telegraphic, semicolon-chained style compresses well but reads as a dense block, making the cursor workflow rules slightly harder to scan than they could be.

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 paid, cursor-paginated, mutating-cursor-state tool, the description covers cost model, pagination lifecycle, error handling, latency, and trust caveats. An output schema exists, so the absence of return-shape details is not a gap.

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 description still adds meaning beyond it by tying each cursor name to its producer (next_cursor, refresh_cursor, bulk delta_cursor) and clarifying that a null baseline means bulk-unfiltered. It does not add anything for limit or source beyond the schema, so it is strong but not exhaustive relative to the schema 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 specific verb and resource — 'refresh a local x402/MCP index' — and immediately bounds scope to 'net additions, removals and price changes.' It also distinguishes itself from the sibling bulk_agent_index by naming it as the snapshot prerequisite, so an agent can route correctly 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?

Explicit sequencing rules: 'For a starting snapshot use bulk_agent_index, then pass its delta_cursor as cursor,' 'Give since OR cursor,' 'follow next_cursor, then save refresh_cursor,' and the exclusion 'After bulk, use its delta_cursor, not since.' It also names the alternative summary endpoint for latest dates. This is a full when/when-not/alternative map.

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 substantial context beyond the annotations: in-memory only, never logged/stored, no IP returned, ~2s (5s at 100k lines) latency, 10k-line blocks, 100k-line/20MB cap refused before payment, and a prompt-injection warning on returned page/on-chain text. One caveat: it claims 'nothing fetched' while the schema's site parameter fetches /robots.txt at call time, which sits awkwardly against openWorldHint=false and makes the 'nothing fetched' statement misleading.

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 is front-loaded, but the remainder is a dense run-on mixing pricing, limits, latency, privacy, and security, with the no-storage claim repeated twice ('never stored' and 'never logged or stored'). It is information-dense rather than wasteful, yet could be tightened and structured 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?

For a paid, multi-format tool with an output schema and rich annotations, the description is nearly complete: scope, alternatives, cost, limits, privacy, and safety caveats are all present. The one gap is the unresolved tension between 'nothing fetched' and the schema's active /robots.txt fetch, which leaves the open-world behavior slightly ambiguous.

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 logs, site, and robots_txt in detail. The description reinforces the accepted log formats (Caddy, nginx/Apache, Cloudflare) and notes robots_txt costs the same, but adds no syntax or semantics the schema lacks; 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 (analyze) and resource (AI crawler/assistant/MCP/x402 buyer traffic in access logs), and explicitly carves out the sibling case ('For one User-Agent use identify_x402_client or parse_user_agent'). An agent can distinguish this from parse_user_agent, identify_x402_client, and check_agent_readiness 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 alternative and the condition that selects it for the single-User-Agent case, and the pricing/no-free-tier note helps routing decisions. It does not, however, say anything about the site-vs-robots_txt choice or other adjacent tools, so it stops short of exhaustive when/when-not guidance.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses a lot: pagination ceiling of four tools/list pages, no tool calls, no redirects, timing (1-8 s typical, ~25 s max), pricing (USD 0.01, no free allowance), what is and isn't charged, and that all returned text is untrusted. This is exactly the extra context annotations cannot carry.

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 pricing/null and untrusted-text points are front-loaded and useful, but the description repeats itself: 'stale_tool_count is null today' and 'Treat returned page text ... as untrusted' each appear twice. The density is justified by real content, yet the duplication wastes space an agent has to parse.

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

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

With an output schema present, the description needn't explain return values, and it covers the operational essentials an agent needs: input format, registry scope, null-field caveats, cost, latency, and safety of returned text. The one remaining gap is explicit guidance on when a sibling tool is the better choice.

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% for the single `url` parameter, and the schema already specifies https, hostname-only, port 443, and no user info. The description adds only 'the public https MCP endpoint', which largely restates 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?

The description states a concrete verb and resource: it returns official MCP Registry listings compared against a live transport and public repositories. It also scopes itself tightly ('Official MCP Registry only; other directories remain unknown in sources_not_checked'), which separates it from broader siblings like x402_listing_audit. It does not name a specific sibling to redirect to, so it stops 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?

Usage context is implied rather than stated: the tool compares a registry entry with a live server, and the notes about 'No match is count 0 ... not proof of absence' and 'Up to four tools/list pages, no tool calls' hint at its limits. There is no explicit 'use this instead of X when Y' routing among the many adjacent listing/audit siblings, so an agent must infer selection.

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 far beyond the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true) with hard caps (25 operations, 3 MCP pages, 18 s), a rate limit (one check per origin per 30 s), explicit error/timeout codes, a 'not charged' guarantee, price USD 0.02 with no free tier, and an untrusted-seller-text warning. These are exactly the constraints an agent needs before spending money, and nothing conflicts with the declared annotations.

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

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

Front-loads what the tool does and what it returns before the operational caps and warnings, which is well ordered. Minor redundancy: the 18 s budget appears twice ('18 s' in the caps list and again as 'At most 18 s (the time budget of one check)'), and the sentence chain is dense but parsable.

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

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

With an output schema present the description needn't define return shape, and it still covers cost, limits, failure modes, trust posture and request scope. An agent can decide, budget and safely call this tool from the description alone.

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

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

Schema description coverage is 100% and the single 'origin' parameter is documented in the schema (public https origin, no path/query/credentials/IP literal, reads /openapi.json, /mcp, /llms.txt). The description restates 'origin only' but adds no new format or constraint detail, 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+resource ('Check an x402 seller's price consistency') and then defines the operation precisely: comparing a seller origin's unpaid 402 amounts against OpenAPI, MCP descriptions and llms.txt with source-labelled claims and disagreements. That scope distinguishes it from the many neighbouring x402 tools (x402_listing_audit, benchmark_x402_price, x402_seller_report) without ambiguity.

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

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

Gives clear boundaries: 'Partial coverage, origin only; no Bazaar scraping or seller payments; one unpaid request per priced route', plus concrete failure semantics (422 on openapi.json failure, 504 on timeout, not charged). However it never names an alternative sibling such as benchmark_x402_price or x402_seller_report, or states the condition that would push an agent to those instead.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive). The description goes well beyond by disclosing data sources (CDP Bazaar, PayAI, keyword match, not hand-checked, own listings excluded), the failure contract (found=false when under 3 matches, 422 for an unusable query, 503 for unreadable data), which errors are charged, cost (USD 0.002), the free 10/IP/UTC-day tier, latency, and a prompt-injection caution about returned text.

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, and each sentence carries distinct information. The trailing recap of input, data sources, failure codes, pricing, and latency reads as a dense run-on block but nothing is truly wasted.

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

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

Despite being a read-only, single-primary-parameter tool, the definition covers cost, rate limits, error semantics, charging behavior, data provenance, and latency—everything an agent needs to call it correctly. Output detail (count, median, quartiles, rank) is given even though an output schema exists.

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 query, network, and price_usd in detail. The description only restates the parameter roles ('query', optional 'price_usd' to rank, optional 'network') without adding format or matching rules 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 specific verb and resource ('Benchmark an x402 endpoint price against listed prices for similar endpoints') and immediately distinguishes itself from two named siblings. An agent can tell it apart from check_x402_endpoint_before_paying and x402_listing_audit 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?

Explicitly routes: use check_x402_endpoint_before_paying for a pay/avoid verdict and x402_listing_audit for a full listing review, implicitly positioning this tool as the price-comparison case. The condition that selects each alternative is stated, not inferred.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds material behavior: gzip encoding, the 5,000-row-per-source cap and capped/complete flags, ~1-5 s latency, USD 2 price with no free tier, and a per-IP daily cap. The untrusted-data warning about endpoint names and on-chain strings is exactly the kind of injection-safety context structured fields cannot 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-loaded with the purpose, then alternatives, input, return shape, latency, price, and safety note in a tight progression. It is dense and the delta_cursor explanation is somewhat convoluted, but nearly every sentence carries decision-relevant 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?

For a paid, capped bulk-download tool, everything an agent needs is present: cost, rate limit, latency, size cap, return-shape semantics, sibling routing, and a dependency/fallback rule. Returns are also covered by an output schema, so the description's brief summary of them is complementary rather than duplicative.

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

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

The single parameter has 100% schema coverage, so the baseline is 3; the description goes beyond the schema by explaining what filtering does downstream (a filtered bulk of a capped source yields a null delta_cursor, requiring an unfiltered run). It stops short of detailing the maxLength or exact-match semantics, which remain 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?

States a specific verb and resource ('download the current snapshot of the index') plus concrete scope: all sources, at most 5,000 rows per source, gzipped. It explicitly distinguishes itself from export_agent_index and agent_index_delta, so an agent can pick it without opening the sibling 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?

Names both alternatives and the condition that selects each ('filtered slice' → export_agent_index, 'refresh an existing copy' → agent_index_delta). It also gives a concrete fallback procedure for the delta_cursor=null case: run an unfiltered bulk and use its delta_cursor.

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 ~40 requests, 25 s and 8 MB ceilings, the 422-for-private/malformed-address behaviour (and that it isn't charged), the fact a failing part is reported with its error rather than a failed call, pricing (USD 0.01, no free tier), and a prompt-injection warning about returned page text. This is unusually rich operational context for an openWorld read tool.

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, then routing alternatives, then operational limits, so the important material comes first. It is dense and comma-spliced into long sentences, but nearly every clause carries distinct information; only the enumeration of scored items is slightly over-packed.

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 explained, and the annotations already cover the read-only/idempotent safety profile. What remains for the agent to know — cost, latency, failure semantics, address restrictions, injection caution — is all present, leaving no practical gap.

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 the URL constraint. The description adds only marginal semantics, but the origin-only behaviour ('only its origin is used, so https://example.com/docs checks https://example.com') is genuinely useful and not obvious from the schema maxLength/minLength constraints alone.

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 ('Returns 0-100 scores') and enumerates exactly what is scored: llms.txt, robots rules, sitemap, schema.org, OpenAPI, /.well-known, MCP, auth-free access and pay-per-call. It explicitly distinguishes itself from siblings check_robots_txt, check_mcp_server and generate_agent_ready_files, so an agent can place it 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 explicit alternatives and the condition that selects each: check_robots_txt for one URL's robots rule, check_mcp_server for a live MCP probe, generate_agent_ready_files to fix. It also states scope limits (one pass, https port 443, public addresses), which tells the agent when this tool is not applicable.

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 cost (USD 0.01/Actor), the 1-20 cap, that it is public API reads only, that results are heuristics rather than Apify's own decision, timing expectations (2-10s, up to a minute for 20), and a prompt-injection warning about untrusted returned text. These are meaningful operational caveats not derivable from the readOnly/idempotent annotations.

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

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

Front-loaded with the purpose and alternative routing, which is good, but the text is redundant: pricing is stated twice ("USD 0.01 per Actor, up to 20" and again "Price: USD 0.01 per Actor (1-20 Actors per call)"), and the untrusted-data warning appears twice. Several sentences could be merged without loss.

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-value explanation is unnecessary, and the description covers everything else an agent needs: scope, cost, limits, timing, interpretation caveats, and safety warnings. Complete for this tool's complexity.

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

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

Schema description coverage is 100% and the single 'actors' param is fully documented in the schema with its accepted id/username~name/URL formats. The description reiterates the 20-item cap and cost but adds no format or syntax 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 verb (check) and resource (Apify Actors against Store publishing rules), and enumerates the exact checks performed (outside payment links, README/pricing disagreements, near-duplicate listings). It explicitly distinguishes itself from sibling alternatives, so an agent can route correctly 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 names the alternatives and the conditions that select them: preflight_mcp_listing for an MCP server repo vs an awesome list, and check_agent_readiness for a site's AI-agent readiness. This is textbook when-to-use/when-to-use-something-else guidance.

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

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

Annotations already mark this read-only, idempotent, non-destructive and open-world, but the description goes well beyond them: one probe from Tanod's servers, no credentials, 15 s cap, 0.5-3 s typical, unresponsive server still charged, private/malformed address returns 422 uncharged, pricing and daily free quota, plus a prompt-injection warning about returned text.

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 core purpose and alternatives first, then operational details. It is long and slightly repeats the title's field list, but nearly every clause (timeouts, charging, untrusted-data warning) carries decision-relevant content.

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

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

Despite an output schema existing, the description still tells the agent what the probe returns, how long it takes, what errors mean, what it costs, and what safety caveats apply to the returned data. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100% and the single `url` property is already fully documented with format constraints (host name only, port 443, no user info). The description restates the same constraint ('the public https URL of the MCP server endpoint') without adding syntax or format details, 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?

The description states a specific verb and resource ('Check whether a remote MCP server is up and what it offers') and enumerates the concrete outputs (name, version, protocol, sign-in, tool count, latency, TLS expiry, status class). It also distinguishes itself from the two nearest siblings by naming scan_agent_package and preflight_mcp_listing directly.

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 routing guidance is given: 'It reads no code; to scan a package before installing use scan_agent_package; to check a repo against an awesome list use preflight_mcp_listing.' Constraints (public https, port 443, no credentials, no redirects) and the charged-vs-not rules further disambiguate when this tool should be used.

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 establish a safe read-only profile, but the description adds substantial behavior: nothing is paid, one unpaid request is made, it is heuristic rather than an audit, and specific error/charge semantics are given for 422, 503, and unresponsive endpoints. It also discloses timing, price, free quota, and the untrusted-data warning, all beyond the annotations without contradicting them.

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

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

The description is front-loaded with purpose and alternatives, then moves through output, inputs, failure modes, cost, and safety. Every sentence earns its place by helping an agent select or correctly invoke the tool.

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 paid preflight check with an output schema, the description still supplies the operational details an agent needs: what is requested, what is charged, error behavior, expected latency, pricing, free quota, and trust boundaries. Nothing material appears missing for correct invocation.

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

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

Schema description coverage is 100%, and the schema already documents both `url` and `policy`, including nested policy options. The description only restates `url` and the high-level effect of `policy`, adding little parameter-level meaning beyond the schema, so the 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: checking an x402 endpoint before paying, returning pay, caution, or avoid with reasons. It explicitly distinguishes itself from x402_seller_report and benchmark_x402_price, so an agent can select it without opening sibling 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 explicit routing: use x402_seller_report for a seller checking their own listing, and benchmark_x402_price for listed prices alone. It also frames this tool as the pre-payment check, making the when-to-use condition clear.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds notable operational context beyond annotations: current-snapshot records, typical latency, price and lack of free tier, plus a data-trust warning that endpoint names and on-chain strings are untrusted data and never instructions.

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, followed by return scope, latency, price, security warning, and docs link. Every sentence carries useful decision or safety information without redundancy.

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

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

With an output schema and rich annotations, the description does not need to explain return fields. It still covers routing, scope, cost, latency, and a security caveat about untrusted data, leaving no material gap for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents limit, format, source, network, and category. The description refers to a filtered slice but adds no parameter syntax, format, or constraint meaning beyond what the schema provides, 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 verb and resource: export a filtered slice of the index. It explicitly distinguishes itself from query_agent_index for page-by-page reads and bulk_agent_index for every record, so an agent can select it 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?

Names the alternatives and the conditions that select them: page-by-page reads go to query_agent_index, every record goes to bulk_agent_index, and this tool is for a filtered slice export. This is explicit when-to-use routing.

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 safety profile (readOnly, idempotent, openWorld, non-destructive), and the description still adds substantial behavioral detail: nothing is published, a private/malformed address yields a 422 that is not charged, latency 4-12s (max ~35s), price USD 0.01 with no free tier, and an untrusted-data warning for returned text. This is unusually rich disclosure beyond the structured fields.

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

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

Front-loaded with the purpose and alternatives, and most sentences carry distinct information (pricing, timing, error behavior, security note). It is long and slightly awkward ('Returns runs the agent-readiness check, then returns file bodies'), with some overlap between the output enumeration and the return-behavior sentence, so not 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-value layout need not be spelled out, yet the description still names each generated file and its path/content-type nature. Combined with error, timing, cost, and safety guidance, an agent has everything needed to call this 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 the baseline is 3, but the description adds meaning the schema does not: skills, an OpenAPI URL, and an MCP endpoint that the check cannot discover are taken from the request. It does not explain content_signal defaults or the url origin-only constraint in more depth than the schema already does, so it stops short of 5.

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 (generate) and resource (agent-ready files) and enumerates the artifacts produced: robots.txt lines, llms.txt skeleton, api-catalog, MCP server card, skills index. It also names the two sibling tools it is not (check_agent_readiness, check_robots_txt), so an agent can separate it from the scoring/checking tools 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 routing: 'To only score a site use check_agent_readiness; for one URL's robots rule use check_robots_txt.' It also states the negative condition ('Generation only, nothing is published') and notes when request-supplied skills/OpenAPI/MCP values are used. When-to-use and when-not are both covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial extra context: latency (0.1-2 s), price (USD 0.05), free quota (5 lookups per IP per UTC day), 404 billing behavior, and an explicit prompt-injection warning that endpoint strings are untrusted data. These are traits annotations cannot express.

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, then routing, output shape, cost/quota, and a safety warning; each sentence carries distinct information. It is dense and the safety boilerplate is somewhat long, but nothing is redundant.

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 sketches them (record plus dated presence rows and price-change points). Combined with annotations and explicit cost/quota/safety context, an agent has everything needed to invoke 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 and the schema already documents id, url, and source. The description adds meaning by stressing that the lookup targets ONE record, which tells the agent this is not a bulk operation and that url/id identify a single indexed entry.

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 (presence and price history of ONE indexed record) and immediately distinguishes itself from the sibling it is not by naming query_agent_index as the way to find records. An agent can tell this apart from the index-query and scan tools 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?

Explicitly routes the agent: 'To find records use query_agent_index', which implies this tool is used only after an id/url is known. It also covers the failure/edge case (404 for unindexed records, not charged) and the free-tier limit. No explicit when-not-to-use or prerequisite statement beyond the implicit routing.

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 safety profile (readOnly/idempotent/openWorld), and the description adds substantial context beyond them: pricing (USD 0.005), a free-tier rate limit (10 calls/IP/UTC day), failure semantics (no samples = 404, missing store = 503, not charged), typical latency (<1 s), and an explicit untrusted-data warning. This is genuinely additive.

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

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

Front-loaded with the when-to-use and return-value summary, then operations details. Dense but nearly every clause earns its place (cost, errors, untrusted data); the 'not a judgement of the service' and vantage-point caveats are slightly tangential but useful.

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 re-explained, and the description still covers purpose, inputs, cost, rate limits, error behavior, latency and security caveats. 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% and both url and host already document the mutual-exclusion rule ('Give url or host, not both'). The description's '`url` or `host`, not both' repeats the schema rather than adding format or scope meaning, 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 verb (know if an endpoint was up) plus a precise resource and scope (one x402 endpoint/MCP server/host over 30 days). The explicit 'one ... or host' scope pairs with the sibling name get_endpoint_uptime_bulk, letting an agent distinguish them 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 when-to-use trigger ('Use when an agent must know if ... was up, with a valid 402, over the last 30 days'). However it names no alternatives or exclusions (e.g. get_endpoint_history for longer windows, or check_x402_endpoint_before_paying), so routing to a sibling is left to inference.

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

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

Adds a great deal beyond the readOnly/openWorld/idempotent annotations: USD 0.05 price with no free tier, typical sub-1s latency, the zero-sample and 404-not-charged edge cases, and an explicit prompt-injection warning about returned page text and on-chain strings. These are exactly the non-schema facts 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?

Front-loads the usage trigger and the return payload, then appends pricing, timing and a safety note. Dense but every sentence carries information; the title duplication at the start of the description is minor waste.

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 the selection trigger, the returned metrics, cost, latency expectation, degenerate-input behavior and a security caveat. With an output schema present, return-value detail is not required, yet the description still summarizes it usefully — nothing material is missing.

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

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

Schema description coverage is 100% and the single `targets` parameter is fully documented (1-25 entries, endpoint URL or host name). The description restates the 'up to 25 endpoints or hosts' limit but adds no new syntax or format detail, 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 verb and resource ('compare the 30-day uptime and valid-402 share of up to 25 x402 endpoints or MCP servers at once') and enumerates the returned metrics. The bulk scope clearly separates it from the single-target sibling get_endpoint_uptime.

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?

Opens with an explicit trigger condition ('Use when an agent must compare... at once'), which is exactly the bulk-vs-single decision an agent faces. It does not name the single-endpoint alternative outright, and no explicit when-not-to-use case beyond 'one vantage point' is given, 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.

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses provenance (CDP Bazaar snapshots, keyword categories, self-purchases included, no facilitator data), data-warmup gaps ('7-day figures appear once enough snapshots exist'), error and billing semantics (422 unknown category, 503 unreadable dataset, neither charged), latency (under 0.1 s typical, up to ~30 s after a new snapshot), price, and a free-tier rate limit. It even adds a prompt-injection caution about treating returned text as untrusted.

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 somewhat run-on, but front-loaded with the use case before the mechanics. Nearly every clause carries actionable information (pricing, latency, error/billing behavior, security note); redundancy with the schema description is the only wasted space.

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

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

For a single-optional-param read tool with an output schema, the description covers trigger, alternative, data provenance, freshness caveats, latency, cost, rate limits, error handling, and safety. Nothing an agent needs to call it correctly is missing, and return values are correctly not belabored since an output schema exists.

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 already 100% and the single `category` parameter is fully documented with its enum list and 422 behavior. The description only restates that the input is 'optional `category` to narrow the category sections; nothing else' and that totals/churn stay marketplace-wide, both of which duplicate 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+resource+scope: 'the daily pulse of the x402 Bazaar' covering listings, sellers, new/gone, payer gains, median price, and gaps. It explicitly names the sibling it is not (get_x402_repeat_demand) and the decision context (what to list or price), so an agent can distinguish it from peers 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?

Opens with an explicit trigger ('Use when an agent must decide what to list or price on x402') and routes the repeat-payer case to get_x402_repeat_demand. Both the when and the alternative are stated directly.

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 readOnly/idempotent annotations it discloses semantic caveats that materially change interpretation: 'Observations, not settlement tests,' 'Stale rows are last-known-good,' and 'Absent fees are not zero.' It also covers failure and cost behavior (503 without charge, ~1 s latency, USD 0.001, no free tier) and a prompt-injection warning about returned page text and on-chain strings.

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, then packed with short, load-bearing clauses; nothing is padding, and the caveats (stale rows, absent fees) each earn their place. It is telegraphic rather than elegantly structured, mixing transport, latency, price, and security into one run-on block, but it stays compact.

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 shape need not be described. Given a one-parameter read tool, the description still covers the things an agent could get wrong: transport, empty-result handling with billing implications, freshness semantics, latency, price, and untrusted-data handling.

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 `since` parameter already carries a full description (inclusive UTC YYYY-MM-DD, default all recorded changes). The description only restates that it is optional and date-based, adding no format or boundary detail the schema lacks, 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?

The description opens with a specific verb and resource: 'Compare x402 facilitator support and changes since a date,' and the title enumerates the dimension set (schemes, networks, signers, fee changes). That is enough to separate it from siblings like get_x402_bazaar_pulse or x402_seller_report, though it never explicitly names or excludes an alternative.

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

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

Usage is implied by 'changes since a date' and the optional `since` input, but there is no statement of when to prefer this tool over sibling history tools such as get_endpoint_history or agent_index_delta. The transport note ('GET query or POST JSON') is invocation mechanics, not selection guidance.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes well beyond that with pricing (USD 0.003), free tier (10 agent-index calls/IP/UTC day), latency (~1 s, up to ~30 s after a new snapshot), exception behavior, and a prompt-injection caution about untrusted page/on-chain strings.

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 purpose and threshold lead, followed by the routing alternative, output attributes, inputs, freshness/errors, pricing, and safety note. Nearly every sentence carries a distinct fact, though the volume is close to overstuffed for one description.

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 sketches the returned fields (payers, calls, price, last paid time, fresh/stale flag) and the exclusion rules. Combined with error codes, latency, and cost, an agent has everything needed to call and interpret 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 description coverage is 100% and each parameter is documented there with defaults, ranges, and the category enum list, so the description mostly repeats existing semantics. It adds only marginal context (sweeps excluded, endpoints listed most payers first) beyond the schema 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 specific verb+resource (find x402 endpoints with repeat paying demand) plus the defining quantitative threshold (2+ calls per payer in 30 days, sweeps excluded). It explicitly names the sibling get_x402_bazaar_pulse and the distinction (whole market today vs repeat demand), so an agent can separate the two 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 an explicit alternative ('For the whole market today use get_x402_bazaar_pulse') and the condition that selects it. It also flags when a result is not proof (test wallets) and lists the error conditions (422 unknown category, 503 missing store, not charged), which is directly actionable routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: pricing (USD 0.001), a free tier, latency (~0.1 s), privacy ('The ua is not stored'), provenance ('observed kinds are not confirmed by the operators'), and billing behavior ('Unknown is `known` false (charged)'). This is exactly the behavioral disclosure structured fields cannot carry.

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 is front-loaded and each clause carries information (alternatives, return shape, billing, privacy). It is dense and semicolon-heavy, reading as a single run-on paragraph, but there is little that is genuinely wasted.

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

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

An output schema exists so return values need not be explained, yet the description still summarizes the key fields, and annotations cover the safety profile. Pricing, privacy, provenance, latency, and sibling routing are all present, leaving an agent nothing essential missing before calling.

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 the `ua` semantics including the empty/absent case ('Empty or absent: the whole table'), which the description repeats. The only added detail is the HTTP transport note ('GET takes it as a query parameter'), which is marginal. Baseline 3 is appropriate when 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 (identify) and resource (an x402 client by User-Agent), and enumerates the categories it recognizes (monitor, indexer, grader, HTTP library). It also names sibling alternatives (parse_user_agent, analyze_agent_traffic), so an agent can distinguish it from related tools 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: 'For any other User-Agent use parse_user_agent; for a whole access log use analyze_agent_traffic.' This gives both the alternative tools and the conditions that select them, leaving nothing to inference.

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

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

Annotations already cover read-only, open-world, idempotent, non-destructive, but the description adds real behavior: rules are read live from the list's files and cached 6 h, public reads only with nothing opened or posted, 422/503 failure semantics, 1-6 s latency (slower on cold list read), USD 0.005 price, a 10-call/day free tier, and an untrusted-data caution. This is well beyond what the annotations declare.

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 is front-loaded, then sibling routing, then behavior, cost, and a docs link, so the structure serves the reader. It is dense and long, and the price/free-tier lines could be trimmed for a tool an agent selects on purpose, but nearly every sentence carries selection or invocation 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 no explanation, yet the description still summarizes what comes back (per-rule pass/fail with README line and PR title). Errors, timing, cost, caching, and a prompt-injection caution are all covered, leaving nothing material an agent needs before calling.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes further by grouping the inputs by list variant ('repo, list, optional description, category, tags; remote list also endpoint, homepage, auth, connector'), which clarifies when each optional group applies. It does not add format or syntax detail beyond the schema, so it stays short of a 5.

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 MCP server repo against a punkpeye awesome list's rules before opening a PR') and explicitly names the two nearest siblings, check_mcp_server and scan_agent_package, with what each does instead. An agent can tell this apart from every sibling 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 the decision context up front ('before opening a PR') and routes to alternatives with their conditions ('To see whether the server answers use check_mcp_server; to scan its code use scan_agent_package'). No inference required to pick the right tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantially more: 0.1-2 s latency, USD 0.02 price, a 10-query/IP/UTC-day free tier, and a prompt-injection warning treating endpoint names/urls/on-chain strings as untrusted data. Cost, rate limits and injection risk are precisely the operational facts annotations cannot carry.

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 is front-loaded, followed by sibling routing, operational facts, and a safety note; every sentence carries decision-relevant information. It is dense and packs several facts per sentence, but there is no filler and nothing clearly droppable.

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 need no explanation, and annotations cover the safety profile. Description completes the picture with cost, latency, quota, routing to alternatives, and a data-trust warning, leaving nothing an agent needs before calling 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 description coverage is 100%, so all eight filters (q substring, page/page_size, source/network/category exact match, price bounds) are already documented in the schema. The description adds no parameter-level semantics beyond that, 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 verb and resource: 'query a daily cross-registry index of x402 endpoints and MCP servers'. It immediately distinguishes itself from the sibling export/index tools by naming them and their distinct scopes, so 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?

Explicitly routes alternatives: 'For one file of up to 5,000 rows use export_agent_index; for one record's history use get_endpoint_history.' This gives when-to-use-this vs when-to-use-that with the selecting condition spelled out, which is exactly the routing guidance an agent needs.

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 readOnly/openWorld/idempotent annotations: it describes the sandbox ('reads every file as text in a sandbox'), confirms it neither executes nor installs, warns that 'safe-looking' means only 'no rule matched', advises treating output as untrusted data, and adds latency bounds (2-15 s, up to 60 s) plus pricing/free-tier limits. 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?

Purpose is front-loaded and almost every sentence carries actionable information (alternative routing, limitations, timing, cost). It is dense and long, with pricing/free-tier and docs-link content that borders on non-essential, but nothing is redundant with structured fields in a wasteful way.

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 scan tool with an output schema already present, the description still adds value by naming the verdict/risk_score/findings shape and enumerating the finding categories. Combined with limitations, non-execution guarantees, timing, and cost, an agent has everything needed to decide and 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 description coverage is 100%, so the schema already documents source, filename, and content_base64 formats in detail. The description adds no parameter-level detail (e.g. no syntax hints or source/content mutual-exclusion note) beyond what the schema provides, so the 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 ('Scan an AI-agent skill or MCP server package before installing it') and immediately distinguishes itself from the sibling check_mcp_server by naming the alternative and its purpose. An agent can tell exactly what this does and how it differs from the reachability-checking sibling.

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 usage condition ('before installing it'), names the alternative tool with the condition that selects it ('To see whether a remote MCP server answers use check_mcp_server'), and enumerates the cases where it will not help (dynamic tool registration, runtime downloads, nested archives, obfuscated logic). When/when-not/alternative are all present.

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: it discloses that every call settles a new on-chain payment, that failed payments are never settled and their 402 names the reason, the 1-4s latency from one on-chain settlement, the USD 0.001 price with no free tier, and where the receipt verification key lives. This is the financial-risk context the readOnlyHint=false / idempotentHint=false annotations imply but do not explain.

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, then cost/latency/failure semantics and a docs link. Dense but every clause carries operational value; the repeated 'agentscan:' branding prefix is the only marginal waste.

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

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

An output schema exists, so return-value shape need not be spelled out, and the description still covers settlement behavior, failure modes, latency, price, and key discovery. Nothing an agent needs to decide whether and how to call this paid 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% and the single optional sha256 param is fully documented in the schema, including its 64-hex format. The description restates the signing semantics (hash signed with time as existence proof) without adding format or constraint 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 verb+resource (make a real x402 payment to test wallet/client) and immediately names the two sibling tools it is not (x402_payment_status, check_x402_endpoint_before_paying). An agent can distinguish this from every other x402 tool 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?

Explicit routing: use x402_payment_status to check a signed authorization without paying, use check_x402_endpoint_before_paying to vet a seller before paying. It also states the intended usage pattern (scheduled health ping). When-to-use and alternatives are fully covered.

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 annotations: exactly two unpaid requests, the bot User-Agent is self-declared (so impersonation is verifiable), a 422 for private/non-https/unreachable URLs with no charge, latency 1-4s (up to ~16s on slow endpoints), price USD 0.005 with no free tier, and an explicit prompt-injection warning to treat returned page text and on-chain strings as untrusted.

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 core purpose and keeps every element earning its place (scope, cost, latency, error code, security caveat, docs link). The single comma-spliced paragraph is dense and reads as a run-on, which costs a point on structure even though nothing is wasted.

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

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

An output schema exists, yet the description still characterizes the return as coded findings covering the four possible outcomes. For a paid, latency-variable diagnostic tool, everything an agent needs — cost, timing, no-charge failure mode, and untrusted-output handling — is present.

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 both parameters are already fully documented, including the GET-then-POST default. The description adds only the framing that the URL is hit twice without payment; it does not add format or syntax details 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?

Names a specific verb and object — checks whether a CDN/WAF still serves the x402 402 challenge to AI bots — and states exactly what it returns (the same URL's answer to an AI-bot request and a plain one). This is clearly distinct from the generic siblings like check_x402_endpoint_before_paying or test_x402_payment, which probe endpoints or payments rather than edge-layer behavior.

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?

Frames the diagnostic scenario well ('does your CDN or WAF still serve the challenge', diagnosing cached/replaced/oversized 402s) and clearly notes it is unpaid and that a 422 means the URL was rejected without charge. It does not explicitly name the sibling to use instead for related but different checks, so there is no explicit alternative routing.

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

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

Beyond the annotations (readOnly/idempotent/openWorld), it discloses that only one unpaid request is made and nothing is charged, that results are heuristic rather than a true audit, that history is limited to days the index has, latency of 2-8s (up to ~25s), the 422/503 error semantics with 503 not charged, and a prompt-injection warning about returned page text. That is unusually rich operational context for a paid, network-touching tool.

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?

It is front-loaded with the purpose and the sibling alternative before the expensive details, and nearly every sentence carries new information. The one redundancy is that the feature list ('lint, price position, preflight, ... ranked fixes') is effectively stated twice in the first and third sentences.

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 explained, and the description still covers cost, latency, failure modes, data limitations, and untrusted-content handling. For a network-calling paid tool with openWorldHint, nothing an agent needs before calling 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 both parameters are already documented, including the GET-then-POST fallback for method. The description adds only indirect value by tying 'private or non-https URL' to a 422, which reinforces the url parameter's validity domain but does not explain formats or semantics 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?

The description names a specific verb and resource ('review one x402 listing') and enumerates exactly what the review contains: lint, price position, preflight, 30-day category demand, 10 closest peers, ranked fixes. It also explicitly separates itself from x402_seller_report, so an agent can distinguish it from siblings 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?

It gives an explicit routing rule: 'For a cheaper report without peers or history use x402_seller_report,' which states the alternative and the condition that selects it. It adds cost/permission context ('Free: your first review is free, then USD 2 each') and the shape of the input that is acceptable, so the when-to-use decision is fully informed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds materially more: non-supported networks return 422, "Used also covers an authorization its signer cancelled," bad input is a 422 and not charged, latency is 1-3s, price is USD 0.002, and there is a free quota of 10 reads/IP/day. It also warns to treat returned text as untrusted data.

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

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

Front-loaded with the purpose and alternative before dense operational facts (error codes, timing, pricing, quota, security note). Every sentence earns its place, though the middle section is clause-heavy and could be split for 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?

Given an output schema exists, return values need not be described. The description still covers network restrictions, error behavior, pricing/quota, latency, input selection, and a security caveat, leaving nothing an agent needs to invoke 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 baseline is 3, but the description adds the key constraint the schema does not encode: network plus either x_payment or authorizer with nonce (and optional token). That XOR-style requirement is genuine semantic value beyond the schema, which only marks network required.

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

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

States a specific verb and resource with scope: "Check an x402 payment: was its USDC authorization used, can it still settle." It explicitly distinguishes itself from the sibling test_x402_payment, so an agent can route correctly without reading 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?

Names the alternative explicitly ("To make a real test payment instead use test_x402_payment") and gives the selecting condition. It also specifies when the tool applies (base/polygon/arbitrum only) and what input shapes are acceptable.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: 422s are not charged, typical 1-3 s latency, USD 0.002 price, a 10-reads-per-IP-per-UTC-day free tier, and a prompt-injection warning to treat returned page text and on-chain strings as untrusted data.

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: the core question comes first, then scope, error behavior, cost and a security note. Each clause earns its place, though the run-on punctuation makes it slightly harder to scan than a sentence-per-topic layout would.

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 sketches the payload and verdict shape. Combined with coverage of errors, pricing, rate limits, chain support and untrusted-data handling, an agent has everything needed to invoke 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 description coverage is 100%, so the baseline is 3; the description still adds semantics by explaining that the `verdict` is computed against `expect_pay_to`, `expect_amount` and `expect_token`, that the default token is the network's native USDC, and that the observed amount need only be at least `expect_amount`.

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 receipt proving that a given tx hash paid a given amount to a given address — and the title carries the same specific framing. It is clearly distinguishable from siblings such as x402_payment_status or test_x402_payment 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?

It gives the operative conditions (token transfers only, native-coin payments yield `no_token_transfer`, amount must be at least `expect_amount`, unsupported networks are 422), which tells an agent when the tool applies. It does not explicitly name sibling alternatives or say when-not to use it versus those, so it stops short of full routing guidance.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses the payment model (one unpaid request, USD 0.01, no free tier), the error semantics ('422 not charged' for private/non-https URL, '503 not charged' for an unreadable index), latency bounds (1-4 s, up to ~15 s), and a prompt-injection warning about returned page text and on-chain strings.

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

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

Front-loaded with the core purpose and the sibling routing before the caveats; every sentence carries information (scope, cost, errors, safety). It is dense and slightly repetitive with the long title, keeping it short of 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 contents needn't be spelled out; the description still summarizes the report's sections. With pricing, error codes, latency, safety guidance, and sibling routing all covered for a complex paid scan, an agent has everything needed to decide and 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 description coverage is 100%, so both url and method are already documented at the field level, making 3 the baseline. The description reinforces that the URL must be public https and that a private or non-https URL produces a 422, but adds no format or fallback detail beyond what the schema already states for method.

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 ('one report on an x402 endpoint for its seller') and enumerates the report's contents: lint, price position, buyer preflight, Bazaar demand, coded fixes. It explicitly distinguishes itself from x402_listing_audit and lint_x402_listing, so an agent can route 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 explicit when-to-use-other routing: 'For category demand history, 10 peers and ranked fixes use x402_listing_audit; for lint alone use lint_x402_listing.' It also sets the scope fence that this is one endpoint, one unpaid request, and not an audit.

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 readOnly/idempotent/non-destructive annotations, the description discloses that nothing is fetched from the seller, that Tanod signs nothing (so the returned file is only a draft), the 404 vs 422 error semantics with the note that 422 is not charged, typical latency (<1s), price ($0.001), and the free tier (10 calls/IP/UTC day). It also flags returned page text and on-chain strings as untrusted. This is exactly the extra context annotations cannot carry.

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 output artifact and its index-derived nature are front-loaded in the first two sentences, followed by error codes, latency, pricing, and a security note. Dense but each clause carries a distinct operational fact; the docs URL is the only mild padding.

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-value detail is unnecessary, and the description still covers errors, timing, cost, free quota, and the untrusted-data caveat. What remains thin is routing guidance relative to sibling tools, but for a single-parameter read-only generator the definition is otherwise complete.

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

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

Schema description coverage is 100% for the single host parameter, and the schema already documents the no-scheme/no-path/no-port format and the www. matching rule. The description only restates that listings become the file's resources, adding little syntax or format detail 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?

The description names a specific verb and artifact: builds/returns the /.well-known/x402 file body for one seller host from its Bazaar and PayAI listings. Scope is precise (one host, index-derived draft). It does not explicitly distinguish itself from the adjacent sibling generate_agent_ready_files, 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?

Usage is implied rather than stated: an agent can infer this is for generating a draft well-known file from the index, and gets the premise 'nothing is fetched from the seller.' But there is no explicit when-to-use versus generate_agent_ready_files or the other x402 audit siblings, and no stated prerequisites beyond the host name.

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