Duo Data Utilities: IBAN, ISIN, VAT & Tax ID, Barcode, Timezone, Geo APIs

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

Going beyond the readOnlyHint=true/openWorldHint=false/idempotentHint=true annotations, the description discloses the coverage scope (airports worldwide with IATA codes and scheduled service), the return shape (matched code type and distance in km), and the cost model ($0.05 per successful call via x402/USDC on Base). The pricing detail is genuinely useful behavioral context. It doesn't mention rate limits or caching, but the extra disclosure is solid.

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 verb+resource, then attributes, then the proximity mode, then return/cost. It's a dense two-sentence block with slight redundancy between the title and the first clause, but every element serves a purpose.

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

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

For a read-only lookup tool with 100% parameter schema coverage and no output schema, the description covers scope, both invocation modes, return contents, and pricing. The absence of an output schema means the description carries more burden, and it mostly does – only the exact response structure is left implicit, which is minor.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (code, near, limit, country, radius_km) with formats and ranges. The description adds only high-level mode descriptions (code vs. proximity) rather than any per-parameter meaning beyond the schema. Baseline 3 is correct.

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 (lookup of an airport by IATA/ICAO code) and names the exact attributes returned (name, city, country, region, coordinates, elevation, IANA tz). It also names a second mode (nearest airports by coordinate), which distinguishes it from all siblings without needing to open 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?

The two modes are described (code lookup vs. proximity via coordinate+radius), giving clear context for how to call the tool. However, there is no explicit when-not-to-use guidance or named alternative siblings (e.g., geo_distance or country_lookup) that an agent might confuse it with.

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

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

Annotations already declare readOnly, idempotent, and closed-world behavior, so the safety profile is covered. The description adds meaningful context beyond the schema: arbitrary precision beyond 2^53, digit validation, input length cap, prefix handling, and a clear pricing model with payment rail. That last detail is important for cost-aware invocation.

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

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

The description is one dense sentence followed by a payment note. It front-loads the core capability and scope, but the run-on structure packs multiple behavioral details into a single clause, which slightly reduces 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 five-parameter, no-output-schema conversion tool, the description covers the essential behavioral facts: precision guarantees, validation, input limits, and the return shape (target base, decimal, bit length, digit count). It is nearly complete, though it could explicitly note that invalid digits produce an error rather than a partial result.

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

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

Schema coverage is 100%, so all five parameters are documented with types, enums, defaults, and accepted values. The description adds context about sign and prefix handling for the value parameter, but does not add format or syntax details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description names a specific verb (convert) and resource (integer between bases 2–36), and explicitly enumerates the scope (hex, binary, octal, arbitrary precision). The sibling tools are all unrelated operations, so the tool is unmistakably distinct.

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

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

The description implies the tool's scope through examples but provides no explicit when-to-use or when-not-to-use guidance. For a tightly scoped numeric conversion utility, this is adequate but leaves the agent to infer that it is only for integer base conversion.

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/no-open-world, and the description goes well beyond them: it discloses the return contents (result date, day count, skipped dates with reasons), the 1,000-entry truncation cap with skipped_truncated flag and exact skipped_total, and the $0.05 x402/USDC-on-Base pricing requirement. That is exactly the operational context annotations cannot express.

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

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

Four sentences, all front-loaded and information-dense: capability first, then calendar semantics, then output/truncation behavior, then pricing. No filler, though the pricing sentence is appended without transition and packs several facts.

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

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

With no output schema, the description does the heavy lifting by summarizing return fields and truncation flags, and it covers both operations, the weekend/holiday model, and payment. A full field-level return spec and pagination/count semantics are not given, leaving a small gap for a 7-parameter tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that the weekend mask supports non-standard weeks (Friday-Saturday, Sunday-only) and that holidays are an explicit list so nothing relies on a stale table. That is genuine semantic value for the weekend and holidays parameters.

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 ('business days calculator... add or subtract N working days... or count the working days between two dates') and immediately frames the caller-supplied calendar, which separates it from siblings like calendar_convert, dst_transitions and rrule_expand. An agent can identify the tool's job without opening the schema.

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

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

The description distinguishes the two modes (add vs count) and notes the calendar is caller-supplied, so usage is implied, but it never names an alternative tool or states when this is the wrong choice versus recurrence or conversion tools. Implied usage only.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower, and the description adds genuinely new behavioral facts not in the schema: it uses runtime calendar support, names the algorithm in every response, and discloses a $0.05 per-call cost paid over x402 (USDC on Base). That pricing constraint is decision-relevant for an agent. It stops short of explaining error behavior for invalid dates or out-of-range years.

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 clause, and the sentence packing is dense but not padded — every clause (calendar list, Easter, runtime basis, algorithm naming, price) carries information. The price disclosure at the tail is slightly abrupt 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 no output schema, the description does some work in that direction by promising the algorithm name in every response, and it fully covers the operation space and all calendar targets. Annotations cover safety, so remaining gaps — exact response shape formalities and failure modes for bad dates or years outside 326-9999 — are minor for a read-only, idempotent converter.

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 3 is the baseline, but the description adds real semantic mapping: 'Islamic (both the tabular civil calendar and the Umm al-Qura variant)' disambiguates islamic vs islamic-umalqura, and 'Easter Sunday ... in both the Gregorian and Julian reckonings' clarifies the rite western/eastern enum. This is meaning beyond the schema strings, so it earns above baseline.

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

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

Specific verb (convert) plus resource (Gregorian date → other calendar systems), with the supported calendar systems enumerated concretely and an additional distinct operation (Easter computation) called out. An agent can separate this from siblings like timezone_convert or base_convert purely from the text, since the calendrical conversions named (Islamic, Hebrew, Japanese era, ROC, Buddhist, Persian) are unique to this tool.

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

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

The description implies usage via its two operations — convert a date, or compute Easter for a year — but never states when to prefer this tool over siblings (e.g., timezone_convert) or any exclusions/preconditions. The routing between convert and easter is really left to the schema's op enum rather than explained as guidance in the prose.

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 (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower; the description adds genuinely useful behavior: exact pricing ($0.05 per successful call, paid over x402 in USDC on Base) and case/accent-insensitive name matching. It does not describe failure behavior for unmatched codes or whether subdivision resolution returns a different shape.

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

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

Front-loaded with the lookup capability, then return fields, then edge cases, then price. Dense but every sentence carries information; the pricing sentence is somewhat tangential but materially affects invocation decisions for a paid tool.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: all code systems, official/common names, UN M49 region, currencies, TLD, and the optional subdivision list with types. Combined with the paid-call and matching-behavior notes, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that 'include' controls the optional full ISO 3166-2 subdivision list with each subdivision's type, and that 'code' also accepts subdivision codes like NL-NH. It does not add syntax or default details beyond the schema's own 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 precise verb+resource ('find a country or territory') and enumerates exactly what is returned: codes, names, UN M49 region, currencies, TLD, and optional ISO 3166-2 subdivisions. It also distinguishes itself from the ISO 3166-2 subdivision-resolution case and from siblings like nuts_region_lookup and currency_lookup by scoping to ISO 3166 data.

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

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

Gives clear context for when the tool applies: lookups by alpha-2/alpha-3/numeric code, by name, or by an ISO 3166-2 subdivision code, and notes that names are matched case- and accent-insensitively. It stops short of explicitly naming an alternative (e.g., nuts_region_lookup) or stating when not to use it, so it lacks true when-not routing.

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

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

Annotations already cover readOnly/idempotent/openWorld=false, so the description's added value is in return semantics and cost: it discloses the ambiguous-multi-chain result, the checksummed EVM form, and failure reasons including unrecognised_format, plus x402 pricing. It does not state auth setup beyond payment or any rate limits, leaving a modest gap for a payment-gated 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?

Purpose is front-loaded in the first clause and the chain/algorithm enumeration is dense but genuinely informative rather than filler. The two-sentence structure is efficient, though the long chain list is close to the edge of what an agent needs before calling.

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-chain parser with no output schema and three parameters, the description covers the return shape (valid chains, ambiguity, checksummed form, failure reason) and pricing well. It omits what happens when `expect` conflicts with the detected chain and says nothing about payment mechanics beyond the price, minor gaps given the otherwise thorough coverage.

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

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

Schema description coverage is 100% and the enum values for expect are fully listed in the schema, so the baseline is 3. The description explains what the underlying validation checks per chain but never mentions the `expect` or `chain_id` parameters or how they alter behavior (e.g. EIP-1191 chain-salted checksums), adding little beyond the schema.

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

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

The description states a specific verb+resource (identify a blockchain from an address and validate its encoding) and enumerates the exact algorithms and chains covered (EIP-55, base58check, bech32/bech32m, SS58, Tron, XRP, etc.). This makes it immediately distinguishable from sibling validators like iban_validate or gtin_barcode_validate 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 clear context: the tool returns every chain an address is valid for and flags ambiguity when several match, which tells the agent when this tool is appropriate. It also discloses the payment requirement ($0.05 per successful call via x402), which is practically necessary usage context. It stops short of naming alternatives or stating when-not to use it, so it is not 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 cover the safety profile (readOnly, idempotent, closed-world), and the description goes well beyond them by disclosing the payment/auth requirement: $0.05 per successful call settled over x402 with USDC on Base. That cost and payment-protocol detail materially affects whether and how an agent should invoke the tool, and it is not available anywhere 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 operation, then the returned fields, then the negative scope, then cost. The sentences are dense but each carries distinct information; the enumeration of return fields is long but not redundant with the schema. Minor trimming would be possible in the field list.

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

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

With no output schema, the description carries the return-value burden and does so well by naming each returned field plus the rounding increment use case. It also closes the exchange-rate expectation. The remaining gap is that all three parameters are optional, and the description never says what a no-argument call yields.

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 code, country, and include with their accepted formats, making 3 the baseline. The description adds only a light gloss on include ('historic codes on request') and does not clarify whether code and country are mutually exclusive or what happens when neither is supplied.

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 ('Currency lookup by ISO 4217 alphabetic or numeric code') and enumerates the exact facts returned (name, minor-unit exponent, fund flag, cash rounding, territories, historic codes). It also carves out negative scope ('returns currency facts only and never an exchange rate'), which prevents confusion with rate tools. It does not, however, differentiate itself from the adjacent sibling country_lookup, which a caller could easily reach for by mistake.

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

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

It gives a purpose statement ('the correct rounding increment for cash amounts, which is what a caller needs to render or settle a price') that implies when the tool is useful. But there is no explicit when-to-use vs when-not, no alternative named, and no guidance on whether the code, country, or include path should be chosen for a given task. Usage is inferable rather than stated.

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

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

Annotations cover the safety profile (readOnly, idempotent, closed-world), so the bar is lower. The description adds real value beyond them: the returned fields, the UNSUPPORTED_VALUE rejection for other scripts, and the $0.05 x402/USDC-on-Base payment requirement — non-obvious operational context an agent cannot infer.

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

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

A single dense paragraph that front-loads the core purpose and standard semantics before returning to outputs and pricing. Every sentence carries information, though the pricing clause is appended abruptly rather than structured.

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

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

With no output schema, the description compensates by enumerating the return fields (transliteration, source script, standard, mapped fraction, unmapped characters) and the error path. Limits and enums live in the schema, so the definition is essentially complete 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 the baseline is 3, but the description adds semantic meaning the schema does not: ISO 9 is one-to-one with diacritics and full coverage, while BGN/PCGN is Russian-only with pass-through for unmapped characters. That materially clarifies the 'standard' parameter's behavior.

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

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

States a specific verb and resource ('Cyrillic transliteration to Latin') and names the two supported standards, distinguishing it from every sibling (none of which do transliteration). The scope — which scripts and letters each standard covers — is explicit.

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

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

The description clearly explains how to choose between the two standards: ISO 9:1995 for full Slavic/historic/non-Slavic coverage, BGN/PCGN for Russian only, with non-Russian letters passed through unmapped. It stops short of explicit when-not-to-use guidance, but the tradeoff is well communicated.

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

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

Annotations already establish read-only, idempotent, non-open-world behavior, and the description adds genuinely new traits beyond them: the per-call price and payment rail ($0.05 via x402/USDC on Base) and the no-DST empty-list semantics. It still doesn't disclose rate limits or output ordering, but the added context is substantive.

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 the return contents, then edge case, then price. Dense but every sentence carries information; the pricing sentence is somewhat extraneous to invocation but is legitimately relevant to an agent deciding whether to 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?

With no output schema, the description steps in to describe the return shape (exact instant, offset before/after, jump forward/back, current offset/DST state, next transition) and the no-DST edge case, which is exactly what an agent needs. Minor gaps remain around ordering and pagination for multi-year ranges.

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 'from', 'zone', and 'years' are already fully documented in the schema. The description restates the range and from-instant concepts but adds no syntax, format, or default detail beyond what the schema provides — 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?

Opens with a specific verb+resource ('DST transitions: list the daylight-saving time changes for an IANA time zone') and states the scope (date range) plus exactly what each result contains. This is clearly distinguishable from sibling timezone_convert, which converts a timestamp rather than enumerating transitions.

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 clear context for when the tool applies (IANA zone + date range, next transition from a given instant) and an edge-case rule (zones without DST return an empty list, not an error). It never explicitly names an alternative sibling or a when-not condition, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the Vincenty-with-haversine-fallback algorithm, supported output units, and a concrete pricing/auth model ($0.05 per successful call via x402 USDC on Base).

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 operation and resource, then operations, then results and pricing. Dense but every clause carries information; the pricing sentence is non-obvious and worth its space, though the first sentence is long enough to require re-reading.

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

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

No output schema exists, so the description must explain returns, and it does specify the result units and the quantities produced (distance, bearings, midpoint, destination, cumulative path length). The only gap is that it never clarifies the zero-required-parameter design or how invalid combinations of op and inputs are rejected.

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 earns above that by tying parameters to outcomes (e.g., 'destination point reached from a start point on a given bearing and distance') and stating that results come back in metres, kilometres, nautical miles and miles. It adds cohesive meaning without duplicating schema syntax.

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 ('distance and direction between WGS-84 coordinates') and enumerates the five operations (distance, destination, midpoint, path) plus the algorithm (Vincenty with haversine fallback). This clearly differentiates it from siblings like point_in_polygon and geohash_encode_decode.

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

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

Usage is implied by the operation list and the schema's op enum, so an agent can infer when each mode applies. However, there is no explicit when-to-use guidance, no mention of prerequisites, and no routing to alternative sibling tools for related geo tasks.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. The description adds genuinely non-derivable behavior: encoding returns the eight neighbouring cells and decode returns centre point plus error bounds in metres. It also discloses the $0.05 per successful call x402/USDC-on-Base payment, which is real operational context an agent must know before invoking. It does not describe failure modes or what counts as an unsuccessful call.

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

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

Two sentences, front-loaded with the core encode/decode purpose before the return-value and pricing details. Every clause carries information, though the pricing sentence is somewhat dense and could be separated for scanability.

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

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

With no output schema, the description correctly compensates by naming the return values (bounding box, centre point, error bounds, neighbours). It also covers cost and payment rail. Only input-validation behavior and an explicit mode-default reminder are absent, which is a minor gap for a 5-param, 0-required tool.

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

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

Schema description coverage is 100%, so op, lat, lon, geohash and precision are all documented with accepted values and defaults. The description restates the encode/decode split and the precision concept but adds no syntax, format or edge-case detail beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The description states a specific verb and resource ('encode a WGS-84 latitude and longitude to a geohash', 'decode a geohash back to its bounding box') and enumerates both modes up front. It also names the extra artifact (eight neighbouring cells), so an agent knows exactly what the tool produces. The only sibling in the same domain, plus_code_encode_decode, is distinguishable by the geohash-vs-plus-code resource 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?

It gives a concrete usage scenario: the neighbour cells are 'what a caller needs to do proximity search over a geohash-indexed store without a spatial database.' That tells the agent when this tool is the right pick. It stops short of naming an explicit alternative or when-not condition (e.g., versus geo_distance or point_in_polygon).

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

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

Annotations only cover the read-only/idempotent safety profile; the description adds substantial behavior beyond that: the exact return contents (check-digit verdict, computed correct check digit, GTIN-14 form with indicator digit, conversions), the absence of company-prefix data and why, and the $0.05 x402 payment model. This is exactly the extra 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?

Information is front-loaded with the capability statement first, followed by returns, exclusions, and pricing. It is dense with colon-separated lists rather than flowing prose, but every clause carries real information, so overhead is low.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it discloses scope limits and the payment requirement. For a 3-parameter read-only validator, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents op, to and value including their enums and the checkdigit omission rule. The description only echoes these (partial code for check-digit computation, conversion between formats) without adding format or syntax detail beyond the schema, 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 ('validate and convert GS1 identifiers') and enumerates exactly which identifier families it handles (GTIN-8/-12/-13/-14, GLN, SSCC). An agent can distinguish it from siblings like iban_validate, vat_tax_id_validate or isin_cusip_sedol_validate without opening the schema.

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

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

The description maps the three operations to intent ('validate', 'checkdigit' to compute a missing final digit, 'convert') and states a clear non-scope ('No company-prefix split is returned', 'Structure only, no product database'). It does not explicitly name an alternative tool, but no sibling overlaps enough to require one, so the guidance is clear rather than exclusionary.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so pure safety is covered. The description adds genuinely new behavioral context: the exact return payload (digest, input byte length, algorithm identifier) and the price/paid-over-x402 payment requirement, which the annotations do not capture.

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: capability, algorithms, encodings, and returns come first, with pricing last. The enumeration of algorithms is long but earns its place by scoping the tool; little waste overall.

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

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

Despite having no output schema, the description discloses the return shape (digest, byte length, algorithm identifier), input/output encodings, the HMAC option, and the payment model. Combined with annotations covering the safety profile, 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 aggregates meaning across parameters: it explains default input encoding (UTF-8 text), the output encoding options, and that HMAC is computed 'with any of them'. This lightly exceeds what the schema fields convey individually.

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 ('compute a cryptographic digest of supplied data') and enumerates the exact algorithm family, distinguishing it clearly from siblings like geohash_encode_decode or solidity_function_selector. An agent immediately knows this is a hashing/HMAC utility.

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 nature of the tool, but there is no explicit 'use this when... instead of X' guidance. With no close sibling alternatives (geohash/selector are unrelated), the omission is low-cost, leaving this at the minimum-viable level.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. The description adds substantive behavior beyond that: check-digit algorithm (ISO 7064 mod-97-10), zero left-padding to registered widths, return in electronic and print formats, 89-country SWIFT registry coverage, and the $0.05 x402/USDC on Base price. That is real operational context 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?

Four sentences, front-loaded with purpose, then input modes, then return behavior, then coverage and price. Every sentence carries information, though the price/payment sentence is dense and slightly interrupts the technical flow. 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?

No output schema exists, so the description must cover returns – and it does, stating electronic and print formats plus the parsed bank/branch/account parts. Combined with the algorithm and coverage details, an agent has everything needed to call and interpret the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond it by explaining the padding rule for digit fields and the constraint that named parts must span the whole BBAN (otherwise pass BBAN), which the schema does not state. It adds genuine semantic value over the field-level 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?

Specific verb+resource: 'construct an IBAN from a country code and the domestic account parts, computing the ISO 7064 mod-97-10 check digits.' This clearly contrasts with the sibling iban_validate (generation vs validation). An agent can route 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?

Gives conditional guidance: 'Takes a single BBAN string or named parts... Named parts work only where they span the whole BBAN; else pass the BBAN.' This tells the agent which input shape to pick. It stops short of explicitly naming iban_validate as the tool to use for the opposite operation, so there is no 'when-not' exclusion.

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

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

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the bar is lowered. The description adds pricing ($0.05 per successful call via x402 on Base) – a paid-call constraint not in the annotations – plus the 'no existence check' limitation, both useful beyond the structured fields.

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

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

Three tightly packed sentences: what is checked, what is returned, what it does not cover – with the payment note last. No filler, front-loaded with the verification mechanics.

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

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

For a one-parameter read-only validator with no output schema, the description fully covers the check performed, the 89-country scope, the return fields (verdict, reason, electronic/print formats, decomposed codes) and the pricing/caveat. Nothing an agent needs to decide or invoke correctly is missing.

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

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

Schema description coverage is 100%: the single `iban` parameter already documents space stripping, case handling and the 64-char cap. The description adds nothing format-wise 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 precise verb+resource ('validate an IBAN's length... check digits') and enumerates exactly what is checked (country length, character classes, ISO 7064 mod-97-10). It is clearly distinguishable from the sibling iban_generate, which produces rather than validates an IBAN.

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

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

The scope is well framed: 'Structure and checksum only, it does not confirm the account exists' explicitly tells the agent when this tool is insufficient. It does not name iban_generate as the alternative, but validation vs generation is unambiguous from the name pair.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the safety profile is covered. The description adds context the annotations do not: the exact return contents (verdict, computed correct check character, country prefix, embedded NSIN) and the pricing model ($0.05 per successful call via x402/USDC on Base), which is materially useful for an agent deciding whether to spend.

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 identifier families and the core action, followed by return contents, scope limitation, and pricing. Every sentence carries information, though the pricing clause slightly interrupts the functional description.

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

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

With no output schema, the description carries the return-value burden and does so explicitly (verdict, correct check character, country prefix, NSIN). All four parameters, both operation modes, and the safety/pricing context are accounted for, leaving nothing an agent needs 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 description coverage is 100%, so the schema already documents op, nsin, value, and country fully. The description restates the build path ('a country code plus a 9-character NSIN') but adds no format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

Names specific verbs (validate check digits, build an ISIN) and concrete resources (ISIN per ISO 6166, CUSIP, SEDOL, FIGI). This clearly distinguishes it from sibling validators like gtin_barcode_validate, iban_validate, and vat_tax_id_validate, which cover different identifier families.

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 bounds the tool's scope with 'Format and checksum only, no security master lookup,' which tells the agent when this is and is not sufficient. It does not name a specific alternative tool for the lookup case, so it stops short of full when/when-not routing.

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

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

Annotations cover the safety profile (readOnly, idempotent, closed-world), and the description layers on real behavioral detail beyond them: the exact return contents, structural-failure reporting (missing part, invalid base64url, alg none), and the commercial constraint of $0.05 per successful call over x402. The cost/auth disclosure is especially valuable for an agent deciding whether to invoke.

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 critical scope qualifier (no signature verification) is front-loaded in the first clause, and the price/auth note is correctly placed last. It is dense with parentheticals but every clause carries information; nothing is padding.

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

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

With no output schema, the description carries the full burden of describing returns, and it does: header, claims, signature length and algorithm, computed time-claim view, and structural error classes. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description adds the semantic tie between the 'at' input and the exp/nbf evaluation ('against a supplied or current instant'), which is mildly useful but largely restates 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 gives a specific verb (decode) and resource (JSON Web Token) and immediately scopes it ('without verifying it'), which no sibling tool overlaps. An agent can distinguish this from hash_generate or crypto_address_validate 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?

It states the decisive when-not condition explicitly: 'It does not and cannot verify the signature; do not use it to decide trust.' That prevents the most dangerous misuse. It does not name an alternative tool, but no sibling in the list performs JWT signature verification, so there is no better route to point at.

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 deterministic remainder distribution, ISO 4217 minor-unit exponent handling with JPY/KWD examples, explicit rejection of metals and XXX, and the $0.05 x402/USDC-on-Base payment requirement. The x402 cost disclosure is exactly the kind of operational 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-loaded with purpose and progresses logically to mechanics, currency handling and price. Slightly dense with some restatement of the rule names already enumerated in the schema, but 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?

Covers inputs, edge cases (zero- and three-decimal currencies, rejected metals/XXX), determinism, and pricing. With no output schema, it would be stronger if it sketched the return shape (e.g. a list of per-share amounts), which is the one remaining gap for a compute tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by explaining what the remainder rules do and why currency drives minor-unit exponent. It loses a point for naming only 'largest-remainder, first-wins or last-wins' while the enum also contains 'round-robin', so the prose is incomplete relative to 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 ('split a money amount into shares') plus the defining constraint ('without losing or inventing a cent'), which no sibling tool covers. An agent can distinguish it from currency_lookup or any other sibling immediately.

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

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

Explains the two usage modes ('divide evenly into N parts, or by a list of ratios') and the conditions under which each applies. It does not name alternatives or exclusions, but no sibling overlaps this function, so the context is sufficient.

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

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

The annotations already establish a safe, idempotent, closed-world read operation, but the description adds material context they cannot: a per-call price of $0.05 paid over x402 (USDC on Base) and a hard value ceiling of 10^15. Payment/auth requirement and input ceiling are genuinely useful behavioral disclosures 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-loaded with capability, then scoping, then pricing in a compact two-sentence block. No filler, and the most decision-relevant facts (languages, forms, currency handling) come first.

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 deterministic conversion tool with no output schema and fully documented parameters, the description covers capability, limits, currency edge cases and cost. The only gap is the unmentioned 'year' form value, which leaves the agent to discover it from the schema alone.

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 value, lang, case, form and currency. The description adds real semantic value on currency behavior (agreement plus minor-unit naming for 19 currencies, fraction fallback otherwise), but notably omits the schema's fourth form value, 'year', while claiming only cardinal/ordinal/currency exist.

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

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

The description opens with a specific verb+resource ('spell a number out') and immediately scopes it by language set, and by cardinal/ordinal/currency form. This clearly distinguishes it from siblings like base_convert, money_split or currency_lookup, which handle different jobs.

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 conveys form-specific rules (currency form agrees the number with the currency noun; other ISO 4217 codes fall back to a fraction) which implicitly tells the agent when each mode applies. However, it never states when to choose this tool over a sibling or names any alternative, so usage guidance is only implied.

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

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

Annotations already declare readOnly/idempotent and closed-world, so the bar is lower; the description still adds real context the annotations do not carry: the $0.05-per-call x402 (USDC on Base) payment model, the default value of 'include', and what the response contains. It omits error behavior and rate limits, so a 4 rather than 5.

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

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

A single dense paragraph but front-loaded with purpose and modes, then coverage, then return content, then price. Every clause carries information, though the first sentence packs several modes into one long clause chain.

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

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

With no output schema, the description does the work of describing returns (Latin and local-language names plus urbanisation, coastal and mountain typologies), scope, and pricing. It leaves the shape of hierarchy responses (how parents/children are returned) unspecified, so not quite a 5.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema. The description reinforces the code/hierarchy/name-search modes but adds no syntax or format detail beyond what the schema properties provide, making the baseline 3 correct.

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 ('NUTS region lookup') and enumerates the three operating modes: resolve a code to name/country/level, walk the hierarchy, or search by name. Explicitly scoped as EU statistical regions with NUTS 2024 coverage, which separates it from the generic country_lookup sibling.

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

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

The description makes clear which task each mode serves (code resolution vs. hierarchy traversal vs. name search), so an agent can pick the right call. It stops short of naming a sibling as an alternative or stating explicit exclusions, which keeps it from 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 establish readOnly, idempotent, and non-open-world behavior, so the safety profile is covered. The description adds material context beyond that: a per-call price of $0.05 paid over x402 in USDC on Base, which is an auth/payment requirement an agent must know before calling. It also states the shape of the returned data (code length, precision in metres, validity).

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

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

Three sentences, purpose front-loaded first, with operation semantics before the pricing note. The prose is dense but every sentence carries distinct information; slightly long for the value delivered, but nothing is 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?

No output schema exists, and the description compensates by naming the return fields (code length, precision, validity). Payment and the default op=encode are covered by the description and schema respectively. Only minor gaps remain, such as what an invalid code yields or error-shape expectations.

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 each property already documents its accepted values and which op it belongs to, so the schema does the heavy lifting. The description reinforces the op-to-parameter mapping (encode at a chosen length, shorten/recover against a reference coordinate) but adds no format or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

Names the specific resource (Plus code / Open Location Code) and enumerates the four concrete operations it performs: encode, decode, shorten, recover. An agent can distinguish it from the similarly-named sibling geohash_encode_decode without opening the schema, since the code system is stated explicitly.

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

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

Explains the context for each operation, notably that shorten/recover is 'how plus codes are normally exchanged in text', which tells an agent when those ops are relevant. However, it offers no explicit when-not-to-use guidance and never names an alternative sibling (e.g. geohash for a different grid system).

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, closed-world), and the description goes well beyond them: it discloses the pricing model ($0.05 per successful call over x402/USDC on Base), the geodesic-versus-planar distinction for area/length versus containment, correct hole handling, and the input size limits. Payment and coordinate-system behavior are exactly the kind of traits an agent cannot infer from structured fields.

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

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

Two dense sentences that front-load the core purpose and then the output set, with pricing last. No filler, though the enumeration of six outputs in one sentence makes it slightly heavy 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?

With no output schema, the description enumerates every returned value (bbox, centroid, area, perimeter, winding) and specifies units (square metres), so an agent knows what it gets back. Combined with the pricing and geometry-acceptance notes, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: it explains that area and perimeter are geodesic on WGS-84 while containment is planar in lon/lat, which resolves ambiguity the schema's 'comma-separated subset' text does not. The 'ops' semantics (default all) are stated in both places.

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 ('point in polygon check') and enumerates the full set of computed outputs: bbox, centroid, signed area, perimeter, winding order. It also names the accepted geometry types, so an agent can distinguish it from sibling geo_distance 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?

It describes what inputs are accepted (Polygon, MultiPolygon, or a Feature wrapping either) and implies the containment test runs when lat/lon are supplied, but it never states when to prefer this over related siblings such as geo_distance or when the containment op is inapplicable. Usage is implied from the input description rather than stated as 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?

Going well beyond the readOnly/idempotent annotations, it discloses the return payload (both forms, per-label breakdown, first rule violated), the specific validation rules applied, that strict mode may reject names, and the cost and payment path ($0.05 per successful call via x402/USDC on Base). This is exactly the extra 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?

Purpose is front-loaded and each sentence carries information (direction, validation, mode semantics, price). The dense enumeration of IDNA2008 rules and the garbled fragment 'it may reject names /v1/code/url displays' cost it a point on polish.

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

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

With no output schema, the description still tells the agent what comes back (both forms, per-label breakdown, first rule violated) and covers failure and cost. For a 3-parameter, single-purpose converter this is sufficient to call 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 both enums are already fully documented with defaults and the ß→ss example. The description restates the strict-mode semantics rather than adding new parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: convert internationalised domain names between Unicode and ASCII punycode in either direction, label by label. The scope plus the embedded IDNA2008 validation makes it clearly distinct from neighbours like cyrillic_transliterate or url_parse 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 explains the strict-vs-non-strict choice (IDNA2008 vs UTS 46 transitional) and warns that output can differ from browsers and URL displays, which implies when each mode applies. However it never says when to pick this tool over siblings such as url_parse or unicode_confusables_check, so tool-selection guidance 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?

Annotations already declare readOnly, idempotent, and non-open-world, but the description adds substantial behavior beyond them: a hard cap of 200 occurrences, dual local/UTC output, a gap:true flag on DST-shifted occurrences, rejection of rules requiring over 50,000 candidate evaluations, and the $0.05 x402/USDC-on-Base pricing. This is exactly the extra context an agent needs before invoking a paid, quota-limited 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, followed by inputs, capabilities, edge-case behavior, and pricing in compact order. It is dense but nearly every sentence carries information; the pricing clause is a slight tail-end addendum but still actionable.

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

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

With no output schema, the description correctly describes the return shape (local wall-clock plus UTC instants, gap flag, 200-item cap), the cost, and the computational rejection limit. Remaining gaps are minor: error behavior on malformed RRULE strings and pagination semantics for the after parameter are not described.

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 genuine value the schema lacks: it enumerates which RRULE parts are supported (FREQ, INTERVAL, COUNT, UNTIL, BYDAY, BYMONTHDAY, BYMONTH, BYSETPOS, WKST), which is the key uncertainty for a rule-expansion call. It does not clarify the after/skip semantics beyond the schema, so it falls short of a 5.

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

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

The description opens with a specific verb and resource: expanding an RFC 5545 recurrence rule into concrete occurrence timestamps, and immediately enumerates the accepted inputs (RRULE, DTSTART, zone, EXDATE, RDATE). This clearly separates it from sibling tools like timezone_convert, calendar_convert, and dst_transitions, which handle one-off conversions rather than recurrence expansion.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for turning a recurrence rule into a list of dates, and the DST-gap and 50,000-evaluation notes hint at edge cases. However, it never says when to prefer this over calendar_convert or dst_transitions, nor any explicit preconditions or 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.

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds genuinely new context: pricing ($0.05 per successful call, paid via x402 in USDC on Base) and what is returned (parsed structure, comparison result, failure reason). It does not mention rate limits or error/edge handling, but the cost and auth model is disclosed.

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 capabilities, then the return values, then pricing—a sensible order with no filler. It is a single dense multi-clause sentence, which is slightly harder to scan but every clause carries information.

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

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

For a six-parameter, multi-op tool with no output schema and no required params, the description covers what each op does, what comes back, and the payment requirement, which is enough to invoke correctly. The only real omission is the sort operation present in the enum.

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 every parameter is already documented in the schema; baseline is 3. The description reinforces op-to-parameter mapping (two versions for compare, range+version for satisfies) but adds no syntax or format detail beyond the schema, and it never explains the versions/sort parameter.

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

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

The description names the specific operations (parse, compare, satisfies) and the resource (semantic version), so an agent can immediately tell it apart from siblings like string_similarity or base_convert. It omits one enum mode, sort, which is inconsistent with the schema's op list, keeping it short of a 5.

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

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

It maps each operation to its intent and its inputs ('compare two versions by precedence including prerelease ordering', 'test whether a version satisfies a range expression'), giving clear context for choosing an op. There are no explicit when-not conditions or sibling alternatives, but the sibling set is functionally unrelated so the routing risk is low.

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/local behavior, but the description adds genuinely new context the annotations cannot: a per-call price ($0.05 over x402 with USDC on Base), the fact that it returns the slug plus what was removed (no output schema exists), and the word-boundary truncation behavior. Payment/auth requirements are exactly the kind of disclosure 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-loaded with the core verb+resource, then progressively narrower detail, ending with the pricing fact. Slightly dense in the middle sentence enumerating letter groups, but each sentence carries usable information.

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

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

For a stateless transform with no output schema, the description fills the needed gaps: what is produced (slug plus a removal report), the pricing model, and the folding behavior. Nothing essential to invoking it correctly appears to be 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 max, case, lang, separator and text in detail. The description largely restates the same transliteration rules (umlauts, Cyrillic table, language inference) rather than adding syntax or constraints beyond the schema, 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 concrete verb+resource ('turn arbitrary text into a URL-safe slug') and scopes it well: accent decomposition, umlaut/Scandinavian/Turkish ligature/Cyrillic transliteration, lowercasing, separator collapsing, word-boundary truncation. It does not explicitly distinguish itself from the sibling cyrillic_transliterate or punycode_convert, so the sibling differentiation is left implicit.

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?

There is no when-to-use or when-not-to-use guidance and no routing to alternatives. It never says how it differs from cyrillic_transliterate (which overlaps on the Cyrillic case) or punycode_convert, so an agent must infer which tool to pick.

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, so the bar is lower, and the description goes beyond them by disclosing the signature normalisation rules (parameter names stripped, uint expanded to uint256, tuples flattened) and the payment model ($0.05 per successful call via x402/USDC on Base). It omits error behaviour for malformed signatures.

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

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

Four sentences, front-loaded with the primary capability before the normalisation detail and the pricing footnote. Efficient overall, though the pricing sentence is dispensable for invocation and the normalisation sentence is 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?

No output schema exists, and the description does cover the return shape (4-byte selector, 32-byte topic), plus payment and normalisation context. Remaining gaps are minor: no statement of precedence between signature and data, and no error/edge-case behaviour.

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 a 3 is the baseline, but the description adds real meaning: it explains that normalisation makes a source-copied signature hash identically to the canonical form, and that the data parameter hashes arbitrary text or hex bytes rather than signatures. That clarifies intent beyond the enum/length descriptions in the schema.

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

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

States a specific verb (compute/derive), a specific algorithm (Keccak-256), and concrete artifacts (4-byte selector, 32-byte event topic) tied to a named domain (Solidity). This is precise enough to separate it from the generic sibling hash_generate 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 implied by the domain description rather than stated: an agent can infer it is for Solidity signatures, but there is no explicit when-to-use/when-not, no mention of hash_generate as the alternative for non-Keccac hashes, and no statement of what happens when neither signature nor data is supplied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), and the description adds genuinely new operational context: ddof defaults to the sample form with always-population companion fields, percentile reproducibility is guaranteed via a named method, and each successful call costs $0.05 paid over x402 (USDC on Base). Disclosing billing and payment rail is material context an agent would not get from annotations.

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

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

Purpose is front-loaded and the long output enumeration is justified for a statistics tool, since an agent must know whether mode, skewness, kurtosis and quartiles are included. The sentence is dense but every listed statistic earns its place; only the trailing pricing sentence is separable.

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

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

With no output schema, the description fully compensates by enumerating every returned statistic (count, sum, mean, median, mode, variance/stdev, min, max, range, IQR, skewness, kurtosis, percentiles). Combined with the 100%-covered input schema, nothing needed to call or interpret the result 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 ddof, method, values and percentiles semantics are already documented in the schema and the description largely restates them. It adds the rationale for the method parameter (reproducible rather than implementation-defined), which is marginal value beyond the enum listing, 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 ('Statistics calculator') plus the precise input shape ('numeric array in one call') and enumerates the outputs produced. No sibling tool in the list computes statistics, and the enumeration makes the scope unambiguous.

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

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

The 'in one call' framing signals this is the consolidated path for computing a batch of descriptive statistics rather than chaining narrower calls, which is useful routing context. However, it never states explicit when-to-use or when-not conditions, so guidance is contextual rather than prescriptive.

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, closed-world), so the description's contributions are the ones that matter here: the $0.05 per successful call price, the x402/USDC-on-Base payment mechanism, and the fact that folds are applied *before* comparison. It does not describe the output shape or error behavior on over-length input, which keeps it below 5.

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

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

Front-loaded with the core action, then the metrics, then preprocessing, then price — a sensible priority order. The metric list is long but each name is load-bearing for selecting this tool, and the only slack is the somewhat dense enumeration.

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

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

For a pure computation tool with no output schema, the description lists every measure returned so the agent knows the response contents, plus cost before committing to a paid call. Only the result format and input-validation failure behavior are left unspecified, which is a minor gap for a deterministic calculator.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the full 'fold' and 'only' value lists. The description adds only the ordering nuance that folding happens before comparison; otherwise it recapitulates what the schema already states, so the baseline 3 is correct.

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

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

The description states a specific action (compare two strings) and exhaustively enumerates the resource/measures returned (Levenshtein, Damerau-Levenshtein, Jaro, Jaro-Winkler, LCS, Dice, Soundex, Metaphone, NYSIIS). No sibling tool overlaps with string similarity, so the agent can immediately tell what this does and that nothing else in the list competes.

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 through the enumerated measures and preprocessing options; there is no explicit when-to-use statement, no conditions selecting it over alternatives (e.g. unicode_confusables_check or hash_generate), and no stated exclusions. Adequate for a self-evidently scoped utility, but guidance 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?

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the bar is lower, and the description still adds real behavioral context: the exact return fields, DST boundary handling policy, and a per-call price with the x402/USDC on Base payment mechanism. Cost and payment rail are non-obvious operational facts an agent must know before invoking, which is above what the annotations convey.

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

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

Three dense sentences, front-loaded with the capability and then the return fields, with no filler. The opening 'Timezone converter:' mildly duplicates the name/title, which is the only wasted token.

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

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

With no output schema, the description compensates by enumerating the returned values (local date/time, offset in ±HH:MM and seconds, abbreviation, DST state, ISO week date, day of year), and it also discloses the payment requirement. Nothing material 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 zone, local, instant, and the ambiguous enum with its default. The description only restates the local/instant duality at a high level and adds no syntax, format, or precedence detail beyond the schema, so the baseline 3 is correct.

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

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

States a specific verb (convert) plus resource (instant <-> wall-clock time in an IANA zone) and names the return shape. An agent can distinguish this from siblings like dst_transitions or calendar_convert from the description alone, since it is the only bidirectional instant/wall-clock converter with DST ambiguity handling.

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

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

Gives clear context for both directions of use and explicitly notes that ambiguous and skipped local times at DST boundaries are handled rather than guessed, which is exactly the situation that differentiates it from a naive converter. It stops short of naming an alternative tool or an explicit 'do not use for X' exclusion, so it is strong but not fully routing.

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

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

Annotations already declare the safe read-only/idempotent/closed-world profile, so the bar is lower. The description adds real value beyond that: the return shape (per-character code points, names, ASCII imitation) and a mandatory pricing/auth detail ($0.05 per call over x402 USDC on Base) that an agent must know before invoking. It doesn't mention rate limits or the exact response envelope, keeping it just short of a 5.

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

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

The description is front-loaded with the core normalization/confusables capability in one dense sentence, then closes with the return format and price. It is appropriately sized for the feature breadth, with only mild density in the parenthetical character list.

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 3-parameter, no-output-schema utility, the description covers what it does, what it returns, and the payment precondition, so an agent has everything needed to call it correctly. Nothing material is missing given the structured fields it already has.

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 form, text, and detail. The description reinforces the accepted forms and the detail flag but adds no syntax or default nuance the schema lacks, which matches the baseline 3 for full-coverage tools.

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 set of operations (NFC/NFD/NFKC/NFKD normalization, form detection, script listing, confusable/homoglyph flagging, invisible-character detection) against a clear resource (a text string). An agent can tell exactly what this does and how it differs from adjacent text tools like cyrillic_transliterate or string_similarity 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling is named. The intended usage (spotting deceptive glyphs, normalizing input) is only implied by the feature list, leaving the agent to infer the routing.

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

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

Annotations already cover read-only/idempotent/closed-world, but the description adds genuinely useful context beyond them: the full set of returned fields, the unicode_host normalization stance (WHATWG/UTS 46 non-strict), and the payment model ($0.05 per successful call via x402 USDC on Base). It stops short of describing failure behavior or what happens on invalid input.

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

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

Purpose is front-loaded, then return payload, then the unicode_host caveat and pricing. Dense and information-bearing with no filler sentences, appropriate for a parse-and-canonicalize tool.

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

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

No output schema exists, so the description carries the return-shape burden — and it enumerates scheme, host, port, path, decoded query params, fragment, suffix, eTLD+1, subdomain, ICANN/private flag, and canonical form. An agent has everything needed to call and interpret results.

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

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

Schema description coverage is 100%, so the schema already documents url and base, and the baseline is 3. The description's parameter-adjacent note about unicode_host normalization doesn't actually map to either declared parameter, so it adds little beyond the schema.

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

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

States specific verbs and resource: parse, canonicalize, and extract the registrable domain (eTLD+1) via the Public Suffix List. An agent can separate it from punycode_convert or unicode_confusables_check 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?

Implies the use case with 'the part an agent needs to decide whether two URLs belong to the same owner,' which is real context. But it never states when to prefer this over adjacent siblings like punycode_convert or unicode_confusables_check, and gives no exclusions.

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

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

Annotations declare read-only and idempotent, and the description adds substantial non-annotation behavior: no registry lookup, no storage of the number, log retention limited to length and character types, and a $0.05 per-successful-call price via x402 (USDC on Base). Privacy, pricing, and side-effect profile are all disclosed.

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 scope in the first sentence, with coverage, behavioral caveats, and pricing following in a logical order. The country/identifier enumeration is dense but earns its place by telling the agent which inputs are in scope.

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

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

With no output schema, the description carries the return-value burden; it conveys that validation is checksum-based and that country echoes back, which implies a validity response, though the exact response shape is not spelled out. Combined with the full behavioral disclosure, it is nearly complete for a stateless validator.

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 all three parameters are already documented, including separator stripping, the 64-character limit, case-insensitivity, and UK/GB handling. The description adds only a broad inventory of supported countries/kind examples, which is useful orientation but not new per-parameter 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+resource ('check a national identity, tax or company registration number against its country's official checksum rule') and enumerates the identifier families and countries covered. An agent can immediately distinguish it from siblings like iban_validate, gtin_barcode_validate, and crypto_address_validate.

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

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

The phrase 'Structure and check digit only, no registry lookup' clearly delimits when this tool applies versus a registry/verification service, and the country/kind list signals the input domain. It does not, however, name a sibling alternative or state explicit exclusion conditions (e.g., what to use for IBANs instead).

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