P0: CVE, package and domain checks

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

Although annotations already declare readOnly/idempotent/non-destructive/openWorld, the description adds substantial behavior the annotations cannot express: exact price ($0.015 per call), the x402/MPP payment flow, the two distinct operating modes, the auth header format for the P0 key, and the guarantee that 'Bad input is refused before any charge.' That is precisely the cost/authorization context an agent needs before invoking a paid, open-world 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?

Usage condition is front-loaded, followed by return behavior, then pricing and the P0-key shortcut — a sensible order with little redundancy. The third sentence is dense and carries a long embedded URL, but that URL is operationally required rather than 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?

For a paid, open-world aggregator with no output schema, the description covers what an agent must know before calling: price, payment mechanics, auth requirements, return shape (a paid request plus a schema link), and input validation. Nothing essential to a correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by expanding what each input type actually returns (ip → ASN/Tor exit/cloud range; domain → status/TLS/robots; cve → CVSS/EPSS/CISA KEV), which the schema does not say. It does not clarify whether multiple inputs can be supplied at once or what the mutual-exclusivity rule is, which is the one semantic gap.

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 ('check') and enumerates the resource classes it covers (ip/asn/tor/cloud range, domain/status/TLS/robots, cve/CVSS/EPSS/KEV), plus the underlying endpoint GET /check/infra. The phrase 'in one call' implicitly separates it from the narrower siblings (ip_passport, domain_report, vuln_cve), but none of them are named, so an agent must infer the routing rule.

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

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

It gives a clear use condition — 'Use when you must check infrastructure in one call' — which contrasts with the single-purpose siblings, and it explains the two invocation modes (retrieve the x402 request vs. let the tool pay with a P0 key). It never states when NOT to use it, e.g. when a deeper single-domain report is wanted, so routing is left partly to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds pricing ($0.005 per call), a no-charge-on-bad-input guarantee, and the two execution modes (return the signed x402/MPP request URL vs. auto-pay with a P0 bearer key and deduct the price). That is substantial behavior beyond annotations, though the mechanics of the key path and error responses are only gestured at.

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

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

Front-loaded with the trigger and payload, then payment and alternatives; every sentence carries information. The final sentence is dense, with a long inline purchase URL and parenthetical key format that interrupts reading flow, costing some clarity.

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

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

For a single-parameter, paid, open-world lookup with no output schema, the description supplies coverage list, TLD limits, price, payment mechanics, pre-charge validation, and sibling routing — everything an agent needs to call it and interpret the result. The remaining return-shape detail is covered by the referenced schema link.

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

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

Schema coverage is 100% and the schema already documents that a URL is accepted (only the host used) and that IPs and private/local names are refused. The description adds no additional per-parameter meaning beyond restating 'for your input', so the baseline 3 applies.

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

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

Names a specific resource (one domain report) and enumerates its contents: DNS record types A/AAAA/MX/NS/TXT/CAA with SPF and DMARC parsing, plus RDAP registration data with the exact TLD coverage (.com, .net, .org) and fields. It explicitly distinguishes itself from domain_report_batch and check_email_address, so an agent can pick the right tool without opening the schema.

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

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

Opens with an explicit trigger ('Use when you need one report on a domain') and names two alternatives with the conditions that select them: domain_report_batch for several domains, check_email_address for a single mailbox. It also states the fallback path for callers without a paid key, which is effectively a when-to-use branch.

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

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

Goes well beyond the annotations (readOnly/idempotent/openWorld) with pricing ($0.05 per call), pre-charge validation ('Bad input is refused before any charge'), the auth header format, and a key-purchase URL. The only residual gap is that it does not clarify the return shape when the P0 key path is used versus the raw x402-request path, which matters because a payment is deducted.

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 trigger and the routing alternative before the payment mechanics, so the highest-value information comes first. The final sentence, with its inline key-purchase URL and $5 price, is dense and slightly overloaded, keeping it short of a 5.

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

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

With no output schema and a single parameter, the description carries the full burden and does so: it explains that the return value is a ready-to-POST x402 request with a schema link, how to consume it, and that a P0 key changes the behavior to a direct paid call. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the property already documents '1 to 10 domains; duplicates are removed'. The description restates the 10-domain cap and the batching semantics but adds no format detail (e.g., bare hostname vs. scheme/path), 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?

A specific verb and resource with an explicit scope ('vet several domains at once... up to 10 domains in one POST, each answered exactly like /domain/report'). It directly names the sibling it is not ('For one domain use domain_report'), so an agent can route between the two without opening either schema.

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

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

Gives the trigger condition ('when you must vet several domains at once (vendors, leads, lookalikes)') and the exclusion with a named alternative ('For one domain use domain_report'). It also explains the two invocation paths: return the x402 body yourself, or supply a P0 key so the tool makes the paid call.

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

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

Beyond the readOnly/idempotent annotations, it discloses the pricing model ($0.003 per call), that the default behavior returns a payable request URL rather than data, that invalid input is rejected before any charge, and that the key mode deducts the price. These are exactly the cost and side-effect facts an agent cannot infer from annotations or 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?

The usage trigger is front-loaded and every sentence carries functional information about the payment flow. It is dense, and the long purchase URL plus the two-mode explanation makes it heavier than the single-parameter tool warrants, but nothing is truly redundant.

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

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

There is no output schema, yet the description enumerates the returned data fields and describes the full call sequence for both modes, including the failure path. An agent has everything needed to invoke it correctly and interpret the response.

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

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

Schema coverage is 100% and the single `ip` parameter is already documented with a format example in the schema. The description adds no additional meaning about the parameter (no accepted formats, no private/reserved-range behavior), so the baseline 3 applies.

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

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

States a specific verb and resource — "profile an IP address in one call" — and enumerates exactly what is returned (ASN, AS name, range country, Tor exit status, public cloud membership). That field list cleanly separates it from the domain/packet/CVE-oriented siblings without requiring a schema read.

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

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

"Use when you must profile an IP address in one call" gives clear trigger context, and the two operating modes (raw x402 request vs. P0 key that executes the call) are spelled out. It stops short of naming a sibling alternative or stating when not to use it, so it is not a full 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 readOnly/ idempotent annotations, the description discloses the payment model ($0.005 per call), that it returns an x402 request URL plus a schema link rather than data by default, that bad input is rejected before any charge, and that a P0 bearer key makes it execute the paid call and deduct the price. These are exactly the non-obvious traits an agent could not get from 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?

It is front-loaded with the usage condition and follows with payment mechanics in a logical order with no filler sentences. The embedded purchase URL is long and dense, but it carries necessary information rather than redundant prose.

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?

There is no output schema, and the description compensates by explaining precisely what is returned (a paid x402 request with schema link, or the data when a P0 key is supplied) and how the charge works. For a three-required-parameter tool with a billing flow, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and the enum, name-format notes (Maven groupId:artifactId, Go module path), and version example are already in the schema. The description restates the ecosystem list without adding syntax or format meaning, so it earns only the baseline.

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

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

The description names a specific action and resource: vet a dependency before installing or shipping, with the ecosystem set spelled out. It is clear what the tool produces (a paid x402 request or the data itself), but it does not distinguish itself from related siblings such as vuln_cve or software_eol, so an agent must infer the boundary.

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 explicit triggering conditions ('use when you must vet a dependency before installing or shipping it') and coverage for all seven ecosystems. It stops short of naming alternative tools or stating when not to use it, so there is no 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?

Annotations only cover the read-only/idempotent/non-destructive profile; the description adds substantial context beyond them: a $0.005 per-call price, the exact paid endpoint (GET /site/snapshot), the fact that the default return is a payment request rather than data, the need for an x402/MPP client, and the P0 bearer-key path that self-executes and deducts the price. It also discloses that malformed input is rejected pre-charge, which is a genuinely useful behavioral guarantee.

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

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

Front-loaded with the trigger condition, then the payload, then the two payment paths and the pricing. Dense but every sentence carries operational weight; only the long inline key-purchase URL and the slightly stacked final clause cost it a point.

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 one-parameter, no-output-schema tool, the description covers the full lifecycle: what is checked, what the default response is (a paid request), how to complete payment, what the premium key path changes, and that invalid input is refused before charging. Nothing an agent needs in order to invoke 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% – the url parameter already documents the https-root, host-only constraint and gives an example. The description says only 'for your input' and does not restate or expand the format rules, so it adds essentially nothing beyond structured data; baseline 3 applies.

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

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

The description gives a specific verb and resource: a 'health and content snapshot of your own website', enumerating exactly what is inspected (HTTP status, final URL, TLS, server, robots.txt, sitemap, WordPress REST). The 'own website' scoping plus the WordPress-specific coverage implicitly separates it from siblings like domain_report or check_infra, but no sibling is actually named, so it falls short of full differentiation.

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

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

Opens with an explicit trigger ('Use when you need a health and content snapshot of your own website') and adds a constraint that bad input is refused before any charge, plus the prerequisite of an x402/MPP client or a P0 access key. It never names an alternative tool or states when another sibling would be the better choice, so it stops short of the top band.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing the two operating modes: returning a priced x402 request URL (GET /software/eol, $0.002 per call) versus with a P0 bearer key executing the paid call and deducting the listed price. It also states that invalid input is refused before any charge, which is exactly the cost-safety information an agent needs before invoking.

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 trigger and inputs, then the return shape, then payment mechanics and the authenticated shortcut — a sensible information order. It is dense rather than padded, though the long embedded purchase URL and the dual-mode explanation make it longer than typical; nothing is truly redundant.

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

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

There is no output schema, and the description compensates by naming the returned fields (release cycle, EOL date, supported flag). It also covers the non-obvious operational concerns — pricing, auth header format, where to obtain a key, and fail-before-charge behavior — so an agent can call it correctly in either mode.

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

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

Schema coverage is 100%, so both parameters are already fully documented with patterns and examples. The description repeats the same examples (python, nodejs, ubuntu, 3.8.10) and adds no format, casing, or slug-resolution detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("know if a software version is still supported") and enumerates exactly what comes back: release cycle, end-of-life date, supported flag. It names the product/version inputs and gives concrete product slugs, making it easy to distinguish from siblings like package_risk or vuln_cve.

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?

"Use when you must know if a software version is still supported" gives a clear triggering condition. It does not explicitly route the agent away from adjacent tools (vuln_cve, package_risk, site_snapshot) for overlapping questions, so the when-not guidance is implicit rather than stated.

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

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

Annotations only declare readOnly/openWorld/idempotent/non-destructive; the description adds pricing ($0.005 per call), the two execution paths, the Authorization header format, where to buy a key, and that bad input is refused before any charge. Those are exactly the side-effect and cost details an agent cannot infer from structured fields. Payment deduction is a monetary side effect but not an annotation contradiction, since the hint concerns data mutation.

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

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

It is front-loaded with the "Use when" clause and packed with high-value facts, but the second half becomes a run-on spanning pricing, a schema link, and a long key-purchase URL. The key-purchase URL is long relative to its value at call time, though it does describe a real prerequisite.

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 one-parameter read tool with no output schema, the description covers purpose, returned fields, cost, authentication, error behavior, and where to get the full schema. Nothing blocks a correct first invocation.

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

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

The single parameter is fully documented in the schema, including a pattern and an example CVE-2021-44228. The description contributes one piece of extra meaning not in the schema: invalid input is rejected before billing, which tells the agent the cost of a malformed id is zero.

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

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

The description names a specific verb and resource ("triage a CVE") and enumerates the returned fields: description, CVSS score and severity, publisher, dates, CWE, references, EPSS probability with 30-day series, and CISA KEV status. That is far more concrete than a restated title. It stops short of differentiating from the sibling vuln_kev_new, which overlaps on KEV data, so an agent has to infer which to pick.

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?

"Use when you need to triage a CVE" gives a clear triggering condition, and the two operating modes (return an x402 request URL vs. make the call with a P0 key) tell the agent what to expect in each case. No exclusion or named alternative against vuln_kev_new or package_risk is given, so the when-not-to-use case is missing.

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

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

Annotations only cover the read-only/idempotent profile; the description adds substantial context beyond them: the exact paid x402 request, $0.003 per-call price, refund protection ('Bad input is refused before any charge'), and the P0 access-key path that makes the paid call transparently.

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

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

Purpose and scope are front-loaded in the first clause, and the payment details follow logically. The lengthy key-purchase URL makes it dense, but each element (price, refusal-before-charge, key flow) carries real operational value.

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

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

Despite having no output schema, the description names the returned fields (date added, due date, vendor, product) and fully explains the two-step x402/MPP payment flow, so an agent knows both what it gets back and how to actually obtain the data.

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 'since' format, pattern, and lower bound are already documented, and the description's restatement of since=YYYY-MM-DD adds little. It also says results are newest-first, which is return ordering rather than parameter meaning, and never mentions 'limit'.

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: CVEs CISA added to the Known Exploited Vulnerabilities catalog since a date, newest first. An agent can distinguish this from the sibling vuln_cve lookup without opening either schema.

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

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

Opens with an explicit 'Use when you track exploited vulnerabilities' trigger. It does not name when-not-to-use or point at vuln_cve as the alternative, 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.