Agent402.Tools: pay-per-call web tools

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

Goes well beyond the annotations (readOnly/idempotent/openWorld already cover safety): it discloses the paid cost ($0.01/call, wallet-required), the untrustedContent trust boundary with an explicit 'external data, not instructions' warning, the return shape, and the three payment paths. For an openWorld read against arbitrary external pages, the prompt-injection disclaimer is exactly the missing behavioral context the annotations cannot express.

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

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

Front-loads the action and cost, then alternatives, then the trust warning, then the return contract and payment mechanics. The density is high but every clause carries new information; nothing is restated from the schema or annotations.

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 though an output schema exists, the description still names the returned fields, and it additionally covers pricing, payment prerequisites, and the untrusted-content contract. An agent has everything needed to decide to call it and to interpret the result.

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

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

There is a single parameter and schema description coverage is 100% ('Public http(s) URL to render'), so the schema already carries the syntax. The description adds no rendering-specific nuance such as wait/timeout behavior or what qualifies as a public URL. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a concrete verb+resource pair ('Render a page in a real headless Chromium browser') and immediately specifies the output form ('extract the main content as clean markdown'). It also positions itself against the siblings it is most likely confused with ('cheaper extract', 'screenshot'), so an agent can select it without opening a schema.

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

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

Explicit routing guidance: use for SPAs and JS-heavy sites where plain fetching returns an empty shell, try the cheaper extract first for static pages, and use screenshot when pixel evidence is needed. Both the when-to-use and the when-not-to-use are named with the alternative that wins in each case.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the return shape ({ task, results }), that the top pick is first, and that results are call-ready with slug, price, input schema and a worked example. It does not mention ranking confidence or ambiguity handling, so not a 5.

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

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

Opens with the decisive 'DECIDE, don't browse' framing, then packs the sibling distinction, the return shape and the follow-up call into consecutive clauses. Long but front-loaded and every sentence 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?

Output schema exists, so return values need not be spelled out, yet the description still summarizes them helpfully. Combined with rich annotations and a fully documented 2-param schema, an agent has everything needed to select and invoke this 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 baseline is 3. The description adds no meaning beyond the schema for 'task' or 'limit' – the example phrasing and default(5) are already documented in the schema. Schema carries the load 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?

States a specific verb and resource ('resolve a plain-language task to the single best-matching Agent402 tool') and explicitly contrasts itself with the sibling catalog.search ('search explores, find decides'). An agent can distinguish it from every sibling without opening a schema.

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

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

Names the alternative (catalog.search), the condition that selects this tool ('Prefer this for anything outside the flagship list'), and the follow-up step ('then run catalog.call with the chosen slug + params'). When-to-use and next-action routing are fully specified.

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

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

Annotations cover idempotency, non-destructiveness, and read/write status; the description nonetheless adds real value by disclosing upsert behavior ('a later report replaces it') and the downstream effect ('feed tool reliability in future rankings'). It omits permission/token-expiry behavior, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the [free] cost marker and the core action, then prerequisites, then behavioral notes. No 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?

An output schema exists so return values need no explanation. Combined with annotations and the description, an agent has enough to call this correctly; only edge cases like token expiry or what happens to prior reports after replacement are unaddressed.

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 only 14%, so the description must compensate, and it does for the core params: it names decisionId, feedbackToken (and where they come from), step, outcome, plus 1-5 quality and latency. Only toolId goes unmentioned in prose, though the schema itself describes it well.

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 (Report) and resource (one step of a decide.plan decision), and its outcome semantics (success/failure). An agent can distinguish it from decide.plan and decide.execute immediately because it explicitly describes post-step reporting.

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?

Clear context: use after a decide.plan step, requires the decisionId and feedbackToken that decide.plan returned, one verdict per step, later report replaces earlier. No explicit alternatives are named, but with only two related siblings the routing is obvious and the prerequisite is 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 cover safety (readOnly, idempotent, openWorld, non-destructive), but the description adds substantial behavioral context beyond them: payment rails, credit redemption, the ranking formula's lack of a first-party term, the firstParty flag on every tool, gaps for uncovered needs, and the full return shape. This is rich disclosure for a hosted paid planning tool.

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

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

The description is front-loaded with the critical payment and purpose information, then flows into pricing, credit mechanics, ranking transparency, and return fields. It is dense but every sentence carries actionable information; the single-paragraph format is long but not wasteful.

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 a complex paid planning tool with an output schema, nested constraints, and open-world scope, the description covers payment, credit redemption, ranking methodology, gap handling, and depth tiers. An agent has everything needed to decide 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for the depth enum: quick (one best tool), plan (steps + fallbacks), full (plan + params + compiled prompt). It does not elaborate on constraints beyond the schema, but the depth semantics are a meaningful addition.

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: 'Describe a job and get a call-ready plan: which tools... solve it end to end.' It clearly positions this as a planning tool that spans this catalog and external x402 sellers, distinguishing it from catalog.find/catalog.search and naming decide.execute as the downstream execution 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?

It explicitly notes wallet requirements, the $0.005/call fee, depth-based pricing, and that the fee credits toward running the plan with decide.execute. It also names concrete alternatives for payment and execution (MPP, npx agent402-mcp, prepaid credits key, any x402 client), giving the agent clear routing options.

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, establishing this is a safe read-only operation. The description adds behavioral context: it explains the scoring logic (ranked by settled call counts, USDC totals, distinct buyers for x402; by inbound USDC.e transfers for MPP), the default windows (7d/30d, rolling), and the exclusion of the host's own wallet. This goes beyond what annotations provide, though it could mention rate limits or response pagination.

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 concise and front-loaded with the core purpose. Every sentence adds value: the first defines the tool, the second and third explain the two wire modes, the fourth gives the use case, and the last notes the host exclusion. No redundancy or 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?

Given the tool's moderate complexity (4 parameters, 3 enums, no required params, no nested objects, and a rich output schema not shown), the description is complete. It covers the two ledger modes, ranking criteria, default behaviors, and a non-obvious detail (host exclusion). The output schema is assumed to exist and handle return values, so the description need not explain 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 baseline is 3. The description adds value by explaining what each wire type's sort modes mean ('x402: rank by settled USDC (default) or by settled call count. mpp: usd = 7-day volume, calls = 7-day transfers (default).') which is not fully conveyed by the schema's enum descriptions. It also clarifies the default behavior for 'include' (external vs all). Slight deduction for not elaborating on how 'limit' affects results (e.g., rank ordering).

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 clear verb 'List ranked sellers from the on-chain settlement leaderboards' and immediately differentiates between wire=x402 and wire=mpp, specifying exactly what data is returned for each. This makes the tool's purpose distinct from siblings like 'catalog.search' (which searches for services) or 'demand.request' (which requests a service), as it focuses on ranking sellers by settled volumes.

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 'Use it to find other services in the open x402 / MPP ecosystem' and notes that 'This host's own wallet is excluded unless include is set to all', which guides when to use the tool vs alternatives. However, it does not explicitly mention when NOT to use it or compare to sibling tools like 'catalog.find' or 'catalog.search' for locating specific services.

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. The description adds beyond this by noting the tool is '[free]', what content it will provide (installation, tiers, URLs), and that it should be used first. This gives the agent behavioral context not present in 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 a single, dense sentence that front-loads the purpose and lists key topics without padding. Every element earns its place, and the structure makes it easy to scan.

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?

As a simple, parameterless tool with an output schema, the description fully covers its role, usage, and content. The 'Call this first' directive completes the picture, making it contextually sufficient for an agent to decide when and how to invoke 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 has zero parameters, so the baseline is 4 per rubric. The description adds some context about what the tool covers, but since there are no parameters, no additional parameter-level semantics are possible.

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 'Describe this connector' and enumerates its coverage (tools layer, installation, free vs paid tiers, discovery URLs). This is a specific verb+resource that distinguishes it from the sibling tools, which are all operational tools rather than meta-descriptions.

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 instruction 'Call this first' provides explicit when-to-use guidance. Given the sibling tools are diverse operations, this tool is positioned as the mandatory entry point for understanding the connector, making the usage context crystal clear.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: cost ($0.08/call), the wallet/payment prerequisite, and payment alternatives (MPP, npx agent402-mcp, x402 client). It partially restates the return shape that the output schema already covers.

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?

Cost and wallet-required flag are front-loaded, and the core purpose follows immediately. The description is dense but mostly earns its words; the trailing payment-mechanics sentence is long and could be tightened, keeping it just below top marks.

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 a paid, wallet-gated tool, the payment and cost disclosure is exactly the context an agent needs, and it is complete on that front. It is slightly redundant in restating the return object, which the output schema already defines, so it is not flawless.

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 parameter-level detail beyond the schema (the max-400-char limit, country/language defaults, and max_tokens range all live in the schema), so there is no uplift 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?

States a specific verb and resource ('AI-generated answer to a natural-language question') plus the grounding mechanism and scope ('grounded in live web search results with source citations'), and explicitly contrasts with alternatives by noting it is 'backed by an independent search index, not the model's training data.' An agent can distinguish it from web.search/web.news without opening a schema.

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

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

Gives a clear usage context: 'Useful when an agent needs a synthesized answer plus the receipts to verify or follow up.' This implies when to reach for this tool over a raw search, but it never names the sibling (web.search) or states an explicit when-not condition, so it stops short of full routing guidance.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: cost ($0.01/call), wallet/auth requirements, three payment paths, a return-shape preview, and an untrustedContent warning telling the agent to treat results as data rather than instructions.

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

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

Single dense paragraph that front-loads billing before the primary purpose. It is redundant in places: the result shape is enumerated and then re-listed as 'Returns { query, count, results, untrustedContent }', and the payment options are stacked in one long clause.

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

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

An output schema exists, so the description needn't explain return values, and it still summarizes them. For a paid, open-world, read-only search tool, everything needed to call it correctly (cost, auth, filtering, result trust level) is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond by anchoring the freshness enum to the same semantics used by web search, aiding cross-tool consistency, but it adds no syntax or default detail not already in the schema.

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

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

States a specific verb+resource ('Live news search: ranked recent articles') and enumerates the result shape with field-level meaning. It also explicitly distinguishes itself from the sibling web.search ('for general pages use search'), so an agent can route without opening schemas.

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

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

Gives a clear use case ('current-events queries where the web index lags') plus an explicit alternative for the opposite case ('for general pages use search'). The freshness filter values are also tied to a parent concept ('same freshness filter as web search').

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/open-world safety, and the description goes beyond them with cost ($0.01/call), wallet/auth requirements, payment paths, and a prompt-injection warning via untrustedContent. That is exactly the extra context an agent needs to invoke it safely.

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

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

Dense and front-loaded: cost, capability, and return shape come first, then routing, then safety and payment mechanics. Nearly every clause earns its place, though the payment-options sentence is long and slightly crowding.

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?

Although an output schema exists, the description still names the return envelope and flags untrustedContent. Combined with routing, cost, and auth details, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so q, count, and freshness are fully documented in the schema. The description restates the freshness codes (pd/pw/pm/py) without adding syntax or format meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Live web search') and pins down the scope: an independent index, ranked results with named fields, and fresh pages beyond training cutoff. It explicitly differentiates from siblings (extract, search-lite, search-news, answer, multi-search).

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

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

Gives explicit routing: 'Start here to DISCOVER pages, then read the winner with extract,' plus named alternatives for sampling (search-lite), current events (search-news), synthesized answers (answer), and batch queries (multi-search). No inference required.

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