x402-list-mcp

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

With no annotations, the description fully discloses the tool's behavioral traits: the $0.25 fee on Base, the pass-through nature ('never holds keys, never signs, never settles'), the challenge/signature/receipt flow, probe pricing and non-refundability, and the no-charge guarantee if the fresh run fails. No contradictions exist with annotations since none are provided.

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 well-structured: a one-sentence summary, then pricing, protocol, probe behavior, and failure semantics. It is front-loaded and each section adds necessary detail for a paid tool. Minor redundancy exists (e.g., pricing mentioned twice), but overall the length 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?

Given the absence of an output schema and annotations, the description thoroughly covers pricing, the two-call payment protocol, probe behavior, failure/no-refund semantics, and alternatives. The only minor gap is the overall response structure beyond the probe_report block, but that is not essential for the agent to invoke 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 coverage is 100%, giving a baseline of 3. The description adds significant meaning beyond the schema, especially for payment_signature_b64, explaining the first call without it returns the challenge and the second call with it returns the report. It also clarifies the probe parameter's live-payment behavior and price impact, though some of this is already in the schema's probe 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?

The opening sentence clearly states the tool's purpose: 'Run a fresh, PAID AI assessment comparing a shortlist of already-listed x402 services for a stated need.' It names a specific verb (run), resource (x402 services), and explicitly contrasts with reading an already-computed assessment via get_service, distinguishing it from siblings.

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

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

The description gives explicit when-to-use guidance, saying 'reading an already-computed assessment stays free via get_service.' It also names sibling tools (search_x402_services, find_best_service) for discovery, and details the two-call payment protocol with clear steps: call once without payment_signature_b64, sign accepts[0], call again with signature.

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 no annotations provided, the description carries the full burden of disclosing behavior. It details what the tool returns in both modes (status counts, per-service status, uptime windows, response time, failures, daily snapshots) and explicitly notes 'No money fields' as a behavioral limitation. It does not mention side effects or permissions, but health checks are typically read-only and the return behavior is well specified.

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 two sentences, front-loaded with the primary verb and resource, and each sentence conveys distinct, useful information. There is no redundant or filler content; it efficiently covers modes, return data, and an important exclusion.

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 and annotations, the description adequately explains the return structure for both modes, listing key fields and counts. It also clarifies the effect of include_services. The only minor gap is not explicitly stating the output format (e.g., JSON), but this is commonly assumed and the description is otherwise complete for a health check utility.

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 tool description adds context about mode selection ('With no slug...' vs. 'With a slug...') which complements the schema's per-parameter descriptions, but the schema already explains each parameter's meaning and defaults. The description does not introduce new parameter semantics beyond what the schema provides.

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 the tool's function: 'Check live health of x402 services.' It distinguishes between two modes (directory-wide snapshot vs. single-service report) and explicitly differentiates from siblings by focusing on live health rather than assessment, discovery, or financial details. The verb 'check' and resource 'health' are specific.

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 provides clear context on when to use each mode: 'With no slug...' and 'With a slug...' It also notes 'No money fields' to steer away from financial use cases. However, it does not explicitly name alternative tools or state when not to use this tool versus siblings, so it stops short of full exclusion 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?

With no annotations, the description carries full burden, and it excels: it details ranking criteria, anti-wash rules, traction caveats (shared payTo, network unmeasured, 30-day floor, single-buyer discount), and the meaning of ranking_version. It also discloses response elements like top_buyer_share_30d. This is exceptionally transparent.

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 main purpose, but it quickly becomes a wall of text over 250 words, covering many edge cases. While each detail is relevant, the length reduces scannability and flirts with over-specification. It is not a model of conciseness.

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 there is no output schema and annotations are absent, the description fully compensates by explaining the return values (ranking_version, top_buyer_share_30d, optional facilitator context) and the reasoning behind them. It covers all significant behavioral nuances an agent would need to invoke and interpret results 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 does not add parameter-specific semantics beyond the schema; it focuses on ranking methodology rather than explaining inputs like q, limit, or prefer. The schema already documents each parameter clearly.

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: 'Recommend the best x402 service(s) for a need.' It clearly distinguishes itself from siblings like search_x402_services (search) and assess_services (assessment) by focusing on ranked recommendations. The purpose is unmistakable.

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 implies usage when a user needs ranked recommendations ('for a need'), but it never explicitly says when to use this tool versus alternatives or provides exclusions. No comparison to search_x402_services or assess_services is made, leaving the agent to infer the appropriate context.

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

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

With no annotations, the description carries the full transparency burden. It discloses important behavioral traits: the 24h fields represent today (UTC) so far and reset at midnight, the verification flag semantics, and that all volumes are USD. This goes well beyond generic verb+resource phrasing and warns about a likely misinterpretation.

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 front-loads the core purpose and packs each sentence with essential information: returns, verification flag, time-window caveat, optional inclusions, currency, and scope. No filler or redundancy; every clause earns its place given the no-annotations, no-output-schema context.

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 tool with 6 optional parameters, no annotations, and no output schema, the description covers the key dimensions: what it returns, critical time semantics, optional parameters, and scope clarification. Minor gaps include lack of explicit mention of pagination (though schema provides page/per_page) and no description of the exact shape of the timeseries/chains breakdown, but these are secondary.

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%, so the description compensates by clarifying the meaning of the timeframe param ('24h sorts by today UTC so far'), mapping include_timeseries and include_chains to the 'Optionally include...' sentence, and adding the critical USD context. This adds value beyond the schema fields.

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+resource: 'Get on-chain-verified settlement volume per x402 facilitator' and explicitly highlights the per-facilitator scope, distinguishing it from sibling tools about services. It clearly states the core metric and differentiates from get_service, search_x402_services, etc.

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 offers concrete usage advice: 'prefer 7d for a stable recent-activity read' and warns against misinterpreting *_24h fields. While it does not explicitly name alternatives or exclusion criteria, the final sentence 'This is PER-FACILITATOR, not per-service' implicitly steers users away from this tool if they need per-service data, giving a clear contextual signal.

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 no annotations provided, the description carries the full burden and does well. It enumerates the returned data fields and adds a critical unit clarification: 'Prices are in US dollars; the per-endpoint `price` field is a raw on-chain atomic token amount, not dollars.' This reveals a non-obvious data interpretation detail beyond what the schema provides.

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 two sentences and front-loaded with the core purpose. Every clause adds value: the data contents list, the usage placement after search, and the price-unit caveat. There is no fluff or repetition of schema 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?

Given the tool's low complexity (2 params, no output schema, no annotations), the description is complete. It tells the agent what the tool does, what data it returns, when to use it, and clarifies a potential misinterpretation about price units. The schema covers the optional include_series behavior, so no additional description is needed.

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 does not add much parameter-specific semantics beyond what the schema already says; it mentions 'by slug' but that mirrors the schema's slug description. The `include_series` parameter is fully documented in the schema, so the description need not repeat it.

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 starts with a specific verb+resource: 'Get full detail for one x402 service by slug', and enumerates the exact fields returned (status, uptime, response time, networks, settlement asset, endpoint prices). It distinguishes itself from sibling tools by explicitly positioning itself after search_x402_services for inspecting a specific service.

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 provides clear usage context: 'Use after search_x402_services to inspect a specific service.' This tells the agent when to use the tool and references the discovery sibling. However, it does not explicitly mention when not to use it versus other siblings like check_health or find_best_service, so it lacks full exclusion 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?

With no annotations provided, the description carries the full transparency burden. It discloses that the operation is a read-oriented search/filter, specifies the returned summary fields (price, uptime, status, verification), and clarifies currency in USD. It does not mention pagination or edge cases, but those are covered in the schema; the description adds meaningful behavioral context on its own.

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 two sentences, front-loaded with the core purpose and followed by a compact summary of outputs and price unit. Every sentence contributes value, with no filler, redundancy, or irrelevant details.

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 10 parameters and no output schema, the description provides a coherent mental model: search/filter the directory, with summarized results. It covers the primary behavior and return fields, though it defers to the schema for pagination and field-selection nuances. It is adequately complete for a directory search tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description recaps the filter dimensions and sort options already present in the schema but does not add new semantic details beyond what the parameter descriptions provide. It reinforces the key parameters without expanding their meaning.

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 specific verb+resource ('Search and filter the x402-list directory of services that accept x402 payments'), clearly distinguishing it from single-service tools like get_service or find_best_service. It enumerates filter dimensions, sort options, and return fields, leaving no ambiguity about its function.

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

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

The description establishes a clear context: this is the directory-wide search/filter tool, implying when to use it (when you need to discover or filter services). However, it never explicitly names sibling alternatives or states when-not-to-use, so it falls just short of the highest bar.

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