x402-mcp

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

The description goes well beyond annotations by disclosing that the operation is paid, settles USDC via x402 when EVM_PRIVATE_KEY is set, and otherwise returns a 402 probe. This is key behavioral context that an agent cannot infer from the schema or annotation flags.

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 concise sentences deliver the core purpose, ordering guidance, payment mechanism, and fallback behavior with no fluff. The most important operational facts are front-loaded.

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

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

Given the output schema exists and the input schema has full parameter documentation, the description adds exactly the missing operational context: paid status, sample-first order, settlement via x402, and 402 behavior. This is complete for an agent to decide and invoke the 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 description coverage is 100%, so the input schema already documents all five parameters including examples. The description itself does not explain individual parameters, but the schema carries that burden, so the baseline score of 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 clearly states a specific verb and resource: 'Run a paid US city property compliance check.' It also distinguishes itself from city.sample by explicitly telling the agent to prefer city.sample first, so the tool's role is unambiguous.

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 direct guidance to use city.sample before this paid check, which is a clear alternative-selection rule. It does not enumerate all when-not-to-use cases, but the preference ordering is sufficient for most agent decisions.

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, idempotent, and non-destructive behavior, so the description is not required to restate those. It adds useful behavioral context by disclosing that the list exposes paid_url, sample_url, and price data, and by identifying the overall paid-address-lookup workflow.

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 with no filler. It front-loads the core purpose and data fields, then immediately gives the workflow order needed to use the related city.* tools correctly.

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

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

For a simple, read-only list tool with zero required parameters and an output schema available, the description is complete. It provides the listed fields, the meaningful sequencing instructions, and enough context for an agent to select and 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%, and the only parameter, agent_id, is already documented as an optional identity for quota accounting. The description doesn't add any parameter-level detail, so the baseline score of 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 uses a specific verb (list) with a specific resource (US City Open-Data Compliance Network cities) and clearly states the fields returned (paid_url, sample_url, price). It is immediately distinguishable from the sibling city.sample and city.check tools because it positions itself as the introductory listing step.

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 workflow guidance: call this tool first, then city.sample, then city.check. This tells the agent exactly when and in what order to use this tool relative to its relevant siblings.

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 communicate read-only, idempotent, and non-destructive behavior. The description adds useful context beyond these flags: the sample is free, tied to a fixed address, and is intended for pre-validation before a paid check. This is meaningful additional behavioral guidance.

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 exactly two sentences: one states the core action and the other states its intended use. It is front-loaded, focused, and every phrase 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?

The tool is simple, has one required parameter, an output schema, and annotations that declare safety. The description provides the critical free/paid distinction and explicit 'use before' guidance. Nothing necessary for calling 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 description coverage is 100%, so the input schema fully documents city_code and agent_id. The description confirms that city_code is a single US city code, matching the schema's examples but adding minimal new semantic information beyond the structured 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 clearly names the action, the resource type, and the scope: 'Get a free fixed-address property compliance sample for one US city code.' It also identifies the related tool city.check, making the purpose distinct and understandable immediately.

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 explicitly states when to use this tool: 'Use before city.check to validate city_code and response shape without paying.' This gives an agent a precise use case and effectively routes to or away from city.check.

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 reveals that the agent will verify a payment and then change the agent's quota state, which is valuable because readOnlyHint=false only says the tool mutates, not what the mutation is. It adds a clear precondition and does not contradict annotations; more error or persistence detail would be helpful but is not missing enough to lower the score further.

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 long and all of it earns its place. The action is stated first, followed by a precise precondition and flow reference; there is no filler or repetition of the tool title.

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 a fully documented parameter schema, an output schema, and annotations covering mutation and idempotency, the description need only supply the workflow context. The description gives that context clearly. It omits error handling or exact return semantics, but those are either covered by the output schema or not essential for calling this 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?

The input schema already provides 100% coverage with descriptive explanations for all three parameters. The description adds context that the payment flow comes from commerce.pro_requirements and USDC, but the parameters themselves are already well-documented, so the schema carries the weight here.

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 action with concrete objects: 'Verify a Pro-tier x402 payment and unlock Pro quota limits for the agent.' This clearly distinguishes the tool from related siblings like commerce.pro_requirements and commerce.purchase_credits, telling the agent exactly what end state the tool produces.

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 call sequence: 'Call after commerce.pro_requirements and a completed USDC payment.' This tells the agent when in the workflow the tool belongs. It does not explicitly name when not to use it or compare it with alternatives, so it stops just short of full 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 readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the description only needs to add relevant context beyond safety. It does so by explaining that the output is a payment requirements artifact tied to a signature usable in a later purchase step. This is useful sequencing and downstream-context information.

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 and front-loaded with the core purpose before the workflow note. Every sentence contributes meaningful information with no filler or redundant restatement.

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?

The combination of tool description, full schema coverage, annotations, and no required parameters provides enough guidance for an agent to call and use this tool correctly. The output schema likely covers return shape, and the description covers the important integration step.

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 has 100% parameter description coverage and documents both parameters clearly. The description adds general context about credit packs but does not add meaning beyond the schema, so the baseline score of 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 uses a specific verb and resource: 'Build x402 payment requirements to buy a pack of per-use MCP tool credits.' It clearly identifies the tool's purpose and differentiates it from the pro-related commerce tools by specifying credits, and it names the follow-up purchase tool.

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 clear context for when to use this tool, namely as the first step toward purchasing credits. It also provides a workflow: build requirements, pay them, then call commerce.purchase_credits with the signature. It does not explicitly exclude alternatives like commerce.pro_requirements, but the credit-specific language makes the use case 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?

The description discloses the non-final nature of the operation by noting that payment and activation must follow. This complements the readOnlyHint and idempotentHint annotations without contradicting them, and it makes the tool's role in the larger workflow clear.

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 short sentences with no filler. The core purpose is front-loaded, and the workflow next steps are conveyed efficiently. Every sentence contributes useful 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?

With one optional parameter, a full output schema, and read-only/idempotent annotations, the description is complete enough for the low complexity. It covers the intended workflow and names the next tool to invoke, so an agent has the necessary context to call it correctly.

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

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

Schema description coverage is 100%, so the optional agent_id parameter is already fully documented. The description does not need to repeat parameter details and adds no extra parameter-specific meaning, so the baseline score of 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 explicitly states the action ('Build x402 payment requirements') and the specific target ('purchase the Pro quota tier'). It also differentiates itself from the sibling activation tool by describing this as a precursor step, so an agent can clearly tell what it does.

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 clear sequential usage context: build the requirements, pay the terms, then call commerce.activate_pro. It does not explicitly list alternatives like commerce.credits_requirements, so it is strong on when to use but weaker on when not to use.

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 discloses the mutation behavior ('add per-use tool credits') beyond what readOnlyHint=false and idempotentHint=false convey, and it notes the payment verification step. It does not cover failure/retry behavior, but the key side effect is clearly stated.

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 tight sentences, no fluff. The core behavior is front-loaded, and the prerequisite ordering follows immediately. Nothing extraneous is included.

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 a full input schema, an output schema, annotations, and a clear sequencing statement, the description gives an agent everything needed to call the tool correctly. Return-value details are covered elsewhere, so the description does not need to restate them.

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 adds no new parameter-specific meaning beyond what the schema already provides, but it does not need to since each parameter has an existing 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 description uses a specific verb-resource pair: 'Verify an x402 payment and add per-use tool credits to the agent.' This clearly distinguishes the tool from related siblings like commerce.credits_requirements and x402.verify, which handle prerequisite steps rather than the final credit purchase.

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 explicitly states the call order: 'Call after commerce.credits_requirements and a completed USDC payment.' This tells the agent exactly when to invoke the tool and makes the prerequisite chain 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?

Beyond the annotations, the description discloses that a webhook fulfills the grant, which is important non-obvious behavior: the grant is not immediate. This aligns with readOnlyHint=false and does not contradict the annotations, though it could say a bit more about checkout flow details.

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 short and front-loaded: it states the action, the resource, the payment-rail context, and the fulfillment caveat in two sentences. Every sentence carries information an agent needs.

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 full parameter coverage in the schema and an output schema present, the description covers the essential context: when to use it, what it creates, and how fulfillment happens. It could also transparently mention that the returned checkout URL is intended for the buyer, but that is mostly covered by the overall tool behavior.

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?

Since schema description coverage is 100%, the parameters are already fully documented. The description only restates the purpose choices ('Pro tier or tool credits') and does not add new parameter-level semantics such as required combinations or format constraints.

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, 'Create a Stripe Checkout Session', and immediately names its two purposes: Pro tier or tool credits. The phrase 'fiat rail' clearly distinguishes it from USDC-based payment siblings, so an agent can tell what this tool does.

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 an explicit usage condition: use when the buyer pays by card instead of USDC. It also clarifies that fulfillment happens via webhook. It doesn't explicitly name a sibling tool for the USDC case, so the comparative routing is implied rather than fully spelled out.

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, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds that it returns a health verdict and is intended for diagnosing the host, which provides some extra context, but it doesn't disclose any nuanced behavior beyond what the annotations and output schema cover.

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 short sentences with no fluff. The core action and data scope are in the first sentence, the second adds the diagnostic trigger and parameter condition efficiency.

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 annotation coverage, a full output schema, and only 2 optional parameters, the description is completely sufficient. It states the resource, the condition for use, and the key optional parameter without missing any critical information.

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 parameters. The description's mention of setting include_processes=true adds no new information beyond the schema's own description. Agent_id is not addressed, but the schema already describes it as optional quota accounting.

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 ('Get'), names the resource ('host OS telemetry'), and lists its key contents (CPU, memory, swap, disk, network, and an ok/warn/critical health verdict). It clearly differentiates this tool from the unrelated sibling tools by focusing on host OS diagnosis.

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 explicitly says 'Call to diagnose this MCP host', giving the primary use case. It also gives action guidance for the include_processes parameter. It does not mention when not to use it or compare to alternatives, but none of the sibling tools offer similar functionality, so the context is adequate.

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 convey that the tool is read-only, idempotent, and non-destructive. The description adds useful context about the live nature of the data and the specific verdict/recommendation returned, which goes 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 a single well-structured sentence that front-loads the core action and outcomes, then immediately adds the practical use-case. Every part earns its place without any padding 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?

Given the tool's read-only nature, complete optional-parameter schema, and presence of an output schema, the description is fully adequate. Knowing which metrics are returned and when to call it is enough for an agent 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?

The input schema provides full descriptions for both parameters (depth and agent_id), achieving 100% schema coverage. The tool description does not add parameter-specific meaning, such as how depth influences results, but the schema already covers the necessary semantics, so the baseline score of 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 states a specific verb and resource: 'Get live Base Network Pulse,' and lists the exact output components (base fee, EIP-1559 projection, utilization, USD settlement cost, verdict). It clearly ties the tool to a settle-now vs hold recommendation, which differentiates it from sibling tools like swarm.settle or x402.pay_and_fetch.

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 explicitly states when to use the tool: 'Call before settling on Base when you need a settle-now vs hold recommendation.' This gives clear situational guidance, but it does not explicitly name alternative tools or state when not to use it, so it falls just 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?

Beyond the annotations, the description discloses that the tool lists a product for resale and that paid upstream inputs are gated behind allow_paid_inputs. This clarifies the free-input default and the behavior when paid inputs are allowed, adding meaningful context beyond the boolean hints.

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 and well structured: it states the core behavior first, then adds the one important caveat about paid inputs. There is no filler or redundant 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?

Given the complete input schema, full parameter coverage, output schema, and annotations, the description provides enough context for the agent to select and invoke the tool correctly. It covers the main side effect, listing for resale, and the paid-input gate.

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 describes all four parameters, including the behavior of allow_paid_inputs and max_price_usdc. The description mostly restates the paid-input conditional and adds little new parameter-level meaning 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 explicitly describes the action and result: run the swarm agency, compose a research product from free inputs, and list it for resale. This is specific and lets an agent distinguish this tool from revenue or settlement tools like swarm.revenue and swarm.settle.

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 clear invocation context: use this when composing a research product and listing it for resale. It also states the key conditional: pass allow_paid_inputs=true only when buying upstream x402 services is intended. It does not explicitly name alternatives, but the use case is clear enough.

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 provide readOnlyHint, idempotentHint, and destructiveHint=false, so no safety warning is necessary. The description contributes an important workflow behavior beyond the annotations: it exposes that this passes the fact that the data reflects realized economics only after the antecedent reports. There is no contradiction with the 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?

The prose is two sentences, front-loaded with outcome and output. It packs the most important information with no waste, while still explaining the scheduling relationship.

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 a single optional parameter, complete schema, and output schema available, the description adds the missing contextual pieces: the domain (economy, revenue), the key metrics, and the required call order. Nothing necessary for invoking this tool is absent.

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, defining the sole optional agent_id as an identity for quota accounting. The natural-language description does not expand on the parameter, so the baseline of 3 applies rather than a higher score.

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?

Description opens with a clear verb, 'Get swarm portfolio revenue intelligence', and lists concrete deliverables: spend, revenue, LTV:CAC, margins, per-source scores. That specificity distinguishes the purpose from sibling tools like swarm.research and swarm.settle, which are tied to data-generation rather than post-hoc economics.

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?

Includes explicit usage sequencing: 'Call after swarm.research or swarm.settle to inspect realized economics.' This provides when to call and why, which is strong guidance. It does not spell out exclusions or alternative-use cases, but the call ordering gives an agent a clear trigger.

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 indicate readOnly=false and idempotent=false, so the description does not need to restate mutation. It usefully explains that the tool verifies payment and records revenue, but it does not disclose side effects like duplicate settlement or what happens if the sale was already settled.

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 compact sentences with no filler. The most important call condition is front-loaded, and every sentence contributes to understanding how and when to 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?

With an output schema present and all parameters documented, the description covers the essential workflow well. A minor gap is not explaining why payment_required is needed or how to confirm a product is actually listed, but these are covered by schema and sibling tools.

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 reinforces that product_id and PAYMENT-SIGNATURE are the key call inputs, but it does not meaningfully elaborate beyond the schema, especially around payment_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?

The description uses a specific verb and object: verify and settle a buyer's x402 payment for a listed composite product and record revenue. This clearly distinguishes it from sibling tools like swarm.research or x402.verify by focusing on settlement and revenue recording.

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 explicitly states the timing and required inputs: call with product_id and PAYMENT-SIGNATURE after the buyer pays. It does not name alternative tools or exclusions, but the sequencing guidance is clear enough for correct invocation.

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 communicate idempotentHint=true and destructiveHint=false, so the safety profile is carried. The description adds one meaningful behavioral side effect: including resource_url and discovery_* catalogs the endpoint in Bazaar. It doesn't cover auth impacts, state changes, or limitations, but it provides enough on top of the annotations for a basic safe invocation.

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

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

Two sentences with no filler. The first states the core action; the second points out the optional discovery path. It is compact, front-loaded, and avoids repeating parameter values already in the schema.

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 12 optional params, 0 required, full schema coverage, an output schema, and non-destructive/idempotent annotations, this description is largely sufficient. It gives the selection context, the core output, and the discovery-related activation pattern. The main gap is not explaining the overall flow relationship to sibling x402 tools, but that is not needed 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 description coverage is 100%, so the agent already gets meaningful parameter meanings, defaults, and examples. The description adds the group-level hint that resource_url plus discovery_* fields work together for Bazaar catalogging, but it does not add detail beyond the schema. This is baseline 3 territory.

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 action and target: 'Build seller-side x402 payment requirements for your own HTTP resource.' This clearly identifies what the tool does and distinguishes it from buyer- or discovery-focused sibling tools like x402.pay_ and_fetch and x402.discover.

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 clearly scopes usage to 'seller-side...for your own HTTP resource' and instructs when to include the discovery_* fields. It does not explicitly name alternatives or say when NOT to use this tool, but the context and the explicit seller-side scoping are clear enough.

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 aspects: readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful behavioral context by identifying the facilitator catalog and the required sequence. There is no contradiction between the description and 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?

The description is two sentences with no filler. The first sentence defines the purpose, and the second explains the workflow position. It is front-loaded and easy to process.

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

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

For a simple, fully-described, optional-parameter discovery tool, the description plus schema and annotations cover invocation well. It could optionally say a bit more about result ordering or catalog scope, but that is not necessary for correct use. A minor gap, not a deficiency.

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 each parameter already has a clear description, default value, and example. The tool description itself does not add parameter-level meaning, which is acceptable because the schema carries the full burden.

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: “Discover paid HTTP APIs in the x402 Bazaar via the facilitator catalog.” It also explains the expected first-step role by saying this tool finds a resource URL to feed into x402.probe and x402.pay_and_fetch, which clearly differentiates it from the related 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: “Call this first to find a resource URL, then x402.probe and x402.pay_and_fetch.” It clearly frames the recommended ordering. It does not enumerate exclusions or alternatives, but the workflow context is strong enough for an agent to orient 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?

The annotations already declare readOnlyHint = true, idempotentHint = true, and destructiveHint = false, and the description does not contradict these. It adds meaningful behavior details by stating the tool also returns facilitators and x402 v2 header names, not just a simple network list. This gives the agent a better sense of what will be present in the response 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?

Two-short sentences carry all the necessary information with no filler. The first sentence states the output scope, and the second sentence orients the selection toward the tools that consume a preferred_network.

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

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

For a simple, read-only, no-required-parameter lookup tool with an output schema, the description provides adequate use-case information and behavior visibility. It might mention what to do after picking a network, but that is not necessary for calling 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?

The only parameter agent_id is already fully described in the schema as an optional agent identity for quota accounting, so schema coverage is 100%. The description does not need to repeat the parameter semantics and generally does not add value beyond the schema for this single parameter; a 3 is the appropriate 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 uses a specific verb ('List') and names the exact resources: supported settlement networks, facilitators, and x402 v2 header names. It clearly identifies what the agent will learn from the tool. It references the paying/building siblings that consume a preferred_network, but it does not explicitly distinguish from every possible sibling such as x402.discover.

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 a concrete usage cue: call when choosing a prefferred_network for x402.pay_and_fetch or x402.build_seller. This is clear context for when the tool is useful, though it does not explicitly state when not to use it or name an alternative lookup 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 handle readOnly=false and idempotent=false, so the description does not need to repeat those. It adds meaningful context beyond the annotations: the operation requires a private key, performs a USDC spend, and is a single combined payment-and-fetch action. It doesn't discuss error or refund behavior, but that level of detail is less critical given the schema and output schema.

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

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

Two sentences, each earning its place: the first states the core action, the second gives prerequisite and the relevant alternative. No filler, no repetition of schema details, and the most important decision point is front-loaded.

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

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

The description covers the essential selection context: the one-call payment-and-fetch behavior, the private-key prerequisite, and the no-spend probe alternative. For a 7-parameter tool with a rich input schema and annotations, this is sufficient for an agent to select and invoke correctly. It could spell out how to pick a network or what can go wrong, but those are delegated to schema and sibling tools without leaving a critical 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 description coverage is 100%, so the schema already documents all seven parameter including url, body, method, headers, agent_id, max_price_usdc, and preferred_network. The description does not add per-parameter meaning beyond the schema; the only extra contextual thing is EVM_PRIVATE_KEY, which is an environment prerequisite rather than a parameter. 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?

Description uses a concrete verb+resource structure: 'Pay USDC via x402 and fetch a protected HTTP resource in one call.' It clearly scopes the action and distinguishes it from the sibling x402.probe by contrasting the paid with the no-spend 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?

Description explicitly states 'Requires EVM_PRIVATE_KEY on this host; otherwise use x402.probe for a no-spend 402.' This names the exact condition and alternative, making both the when-to-use and when-to-avoid crisp.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safe inspection behavior is largely established. The description adds important behavioral context that is not in annotations, explicitly warning 'without spending' and indicating it probes for 'price, network, and payTo'. It doesn't state possible error responses or network dependencies, but annotations plus this disclosure adequately cover core behavioral 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?

Two economically written sentences convey purpose, target behavior, key outputs, and the relationship to a sibling tool. Every phrase earns its place, and the main action is front-loaded so the agent immediately understands what the tool does.

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 probe with a full input schema, rich output schema, and explicit annotations, this description is complete. It explains what will (price, network, payTo), what will not happen (no spending), and when to use it (before pay_and_fetch). An agent has everything needed to call this correctly without opening the schema.

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 parameters' meanings are fully documented in the schema itself. The description adds no parameter-specific detail beyond what the schema already provides, which matches the baseline of 3 for a highly documented schema.

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

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

The description uses the specific verb 'probe' with the resource 'URL' and explicitly defines HTTP 402 PAYMENT-REQUIRED terms, which includes what data is inspected (price, network, payTo). It clearly stands apart from its sibling tools by narrowing the action to a pre-payment inspection step, making the tool's intent unambiguous.

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 explicitly states when to use the tool: 'Use before x402.pay_and_fetch' and what it accomplishes ('inspect... without spending'). It does not explicitly mention cases where the tool should not be used or call out alternative siblings, which keeps this from a 5, but the single-sentence context is clear and actionable.

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 adds some behavioral context by noting the verification is done 'via the facilitator,' which implies an external network call, and places it in the payment flow. It does not go deeper into side effects, account implications, or failure behavior, and the readOnlyHint=false annotation already suggests this operation might not be truly read-only. The description neither contradicts nor fully clarifies that.

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

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

A single, immediately readable sentence. It front-loads the action and then adds the essential lifecycle guidance without unnecessary words. 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?

With schema covering all parameters and an output schema presumably describing the verification result, the description adds the missing workflow context: when to call and what operation it performs. It is complete enough for a straightforward verification tool, though it could mention what happens if the signature is invalid or if the facilitator is unreachable.

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 parameters and their descriptions, including the optional quota-accounting role of agent_id. The description does not need to repeat parameter details and does not add much beyond what the schema covers. This matches the baseline-3 expectation for high schema coverage.

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 a specific verb ('verify') applied to a specific resource ('PAYMENT-SIGNATURE against PAYMENT-REQUIRED terms') and identifies the pathway ('via the facilitator'). It immediately reads as distinct from siblings like x402.pay_and_fetch or x402.discover, so an agent can confidently choose this tool.

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 flow guidance: 'Call after a buyer presents a signature and before releasing paid content.' This tells the agent when in the interaction to invoke it. It does not explicitly mention alternatives or exclusions, but the domain context makes the choice clear, so only a small deduction is warranted.

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