x402-list-mcp

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

Annotations only say readOnlyHint=false / idempotentHint=false / openWorldHint=true, and the description goes far beyond them: two-call payment protocol, price ($0.25 USDC on Base plus probe endpoint price X), the server's no-keys/no-signing/no-settlement relay role, non-refundable probe fees, and settle-only-after-success behavior. This is exactly the operational context an agent needs that annotations do not provide.

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

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

Long but highly informative; every sentence carries a distinct operational fact. The trigger condition is front-loaded, then the what, then the two-call mechanics, then probe and caveats. Minor redundancy ('non-refundable' and 'there is no refund') keeps it from a 5, but the density is justified by the tool's complexity.

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-step tool with nested probe objects and no output schema, this is remarkably complete: it covers the challenge contents (accepts[], amount, payTo, PAYMENT-REQUIRED header), the report trigger, probe behavior and cost, and failure/refund edges. Nothing an agent needs to execute the two calls correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters well. The description adds operational meaning the schema lacks: the omit-then-set protocol for payment_signature_b64 requiring 'the SAME question and services', and the probe's price-inflation and probe_report implications beyond the schema's structural description.

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 ('buys one fresh AI assessment reasoned against your question') and explicitly contrasts itself with x402_get_service ('not a cached grade... stays free via x402_get_service') and with the search tools that produce the finalists. An agent can immediately tell this is the paid fresh-assessment tier and not a search or cached-read 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 trigger condition ('when the free signals have run out: you hold 2 to 8 finalists... and choosing wrong costs more than a quarter') and names the alternative for the cheaper case ('reading an already-computed assessment stays free via x402_get_service'). The qualification criteria are concrete enough to route correctly.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds meaningful behavioral caveats: payTo values are masked by design, prices are atomic token amounts not dollars, and the feed reports exactly three event types. This goes well beyond the annotations and sets accurate expectations.

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

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

The description is compact yet dense: every sentence adds value, the trigger scenarios are front-loaded, and the caveats are tucked efficiently at the end. No filler or repetition.

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

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

With no output schema, the description still explains the return nature, event types, ordering, filtering options, units, and masking behavior. Combined with the fully described input schema and annotations, an agent has enough to select and call the tool 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 all five parameters. The description adds some restated context for service, type, and days, but does not meaningfully explain page or per_page beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description names a concrete resource and operation: it returns observed payTo, price, and 402-schema changes on listed services, framed as a monitor log. This clearly distinguishes it from sibling tools that assess, search, or fetch current service state.

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

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

The description gives explicit, contextual use cases: call before trusting cached data about a service and right after a payment fails for no obvious reason. It does not name alternative tools or exclusion criteria, but it clearly states when this tool is the right choice.

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

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

With readOnlyHint already present, the description adds meaningful behavior context: the difference between directory mode and single-service mode, what include_services=true does to the payload size, and the explicit guarantee that no money fields are returned. This goes well beyond the annotations and helps the agent anticipate the response shape and scope.

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

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

The description is dense but efficient, with every sentence earning its place: usage timing, mode behavior, and a safety/scope disclaimer. It front-loads the most important invocation guidance and avoids generic filler.

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

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

Even without an output schema, the description tells the agent what to expect in both modes: status counts for the directory, and status/uptime windows/response time/consecutive failures/daily snapshots for a single service. It also addresses payload size and the absence of money fields, making it complete for a read-only health check tool.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by clarifying mode-dependent behavior: no slug means directory snapshot, slug enables single-service detail, and include_services only applies in directory mode. This reinforces and extends the schema descriptions without redundancy.

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 ('check x402 service health') and explains exactly what the tool does: tells whether a service is up right now. It also distinguishes the two operating modes (directory snapshot vs single service) and even notes what it does not return ('No money fields'), which separates it from sibling payment-related tools.

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

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

The description gives explicit timing guidance: call before sending a payment or right after an unexpected failure. It does not name alternative sibling tools or say when not to use this tool, but the usage context is clear and actionable enough for an agent to know when to invoke it.

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

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

The description goes beyond the readOnlyHint annotation by explaining important behavioral caveats: the 24h fields cover today so far and reset at 00:00 UTC, the metric is per-facilitator not per-service, and the verification flag transitions from 'listed' to 'on-chain'. This is valuable operational context an agent needs to interpret results correctly.

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

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

The description is front-loaded with the key routing instruction, then packs the return scope, optional parameters, and critical caveats into three efficient sentences. Every sentence adds distinct value without redundancy.

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

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

Given the absence of an output schema, the description adequately characterizes the response: settlement volume, transaction counts, time buckets, verification flag, facilitator coverage, and optional timeseries/chain breakdowns. It also covers the most likely misinterpretation (24h semantics) and the service-versus-facilitator distinction.

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

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

Schema coverage is 67%, and the description usefully adds meaning by explaining that volume is decimal USD, the optional timeseries is up to 90 days, and the per-chain breakdown is available. It also reinforces the non-trailing meaning of '24h'. Page and per_page are not described, but their pagination purpose is self-evident.

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

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

The description states a precise verb and resource: it reports settlement volume and transaction counts per x402 facilitator, and explicitly contrasts this with the service layer. This clearly differentiates it from sibling service-focused tools.

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

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

The opening instruction 'Call this when the question is about the rail rather than the service' gives explicit guidance on when to use it, and 'never per-service' further clarifies the boundary. The sibling tools are service-oriented, so the usage context is unambiguous.

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

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

The description goes well beyond the readOnlyHint and openWorldHint annotations by disclosing the ranking methodology, the approximately 10% weight on settlement traction, the ranking_version field, and the need_blind_ranking behavior. It also explicitly warns about a 'units map' containing scoring caveats, such as compliance caps and the $10 volume floor, which is valuable behavioral context an agent would otherwise not know.

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 long but highly information-dense. It front-loads the primary purpose and invocation, then explains the ranking logic and response caveats in structured sentences. Every sentence earns its place; it is not bloated, though it could be tightened slightly by separating the caveat list into a clearer structure.

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 read-only ranking tool with no output schema, the description is remarkably complete: it explains when to use it, what parameters to pass, what the response contains (ranked recommendations, ranking_version, need_blind_ranking, units map), and how the ranking works. It also includes important caveats and a pointer to read units before comparing scores, leaving little ambiguity for an agent deciding whether and how to call 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?

The input schema already documents all 8 parameters with 100% coverage, so the baseline is 3. The description adds a small amount of extra meaning by explaining q as 'a need in words' and grouping the relevant filter parameters, but it does not provide new details beyond what the schema descriptions already contain.

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

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

The description clearly states that the tool converts a natural-language need (q) into a single recommended service, returning up to 20 ranked recommendations. It distinguishes itself from list-returning tools by explicitly framing it as 'the free ranking step between searching and paying' rather than a list to read.

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 a clear when-to-use condition: call when you want one service to call rather than a list to read, and positions it between searching and paying. It does not explicitly name the sibling alternatives, but the 'rather than a list to read' phrase effectively tells the agent when not to use this tool in favor of a list-returning one.

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, and the description adds meaningful behavioral detail: include_series is off by default to keep the response small, series is 90 daily points, and the per-endpoint price field is in atomic token units, not dollars. This last warning is exactly the kind of non-obvious runtime behavior an agent needs.

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?

Every sentence earns its place: usage timing, returned fields, optional series behavior, and a critical units caveat. The most important guidance is front-loaded in the first sentence.

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

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

With no output schema, the description carries the burden of describing the response, and it does so thoroughly: status, uptime windows, response time, networks, settlement asset, endpoints, assessment block, optional series, and units. For a simple slug lookup with two parameters, nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents both slug and include_series. The description reinforces include_series behavior but does not add meaning beyond the schema, so it stays at the 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?

The description clearly identifies this as the tool for retrieving the full service record behind a directory row once a slug is already held. The phrase 'the full record behind a directory row' plus the enumeration of live status, uptime, endpoints, and assessment block distinguishes it from lighter-weight search or assessment siblings.

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

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

It gives an explicit when-to-use condition: 'Call this once you hold a slug and are deciding whether to commit to that service.' It does not explicitly name sibling tools or state when not to use them, but the 'slug already held' condition makes the intended context 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 signal readOnlyHint and openWorldHint, and the description adds useful behavioral detail beyond that: it explains pagination ('up to 100 compact summaries a page'), the kind of output returned (price, uptime, status, verification), and the candidate-narrowing workflow. No contradictions with annotations.

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

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

Two dense, front-loaded sentences cover purpose, filters, sorting, result size, output content, and the follow-up tool. There is no filler or repetition of schema details; every clause earns its place.

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

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

For a 10-parameter, no-output-schema search tool, the description is largely complete: it explains when to use it, what it filters/sorts by, page limits, and what to do next. Minor gaps remain around exact pagination metadata and the full list of compact summary fields, but the schema compensates for parameter-level details.

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

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

The schema has 100% parameter description coverage, so the baseline is 3. The description correctly summarizes the filter dimensions and sort options, but it does not add meaningful detail beyond the schema's per-parameter descriptions, such as exact filtering behavior or response shape details.

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

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

The description uses a specific verb and resource: it 'narrows a directory of 500+ listed services to candidates' and is explicitly positioned as 'your first call' when the target service is unknown. It clearly distinguishes itself from x402_get_service, which is described as the follow-up for the full record.

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 provides a clear when-to-use condition ('when you do not know which x402 service exists for a job') and points to x402_get_service as the natural next step for full records. It does not explicitly cover when not to use this tool versus other siblings like x402_find_best_service, but the context is strong.

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