Developer Utilities & Validators (Tanod)

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

Annotations only cover the safety profile (readOnly/idempotent/non-destructive), while the description adds substantial behavior: no network access and nothing persisted, deterministic derived uids, exact timezone serialization rules, all-day inclusive-end handling, and a 422-with-event-name error contract that is explicitly not charged. This is far beyond what the annotations convey (the openWorldHint=true annotation is arguably imprecise against 'pure computation', but it does not contradict the safety hints).

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

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

Front-loaded with purpose and the sibling alternative, then output shape, then edge-case serialization rules, with pricing/limits/docs trailing. Dense and mostly waste-free, though '1-50 events' is repeated three times (title, description, schema) and the billing snippet sits mid-paragraph.

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 multi-field, nested-input generator, the description covers what the agent must know before invoking: input shape, defaults, serialization semantics, failure mode, cost, and a docs link. An output schema exists, yet the description still usefully names the return artifacts (VCALENDAR text, base64, data: URI, uids), leaving nothing critical 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?

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine semantics the schema omits: how a zoned start becomes TZID=<IANA name> with no VTIMEZONE block, how an offset becomes UTC, how a plain local time stays floating, and that all-day `end` is inclusive. These interpretation rules are the main thing an agent could get wrong.

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 ('Build an iCalendar file from JSON events') and immediately names the sibling it is not ('To read an .ics file use parse_ics'), so the agent can distinguish it from parse_ics without opening either schema. Scope (1-50 events) and output format (RFC 5545 VCALENDAR text) are also pinned down.

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 routes the agent explicitly: build here, read with parse_ics. It supplies context an agent needs before calling (pure computation, no network, nothing stored, cost and free-tier limits, typical latency) but never states a positive when-to-use condition for this tool beyond the implied 'you have JSON events and need an .ics'.

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 annotations: discloses that only names and sizes are returned, never header values; that results are estimates; the 1-4s typical runtime and 25s wall-clock limit; cost ($0.002) and free tier (10/day per IP); and a prompt-injection caution about treating page text as untrusted. These are exactly the behavioral facts an agent cannot get from readOnlyHint/idempotentHint 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?

Purpose is front-loaded and nearly every clause carries information (returns, cost, timing, safety). It is dense to the point of being a run-on, and the 'limit overrides' phrase costs clarity, but there is little pure filler.

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

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

An output schema exists, yet the description still sketches the return shape, error behavior, cost model, timing bounds, and trust posture. For a single-parameter read-only measurement tool, nothing material 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% for the single url parameter, so baseline is 3. The description reinforces constraints (public HTTPS, port 443, no redirects) but also mentions 'limit overrides' that do not appear as parameters in the schema, which adds slight ambiguity rather than clarifying argument semantics.

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 (measure) and resource (response headers) and names the exact comparison targets (nginx, aiohttp, Node fetch, Python limits). This distinguishes it from siblings like check_security_headers and get_page_meta without opening either schema.

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

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

Gives clear operating context: one unpaid public-HTTPS GET, no redirects or body read, and invalid/unreachable hosts return 422 without charge. It does not explicitly name a sibling alternative or state when-not to use it (e.g., vs check_security_headers), 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 declare read-only/idempotent/non-destructive, and the description goes well beyond them: it documents the return shape (ratio plus AA/AAA pass-fail for normal, large, and UI text), a concrete unrounded example, 422 behavior on invalid colors with the key note that no charge occurs, translucent-color compositing semantics, typical latency, and price/free-tier terms.

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 layered details. It is on the longer side (pricing, free tier, docs link, example) but each sentence carries operational value; the 'unrounded: #777 on white is 4.48:1' example notably 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?

For a two-param utility with an output schema, the description covers everything an agent needs: purpose, sibling routing, error semantics, billing, compositing behavior, and latency. Nothing material is left unspecified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: it clarifies the foreground is the text/UI color, and that a translucent color is composited over the background before computation, which affects how inputs are interpreted.

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: checking WCAG contrast between a text/foreground color and a background color. It also explicitly names the sibling convert_color_check_contrast as the tool for format conversion, so an agent can distinguish the two without opening a schema.

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

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

Provides an explicit routing hint ('To convert colour formats too use convert_color_check_contrast'), which covers the main adjacent use case. It does not state when this tool should not be used or other alternatives, but the context is clear for a single-purpose utility.

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). The description adds real operational context beyond them: unparseable/out-of-range colors return 422 before any charge, translucent colors are composited over the background before contrast is computed, typical latency under 0.1 s, price USD 0.001, and a free tier of 10 calls per IP per UTC day.

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

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

Purpose and the sibling alternative are front-loaded, followed by outputs, edge-case behavior, and pricing/logistics. Dense but every sentence conveys distinct, actionable information 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?

Even though an output schema exists, the description summarizes the return shape, error semantics, compositing behavior, latency, and pricing. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining what supplying `background` actually does (adds the WCAG 2.x ratio, AA/AAA pass/fail for normal/large text and UI components) and how translucency interacts with it, which the schema description only states tersely.

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 compound verb+resource: converting a color across four formats and checking WCAG contrast. It explicitly distinguishes itself from the sibling check_wcag_contrast ('For contrast alone use check_wcag_contrast'), so an agent can route correctly without opening a schema.

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

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

Names the alternative tool and the exact condition that selects it ('For contrast alone'). Combined with the behavior when `background` is omitted, the agent knows precisely when to pick this tool over its sibling.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context beyond them: YAML restricted loader refusing alias bombs, XML with DTDs/entities returning 422 xml_forbidden, lossy conversions surfaced as 422 instead of silent changes, CSV strings / ISO date coercion, isolated no-network child process, latency and 1 MB caps, pricing, free tier, and a no-logging guarantee. This is far richer than the 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?

Dense but front-loaded: the core purpose and the sibling routing come first, then errors, then operational details. Each sentence carries information, though the run-on stream of 422 codes is slightly crowded and could be tightened.

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

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

With an output schema present, return values need not be explained, and the description fills the remaining gaps: error semantics, format limitations, size/time limits, cost, and privacy. An agent has everything needed to call it correctly and interpret failures.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds real semantic value: it clarifies that CSV values remain strings, dates become ISO strings while TOML keeps native dates, and that both `from` and `to` have asymmetric format sets (XML is input-only). That exceeds what the schema states.

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) and resource (data), enumerates the exact source and target formats (JSON, YAML, CSV, TOML, XML), and explicitly distinguishes itself from the sibling validate_json. An agent can identify this 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?

Names the alternative explicitly: 'To check JSON against a schema use validate_json.' It gives clear context for what the tool is for, but does not spell out when-not-to-use (e.g., large-document workarounds or batch needs beyond the individual-call model).

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, non-destructive, open-world behavior. The description goes further with tzdata source, DST gap/fold flags, 422 error semantics, 'not charged' for invalid input, latency, price, and daily free tier—rich context beyond 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?

Front-loads the core conversion purpose, then the alternative, then behavioral details. Dense but every clause carries actionable information (errors, latency, pricing, docs).

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

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

An output schema exists, so return format needn't be described. Given 3 parameters, 100% schema coverage, and annotations, the description supplies all missing operational context an agent needs.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics: from_tz cannot be combined with an offset-bearing time, and DST gap/fold times are flagged, which are not in the schema descriptions.

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') and resource ('one instant between time zones'), and names the sibling to use for business-day math. An agent can distinguish it from count_or_add_business_days without opening either schema.

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

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

Explicitly routes business-day needs to count_or_add_business_days and describes error conditions (offset plus from_tz, unknown zone, malformed time) that define when this tool will not work. No other time-conversion alternative is needed from the sibling 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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds substantial extra context: exact-factor returns, 422 error conditions before payment, no-charge guarantee, US vs imperial unit conventions, typical latency, price, free tier, and documentation link.

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 stays in one dense paragraph. It has minor redundancy: the category list appears twice with slight variation ('weight' vs 'mass'), and the 'utilpeek:' prefix repeats 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?

An output schema exists, so return-value structure need not be explained. The description is thorough for a conversion tool, covering scope, supported categories, error cases, payment/free-tier behavior, latency, and external docs.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful unit-category semantics beyond the schema, including US vs imperial suffixes, exact data-size conventions (kB vs KiB), reciprocal fuel units, and ambiguous-spelling handling.

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') and resource ('units of measurement') and enumerates the supported categories. It also names the sibling text_numbers as the right tool for numbers written in words, so an agent can distinguish it from at least one alternative.

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 usage context (units of measurement) and an explicit alternative for numbers in words ('use text_numbers'). It does not, however, distinguish this tool from the sibling convert_time, even though it claims to handle time and fuel economy.

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 (which only cover read-only/idempotent safety) by disclosing bad-input behavior (422, not charged), latency (<0.2 s), price and the 10-free-calls-per-IP-per-UTC-day quota, and an accuracy caveat that holiday rules are library-modelled and should be confirmed with an official source for legal/payroll use.

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

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

Purpose and the mode split are front-loaded, and most information earns its place. It is dense and includes some boilerplate (pricing, docs URL) and re-explains return values the output schema already carries, so it is not maximally tight.

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

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

With an output schema present and 100% parameter coverage, the description only needs to frame behavior, and it does: both modes, inclusion semantics, supported date ranges (20 years; 1990-2100 with a country), error code, cost, and a legal caveat.

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 already 100%, so baseline is 3, but the description adds value by grouping which parameters apply to which mode (end/include_start/include_end for count; days/weekend/country/subdivision for add) and flags that weekends are configurable and a country adds its public holidays.

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 two specific operations with verb+resource: count business days between two dates, or add working days. It distinguishes itself from the sibling get_public_holidays by naming it and explaining the relationship (this tool uses the holiday data, that tool lists 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?

Explains when to use each mode (count vs add) with the Excel NETWORKDAYS/WORKDAY analogies and routes to get_public_holidays for the holiday list. It does not compare against other date siblings (convert_time, cron_next_runs, expand_rrule), so the routing is clear but not exhaustive.

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

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

Annotations cover the read-only/idempotent safety profile, and the description adds substantial context beyond them: 422 outcomes for no_next_run and for invalid expression/start/zone, that these are not charged, the `exhausted: true` flag for rare schedules, expected latency (~0.1 s), price (USD 0.001) and the free 10/day quota. This is exactly the extra behavioral detail annotations cannot carry.

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

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

Dense but front-loaded: purpose and alternative first, then grammar, then edge-case behavior, then cost. The pricing/quota/docs tail is useful but slightly heavy relative to the core call semantics, keeping it short of a 5.

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

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

An output schema exists so return structure needn't be restated, and the description still flags the notable `exhausted: true` case. Between annotations, full schema coverage, the output schema, and the description's error/pricing/grammar coverage, nothing needed to invoke 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 coverage is 100%, so count/start/timezone are fully documented in structured data (baseline 3). The description goes further on the required `expression` parameter by explaining Vixie OR semantics between day-of-month and day-of-week and the accepted grammar, which is meaning the schema does not convey.

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 ('the next run times of a cron expression') and immediately names the sibling it is not ('For iCalendar RRULEs use expand_rrule'). An agent can distinguish it from expand_rrule without opening either schema.

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

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

Explicitly routes to expand_rrule for RRULEs, and enumerates when the tool applies (5-field cron or macro) plus what it rejects (no seconds/year fields, no R/H/W). The never-fires and invalid-input cases are called out, so the agent knows the boundary conditions.

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?

Despite annotations already covering the safety profile, the description adds substantial behavior: no network access, nothing stored or logged, keys/secrets not echoed, error shape (422 for malformed tokens and JWEs, not charged), latency (<0.1s), and pricing/quota. This is well beyond what the annotations convey. The only minor tension is openWorldHint=true alongside 'no network access,' but this is not a safety contradiction.

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 decode/no-verify distinction and generally dense and useful. However, the 'not verified' point is restated twice ('without verifying it' and 'Decoding does not verify the signature'), and the trailing pricing/free-tier/docs block adds bulk, so it is slightly redundant for its 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?

An output schema exists, yet the description still sketches the return shape (header/payload split, alg/typ/kid, iat/nbf/exp as ISO 8601, expired/not_yet_valid flags) and the error condition. Combined with annotations, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% and the single 'token' parameter is fully documented there, including the accepted leading 'Bearer ' form. The description adds no parameter-level syntax or format detail 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?

States a specific verb (decode) and resource (JWT), immediately scopes it as 'without verifying it,' and names the sibling verify_jwt as the contrasting tool. An agent can distinguish it from verify_jwt and decode_calldata 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?

Explicitly routes: 'To check the signature use verify_jwt' and reinforces that 'the result is untrusted until verify_jwt passes.' The condition separating decode from verify is stated outright rather than 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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: pure local computation with no network access, nothing paid or stored, payment secret not echoed, untrusted description handling, 422 on invalid input, ~0.1 s latency, and price/free-tier terms. This is exactly the extra behavioral detail the rubric rewards.

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

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

Front-loads purpose, sibling routing, return fields, then safety/cost notes, so it is well structured. It is fairly long for a single-argument decoder, though nearly every clause (untrusted-data warning, 422, price) carries actionable 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?

Even though an output schema exists, the description enumerates the decoded fields (network, msat/sat/BTC amounts, expiry flag, recovered payee key, payment hash, route hints, feature bits) and covers error, latency, and cost. An agent has everything needed to invoke and interpret it correctly.

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

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

Schema description coverage is 100% and the single 'invoice' parameter already documents accepted prefixes (lnbc/lntb/lntbs/lnbcrt), case handling, and length bounds. The description adds no additional parameter syntax, so the baseline 3 for schema-dominant tools 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 (decode) and resource (Lightning BOLT11 invoice) and enumerates the returned fields (amount, payee, payment hash, expiry). It explicitly distinguishes itself from siblings: "For EVM calldata use decode_calldata; for Nostr ids use decode_nostr_id." An agent can route to it 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?

Names the alternatives (decode_calldata, decode_nostr_id) and the input condition that selects each, making the when-to-use-vs-sibling decision explicit. It also clarifies the 422 behavior for non-BOLT11 input, removing the main ambiguity about acceptable inputs.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses that nsec keys are refused with 422 and never decoded/stored/returned, that NIP-05 triggers a fetch of the domain's nostr.json, that bad identifiers yield 422 and unlisted names 404 with no charge, plus latency (0.1 s vs 0.3-8 s), price, free tier, no-logging, and an untrusted-data warning.

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

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

Purpose and scope are front-loaded, then error/behavior/price facts in tight clauses; nearly every sentence carries operational value. It is dense and slightly long, but there is little filler to cut.

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 decoder with an output schema, everything an agent needs is present: accepted formats, refusal cases, error codes, timing, cost, and a prompt-injection caveat. Return-value detail is supplied by the output schema, so nothing material is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the verify_nip05 verification semantics. The description only restates the 'optionally checked against a key' idea, adding essentially no syntax or format detail beyond the structured fields.

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

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

States a specific verb (decode) plus the exact resource set (npub, note, nprofile, nevent, naddr) and the second capability (resolve NIP-05). It also names the sibling that handles the adjacent case ('For ENS names use resolve_ens'), so an agent can route without opening either schema.

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

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

Explicitly routes ENS-name queries away to resolve_ens and explains the two input modes (NIP-19 identifier vs NIP-05 address, with the optional verify_nip05 check). It stops short of a full when-to-use/when-not matrix against the other decode_* siblings, so it is clear context rather than exhaustive 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?

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses hard limits (1,000 occurrences, search_horizon from 1 hour to 100 years), a 1.5 s stop, 422 error semantics for bad rules/zones (not charged), typical latency, DST wall-clock preservation, cost and free-tier throttling. This is unusually rich behavioral context the annotations do not carry.

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

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

Single dense paragraph, front-loaded with purpose then sibling routing, then behavior/cost. Every sentence carries operational value (limits, errors, price, docs); none is filler despite the length, which is justified by the tool's complexity.

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

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

With an output schema present, the description need not explain return structure, and it still summarizes it (ISO 8601 with offset, 'whether more exist'). For a 7-param paid computation tool it covers limits, failure modes, DST, cost and latency — 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?

Schema coverage is 100%, so the baseline is 3, but the description still adds meaning: the [from, to] window is inclusive, until is an 'extra' bound layered on the rule, exdates are omitted occurrences, and timezone governs wall-clock retention across DST. It does not, however, add syntax/format detail 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?

Starts with a precise verb+resource ('Expand an iCalendar RRULE into dates') and immediately names the two nearest siblings it is not: cron_next_runs (cron) and build_ics_event (build an event). An agent can route correctly 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?

Explicit when-to-use-this vs. the alternative tools ('For cron use cron_next_runs; to build an event use build_ics_event'), plus context on when it is appropriate (expanding a rule into an occurrence list). Nothing is left 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?

Goes well beyond the annotations: pricing (USD 0.005), free tier (10 calls/IP/UTC day), latency (2-15 s, faster cached), error semantics (0 matches charged, 422/404/503 with charging rules), ODbL attribution, and an untrusted-data warning. Annotations only cover read-only/open-world, so this adds substantial 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?

Front-loaded with purpose and input shape, and the operational facts are terse. Minor waste: the place-kind enumeration and the untrusted-data caution each appear twice, lengthening an already dense paragraph.

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

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

With an output schema present, return formatting needn't be described; the description still covers input modes, defaults, error outcomes, latency, cost, and licensing. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3; the description adds the useful combination logic that lat/lon and place are alternatives and that radius_m/limit are optional. It doesn't restate the kind list fully (it says 'and more'), but the schema carries that detail.

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 ('Find places nearby'), names concrete place kinds, and bounds scope (one kind, near a point, nearest first, OpenStreetMap). An agent can distinguish it from siblings like geocode purely from the 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?

Explicitly routes city-name resolution to the sibling 'geocode' and clarifies that a city name means its centre, not an address. It also states the required input order (kind, then lat/lon or place) and that one kind is returned per 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/destructive/idempotent hints, yet the description adds substantial context: monotonicity applies per-response deliberately so callers cannot predict other callers' IDs, invalid combos return 422 uncharged, latency is typically under 0.1s, and pricing/free-tier limits are given.

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 the sibling alternative, then defaults, error cases, latency, and pricing. Every clause is useful, though pricing/free-tier/docs appended to the same paragraph makes it slightly dense.

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

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

An output schema exists so return values need no explanation; the description still covers input defaults, valid combinations, failure modes, timing, and cost. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not encode: `version` is only valid with kind=uuid and `monotonic` only with v7/ULID, both a 422. That is genuine meaning beyond the per-field descriptions.

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 (Generate) and resource (UUIDs v4/v7, ULIDs) and explicitly routes the agent away from the sibling generate_random. An agent can pick this over generate_random without opening either schema.

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

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

Gives the exclusion rule ('For numbers, bytes and picks use generate_random') and the default behavior ('an empty body gives one UUID v4'). It also states which combinations are rejected (version with kind=ulid, monotonic with v4), leaving little to infer.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description goes well beyond that by disclosing that validation errors return 422 before any payment (not charged), that nothing is stored or logged, expected latency (<0.1 s), the price (USD 0.001) and a free tier (10 calls/IP/UTC day). These are exactly the kind of non-indexed operational traits an agent needs.

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, followed by the sibling redirect, then mechanics, then constraints/pricing. Every sentence carries information (source, defaults, limits, 422 semantics, no-logging, price). It is dense rather than padded, though it packs a lot into a single flowing block and could be marginally tightened.

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

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

With an output schema present, return-value explanation is unnecessary, and the description still covers the essential caller questions: what defaults apply, how errors surface (422, uncharged), durability (nothing stored/logged), latency and cost. For a 9-parameter tool with zero required params, it leaves nothing material for the agent to guess.

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 each parameter and a baseline of 3 applies. The description nonetheless adds meaning beyond it: integer ranges are inclusive vs. floats being [min, max), the dice expression grammar (3d6 / 2d10+3 returning the total), the 1-1,024 byte bounds and the behavior of an empty body (one integer 0-100). This is real added value on top of an already-complete 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 (generate cryptographically strong random numbers, bytes, UUIDs, dice, picks, shuffles) and immediately names the sibling it does NOT cover (generate_ids for UUIDs/ULIDs in the sense of id generation). The CSPRNG source (OS CSPRNG via Python `secrets`) is explicit, so the agent knows this is a security-grade random tool, not a pseudo-random 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?

It routes clearly to a sibling: 'For UUIDs and ULIDs use generate_ids' — a concrete when-to-use-another-tool rule. It also documents the default empty-body behavior (one integer 0-100) and advises 'Generate secret keys locally', which is actionable guidance. It lacks explicit when-not conditions beyond the id-generation redirect, but the context is clear.

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

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

Annotations already declare read-only/idempotent/open-world, and the description adds genuinely new behavior: a 404 place_not_found that is not charged, typical latency under 0.1 s with a 1 s first call, price USD 0.001, a 10-call free tier per IP per UTC day, and the attribution obligation carried in the `attribution` field.

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 the alternative tool, then input rules, then operational facts. Every sentence carries information, though the pricing, license, and docs-link tail makes it denser than strictly necessary for a 3-parameter call.

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

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

An output schema exists so return values need no explanation, and the annotations cover the safety profile. What remains — input modes, matching limits, error behavior, cost model, and data provenance — is fully addressed.

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, but the description adds real matching semantics not in the schema: `place` accepts "City" or "City, CC" with an ISO country or US state code, and it only matches cities, never street addresses. The either/or exclusivity rule is also clarified.

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 (geocode) and resource (city names / coordinates) and immediately scopes it to the offline GeoNames cities15000 table. It explicitly distinguishes itself from the sibling find_places_nearby, so an agent can route without opening either schema.

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

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

It states the exact input modes (either `place` alone or `lat` and `lon` together), names the alternative tool for nearby-place queries, and gives the matching scope (cities of 15,000+ people, no street addresses). When-to-use and when-not-to-use are both covered.

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), yet the description still adds substantial behavioral context beyond them: days without a snapshot are returned as gaps rather than interpolated, typical latency under 0.1 s, a USD 0.002 per-call cost, a free tier of 10 calls per IP per UTC day, and a docs link. These are exactly the operational facts an agent needs before invoking a metered 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?

Front-loaded with the tool's identity and return shape, then progressively adds caveats and cost. The opening 'utilpeek: GPU price index:' restates the name and title before the substantive sentence, which is mild redundancy rather than bloat. Every other sentence carries distinct 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?

An output schema exists, so return structure need not be explained, yet the description still covers the semantics that matter: what the prices represent, the missing-day/no-interpolation rule, latency, cost, and quota. Nothing an agent needs to call this correctly and interpret the result is absent.

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

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

Schema description coverage is 100%, so the schema already documents chip, from, and to including formats and defaults. The description contributes one piece of extra meaning not in the schema ('per GPU-hour' as the unit of the returned prices), but otherwise defers to the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Returns a GPU chip's daily rental price history') and enumerates the exact series returned: lowest/median on-demand list price, lowest spot, Akash median bid, and free GPUs. The 'daily ... over time' framing cleanly separates it from the sibling get_gpu_prices, which reads as a current-snapshot tool. An agent can select between them without opening either schema.

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

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

Usage is only implied by the word 'history' and 'over time' – the description never states when to prefer this over the sibling get_gpu_prices, nor any exclusion. It does clarify that the data reflects list prices and marketplace bids rather than executed trades, which is useful scoping, but that is about data meaning rather than when-to-call guidance.

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

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

Annotations cover the safety profile, and the description then adds genuinely operational context: data is a snapshot refreshed twice a day, excludes tax, egress and storage, spot moves often, a snapshot older than 36 hours returns 503 (not charged), typical latency under 0.1 s, the price is USD 0.002 per call, and there is a free tier of 10 calls per IP per UTC day. Those cost, rate-limit and failure-mode details are exactly what 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?

The core purpose is front-loaded, and most of the length is earned operational detail. However, the first sentence repeats what the second sentence says, listing the same providers, chips and pricing unit twice, which is wasted space in an already dense run-on.

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 an output schema exists, the description need not explain return shape, yet it still notes machine-hour versus GPU-hour pricing, null for unknown shape, and the exclusion count. Combined with freshness, pricing, latency, cost, and docs URL, 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?

Schema coverage is 100%, so every parameter is already documented in the schema, which sets the baseline at 3. The description restates the optional parameter names and adds meaning for a few (rent_vs_buy break-even, per-machine vs total GPU semantics) and for the unknown-shape exclusion count, but most parameters add no detail 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 and resource: cheapest GPU price per GPU-hour across AWS, Azure, Google Cloud and Akash, filtered by chip, memory, machine shape, region and price ceiling. Scope and dimensions are unambiguous. It does not acknowledge the similarly named sibling get_gpu_price_index, so the agent must infer the split between a price lookup and a price index.

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 strong purpose statement and the pricing enum note ('on_demand and spot are cloud list prices only'), which helps the agent choose a mode. However, there is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool such as get_gpu_price_index for historical/index data. Guidance is inferable but not 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 safety (readOnly, idempotent, openWorld, non-destructive), and the description goes well beyond them: 422 error semantics with no charge, sub-0.1s latency, USD 0.001 price, a 10-calls-per-IP-per-UTC-day free tier, and an important accuracy caveat that data comes from python-holidays rules rather than an official calendar.

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

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

Front-loads the purpose, then routing, error behavior, cost/latency, caveat and docs link in a logical order. Every sentence carries distinct information, though the pricing/latency/free-tier block makes it denser than strictly 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?

With an output schema present, return values need no explanation. The description covers the remaining gaps an agent would care about: the alternative tool, error behavior, cost, rate limits, and the reliability caveat for legal/payroll use.

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

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

Schema description coverage is 100%, so the schema already documents year, country, language and subdivision. The description only references these parameters collectively via the 422 message and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (public holidays of a country for a year), and the title reinforces it. It explicitly names the sibling it is not for ('To count working days use count_or_add_business_days'), so an agent can separate it from count_or_add_business_days without opening either schema.

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

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

Gives an explicit alternative and the condition that selects it: counting working days routes to count_or_add_business_days. It also tells the agent what happens on bad input (422 naming supported values), so edge-case routing is covered.

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 goes well beyond them: exact-one-of input constraint with 422 invalid_request, 422 invalid_base64 for malformed input, no echo/no logging guarantees, latency profile (keccak256 ~2 s per MB), pricing and a 10-calls/day free quota. That is unusually rich behavioral 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?

Front-loaded with purpose and the sibling redirect, with each clause carrying distinct information. It is dense with pricing/quota/docs-link tail matter, but nothing is genuinely redundant.

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

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

Given an output schema exists, the description need not detail return shape, yet it still notes the digest format (hex of UTF-8 text, or base64 bytes). Input constraints, errors, timing and quotas are all covered, leaving no material gap for calling the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by stating the mutual-exclusion rule ('Send exactly one of text or base64') and the failure modes, which the schema's maxLength/anyOf does not convey.

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 ('Hash text or bytes') and enumerates the algorithm family, then explicitly names the sibling it is not (hmac_sign_verify). An agent can distinguish it from hmac_sign_verify, image_hash and text_encode 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?

Routes the agent away to the alternative with the selecting condition ('For a keyed HMAC use hmac_sign_verify') and adds a suitability caveat ('md5 and sha1 are for checksums, not security') that steers algorithm choice. This is explicit when-to-use and 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 cover readOnly/idempotent/destructive, and the description adds substantial context beyond them: constant-time comparison, the 422 error cases that are not charged, that prefixes like v0=/v1= are not stripped, that key and message are never echoed or logged, latency (~0.1s), and pricing.

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

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

Front-loads the purpose and alternatives, then inputs and error behavior. It is dense but nearly every clause carries operational detail; the price/free/docs tail adds slight marketing bulk but remains relevant to cost-sensitive callers.

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

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

With an output schema present and rich annotations, the description needn't cover return values. Combined with explicit error cases, format handling, and encodings, an agent has everything needed to call it correctly across the three webhook providers.

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 each parameter. The description still adds meaning: the accepted sha256= prefix behavior, how Stripe v1 signs {t}.{raw body} and Slack v0 signs v0:{timestamp}:{raw body}, and the key_encoding/algorithm interplay. Good value beyond the schema, though some format specifics live in the params.

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 resource: returns HMAC of a message under a shared key (sign) or verifies a signature in constant time (verify), and names the concrete webhook formats (GitHub, Stripe v1, Slack v0) it handles. It distinguishes itself from siblings hash_text and verify_jwt by name.

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?

Explicitly routes alternatives: 'For plain digests use hash_text; for JWTs use verify_jwt,' and confines sha1 to legacy webhooks. The sign-vs-verify mode distinction and the verify-requires-signature condition are stated outright.

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 confirm readOnly/idempotent/non-destructive, and the description layers on substantial extra context: coverage has no free tier (10 free utilpeek calls/IP/UTC day), per-mode prices (USD 0.001 vs 0.01), 422-not-charged error semantics, latencies (0.2-10 s / 3-18 s), a daily snapshot, a 25-route probe cap, and a prompt-injection warning. This is unusually rich disclosure for a read-only 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 purpose is front-loaded in the first sentence and the dense run of facts (inputs per mode, errors, timing, pricing) each carries decision-relevant information. It is somewhat long and restates the title, but there is little true 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 dual-mode, zero-required-param tool with an output schema and full annotation coverage, nothing needed to call it correctly is missing: mode selection, mutually exclusive inputs, cost, error behavior, latency, and safety guidance are all present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the cross-parameter constraint not fully stated in the schema: 'mode lint: exactly one of listing or url; mode coverage: exactly one of host or openapi_url.' It reinforces mode/param coupling as a rule rather than leaving it as a per-field hint, though syntax detail still lives in the schema.

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

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

The description states a specific verb+resource ('Lint an x402 listing, or check a seller's Bazaar coverage') and clearly separates the two modes. It names what each mode returns and explicitly distinguishes itself from the sibling x402_seller_report, so an agent can route 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?

It gives explicit routing: mode lint for a single listing (send listing or url), mode coverage for a seller's paid routes (host or openapi_url), and names x402_seller_report for price position, preflight and demand. It does not, however, distinguish itself from other nearby siblings such as x402_listing_audit or x402_payment_status, which is the remaining 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?

Beyond the safey annotations (readOnly/idempotent/openWorld), the description discloses error semantics (503 when all sources are down, 422 for no barcode, both uncharged), latency by input type, pricing, ODbL licensing with sources never merged, conflict/test-data flagging, and a prompt-injection warning. This is unusually rich behavioral 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?

It is dense and long, but front-loaded with the core purpose and routing before secondary facts (latency, price, docs). Every sentence carries operational information; the price/latency lines are useful though slightly additive to the core definition.

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

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

An output schema exists, so return-value documentation is not required, yet the description still summarizes what comes back (check digit, GS1 prefix, four databases side by side). Given the tool's complexity and multi-source nature, nothing an agent needs before calling 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 per-parameter syntax is already documented. The description adds a genuine constraint absent from the schema — that exactly one of code/image_url/image_base64 must be supplied — which materially affects how the agent invokes the tool.

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 precise verb+resource ('look up the product behind a barcode in open product databases') and immediately differentiates itself from three named siblings (make_barcode, read_qr_barcode, validate_identifier). An agent can select it correctly 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?

Explicit routing is given: make_barcode for producing codes, read_qr_barcode for reading all codes in an image, validate_identifier for other identifiers. It also states the input contract ('exactly one of code, image_url or image_base64'), leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on real behavioral context: ambiguity handling with `candidates`, portability caveat (original range holder, not current network), offline metadata, 422 on bad input with no charge, sub-0.1s latency, pricing, and a free tier.

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 and the content is dense with little redundancy. However it is a single run-on paragraph that also carries pricing, free-tier, latency, privacy and docs details, which makes it somewhat overloaded and harder 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?

Complete for this tool: input modes, error behavior, cost, latency model, privacy, and a docs link are all present, and return values are explained even though an output schema exists. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter and the baseline would be 3. The description adds value by spelling out the inter-parameter contract (region+prefix vs. list+region, national form listing candidate countries), which the per-field schemas state only in isolation.

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 (look up) plus the exact resource (phone number prefix) and the payload (country, line type, original network). It also distinguishes itself from the sibling parse_phone_number by name, so an agent can route correctly without opening either schema.

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

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

Explicitly routes full numbers to parse_phone_number and describes both modes: prefix with optional region, or `list: true` with region and no prefix. It also explains the national-form-without-region case, giving complete 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?

Goes well past the annotations: check-digit validation producing a 422 invalid_checksum, independent ZXing-C++ re-decode with verified/decoded_text, a 500 verify_failed on mismatch, and explicit 'not charged' guarantees. It also discloses latency (under 0.1 s), price (USD 0.001), and the free tier of 10 calls per IP per UTC day.

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 and alternatives, then output shape, then error/pricing detail. Every sentence carries information, though the middle sentences are long and run together, costing some scannability.

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 5-parameter generation tool with an output schema, an agent still gets return fields, error codes, charge behavior, timing, and rate limits. Nothing needed to call it correctly or interpret a failure 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 real meaning: it explains that `output` "url" yields a 24-hour link and that only certain symbologies (ean13, ean8, upca, isbn13) carry a check digit that must be correct. That goes beyond the enum labels.

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 ('make a 1-D barcode image') and explicitly separates it from the QR tool (make_qr_code) and the lookup tool (lookup_barcode_product). An agent can route to it 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?

Names the alternatives and the condition selecting each: QR codes go to make_qr_code, product lookups go to lookup_barcode_product. It doesn't cover the decode-side sibling (read_qr_barcode), but for the generate direction the routing 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?

Goes well past the annotations: local encoding with nothing fetched, sub-0.1 s latency, 422 on data too long and explicitly not charged, price USD 0.001, and 10 free calls per IP per UTC day. The 24 h expiry on url output is exactly the kind of side effect an agent needs before choosing that mode.

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 and alternatives, then returns, failure mode, operational facts, and pricing. Dense and mostly earning its place, though the doc link and price/free-tier run together in a way that reads like a listing rather than prose.

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

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

Even though an output schema exists, the description names the return keys so an agent can pick a format correctly, and covers failure, cost, latency, and persistence. Nothing needed to call this tool correctly is missing.

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

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

Schema coverage is 100% with enums on error/format/output, so the baseline is 3; the description still earns credit by tying format/output to concrete return fields (`svg` text vs `data_base64`, `url` link) and by explaining that error level drives the 422 payload-limit failure. It does not add much on scale/border 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 and resource ('make a QR code image') and immediately scopes the output formats (SVG or PNG). It also names the exact siblings it is not — make_barcode for 1-D codes and read_qr_barcode for decoding — so an agent can route without opening a schema.

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

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

Explicit routing to alternatives with the condition that selects them ('For 1-D barcodes use make_barcode; to read a code use read_qr_barcode'), plus guidance on choosing between inline base64 and the 24 h url output. This is about as close to when-to-use/when-not-to as a generation tool gets.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses the 1 MB input cap, the 2,000-event cap with a `truncated` marker, that only VEVENT is returned (to-dos/journals/alarms skipped), that unknown TZIDs stay floating with a per-event warning, that all-day `end` is inclusive, that non-VCALENDAR input yields an uncharged 422, typical latency, price, and the untrusted-data warning. This is the exact behavioral context annotations cannot carry.

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

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

Front-loads purpose and the sibling disambiguation, then layers constraints, error behavior, and economics in short clauses. Dense but nearly every sentence carries actionable fact; the price/free-tier/docs sentences edge toward boilerplate but are genuinely decision-relevant for a paid x402 endpoint.

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

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

An output schema exists, so return shape need not be restated, and the description fills every remaining gap an agent needs: input envelope, truncation behavior, filtering of non-VEVENT components, timezone edge cases, error semantics, and cost. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents `ics`, `timezone`, and `max_events`. The description mostly restates those semantics ('optional `timezone` for floating times and `max_events`'), adding only the unknown-TZID fallback rule, which is worth having but does not exceed the baseline for fully documented schemas.

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 ('Parse an iCalendar file into JSON events') and immediately distinguishes itself from the sibling it is not: 'To write one use build_ics_event.' An agent can route between the two calendar tools without opening either schema.

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

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

Explicitly names the alternative tool (build_ics_event) for the write direction, and the pricing/free-tier lines imply the conditions of use. It stops short of stating when this tool is the right choice versus e.g. expand_rrule or convert_time, so it is clear context 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 declare readOnly/idempotent/non-destructive/openWorld, and the description adds the traits annotations cannot carry: 422 errors are not charged, 'valid' means numbering-plan conformance only (not assigned, in service or reachable), 'carrier' is the original range holder so ports go undetected, the input is processed in memory and never logged or stored, and latency is under 0.1 s. This is exactly the extra context the lower bar with annotations calls for.

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 routing, then caveats; every sentence carries distinct information (errors, validity semantics, privacy, cost, quota, docs). It runs long and packs pricing/quota/docs into the same paragraph as behavioral caveats, but there is little filler to cut.

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

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

With an output schema present, return values need not be described, and the description covers what remains: cost, free-tier quota, error behavior, the precise meaning of the reported fields, privacy handling, and a docs link. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description goes further by explaining the interaction between the two fields: a national-form number without a region is a 422, which tells the agent why 'region' matters and when it is mandatory even though the schema marks it optional. That is real semantic value beyond the schema text.

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

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

States a concrete verb+resource ('parse and format a phone number') and immediately scopes it as a numbering-plan check, which separates it from the sibling lookup_phone_prefix. An agent can pick it over the other identifier/contact tools 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?

Names the alternative tool explicitly and the exact condition that selects it ('For a prefix's country and network use lookup_phone_prefix'), and gives a when-not boundary (a non-phone string, or a national form without region, returns 422). Routing is fully determined, not left 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 read-only, idempotent, non-destructive safety, and the description adds substantial context beyond them: PSL snapshot date (2025-04-07) and its known staleness, handling of the PSL private section, that credentials are never echoed, that unparseable URLs return 422 without charge, typical latency, and pricing/free-tier 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?

Purpose and the sibling distinction are front-loaded, and the remaining detail (PSL limits, credential handling, 422, latency, price, docs) all earns its place for an agent deciding whether to call. The single dense paragraph with stacked parentheticals is slightly run-on but not wasteful.

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

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

With an output schema present, return values need not be described, and the description still covers the operational envelope an agent would otherwise guess at: no fetching, privacy of credentials, known PSL staleness, error semantics, cost, and rate 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?

Only one parameter and the schema already documents it at 100% coverage ('URL to parse (never fetched).' with min/max length). The description adds behavioral context around the URL but no additional syntax, format, or normalization detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('parse a URL') and explicitly contrasts with the fetching sibling ('To fetch the page use render_page ... The URL is parsed, never fetched'). An agent can distinguish this from render_page, fetch_page_contents, and search_with_contents 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?

Names the alternative (render_page) and the condition that routes to it, and reiterates that this tool never performs network fetches. This is explicit when-to-use/when-not guidance rather than implied context.

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

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

Adds substantial context beyond the annotations: warns that User-Agent is self-reported and spoofable, that is_bot is a heuristic covering declared crawlers, HTTP libraries, and headless browsers, and discloses latency budget and engine provenance (ua-parser/uap-core). It also conveys pricing and free-tier quota. None of this is in 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?

Front-loaded with the purpose, then caveats, engine, latency, and pricing. Multiple ideas in one block, but every sentence earns its place; the only minor concern is that pricing/docs info might be better segmented.

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?

Complete for a single-parameter parse tool: it explains what is parsed, the heuristic nature of is_bot, the engine, latency, and pricing, and it routes to the sibling for x402 detection. Output schema covers the return shape, so nothing 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?

Only one parameter, so the 100% schema coverage already handles it. The description adds the 1-1024 char bound via the schema reference and clarifies the semantic nature of the input (self-reported string) which the schema doesn't.

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 ('parse a User-Agent string') with the returned dimensions (browser, OS, device, bot) named in the title. It is clearly distinguished from parse_url, parse_phone_number, and identify_x402_client, which it explicitly routes away from.

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?

Explicitly names the alternative (identify_x402_client) for known x402 monitors/indexers, including the differentiator ('with call rates'). This is proper when-to-use/when-not routing rather than vague hints.

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 safety, and the description adds substantial context beyond them: the answer comes from the SML DNS record, a DNS hit means reachable rather than verified, unreadable SMP still returns DNS plus `smp_error`, bad IDs are 422 and outages 503 with neither charged, and typical latency is 0.2-2 s. Pricing (USD 0.002) and the 10-free-calls-per-IP-per-day limit further inform invocation decisions.

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, then caveats, error semantics, latency, pricing and docs follow in a logical order. It is dense and runs long, but nearly every sentence carries decision-relevant information, so little 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?

An output schema exists, yet the description still flags the key return semantics (SMP URL, labelled vs raw document types, smp_error fallback) and all failure modes with status codes, latency and cost. For a read-only, open-world lookup with two parameters, nothing an agent needs before calling it is missing.

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

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

Schema description coverage is 100%, so both `scheme` (only iso6523-actorid-upis) and `participant` (ICD:identifier format, accepted full form) are already fully documented. The description repeats the example ID but adds no syntax or constraint detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Check whether a company is registered on the Peppol e-invoicing network') and immediately scopes the input as a participant ID such as 0192:983887457. It also distinguishes itself from the legal-entity sibling by pointing to search_lei, so an agent can separate it from lookup_lei/search_lei without opening either schema.

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

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

Gives clear context (Peppol network registration/reachability) and an explicit alternative for a related need ('For the legal entity use search_lei'). It does not spell out a full when-not-to-use list (e.g. versus validate_identifier), but the routing guidance is concrete and actionable.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses latency (0.5-2 s), price (USD 0.002), a free-tier rate limit (3 calls per IP per UTC day), a failure mode ('Damaged or tiny codes may be missed'), a security posture ('Images are never logged or stored') and prompt-injection guidance for the decoded payload. That is unusually rich behavioral context for a read 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?

Front-loaded with the core action and the sibling routing before moving to output detail, price and caveats. It loses a point for a duplicated untrusted-data warning appearing twice in slightly different wording, which is minor waste in an otherwise dense, earned block of 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?

For a zero-required-parameter read tool with an output schema, everything an agent needs is present: input alternatives, return shape, exclusions, latency, cost and rate limit. Nothing material is missing even though the output schema already covers return values.

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 already 100%, so the baseline is 3, but the description adds real meaning on top: it explains the emv field emitted when parse_emv triggers, the 000201 EMVCo prefix and supported schemes, and the CRC check performed. It does not restate the url/image_base64 alternatives, which the schema handles.

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 ('Read every QR code and barcode in an image') and explicitly distinguishes itself from siblings, routing QR generation to make_qr_code and plain text extraction to ocr_image. An agent can pick this tool versus its neighbors 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?

Names two concrete alternatives with the condition that selects each ('To make a QR code use make_qr_code; for other text use ocr_image'), and adds negative guidance by listing unsupported symbologies (Data Matrix, PDF417, Aztec). Nothing about when to use this is left 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?

Goes well beyond annotations: offline sandboxed browser with strict security and no network, Mermaid 11.4.1, typical latency 1-3 s, USD 0.003 price with no free tier, and the full failure surface (422 invalid_diagram with line number, 422 over 8,000x8,000 px, 413 for PNG over 8 MB, none charged). That is exactly the operational context an agent needs before spending money on a retry.

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 action and output, then packed with limits, errors and pricing; nearly every clause carries information. Minor waste in restating the title ('Returns Mermaid diagram code drawn as an SVG or PNG file') and the terse backtick style makes it dense but still readable.

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

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

An output schema exists, so return shape needn't be described, and the description still covers cost, latency, size caps, error codes and the url-vs-base64 retention difference. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so all five parameters are already documented, including enums for format, theme and output. The description largely restates the same option sets (svg|png, theme list, scale 1-4, url 24 h) rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource (render Mermaid diagram code) plus the concrete output forms (SVG or PNG file). No sibling in the list overlaps, so an agent can select it unambiguously from the name and first sentence alone.

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 input being Mermaid source and the description notes format/theme/scale trade-offs (svg scalable vs png, scale for zoom, base64 vs 24h url). It never states when to prefer this over alternatives (e.g. make_qr_code or upload_file_get_link) or any preconditions/exclusions, leaving routing to inference.

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