x402 Toolbox

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds genuinely new behavior: strict bounds-checking of every offset and length, rejection of dirty padding, and a per-call price of $0.003 USDC via x402 on eip155:8453. The only gap is that failure behavior (what error shape a rejected decode returns) is not described.

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 sentences, front-loaded with purpose, then validation semantics, then cost — nothing padded. The first sentence duplicates the title almost verbatim, which is minor redundancy rather than wasted space.

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 decode semantics, strictness, and pricing are covered, and annotations handle the safety profile. With no output schema, though, the description never says what a successful decode returns (the decoded value array? named fields when a signature is used?), which an agent needs 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?

Schema description coverage is 0%, so the description carries the full burden; it does explain that data is the hex payload, types is a list of ABI types, and signature is a function signature with the selector stripped. However it omits the relationship between types and signature (mutually exclusive? which wins?) and the size limits the schema enforces.

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 (ABI-decode calldata, return data, or log data) and names the two input modes (types list or signature). It implicitly separates itself from the sibling abi_encode (inverse) and calldata_decode (generic decoding), but never names an alternative explicitly.

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

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

The description implies the calling context (you have hex data plus known types or a signature) and notes the 4-byte selector is stripped and checked when present. It gives no explicit guidance on when to prefer this over abi_encode or calldata_decode, and does not say what to do when neither types nor signature is supplied.

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, so the description is free to add real behavioral detail: integer range-checking, accepted integer literal forms (decimal or 0x), nesting support, and a concrete price/rail ($0.003 USDC via x402 on eip155:8453). That cost disclosure is genuinely useful and consistent with openWorldHint.

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?

Four tight sentences, front-loaded with purpose then capability then return behavior then cost. No filler or restatement of the 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?

No output schema, and the description does describe the signature-mode return (calldata with selector) while leaving the values-only return implicit as ABI-encoded hex. Combined with full schema coverage and annotations, an agent has what it needs, though the values-mode return could be stated.

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 baseline is 3; the description goes beyond it by clarifying that integers accept decimal or 0x strings and that tuples are supplied as arrays, resolving ambiguity the schema does not.

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 (ABI-encode) and both operating modes: encoding a value list, or producing full calldata when a function signature is supplied. The verb/resource pairing makes it trivially separable from abi_decode and calldata_decode.

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 for both modes — 'with a function signature, returns calldata with the selector' tells the agent when to add the signature. It does not, however, explicitly rule out or route to abi_decode / calldata_decode for the reverse direction.

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 read-only/idempotent/open-world; the description adds substantial behavior the annotations cannot: the selector lookup order, the round-trip re-encode collision filter, the fact that non-matching candidates are still returned, and a per-call price ($0.005 USDC via x402 on eip155:8453). The payment requirement in particular is critical operational context.

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 dense sentences, front-loaded with purpose, then mechanism, then return shape and price. No filler; every clause carries decision-relevant 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 no output schema, the description defines the return payload (function, arguments, other candidates), which is exactly what an agent needs. Minor gap: it doesn't say what happens when no candidate decodes (empty result vs error), which matters for a 1-param open-world lookup tool.

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

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

Schema coverage is 0% for the single `data` parameter, so the description carries the burden; it hints the input must contain a function selector ('looks up the selector'), implying 0x-prefixed calldata rather than bare arguments, but never states the required hex format or length constraints. Partial compensation only.

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 ('Decode unknown transaction calldata') plus the mechanism ('find the function signature and decode the arguments'). The word 'unknown' implicitly scopes it away from abi_decode, which needs a known ABI, so an agent can distinguish the two 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?

Usage is only implied by the word 'unknown' in the title/description; there is no explicit statement of when to prefer this over abi_decode, evm_selector_lookup, or evm_selector. The lookup-fallback chain (built-in list, then openchain/4byte) gives contextual hints about when it works, but no when-not or alternative routing.

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, closed-world, so the safety profile is covered. The description adds real context beyond that: the exact-equivalence semantics (no addresses gained or lost) and a per-call price of $0.003 USDC via x402, which is critical operational information for an agent.

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 short sentences with the purpose and output guarantee front-loaded, and the payment note last. Every sentence carries load; nothing is repeated from the title 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?

No output schema exists, so the description takes on the return-value burden, which it does ('returning the minimal CIDR list that covers exactly the same addresses'). Combined with pricing and annotation-covered safety, nothing an agent needs in order to call this 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% and the schema already documents the array-or-comma/space-separated string forms plus the 1000-item cap. The description adds nothing further about the single `cidrs` parameter, 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 operation (merge/summarize CIDRs) on a specific resource, and pins the exact guarantee: the output covers exactly the same addresses. This cleanly separates it from cidr_split (inverse operation), cidr_contains (membership test), and ip_range_to_cidr (range conversion).

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?

'Route summarization' implies the use case, but the description never says when to prefer this over cidr_split or ip_range_to_cidr, nor any preconditions (e.g. input limits, mixing v4/v6). Implied usage only.

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, non-destructive), and the description adds genuinely new behavior: batch limits of 1,000 IPs and 1,000 CIDRs, IPv4/IPv6 support, non-fatal handling of invalid entries, and per-call pricing via x402. The error-tolerance and cost disclosures are exactly the kind of context structured fields cannot convey.

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 compact sentences: what it does first, then operational limits and error behavior, then price. Every sentence carries information an agent needs, with no filler or repeated title text beyond the lead.

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 explains the return shape (per-IP list of all matching ranges) and how failures surface (invalid entries reported, not fatal). Combined with limits and pricing, an agent has everything needed to call and interpret results.

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 declares maxItems 1000, maxLength, and the array-or-delimited-string acceptance, so the description's restatement of the 1,000 limit is largely redundant. The only added semantic is IPv4/IPv6 support, which is not a per-parameter detail; baseline 3 fits.

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 operation — checking IPs against CIDR ranges and returning, per IP, every matching range — with both resource types named. This is clearly distinguishable from siblings like cidr_aggregate, cidr_split, or cidr_info without opening any 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?

The parenthetical '(allowlist / blocklist check)' gives a concrete usage context that tells an agent when to reach for this tool. It stops short of naming alternatives (e.g., cidr_info for range details) or stating when not to use it, so it lands at a clear but non-exhaustive 4.

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, closed-world, so the safety profile is covered; the description earns credit by adding two things annotations can't express — the $0.003 USDC x402 payment requirement (with chain id) and the normalization note that it flags when the input had host bits set. It stops short of explaining output format or error behavior, but that is a minor gap given the free-standing read-only profile.

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: the first fronts the purpose and the enumerated results, the second carries the single caveat and pricing. No filler, no repetition of the title, and no sentence that could be dropped without losing 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 no output schema, the description must signal return values and it does so by listing the computed fields, which is exactly what an agent needs to decide whether to call it. The only omission is that the shape of the response (flat object vs. text) is left unstated.

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?

Only one parameter and schema description coverage is 100%, with concrete examples (10.0.0.0/22, 2001:db8::/48) already in the schema. The description's mention of 'IPv4/IPv6' and the host-bits note adds a little semantic value but nothing about accepted formats beyond what the schema carries, so this sits at the baseline.

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

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

States a specific verb+resource ('Subnet calculator for an IPv4/IPv6 CIDR block') and itemizes exactly what it computes. The enumerated outputs (network/broadcast, first/last usable host, netmask, wildcard, counts, class/scope) differentiate it from siblings like cidr_split and cidr_aggregate, which also take CIDR input.

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?

Usage is only implied: the enumerated outputs make it clear this is the 'inspect one block' tool versus cidr_split or cidr_aggregate, but no sibling is named and no when-to-use/when-not guidance is given. An agent must infer the routing from the output list.

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, closed-world, so the safety profile is covered. The description adds genuinely new context: a 4,096-per-call cap, that a total count is returned, and that payment of $0.003 USDC via x402 on eip155:8453 is required — a material operational detail no structured field conveys.

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 compact sentences, front-loaded with the core action, then scale/response, then cost. No filler; the pricing sentence is dense but necessary.

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?

No output schema exists, and the description compensates by mentioning the subnet list plus total count and the per-call cap. Combined with annotations and the paywall note, an agent has nearly everything needed 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 0%, so the description must compensate. It explains cidr and newPrefix indirectly ('subnets of a given prefix length inside a parent block') and the limit cap ('up to 4,096 per call'), but omits the default limit of 256 and the valid prefix range, leaving partial gaps.

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?

Specific verb+resource: 'Split a CIDR block into smaller subnets', reinforced by a concrete example (/16 into /24s). It does not explicitly distinguish itself from cidr_aggregate or cidr_info, though the split semantics are inherently distinct from aggregation.

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 example clarifies the intended operation, but there is no explicit statement of when to use this versus cidr_aggregate (the inverse) or cidr_info, nor any note about prerequisites such as newPrefix needing to be longer than the parent prefix.

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, so the safety profile is covered. The description adds substantive context beyond that: it lists the parsing inputs, the exact returned fields (hex, RGB, HSL, relative luminance, contrast ratio, AA/AAA verdicts), and — unusually and valuable — the per-call price and payment rail (x402, $0.003 USDC on eip155:8453), which an agent must know before invoking a paid endpoint.

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 sentences, front-loaded with the core capability, then the return shape, then the conditional contrast mode, then pricing. Nothing is redundant and no sentence merely restates the 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?

Only two simple non-nested parameters and no output schema, so the description carries the return-value burden and does so completely: it enumerates the returned fields and the conditional WCAG verdicts. Combined with annotations, an agent has everything needed to call it correctly and understand the cost.

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 only 50% (`color` has no schema description), so the description must compensate — and it does, explicitly naming the accepted formats (hex, rgb(), hsl(), CSS names) that `color` parses. The optional `against` semantics are covered both by the schema field description and by the 'second colour' clause in the description.

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

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

States a specific verb set and resource: colour conversion across hex/RGB/HSL plus a WCAG contrast computation. It enumerates the accepted input syntaxes and the returned fields, which immediately distinguishes it from any other sibling (currency_convert, unit_convert operate on different domains).

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 conditional usage: 'With a second colour, returns the WCAG 2.x contrast ratio and AA / AAA pass/fail', which tells the agent exactly when to supply the optional `against` parameter rather than the single-colour conversion mode. It does not name a when-not case or sibling alternative, but none of the other 50+ siblings overlap this domain.

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 establish the safe, read-only, idempotent profile, so the bar is lower. The description adds real context beyond that: the parsing semantics (Vixie OR rule, macros), DST-awareness, a hard cap of 50 results, and an explicit per-call price ($0.003 USDC via x402 on eip155:8453) that 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?

Two tight sentences, front-loaded with the purpose and then capabilities plus pricing. Dense but every clause earns its place; the pricing tail is slightly tacked-on but necessary.

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?

No output schema exists, yet the description states what comes back (next N run times in UTC and the given IANA zone, DST-aware), which covers the return contract. Combined with pricing and parse-feature disclosure, an agent has enough 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 only 25%, so the description must carry meaning and it largely does: it explains the expression format (5-field, lists/ranges/steps/names/macros), the output time zone semantics for tz, and the count ceiling of up to 50. Only 'from' is left to the schema's one-line description, which is adequately covered there.

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 specific verbs (explain, list) plus the resource (cron expression / next run times) and scope (any time zone). It is trivially distinguishable from the nearest siblings like time_convert and time_diff, which do not parse cron schedules.

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?

Usage is implied by the purpose – an agent can infer it should call this for cron parsing/scheduling questions – but there is no explicit 'use when' or 'use instead of X' guidance. With no cron-specific sibling to route against, the omission is minor but still leaves context 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 (read-only, idempotent, non-destructive), and the description adds important context beyond that: quoting rules, delimiter auto-detection, return shapes, type inference, a 50,000-row limit, and the x402 payment requirement. This is a strong disclosure of behavior an agent would not get from annotations alone.

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 and appropriately sized, moving quickly from the core operation to quoting, delimiters, return shape, limits, and pricing. The opening phrase repeats the title, which is minor redundancy, but the remaining sentences earn their 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 no output schema, the description correctly explains the return shape as an array of objects or arrays. It also covers parsing behavior, row limits, and payment requirements. It is complete enough for correct invocation, though it could say more about the header and inferTypes parameters explicitly.

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 0%, so the description must carry parameter meaning. It explains delimiter auto-detection, type inference, and header-row behavior, which maps well onto the delimiter, inferTypes, and header parameters. The csv parameter is obvious from context, though the exact meaning of header=false is only implied rather than stated.

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 conversion operation with the resource (CSV/TSV to JSON) and details its parsing behavior. It does not explicitly differentiate itself from the inverse sibling json_to_csv, so it falls short of the full sibling-routing clarity required for a 5.

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?

Usage is implied by the feature description and row limit, but there is no explicit guidance on when to use this tool instead of json_to_csv or other JSON utilities. The agent must infer the appropriate use case from the tool name and behavior.

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, non-destructive behavior; the description adds meaningful context beyond them: ECB sourcing, cross-rate calculation via EUR, return fields of rate/date/source, the non-trading-quote caveat, and a $0.005 USDC per-call x402 price.

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 core purpose and source, then adds only useful constraints and pricing. Every sentence earns its place without padding.

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, but the description states what is returned: the rate, its date, and source. It also covers data source, currency coverage, pricing, and the reference-rate caveat; the remaining gap is detailed parameter 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?

With schema description coverage at only 33%, the description partially compensates by listing supported currencies and mentioning the amount and cross-rate method. However, it never explains the from/to code format, the comma-separated or "all" behavior of to, or the default amount.

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?

Opens with a specific verb and resource: converts currency amounts using official ECB euro reference rates. It names the data source and 30-currency scope, which clearly distinguishes it from generic conversion siblings like unit_convert.

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 frames the use case as reference-rate conversion rather than trading quotes, giving an important usage boundary. It does not explicitly name alternatives such as unit_convert or state exclusions, so it falls 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 already cover read-only, idempotent, open-world and non-destructive traits, and the description adds real context on top: the DNS lookup target, the fallback to the organizational domain when no record exists at the subdomain, and the per-call price of $0.005 USDC via x402 on eip155:8453. It stops short of describing the response shape or behavior on NXDOMAIN/timeout.

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: what it reads, what it parses, and what it flags, with cost appended last. Nothing is repeated from the title and no sentence is 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?

With no output schema, the description accepts the burden and lists the parsed tags and weakness categories, plus payment requirements. It leaves the concrete return structure and failure modes unspecified, which keeps it just below complete for an open-world network tool.

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

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

Schema coverage is 0%, so the description must carry the single 'domain' parameter — and it does, explaining the query is against '_dmarc.<domain>' and that a bare subdomain will fall back to the organizational domain. That is meaningfully more than the schema's bare string with maxLength 300.

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 (DMARC record check plus parsed policy) and immediately narrows scope to '_dmarc.<domain>' with organizational-domain fallback. The enumerated tags and weakness list make it unmistakably different from dns_spf or email_security.

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

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

The description implies its use case (auditing a domain's DMARC posture) but never says when to pick it over the sibling tools dns_spf or email_security, nor any prerequisites. Usage is inferable 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 already cover readOnly/openWorld/idempotent/non-destructive, so the description's added value is the return shape (answers with TTLs, DNS status, DNSSEC validation flag), the TXT-string-joining normalization, and the payment requirement ($0.005 USDC per call via x402, eip155:8453). The cost/payment disclosure is meaningful context an agent needs before calling, though pagination/truncation and failure behavior are unstated.

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 is front-loaded in the first sentence, followed by supported types, return shape, and price — a logical order with little waste. The 16-type enumeration duplicates the schema enum and is the one stretch that doesn't fully earn its space.

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 describing return contents (answers with TTLs, status, DNSSEC validation). Combined with the payment terms and the 100%-covered input schema, an agent has everything needed to call it correctly and understand the cost.

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 enum already lists every record type, so the description's record-type enumeration largely restates structured data. It adds no format or syntax detail for the 'name' parameter beyond what the schema provides (IDN allowed, maxLength 300, example).

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 ('DNS lookup'), the transport ('DNS-over-HTTPS'), and scope ('any record type'), which is exactly what separates it from the specialized siblings dns_mx, dns_spf, dns_dmarc and dns_reverse. An agent can tell from the description alone that this is the general-purpose resolver.

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 is implied by 'any record type' and the record-type enumeration, which suggest this is the catch-all resolver versus the specialized siblings, but the description never explicitly says when to prefer dns_mx, dns_spf, dns_dmarc or dns_reverse over this tool. No exclusions or prerequisites are 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 already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: RFC 7505 null-MX detection, implicit A/AAAA fallback, provider detection, and the $0.005 USDC x402 payment requirement (eip155:8453) — cost and payment prerequisites are exactly the kind of context 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?

Two sentences, both front-loaded with substantive content; the feature enumeration in the second sentence and the price note each carry information an agent cannot get from annotations or schema. 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?

With no output schema, the description does explain what comes back — priority-sorted MX records, null-MX and implicit-MX cases, provider label — plus the payment model. It is close to complete; a note on error behavior for nonexistent domains would close the remaining 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?

Only one parameter (domain) at 100% schema description coverage, so the schema already does the work. The description adds nothing about the domain argument (e.g., IDN handling, subdomains), leaving this at the baseline.

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

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

States a specific verb+resource: retrieve the MX records of a domain, sorted by priority, with provider detection. This is clearly distinguishable in content from siblings like dns_lookup or email_security, but the description never explicitly contrasts itself with them.

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?

No explicit when-to-use or when-not-to-use statement, and no mention of dns_lookup or email_security as alternatives. The described output (MX priority, null-MX, provider) implicitly signals the intended use case, which is only minimal 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the FCrDNS semantics (whether the PTR hostname resolves back to the same IP) and a concrete per-call price of $0.005 USDC via x402 on eip155:8453, which is critical for an agent deciding whether to invoke a paid endpoint.

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 short sentences, front-loaded with the operation and then the payment constraint. The opening sentence duplicates the title verbatim, which is a small amount of redundancy but not enough to hurt readability.

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 does explain the two things returned: the PTR name and the FCrDNS result. It stops short of describing the output shape (field names, behavior when no PTR exists), which is the only remaining gap for a single-parameter paid lookup.

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% for the single `ip` parameter, and the description only restates that it is an IPv4 or IPv6 address. No additional meaning (accepted formats, whether hostnames or CIDRs are rejected) is contributed 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: PTR lookup of an IP address plus a forward-confirmation check. The PTR/FCrDNS framing clearly separates it from the A/AAAA-oriented dns_lookup sibling, though it never names an alternative explicitly.

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?

Usage is implied by the resource (reverse lookups of an IP) rather than stated. There is no guidance on when to prefer this over dns_lookup or ip_info, and no note about which IP families or edge cases (private ranges, no PTR record) are handled.

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, open-world, non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: recursive include:/redirect= expansion, counting DNS-querying mechanisms against the RFC 7208 limit of 10, and — critically — that each call costs $0.008 USDC via x402 on eip155:8453, which the annotations do not convey.

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

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

Two dense sentences with the capability and the flagged-problem list front-loaded and payment terms last. The only waste is the opening phrase repeating the title verbatim rather than adding a verb like 'Checks an SPF record by...', a minor redundancy.

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

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

With no output schema, the description does the work of describing return content: include tree, lookup count vs the limit of 10, ip4/ip6 ranges, and the enumerated problem classes (multiple records, +all, ?all, missing includes, ptr, loops, void lookups). It is short only on failure modes — no-SPF-record or payment-failure behavior — which an agent would want to know.

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?

Only one parameter (domain) with 0% schema description coverage; the description implies the domain is the lookup target but never states format constraints (apex vs subdomain, no scheme/path) or the 300-char max. With a single obvious parameter the baseline of 3 is appropriate, though a clarifying clause would be cheap.

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 and verb ('SPF record check') and immediately enumerates the deliverables: full include tree, DNS lookup count, problems. An agent can tell this apart from dns_lookup, dns_dmarc, and email_security without opening any 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?

Usage is implied by the tool's specialization (SPF-only, RFC 7208 lookup counting), but there is no explicit when-to-use guidance, no mention of when to prefer dns_lookup or email_security instead, and no stated prerequisites such as the domain needing to exist.

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, so the safety profile is covered. The description still adds material context beyond them: the IANA bootstrap resolution step, the exact return payload, and the paid-access model ($0.01 USDC via x402 on eip155:8453), which is essential to know 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?

Three sentences, front-loaded with what is returned and followed by purpose and price. The opening clause duplicates the tool title almost verbatim, which is slight waste, but nothing else is padding.

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

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

With no output schema, the description usefully enumerates the returned fields, which is the right call. What is missing is failure behavior (unknown TLD, domain not found, bootstrap failure) and whether results are cached — relevant for a paid, network-dependent 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 0% for the single required 'domain' parameter, so the description must carry the meaning. It only implies the parameter via 'for the TLD' and adds nothing about accepted format (bare FQDN vs URL, IDN, subdomains, maxLength 300). Adequate but leaves a real 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 names a specific verb and resource ('Looks up the registry RDAP server for the TLD') and enumerates exactly what fields come back: registrar, registration/expiry dates, age, EPP status, nameservers, DNSSEC. It is clearly distinct from dns_lookup-style siblings, though it never explicitly contrasts itself with them.

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 offers one usage cue ('Useful for fraud and phishing checks (young domains)'), which points an agent at a legitimate scenario. There are no exclusions, no alternatives named (e.g. dns_lookup, web_metadata), and no guidance on what to do when a TLD has no RDAP server.

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 readOnly/idempotent/non-destructive, so the description's job is to add what they can't — and it does: it discloses the return shape (0-100 score, letter grade, prioritized fixes) and, critically, the x402 payment requirement of $0.02 USDC per call on eip155:8453. Undisclosed are failure modes (invalid domain, missing records) and whether partial results are still billed.

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 checks, then return values, then price — a sensible order with no filler. The only waste is the first clause, which restates the title verbatim before the more informative sentence begins.

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

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

With no output schema, the description correctly supplies the return contract (score, grade, prioritized fixes) and the payment precondition. For a two-parameter, read-only audit tool, an agent has everything needed to call it and 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?

Schema description coverage is 50%: dkimSelectors is documented in the schema, while the required 'domain' parameter carries only a maxLength. The description's mention of 'DKIM keys at common selectors' usefully implies a built-in selector list that dkimSelectors appends to, but no format detail (bare domain vs FQDN vs IDN) is added for the required parameter.

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

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

The description names a concrete verb and resource ('audits a domain's mail setup') and enumerates exactly what is inspected: MX, SPF tree and lookup count, DMARC policy, DKIM selectors, MTA-STS, TLS-RPT, BIMI. It implicitly separates itself from the granular siblings (dns_mx, dns_spf, dns_dmarc) by framing this as one aggregate call, but it never names those siblings explicitly.

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 phrase 'One call audits a domain's mail setup' hints that this is the aggregate alternative to the per-record DNS siblings, but it is inference rather than instruction. There is no explicit when-to-use/when-not statement and no named alternative, so guidance is only implied.

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: discloses that no mail is sent, lists the exact check pipeline, names the four verdict outcomes (deliverable, risky, undeliverable, invalid), and — critically — states the payment requirement and rate ($0.005 USDC per call via x402 on eip155:8453). The x402 pricing/auth detail is exactly the kind of context annotations cannot convey.

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 dense sentences, front-loaded with the check list and verdict categories with no filler. Minor waste: the first sentence is a near-verbatim repeat of the title field, and the check list is stated twice (once as a summary, once in the detailed 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?

With no output schema, the description usefully names the verdict vocabulary and the checks performed, so an agent knows what comes back conceptually. It stops short of describing the response shape (per-check booleans, suggested correction field for typos, normalized domain value), which would fully close the gap given there is no output 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?

Only one parameter exists and the schema gives it zero description coverage (just type string, maxLength 320). The description never says what input form is accepted — bare addr-spec vs display-name form like 'Foo <a@b.com>' — nor does it mention normalization behavior applied to input, so it adds little beyond 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 (an e-mail address check) and enumerates exactly what is checked: RFC syntax, IDN normalization, MX/A records, null-MX, disposable lists, role accounts, free providers, typo suggestions. This clearly separates it from siblings like dns_mx (MX only) and email_security (domain policy records).

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?

"Validates an address without sending mail" gives clear context that this is a non-invasive, no-email-sent check with a bounded set of criteria. It does not, however, explicitly route the agent between this and siblings such as dns_mx or email_security, so no exclusions or named alternatives are provided.

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, so the safety bar is low. The description still adds genuinely useful behavior: 'Reports invalid UTF-8 instead of guessing' (error semantics) and the x402 pricing/metering model, which an agent needs to know before calling. It does not say what a return value looks like, but no output schema exists and that gap is minor for an encode utility.

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 capability and kept to three sentences with no filler. There is mild redundancy: sentence one restates the title and sentence two repeats the same encoding list, so one sentence could be trimmed.

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 pure, idempotent transform tool with full enum schemas and annotations, this covers the encodings, escaping modes, error behavior, and cost. Missing only the default direction and input-size ceiling, which would round out an otherwise complete definition.

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 0%, so the description must carry parameter meaning. It does supply the semantic mapping the enums alone don't: 'to=url' means url-encode and 'from=url' means url-decode, and similarly for html-escape/unescape — that is real added value. It omits the defaults (to=base64, from=utf8) and the 1 MiB data limit, which the schema also leaves undocumented.

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 (re-encode/convert) plus the full set of supported encodings, and the escaping operations. An agent can immediately tell this apart from hash, hmac, url_parse or text_transform.

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?

Usage is implied by the enumeration of operations, but there is no explicit when-to-use or when-not-to guidance relative to neighbors like url_parse (which parses a URL into components) or hash/hmac (which digest rather than encode). The reader must infer the boundary.

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 (readOnly, idempotent, openWorld, non-destructive), it discloses that it reads the ENS registry on Ethereum mainnet, that reverse results are verified by re-resolving the name forward, and that each call costs $0.005 USDC via x402 on eip155:8453. That cost/auth and verification context is genuinely additive. It doesn't say what happens with zero parameters (both are optional per the schema) or what the response looks like for an unregistered name.

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 dense sentences, front-loaded with purpose before inputs and payment details. The opening clause duplicates the tool title almost verbatim, which is a small redundancy, but no sentence is 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?

With no output schema, the description does the work of sketching return values (address, resolver, namehash; primary name) plus chain and pricing. The remaining gap is failure/edge-case behavior for names that don't resolve or an address with no primary name, but an agent could reasonably invoke this correctly from what's given.

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 0%, so the description carries the burden and does so for both parameters: it explains what each input yields and gives a format example for "name" (vitalik.eth). It does not state mutual exclusivity or behavior when both/neither are supplied, which matters given required=[] with two optional 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 names a specific verb and resource and covers both directions explicitly: name to address (plus resolver and namehash) and address to primary name via reverse resolution. An agent can distinguish this from dns_lookup and evm_address without opening the schema, since the ENS registry and verification semantics are stated up front.

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 concrete selection guidance: pass "name" (vitalik.eth) to get an address, pass "address" to get the primary ENS name. That is a clear conditional for the two modes. What's missing is a stated preference against the similar-looking siblings (dns_lookup, evm_address) and any note about precedence when both parameters are supplied.

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 real value beyond annotations: which checks run (0x + 40 hex, mixed-case EIP-55 checksum, typo flagging), what is returned (checksummed, lowercase, zero-address flag), and the x402 payment model ($0.003 USDC on eip155:8453). However, 'No network access' directly conflicts with openWorldHint=true in the annotations, creating confusion about whether the call reaches external systems. Per the rubric, a description that contradicts annotations is penalized heavily.

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?

Five short, front-loaded statements: purpose, validation performed, return shape, network behavior, and cost. Nothing is redundant and the cost/constraint details come after the primary purpose.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it also discloses the payment requirement and no-network behavior. For a single-parameter pure validator, an agent has everything needed 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?

There is one required parameter with 0% schema description coverage, so the description must carry the burden — and it does partially, by stating the accepted format ('0x + 40 hex'). It never explains why the schema permits up to 64 characters, so an agent cannot tell whether non-checksummed, non-prefixed, or longer inputs are tolerated.

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 ('Validate an EVM address') plus the concrete output (EIP-55 checksum form), which cleanly separates it from siblings like ens_resolve and evm_verify_message. An agent can identify the 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?

Gives clear operating context — it performs format + checksum validation and needs 'No network access' — which implicitly distinguishes it from resolution/network tools such as ens_resolve. It does not explicitly name alternatives or state when not to use it, so it stops 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?

Annotations already declare read-only, idempotent and open-world behavior, so the description isn't burdened with safety. It still adds real context the annotations don't: the price of $0.005 USDC per call via x402 on eip155:8453, and the fact that values are read at the latest block, which tells the agent about freshness.

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 the purpose front-loaded, followed by output shape and pricing. Dense but nothing is wasted, though the parenthetical about decimals/symbol makes the second sentence heavy.

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

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

With no output schema, the description usefully discloses the return shape (raw plus formatted values with decimals and symbol) and the billing cost. It stops short of covering failure modes such as unsupported chains or invalid token addresses, which matters for a paid, open-world call.

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

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

Schema coverage is 67% and already documents chain options and the tokens array. The description adds the useful cap of 'up to 10 ERC-20 tokens' and clarifies that the chain is user-chosen, but says nothing about the required address format or the string-vs-array flexibility of tokens.

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+resource: reading native coin and ERC-20 token balances for a given address on a chosen chain. That is clearly distinct from siblings like evm_token or evm_contract by resource type, though no sibling is named explicitly.

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?

Usage is implied (you need balances for an address, so call this), but there is no explicit when-to-use/when-not guidance, no mention of prerequisites beyond payment, and no pointer to an alternative such as evm_token for token metadata.

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, so the bar is lower, and the description still adds genuinely useful context: a $0.005 USDC x402 price on eip155:8453, and the concrete set of proxy standards detected including legacy ZeppelinOS (USDC). It stops short of describing response shape or failure modes (e.g. what happens for an address with no code on an unsupported chain).

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 core question, then capability detail, then pricing – a sensible ordering with no filler. The only waste is the near-verbatim repetition of the title as the opening clause, which costs a few tokens without adding 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 no output schema, the description steps in to name the returned fields (EOA vs contract, code size, hash, proxy slots, native balance, nonce) and the payment requirement, which is enough to call it correctly. Missing only error/edge-case behavior and multi-chain semantics for chains without code.

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 50%: `chain` already has its allowed values documented inline and `address` has a regex pattern, so the schema carries most of the weight. The description adds only the loose phrase 'on a chain' and does not explain the address format, chain-id fallback, or default behavior, so it neither compensates nor detracts.

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?

Opens with a concrete question the tool answers ('Is an address a contract or a wallet?') and then enumerates the specific resources it inspects: bytecode, code size/hash, EIP-7702 delegations, EIP-1167 minimal proxies, EIP-1967 implementation/admin/beacon slots. This clearly separates it from siblings like evm_address, evm_balance and evm_token, which don't inspect bytecode.

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 framing question implies when to reach for it (classifying an address), but there is no explicit when-not guidance and no routing against siblings. Notably it also returns native balance and nonce, overlapping evm_balance, without saying which tool to prefer for balance-only lookups.

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 read-only/idempotent/non-destructive profile, and the description goes further by disclosing the exact payload contents and — importantly — that each call costs $0.003 USDC via x402 on eip155:8453. That cost disclosure is genuine behavioral context an agent needs before invoking. It stops short of stating data freshness, caching, or what happens with unsupported chains.

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, front-loaded with purpose and then return contents and price. Every clause carries information, though the opening clause duplicates the title verbatim rather than extending it.

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

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

With no output schema, the description fully compensates by listing the returned fields (block number, base fee, priority fee, gwei price, 21k-transfer and 65k-ERC-20 costs) and the payment model. Nothing an agent needs to call this correctly is missing for a single-parameter read tool.

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

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

Schema coverage is 100% and the single `chain` parameter already enumerates every accepted value plus the chain-id alternative, so the description adds nothing parameter-specific. Baseline 3 applies when the schema fully carries parameter meaning.

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

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

The description names a specific resource (gas price, base fee, priority fee) and scope (EVM chains), and it clearly occupies a niche none of the evm_* siblings fill (balance, tx, token, units, selector). An agent can tell immediately what this tool produces 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?

Usage is only implied — an agent infers 'call this when you need gas/fee data'. There is no explicit when-to-use framing, no mention of alternatives, and no statement about when this is unnecessary (e.g. historical fee queries are out of scope).

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, non-destructive, and open-world status. The description adds meaningful context beyond those: normalization rules (parameter names dropped, uint expanded, tuples/arrays handled), no network access, and the x402 payment requirement with price and chain.

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 efficient sentences, front-loaded with the core purpose and followed by normalization behavior and payment context. Every sentence earns its place for an agent deciding whether and how to call 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?

For a one-parameter computational utility, the description says what it returns (4-byte selector, 32-byte topic), how input is normalized, that it is offline, and what it costs. Combined with annotations, nothing essential is missing even though there is no output 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 coverage is 100% and the schema gives an example signature. The description adds value beyond the schema by explaining how the signature is normalized before hashing, which is directly relevant to the single required parameter.

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: computes the function selector and event topic from a Solidity signature, and enumerates normalization behavior. It does not differentiate from the sibling evm_selector_lookup, so an agent cannot tell from the description which one to use.

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?

Usage is implied by the purpose: when you have a Solidity signature and need its selector/topic. There is no explicit when-to-use or when-not guidance, and the presence of the sibling evm_selector_lookup makes the lack of differentiation a real gap.

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 open-world behavior, but the description adds material context: public openchain database with 4byte.directory fallback, verified-contract signatures returned first, and a $0.005 USDC x402 charge on eip155:8453. This is exactly the kind of behavioral and payment detail an agent needs before 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?

Three sentences, front-loaded with the action and formats, then source and ordering, then price. Every sentence carries operational value with 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?

For a single-parameter read-only lookup with rich annotations and no output schema, the description is complete: it explains the lookup source, fallback behavior, result ordering, accepted input formats, and x402 payment requirement. 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%, so the baseline is 3, but the description adds useful format detail beyond the schema: selectors are 0x + 8 hex and event topics are 0x + 64 hex, up to 20 items. The schema already covers array/string and comma separation, so this is a meaningful but not exhaustive enhancement.

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: reverse-look up 4-byte selectors and 32-byte event topics to signatures. The word "reverse" distinguishes it from the forward-signature sibling evm_selector, and the scope is clear 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?

The usage context is implied: use this when you already have selectors or event topics and need candidate signatures. However, it does not explicitly name when-not-to-use cases or the alternative evm_selector for forward lookups, nor does it state prerequisites beyond the x402 price.

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 open-world behavior, so the description only needed to add value — and it does: it discloses that the supply is formatted using the token's decimals, that bytes32 name responses are handled, and that each call costs $0.005 USDC via x402 on eip155:8453. It stops short of describing failure modes (non-ERC20 or non-verifying contracts) or return shape.

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, front-loaded with the resource and followed by implementation and cost details. Minor redundancy: the opening sentence duplicates the tool title verbatim, which costs a little space without adding 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?

For a two-parameter read-only lookup with no output schema, the description covers what is returned (name, symbol, decimals, formatted total supply), how it is obtained (direct contract reads, bytes32 handling), and the cost model, which is enough for an agent to call it confidently.

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 50%: `chain` is documented with its allowed values and `address` is constrained by a regex pattern, but the address parameter has no prose explanation. The description only implicitly reinforces 'the chosen chain' and the token-contract nature of the address; with coverage at 50% it does not fully compensate.

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 (ERC-20 token metadata) and the exact on-chain functions read (name, symbol, decimals, totalSupply), plus the chain scoping. Distinguishable from siblings like evm_balance (native balance), evm_contract (arbitrary calls) and evm_units (unit conversion).

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?

Usage is implied by the resource (fetch token metadata from a contract address), but there are no explicit when-to-use/when-not rules or pointers to alternatives such as evm_contract for non-standard tokens. The x402 pricing note is the only operational guidance added.

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/openWorld annotations, the description discloses the data source (public RPC), the fact that the receipt is also fetched, the token formatting behavior (decimals/symbols), and a per-call price with payment rail ($0.01 USDC via x402 on eip155:8453). Cost and source disclosure are exactly the kind of operational context annotations cannot convey.

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, front-loaded with purpose before detail, and every clause carries substantive content (scope, source, output fields, price). The second sentence is a long comma-chained list, but it is scannable and does not pad with marketing language.

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

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

With no output schema, the description must describe return contents — it does so thoroughly, covering status, fee, method decoding, and transfer events with formatting details. The main omission is that chain selection and the supported-chains list live only in the schema, and failure modes (nonexistent hash, unsupported chain) go unmentioned.

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 description never mentions either parameter. The `chain` field has schema documentation, but `hash` — the only required parameter — has no description in either the schema or the prose, leaving the agent to infer its purpose from the pattern alone. At 50% schema coverage, the description does not compensate for the 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?

States a specific verb and resource ('Explain an EVM transaction') and enumerates exactly what the explanation covers: status, fee, decoded method, ERC-20/721 transfers. This clearly separates it from siblings like evm_contract, evm_balance, or evm_gas, which fetch other data for the same chain family.

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?

Usage is implied by the required transaction hash and the listed outputs, so an agent can infer it's for post-hoc inspection of a known tx. However, no sibling is named as an alternative and there is no explicit when-not guidance (e.g., use evm_contract for contract metadata, evm_gas for fee estimation).

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 (readOnly, idempotent, non-destructive, openWorld), the description adds key behavioral details: exact integer arithmetic with no floating-point rounding, refusal of conversions that would drop digits, and a specific per-call price via x402. These are material facts an agent needs before invoking the 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 short and front-loaded, with the core purpose first, then behavioral detail, then pricing. The opening sentence largely repeats the title, which is slightly redundant, but the remaining content is efficient.

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 low-complexity read-only conversion tool with no output schema, the description is sufficiently complete: it covers supported units, precision behavior, refusal semantics, and cost. Nothing critical 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 description coverage is only 33%, so the description must compensate. It does by explaining the unit/decimals space for from/to (wei, gwei, ether, or 0-36 decimals such as 6 for USDC) and the exactness constraint on the value, though it does not clarify defaults or value formatting beyond 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?

The description states a specific verb and resource: exact conversion of amounts between wei, gwei, ether, or any token decimals. It clearly distinguishes itself from general sibling tools like unit_convert and currency_convert by naming crypto-specific units and exact integer arithmetic.

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

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

The description implies when the tool applies (crypto unit conversions and token decimals 0-36), but it does not explicitly say when to use it versus siblings like unit_convert or currency_convert, nor does it state exclusions. Usage is inferable but not 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 read-only, idempotent, and open-world behavior, and the description adds real context not in them: the 65-byte signature format with v = 27/28 or 0/1, and the x402 price of $0.003 USDC per call. It also disclaims EIP-1271 coverage. It leaves the return shape unstated, which is the main remaining gap.

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 core action, then signature format, then applicability, then pricing. Each sentence adds information, though the opening clause repeats the title nearly verbatim.

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?

No output schema exists, so the description should say what comes back (recovered address, match boolean, or error on invalid signature). It implies the recovery but never describes the return value, and it omits messageEncoding entirely, leaving two meaningful gaps for a paid 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 0%, so the description must carry parameter meaning. It explains message, signature (65-byte, v value conventions), and the optional expected-address comparison, but never mentions messageEncoding (utf8 vs hex), which is an enum parameter an agent could easily mis-set.

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?

Uses a precise verb+resource: recompute an EIP-191 hash and ecrecover the signer, optionally comparing against an expected address. That is clearly distinct from siblings like evm_address or evm_tx, which do not handle signature recovery.

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?

'Works for Sign-In-With-Ethereum messages and wallet login challenges' gives the positive use case, and 'Contract (EIP-1271) wallets are not checked' gives an explicit exclusion. No sibling alternative is named for the EIP-1271 case, which keeps it below 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new operational facts: a 1 MB input cap and a paid x402 price of $0.003 USDC per call on eip155:8453. It stops short of describing rate limits or what the response looks like, particularly for algorithm='all'.

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 capability, then input/output encodings, then the size and pricing constraints. The long algorithm enumeration duplicates the schema enum and the title, which is mild waste, but the density of useful facts per sentence is high.

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

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

With no output schema, the description should explain the shape of the result, yet it only names output encodings, not the return structure (e.g. whether 'all' yields a map keyed by algorithm). Constraints, pricing and encodings are covered, so it is adequate but not complete for an agent parsing 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 0%, so the description must carry parameter meaning, and it does so only nominally: it restates the same algorithm, encoding and size vocabularies already present as enums in the schema. It adds a little value by clarifying that 'all' is a valid algorithm choice, but does not explain defaults or how 'data' is interpreted when inputEncoding is hex/base58.

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?

Starts with a specific verb+resource ('Hash text or bytes') and immediately enumerates the supported algorithm families, so the agent knows exactly what the tool computes. It is clearly distinct from the neighbouring hmac, encode and abi_encode tools.

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

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

The description implies usage (compute a digest of given data) but never states when to choose this over close siblings such as hmac (keyed hashing) or encode. No exclusions or preconditions beyond the implicit 1 MB cap are given.

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/non-destructive, yet the description still adds real behavioral context: constant-time comparison (a meaningful security property), an explicit guarantee that keys are neither stored nor logged, and the x402 payment cost with the network identifier. These are traits an agent cannot infer from the 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?

Four compact sentences, front-loaded with purpose, then behavior, then privacy, then price — a sensible order. The opening clause substantially duplicates the title, which is the only wasted text.

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

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

With no output schema, the description must convey return semantics; it states that the comparison mode reports whether the signature matches, but it never says what the plain computation returns (hex digest format), which is a small but real gap for a tool with five parameters.

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 20% (only `expected` is documented), so the description must compensate, and it does: "key (text, hex or base64)" explains the `keyEncoding` enum values, the algorithm list mirrors the `algorithm` enum, and the constant-time comparison explains the `expected` parameter's behavior. `message` and the default behaviors are left to the schema, which is a minor 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 first sentence names a specific operation (HMAC computation), enumerates the supported algorithms, and gives a concrete use case (checking a webhook signature). The second sentence clarifies the verb+resource pair precisely. It does not differentiate from the sibling tool `hash`, which an agent could easily confuse with this one.

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?

"e.g. to check a webhook signature" gives a clear context for selecting this tool, and the description explains that the comparison against an expected signature is optional, which implies two modes. It stops short of naming when NOT to use it or pointing to the `hash` sibling for non-keyed digests.

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, so the safety profile is covered. The description adds genuinely useful context beyond that: the 2 MB input ceiling, the optional base URL for link resolution, the returned field set, and the x402 pricing requirement ($0.005 USDC per call on eip155:8453), which 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?

Two sentences, front-loaded with the core action, followed by the constraint and the cost. The output-field enumeration is a bit of a list but each item tells the agent what it gets, so it 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 no output schema, the description helpfully names the return fields, and it covers pricing and size limits. However, for a 5-parameter tool with 0% schema coverage and no output schema, the undefined 'mode' enum and 'maxChars' truncation knob are meaningful gaps an agent would need to guess at.

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 0%, so the description has to carry parameter meaning. It explains html (size limit) and baseUrl (resolves relative links) and implies format, but leaves 'mode' (main vs all) and 'maxChars' entirely unexplained, which is a real ambiguity given 'mode' is an opaque enum.

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 (convert/extract) and resource (HTML input), and explicitly distinguishes itself from its closest sibling: 'Same engine as web-extract, without fetching'. An agent can immediately tell this is the offline counterpart to web_extract.

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?

'Convert HTML you already have' and 'without fetching' clearly signal when this tool applies versus web_extract, and the 2 MB cap sets a boundary. It stops short of an explicit 'if you have a URL instead, use web_extract', but the contrast is strong enough to route correctly.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, and the description adds genuinely new behavioral facts: it runs offline, stores nothing, and costs $0.003 USDC per call via x402 on eip155:8453 — a paid-endpoint fact an agent must know before invoking. It also discloses return content (normalized/print-formatted IBAN, BBAN, and DE/GB bank or sort codes) that no output schema provides.

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

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

Three front-loaded sentences, each carrying distinct information: what is checked, what comes back, and operating constraints including price. Slightly dense, but nothing is redundant and the most decision-relevant content (validation scope) leads.

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

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

With no output schema, the description takes on the burden of describing return values and does so concretely (normalized IBAN, BBAN, DE/GB bank codes), plus cost and privacy behavior. For a one-parameter validation tool this covers everything needed to call it correctly, with only input-format tolerance left implicit.

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 0% for the single 'iban' parameter, so the schema only supplies type and maxLength 64. The description hints that input may be unnormalized (it returns a 'normalized and print-formatted' IBAN) but never states whether spaces, hyphens, or lowercase are accepted — the most common real-world failure mode for this call.

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 ('Validate an IBAN') and immediately specifies the checks performed: country-specific length and ISO 13616 mod-97 checksum, across 80+ countries. The resource (IBAN) alone separates it from email_validate and json_validate in the sibling list; no schema inspection is needed to know 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?

Gives clear context for use (validating International Bank Account Numbers for 80+ countries) and implies the boundary is IBAN-specific, with no sibling doing that job. It does not include explicit when-not guidance or name alternatives, but the domain is narrow enough that none is needed.

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 openWorld=false, so safety is covered. The description adds genuinely new behavioral context: a per-call price of $0.003 USDC via x402 on eip155:8453, which the agent cannot learn from structured fields. It stops short of saying what happens on malformed input.

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, front-loaded with the core action, and the returned fields are grouped efficiently. Minor redundancy: the category list appears in the title and again in the second sentence, costing a few tokens without new 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 no output schema, the description correctly enumerates return values (canonical/expanded forms, integer and hex, version, scope, routability, reverse DNS), and pricing is disclosed. The only real gap is behavior on invalid or non-address input.

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?

One parameter at 0% schema description coverage, so the description must carry the load. It does identify the parameter's meaning ('an IPv4/IPv6 address') and hints at accepted families, but says nothing about whether CIDR notation, ports, or bracketed IPv6 forms are accepted.

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?

Specific verb pair ('parse and classify') plus an explicit resource ('an IPv4/IPv6 address'), followed by an enumeration of the classification outputs. An agent can immediately tell this operates on a single address, unlike cidr_info or ip_range_to_cidr which work on blocks.

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?

Usage is only implied: you have an IP string and want it classified. No explicit when-to-use statement and no named alternatives, even though cidr_info, ip_range_to_cidr, and dns_reverse are adjacent siblings an agent could confuse it with.

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, closed-world safety. The description adds real operational context beyond them: exactness of the conversion, the 1,000-block ceiling (which implies a failure mode), and the $0.003 USDC x402 payment on eip155:8453, which the agent must consider 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?

Three short sentences, front-loaded with the core transformation, then bounds, then pricing. The opening sentence largely restates the title, which is the only redundancy.

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

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

For a two-parameter pure function with no output schema, the description covers the transformation, input domain, output shape ('list of CIDR blocks'), size limit, and cost. The missing piece is return-value detail (ordering, error behavior above 1,000 blocks).

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 0%, so the description must carry the burden, and it partly does: it identifies start/end as an inclusive address range accepting IPv4 or IPv6. It never specifies the string format (e.g. dotted-quad vs. bracketed IPv6) or what happens on malformed or maxLength-exceeding input.

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 ('Convert an IP range (start - end) to the minimal list of CIDR blocks'), which is distinguishable from the sibling CIDR tools (cidr_aggregate takes CIDR inputs, cidr_split subdivides a block) without opening their 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?

The input shape (range -> CIDR) implies the usage case, but there is no explicit when-to-use or when-not guidance, and none of the adjacent CIDR/ip_info siblings are named as alternatives. An agent has to infer the boundary itself.

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 and non-destructive, so the safety bar is met; the description adds genuinely new context: the returned operation set (add/remove/replace) with JSON Pointer paths and old/new values, a 2,000-operation cap that signals possible truncation, and the per-call price via x402 on eip155:8453. It stops short of describing error behavior for malformed JSON input.

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 sentences, front-loaded with the core purpose followed by return shape and then cost. Every sentence carries distinct information with no repetition of the title 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?

With no output schema, the description carries the burden of describing return values and does so well (operation types, JSON Pointer paths, truncation cap). Pricing is also disclosed. Minor gap: nothing about error handling or how type changes versus value changes are represented.

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 both parameters are already documented, including the 'JSON value or string containing JSON' acceptance. The description adds nothing about the parameters beyond the schema, so the baseline of 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 verb (structural diff) and resource (two JSON documents) and pins down the output shape as JSON-Patch-style operations. The emphasis on 'key by key and index by index' distinguishes it from sibling text_diff and from json_query/json_format without needing to name them.

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 single-purpose nature makes the use case inferable, but the description never says when to reach for this over text_diff or json_query, nor any exclusions. No explicit routing guidance is given.

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 and non-destructive, so safety is covered; the description adds real value beyond them by disclosing the x402 price ($0.003 USDC, eip155:8453) and the error behavior (line/column on invalid input). It does not state size limits on input (512KB max lives only in the 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?

Three tight sentences, front-loaded with the modes and output shape, then error handling, then pricing. No filler; the only redundancy is restating the title verbatim in the first sentence.

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

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

With no output schema, the description carries the return-value burden and does so (pretty/minified/canonical text plus size, node count, depth, and error line/column). Missing only the input size limit and a couple of indent semantics, which are minor for a stateless utility.

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

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

Schema description coverage is only 25%, so the description must compensate; it does explain the three modes and their outputs, and 'canonical with sorted keys' clarifies sortKeys. But it mentions tabs for indent while the enum only allows 0/2/4/8, leaving the 0 and 8 values and the defaults undocumented.

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 set (parse, pretty-print, minify, canonicalize) against a specific resource (JSON), and names the error-location capability. It is clearly distinguishable from json_validate or json_query, though it does not name those siblings explicitly.

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?

Usage is implied by the format list and the 'locate syntax errors' clause, so an agent can infer when it applies. However, there is no explicit when-to-use/when-not guidance and no routing to the obvious alternatives json_validate, json_diff or json_query.

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, closed-world and non-destructive behavior, so safety is covered. The description adds genuinely new operational context: the x402 payment requirement, the exact price ($0.003 USDC on eip155:8453), and the 20-path ceiling per call — things an agent cannot learn from the structured fields.

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 compact sentences: capability, syntax, cost. The first sentence largely restates the title/schema capability, which is minor waste, but nothing else is padding and the payment detail is placed where it will be seen.

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?

No output schema exists, so the description should hint at return shape; it says "extracts values" but not whether multiple paths yield an object keyed by path or a positional array. Otherwise a 3-parameter, low-complexity read tool is adequately covered, including cost and limits.

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 only 33% (`path` and `paths` are undocumented in the schema), so the description must compensate. It does: it specifies RFC 6901 pointer syntax `/a/b/0`, the dotted-path variant `a.b[0].c`, and `[*]` wildcards, and it ties the 20-item cap to the `paths` parameter. It does not clarify whether `path` and `paths` can be combined, which leaves one real ambiguity.

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 ("extract values from JSON") and immediately names two supported addressing modes. This clearly distinguishes it from siblings such as json_format, json_validate and json_diff, which the description's extraction framing implicitly rules out.

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?

"Reads one value by RFC 6901 JSON Pointer ... or a dotted path" plus "Up to 20 paths per call" implies the single-path vs. batch-path usage, but never explicitly says when to use `path` versus `paths`, nor does it name an alternative tool. Usage is inferable 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 already declare readOnly/idempotent/non-destructive, and the description adds real value beyond them: array values are JSON-encoded, cells beginning with = + - @ are escaped against formula injection, and the call costs $0.003 USDC via x402 on eip155:8453. The payment/auth requirement is exactly the kind of context annotations cannot express. It stops short of describing failure behavior on invalid JSON.

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 verb+resource, then layered detail (union headers, flattening, escaping, pricing) in a compact two-sentence body. The opening phrase slightly repeats the title, and the pricing sentence is dense but earns its place since it affects whether the agent can call at all.

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 stateless pure-transform tool with no output schema, the description covers output shape (header row, column naming, escaping) and the payment gate, which is what an agent needs. The gap is the undocumented flatten=false and delimiter behavior, but the enum in the schema partially covers delimiter.

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 only 33%, so the description carries extra burden. It effectively explains the flatten behavior ('nested objects become dot.separated columns') but never says what flatten=false does, and the delimiter parameter and its enum options are not mentioned at all in the description. Partial compensation only.

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 transformation (JSON array of objects to CSV) plus the non-obvious scope: header row from the union of keys, dot-separated nested columns. The inverse sibling csv_to_json is trivially distinguishable by direction, so nothing is ambiguous.

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?

Usage is implied by the direction of conversion, and the sibling csv_to_json makes the alternative obvious, but the description never states when to choose this versus csv_to_json nor any preconditions on input shape. An agent can infer it, but it is not 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?

The description discloses the return format ('Returns every error with its JSON Pointer path'), a key limitation ('Remote $ref is not fetched'), and the payment requirement ('Price: $0.003 USDC per call via x402'). This adds substantial value beyond the annotations, which already cover safety and idempotency.

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 purpose, then provides a dense but useful enumeration of supported features, followed by return behavior, limitation, and price. It is not wasteful, though the long keyword list could be trimmed for tighter readability.

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 complexity of JSON Schema validation and the absence of an output schema, the description covers purpose, supported features, return behavior, and key constraints. It stops short of fully specifying the response shape (e.g., a success/error object), but is otherwise complete for an agent 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 coverage is 100%, so the schema already documents all three parameters. The description does not clarify the semantics of the 'formats' boolean parameter beyond listing supported format keywords. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 ('Validate JSON data against a JSON Schema') and enumerates supported keywords, making the tool's function unmistakable. Sibling tools like json_format, json_query, and json_diff have clearly different purposes, so an agent can distinguish this tool without opening its 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?

The description implies when to use the tool by describing its validation checks, but it does not explicitly say when to prefer it over alternatives or note exclusions (e.g., 'use json_format for reformatting'). The context is clear but leaves routing inference to the agent.

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?

Adds substantial behavior beyond the readOnly/idempotent annotations: converts exp/iat/nbf to ISO dates, reports expired or not-yet-valid, flags alg=none, verifies in constant time, and states secrets are not stored or logged. Pricing via x402 is also disclosed. No contradiction with annotations.

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

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

Three tight, front-loaded sentences covering core behavior, optional verification, security, and pricing. Slight redundancy with the title's wording, but every sentence carries 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?

No output schema exists, so the description must describe results; it does so reasonably (decoded header/payload, ISO dates, validity flags, alg=none, verification result implied). It does not specify output shape or malformed-token error behavior, but is adequate for a simple decode tool.

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

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

Schema coverage is only 33% (only 'secret' is described in the schema). The description clarifies the secret parameter's purpose and supported algorithms, but never explains 'secretEncoding' (utf8/base64/hex) or the token format/length expectations, leaving a meaningful 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?

States a specific verb and resource ('Decode a JWT') plus the full scope: time checks and optional HMAC verification. An agent can tell exactly what this does and that it is not a general HMAC tool like the sibling 'hmac'.

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 condition for the optional path: 'If a shared secret is given, verifies HMAC signatures'. Implies usage for inspecting tokens and choosing secret only when verification is needed, but does not explicitly name alternatives or exclusions.

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 read-only/non-destructive profile, and the description adds meaningful context beyond them: CSPRNG source, entropy reported in the result, no persistence, and the x402 payment price. It leaves output shape and count behavior unspecified, 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?

Four compact sentences, front-loaded with the core capability, then a mechanism note, a storage note, and pricing. Each sentence carries information; only the trailing price line is arguably tangential to calling 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?

For a read-only generator with no output schema, the description supplies the important missing pieces: entropy reporting, non-persistence, and payment. It could say more about how 'count' batches results and what the response fields look like, but overall an agent has enough 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 coverage is only 20% (only 'length' is documented), so the description must compensate. It does explain the encoding options and the password character-class mode, but 'count', the interaction between length and kind, and the default values are not addressed, and the encodings merely restate an existing enum.

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 ('generates random bytes, passwords, numeric PINs') plus the mechanism (CSPRNG), which clearly separates it from siblings like uuid or hash. An agent can tell what this tool produces 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?

The enumerated modes (bytes, password, PIN) imply usage, and 'Nothing is stored' hints at the ephemeral-secret use case, but there is no explicit when-to-use guidance or routing to alternatives such as uuid for identifiers. Usage is inferable 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 already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds real behavior the annotations cannot: invalid versions are reported rather than silently dropped, prerelease rules are handled correctly, the range check returns the single highest satisfying version, and it discloses a per-call price ($0.003 USDC via x402 on eip155:8453) — a material cost signal for an agent.

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 resource and its operations, then capabilities, then pricing — good ordering with no filler. It is one dense semicolon-chained block, though, and the price/x402 clause could be separated for scanability.

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

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

With no output schema, the description carries the return-value burden and does so partially: it states the range check returns the highest satisfying version and that invalid entries are reported. It does not describe the shape of parse output or compare results, and never explicitly names `compareTo` as the field that triggers comparison mode, leaving a small gap for a multi-mode tool.

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

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

Schema coverage is 67%; `range` and `versions` are documented in-schema, but `compareTo` has no schema description at all, and the description partially compensates by explaining the two-value comparison mode. It also adds meaning beyond the schema example by enumerating supported range operators (^, ~, x-ranges, hyphen ranges, comparators, ||), which is more than the schema's single example conveys.

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 the specific resource (SemVer 2.0 versions) and enumerates the four distinct operations it performs: parse, compare, sort, and range-check. No sibling tool overlaps with semantic versioning, so an agent can route unambiguously from the name plus this sentence.

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 clause structure ('compares two (a vs b)', 'sorts a list', 'checks versions against npm range syntax') implicitly maps operations to input shapes, which helps an agent pick a mode. But there is no explicit when-to-use/when-not guidance, no statement of what happens if `range` and `compareTo` are both supplied, and no alternative tools are named.

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/closed-world, so the safety profile is covered; the description adds real behavioral context on top: the algorithmic basis (LCS), the return contents (hunks plus added/removed counts), the 5,000-line-per-side limit, and the x402 payment requirement. It stops short of stating truncation behavior when the limit is exceeded, which is the one notable gap.

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 sentences, front-loaded with the core purpose before algorithm, limits, and pricing. Slight redundancy between the title-like opening and the rest, but no sentence is wasted.

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

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

With no output schema, the description correctly takes on the job of describing returns (unified hunks, added/removed counts) and adds cost and size limits. An agent could call this confidently; only the a/b parameter meaning and overflow behavior are left implicit.

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 0%, so the burden falls on the description, and it only partially compensates: it names 'configurable context' and states the line limit per side, but never explains that 'a' and 'b' are the old/new texts or how 'context' affects hunk size. The schema itself supplies defaults, min/max, and length caps, so the description adds only marginal meaning.

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

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

The first sentence names the verb ('line diff'), the resources ('two texts'), and the output form ('unified diff with added/removed counts'), which immediately separates it from the sibling json_diff. The follow-up sentence pins down the algorithm (LCS) and output shape (hunks), leaving no ambiguity about what the 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?

Usage is only implied: 'line diff of two texts' suggests plain-text comparison, and the 5,000-line cap hints at expected input size. However, there is no explicit statement about when to prefer this over json_diff or text_stats, and no exclusions or prerequisites are listed beyond the pricing note.

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, closed-world), so the description's job is to add context — and it does, disclosing the $0.003 USDC per-call price on eip155:8453 via x402, plus the English-only limitation of the Flesch scores and the stop-word filtering on keywords. That pricing and language-scope disclosure is the kind of behavioral fact an agent cannot get from annotations, though the response shape is only enumerated rather than described.

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 single dense paragraph front-loads the metric inventory before the pricing caveat, which is the right order. The main waste is the opening clause repeating the title verbatim, and the semicolon-chained metric list is long but each clause adds a distinct capability 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?

With no output schema, the description effectively serves as the return-value spec by enumerating every computed statistic, and it adds the payment and language constraints an agent needs before invoking. The one meaningful gap is `top` — how many keywords come back and how to control that — which leaves the agent guessing at a tunable knob.

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 0%, so the schema gives only types, defaults and bounds with no prose, and the description does not compensate: the `top` parameter (default 10, max 100) is never named or explained, and the 1 MB `text` maxLength constraint is not mentioned. The phrase 'most frequent keywords' is the only hint at `top`'s purpose, and it never states how many keywords are returned by default.

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

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

The description names a concrete resource (text) and enumerates the exact metrics computed — characters, graphemes, words, sentences, paragraphs, lines, reading/speaking time, Flesch and Flesch-Kincaid scores, and keyword frequency. That specificity separates it cleanly from the nearest siblings, text_diff and text_transform, which analyze or alter text rather than quantify it.

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?

Usage is implied by the metric list: an agent can infer this is the tool for counting/readability on a block of text. However, there is no explicit routing guidance — no statement of when to prefer it over text_transform or text_diff, and no note on what to do with non-English input beyond the parenthetical '(English)' attached to the readability formulas.

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 establish that this is a safe, read-only, idempotent, non-destructive operation. The description adds valuable context beyond annotations by stating the price and payment mechanism: $0.003 USDC per call via x402 on eip155:8453. It does not describe the output format, but the payment disclosure is meaningful behavioral 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 front-loaded and compact, listing the operations efficiently. It does repeat the title almost verbatim in the first sentence, which is wasted space, but the second sentence adds useful operation detail and pricing information without excessive length.

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 two-parameter text transformation tool with strong annotations and no output schema, the definition is mostly complete: it lists operations and discloses the x402 payment cost. The main gap is that it does not describe the required text input or clarify the output, but an agent can reasonably infer the behavior from the operation list.

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 0%, so the description must compensate for parameter meaning. It does enumerate operation names that map to the op enum, such as strip accents, collapse whitespace, sort/dedupe lines, and remove HTML tags. However, it never mentions the required text parameter or the 524288 max length, leaving some parameter semantics to the schema alone.

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 (transforms text) and enumerates the exact operation family: slugify, camelCase, snake_case, kebab-case, title case, trimming, deduping, and more. This clearly distinguishes it from sibling tools like text_diff and text_stats, which analyze rather than transform text.

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 makes the intended use clear by listing transformation operations, so an agent can infer this is the tool for text normalization. However, it gives no explicit when-to-use guidance, no exclusions, and does not mention alternatives such as text_diff or text_stats.

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), so the description's value is in what it adds: DST-aware offset handling, a hard cap of 20 target zones, an enumerated return payload, and a metered cost of $0.003 USDC per call via x402 on eip155:8453. That payment requirement is exactly the kind of behavioral fact an agent cannot get from structured fields.

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 dense sentences, front-loaded with purpose and then inputs, outputs, limits and price. The opening clause repeats the title nearly verbatim, which is the only wasted space.

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 does the necessary work by enumerating what comes back (UTC plus each target zone with offset, weekday, ISO week, day of year, unix s/ms, RFC 2822). For a three-parameter, all-optional read tool this is close to complete; only error behavior and an output example are 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?

With schema coverage at 67% and the 'time' property carrying no schema description at all, the description compensates by specifying accepted input forms (ISO 8601, unix seconds/ms, 'now') and the from-zone interpretation of offsetless input. It also restates the 20-zone ceiling for 'to'. It does not explain the comma-separated string form versus array form beyond the schema's own note.

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 (convert) plus the resource (a time) and the two axes of conversion (time zones and formats), naming the supported representations. It is clearly distinguishable from siblings like time_diff (differences) and unit_convert (physical units).

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?

Usage is implied rather than stated: nothing tells the agent when to pick this over time_diff, or what happens if no target zone is supplied. The input conventions (bare local time read in the 'from' zone, 'now' accepted) do give real operational guidance, which lifts it above a bare 2.

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, idempotentHint, non-destructive and openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are evaluated in a caller-chosen time zone and each call costs $0.003 USDC via x402 on eip155:8453, which matters for invocation decisions. It does not disclose return shape or rounding conventions.

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 opening sentence is nearly verbatim the tool title, so the first clause spends space restating structured data. The remaining content – output categories, time zone, price – is efficient, but the pricing note sits at the end where it is easy to lose.

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

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

With no output schema, the description does a fair job enumerating what is returned (seconds/minutes/hours/days, years/months/days, weekday count). However, for a date-math tool with three undocumented string parameters it omits input formats and defaults, and it advertises a duration-addition mode the schema cannot express.

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 0%, so the description carries the full burden, yet it never states accepted date formats for start/end, never mentions that end defaults to 'now', and never explains the tz default of UTC. Only the time-zone concept is loosely conveyed. The claimed 'add a duration' capability has no corresponding parameter at all, leaving a gap an agent cannot resolve from 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?

The description names a concrete operation (duration between two dates/times) and enumerates the outputs it computes: exact duration, calendar difference, and weekday count. That is enough to separate it from siblings such as time_convert or cron_next, though it never names those alternatives. The trailing claim that it 'optionally adds a duration to a date' muddies the scope, since the input schema exposes no duration operand.

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?

Usage is implied by the feature list – an agent can infer this is the tool for elapsed-time or business-day questions – but there is no statement of when to prefer it over time_convert, nor any exclusion or prerequisite. The agent must reason from siblings' names alone.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful non-schema behavior: exact-factor conversion for 140+ units, temperature offset handling, the 'to=all' mode, and the $0.003 USDC x402 price.

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 core purpose and then adds scope, special cases, and pricing in a compact paragraph. The first sentence largely repeats the title, but overall it is efficient and 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?

The tool has three required parameters, low schema coverage, and no output schema, so the description should carry more weight. It covers dimensions, special temperature handling, and the 'to=all' mode, but it omits return-shape details and does not clarify how unit strings are formatted or how invalid units are handled.

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 33%: only the 'to' parameter is documented in the schema. The description partially compensates by listing supported dimensions, unit families, temperature offset units, and 'to=all' behavior, but it does not explain accepted string formats for 'from' or what 'value' represents beyond being numeric.

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: 'Convert between units' and enumerates 12 supported dimensions. It is clear what the tool does, but it does not distinguish itself from siblings like time_convert, currency_convert, or evm_units, which also handle unit-like conversions.

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 explains how to use the 'to=all' option but gives no guidance on when to use this tool versus alternatives such as time_convert or currency_convert. An agent must infer tool selection from the name and dimension list alone.

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 and non-destructive behavior, so the bar is lower. The description still adds real value beyond them: it discloses offline operation ('No network access'), the exact normalization rules (lowercase host, dropped default port, sorted query), tracking-parameter removal, and the x402 payment requirement with the eip155:8453 rail. It omits input-constraint behavior such as rejection of URLs longer than 8192 characters.

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 definition is front-loaded with the action and the decomposition, then lists the normalized/clean outputs, then operational facts (no network, price). It is dense but every sentence earns its place; the one minor cost is that the capability list is crammed into semicolon clauses rather than being easily scannable.

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

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

With no output schema, the description appropriately spells out the returned components and both normalized and cleaned forms. Combined with annotations covering the safety profile, an agent has enough to call it correctly; the only real gap is input-side detail (format validation, length limit).

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 0% and the single parameter is undocumented there, so the description must carry the load. It makes clear the tool operates on a URL but never states that the input is the `url` string, nor does it mention the maxLength 8192 constraint or expected URL format. It adds context about what the URL is decomposed into, but not about the parameter itself.

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

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

The description opens with a specific verb and resource ('Parse, normalize and clean a URL') and immediately enumerates the outputs (scheme, host, port, path, query, fragment). No sibling tool performs URL parsing, so the purpose is unambiguous and distinguishable within the list.

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?

Usage is implied by the capability list and the 'No network access' note, which tells the agent this is an offline transformation rather than a fetch. However, there is no explicit when-to-use/when-not-to-use guidance or naming of related tools (e.g., web_extract, encode) that an agent might confuse with this one.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the description's real addition is the payment requirement: $0.003 USDC per call via x402 on eip155:8453, plus the breadth of the bot database (35+ including GPTBot, ClaudeBot, CCBot). It does not say what happens with a malformed or empty UA, nor whether unknown agents return null vs. 'unknown'.

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, front-loaded with purpose, then coverage detail, then pricing. The bot-category enumeration ('search engines, AI crawlers, social preview fetchers, SEO tools, monitors and HTTP libraries') is informative but slightly sprawling and could be trimmed without loss.

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?

No output schema exists, and the description compensates by listing the returned fields (browser/version, engine, OS/version, device class, bot identity). For a one-parameter, no-side-effect tool that is nearly complete; the only gap is error/edge-case behavior for unparseable input.

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 0% and the description never mentions the single `ua` parameter, its 2000-character cap, or that it is the only required input. The parameter name is self-explanatory and there is only one, which limits the damage, but the description adds nothing the schema does not.

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?

Specific verb ('Parse') plus resource ('User-Agent') followed by an explicit enumeration of the parsed fields (browser, engine, OS, device class, bots). No sibling tool (url_parse, web_headers, web_extract) does UA parsing, so an agent can route here unambiguously.

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?

Usage is implied rather than stated: an agent with a UA string and an interest in bot/device classification will infer this is the tool. There is no explicit 'use when...' clause, no exclusions, and no mention of an alternative for related needs such as header inspection (web_headers) or URL breakdown (url_parse).

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 read-only, non-destructive, non-idempotent behavior, but the description adds real value beyond them: CSPRNG source, a 100-item cap, and the monetary cost ($0.003 USDC via x402 on eip155:8453) – a payment gate an agent must know about. It also hints at return contents (canonical form, version, variant, embedded timestamp for v1/v6/v7).

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 sentences, front-loaded with the purpose, then the two operating modes, then cost. Nothing is redundant or padding; every clause adds decision-relevant 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 no output schema, the description carries the burden of return values and does describe what parsing yields (canonical form, version, variant, timestamp). Cost and limits are covered. Minor gaps remain (exact response shape for bulk generation, error behavior on invalid input), but the essentials an agent needs to call it are 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 only 33%, so the description compensates by explaining the 'uuid' parameter's role (switches the tool from generation to parsing) and the practical meaning of 'count' (up to 100 per call) and 'version' (4 random vs 7 time-ordered). Only the default values and enum listing are left to the schema, which handles them.

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 specific verbs and resources: generate v4 random/v7 time-ordered UUIDs, or parse/validate an existing one. The dual-mode nature is spelled out in the title and first sentence, so the agent knows exactly what the tool does. It does not explicitly differentiate itself from nearby siblings like 'random' or 'hash', which keeps it at a 4.

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

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

Gives an explicit branching rule: omit the 'uuid' parameter to generate, supply it to validate/parse. That effectively covers when each mode applies. It stops short of naming alternatives or exclusions, so no 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds genuinely new behavior: redirects are followed and re-checked, nav/footers/scripts are stripped, links are made absolute, and non-HTML content types are passed through unchanged. It also discloses the x402 payment requirement ($0.01 USDC on eip155:8453), which is critical operational context absent from annotations. It omits truncation behavior and failure modes.

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 core action and output, then layered with processing details and the price. Dense but each clause carries information; only the heading/word-count enumeration is slightly listy.

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?

No output schema exists, so the description must describe returns - and it does, naming title, description, language, canonical URL, headings and word count. Payment, redirect and cleaning behavior are covered. The remaining gap is truncation/maxChars behavior and error handling for unreachable or non-public URLs.

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 25% (only 'mode' is documented), so the description needs to compensate. It partially does - 'main/article content first' and 'navigation/footers/scripts removed' explain the main vs all tradeoff, and 'plain-text and JSON responses are returned as-is' hints at format behavior - but maxChars is never mentioned and truncation semantics are left entirely undocumented.

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 ('Fetch a web page') plus the exact output shape (clean main text, Markdown, title, metadata), which distinguishes it from pure converters like html_extract. It does not explicitly say how it differs from web_metadata or web_links, which overlap on the metadata portion.

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

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

The description implies usage ('Fetches a public URL') and names an implicit constraint (public URLs only, paid per call), but gives no when-to-use/when-not guidance relative to siblings such as html_extract (for HTML you already have) or web_metadata. The agent must infer the alternative.

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 safety is covered. The description adds genuinely non-structured context: an x402 micro-payment of $0.005 USDC per call (eip155:8453) and the guarantee that cookie values are never returned, only flags. It stops short of describing failure modes (timeouts, unreachable hosts).

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 first sentence duplicates the title, which is mild waste, but the rest is dense and front-loaded: capabilities first, then mechanism, then the pricing/limits caveat. No filler sentences.

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

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

With no output schema, the description does the heavy lifting by enumerating exactly what is returned, including the graded security audit and cookie flags. Missing only error/edge-case behavior and the HEAD-vs-GET tradeoff, which keeps it from a 5.

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 0%, so the description must carry parameter meaning. It does note that the URL is requested via HEAD or GET, but it doesn't explain the default (GET), when HEAD is preferable (headers-only, cheaper), or any URL constraints like the 2048-char max.

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 (requests a URL) and enumerates the concrete artifacts returned: final status, redirect hops, headers, latency, security-header audit with grade, and cookie flags. This clearly separates it from siblings like web_metadata, web_extract, or web_links, which focus on page content rather than transport-level diagnostics.

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?

Usage is implied by the output list (use it when you need status/headers/redirects/timing), and the HEAD/GET mention hints at usage modes. However, it never states when to choose this over web_metadata or web_extract, nor does it give exclusions or prerequisites beyond the price line.

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 carry readOnly/openWorld/idempotent, but the description adds genuinely new behavioral facts: URLs are absolutized, results de-duplicated, internal/external determined by registrable host, and extra counts are included. The explicit '$0.008 USDC per call via x402 (eip155:8453)' pricing is material context an agent cannot get from annotations or schema. It stops short of covering failure modes (blocked pages, JS rendering, fetch errors) or rate limits.

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, output shape stated first and cost last. Every clause carries information: returned fields, normalization rules, classification rule, extra counts, price. 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?

With no output schema, the description does its duty by enumerating the return contents (href, anchor text, rel, internal/external flag, nofollow/mailto/tel/image counts) plus the payment requirement. Gaps remain on parameter behavior and on what happens when a page can't be fetched or rendered.

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 0% and the description never mentions the three parameters by name. It doesn't explain what 'url' must be, what 'limit' bounds (500 default / 2000 max), or that 'filter' narrows the internal/external split — the enum values are inferable but the limit behavior is not compensated for anywhere.

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?

Every sentence names a concrete verb and resource — 'fetches a page and returns every <a href> as an absolute URL with its anchor text and rel' — and the title/description pin down the exact shape of the result. This is clearly distinguishable from web_extract and html_extract, which return general page content rather than a link inventory.

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 scope implies when the tool fits (link audits, internal/external analysis), and the splitting into internal vs external hints at the reason to pick it over html_extract. However, no sibling is named, no exclusions are stated, and there is no guidance on when web_extract would be the better 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the crucial behavioral fact that is nowhere in structured data: a $0.008 USDC per-call cost via x402 on eip155:8453, which materially affects invocation. It omits error/timeout/redirect behavior, keeping it below 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?

Front-loaded with purpose, then a dense but useful inventory of return fields and the price. It is a long run-on sentence, but essentially every clause carries information the agent needs; minor deduction for density rather than any wasted sentence.

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

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

No output schema exists, so the description must explain return values and does so exhaustively, while also disclosing the payment requirement. An agent has everything needed to decide to call it and to know it costs money.

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?

With one parameter, 0% schema description coverage, and maxLength 2048 only, the description carries the burden. 'Fetches a URL' confirms the url param is the target page, but adds no scheme/format constraints (absolute? http vs https?) or handling for redirects. Adequate but with a real 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?

States a specific verb (fetches a URL) and resource (page metadata) and then enumerates exactly what is returned: title, meta description, canonical, OpenGraph, Twitter cards, JSON-LD, favicon, feeds, hreflang, and SEO checklist. That field list makes it unmistakable against siblings like web_extract, web_headers, and web_links without needing to name them.

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 framing 'for link previews and SEO' gives a clear usage context. It stops short of explicit exclusions or naming alternatives (e.g., 'use web_extract for body text'), so it lands at clear-context-no-exclusions rather than full when/when-not 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 establish read-only, open-world, idempotent, non-destructive behavior. The description adds meaningful context beyond them: it discloses RFC 9309 matching behavior, returned fields, and a per-call x402 price. It does not cover error handling or rate limits, but it is substantially transparent.

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

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

The description is compact and front-loaded with the core question, followed by the matching algorithm, return values, and pricing. Every sentence contributes useful information without 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?

There is no output schema, so it is important that the description names the return fields, and it does: allowed/disallowed, deciding rule, crawl-delay, sitemaps, and agent groups. Combined with the annotations and parameter schema, this is complete enough for an agent to invoke the tool correctly.

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

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

The url parameter is well explained as the page whose origin's robots.txt is read, but the userAgent parameter has no schema description and is only indirectly referenced in the description as the crawler being evaluated. With 50% schema description coverage, the description adds some meaning but does not fully document userAgent matching or default behavior.

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 question and operation: fetch /robots.txt and evaluate a URL path for a user-agent under RFC 9309. It clearly distinguishes this from sibling web tools such as web_sitemap by focusing on robots.txt rules, crawl-delay, and agent groups.

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 context of use is clear: checking whether a crawler user-agent is allowed to access a URL path according to robots.txt. It does not explicitly name when not to use it or point to a specific alternative, but the intended scenario is unambiguous.

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

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

Annotations already cover safety (readOnly/idempotent/non-destructive), yet the description adds genuinely new operational facts: a 5,000-entry cap, that gzip sitemaps are NOT decoded (a real failure mode), and a per-call price of $0.008 USDC via x402 on eip155:8453. Cost and decode limitations are exactly the behavioral traits 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?

Three tight sentences: purpose and payload first, resolution behavior second, output shape and constraints third. No filler, no restatement of the title, and the cost caveat is placed last where it belongs.

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