Agent Data Tools: Utilities

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true and idempotentHint=false, but the description adds genuinely new operational context: per-call pricing via x402 USDC or card key, 25 free calls, failed calls free, and the practical consequence that repeated identical calls are still charged. The only redundancy is "reads or computes only and changes nothing", which restates readOnlyHint.

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 output payload is front-loaded in the first sentence, then usage, example, and cost. Every sentence carries information, though the pricing clause is dense and could be split for readability, and "reads or computes only and changes nothing" is the one phrase that could be cut without loss.

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

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

With only two fully documented required parameters and no output schema, the description compensates well by listing the exact quantities returned and the model source. It does not state units or the response shape, but for a two-parameter lookup tool this is close to sufficient.

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 parameters carry their own range documentation (-90 to 90, -180 to 180), so the schema does the heavy lifting. The description adds only a worked example (lat=59.33, lon=18.07), which is mildly useful but adds no coordinate-format or rounding semantics beyond the schema. 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?

"Current air quality at a point" gives a specific verb and resource, and the description enumerates the exact metrics returned (European and US AQI, PM2.5, PM10, O3, NO2, SO2, CO) plus the upstream source (Open-Meteo, CAMS). No sibling tool in the list covers air quality, so it is trivially distinguishable from elevation, uv, and ip_geolocate.

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

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

"Use for health, outdoor-activity and travel decisions" gives a concrete usage context, and the example coordinates show the calling convention. It stops short of explicit when-not guidance or naming an alternative (e.g. the uv tool for UV-only needs), so it is clear but not routing-complete.

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

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

Annotations already declare readOnly/openWorld/non-destructive, but the description adds substantial context beyond them: the pricing model ($0.01/call via x402 USDC or card key, first 25 free, failed calls free) and the fact that each call is charged so repeats are not free. The 'reads or computes only and changes nothing' line also reconciles with the counterintuitive idempotentHint=false by explaining the cost basis.

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

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

Dense and front-loaded — the encoding options, output format, usage, and pricing all appear in a logical order with no filler. It is on the longer side, but nearly every clause carries actionable information for the agent.

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?

Though there is no output schema, the description explicitly states the return value (SVG plus a data URL ready for an <img> tag), covers encoding defaults, and discloses the cost model. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the schema already documents all five parameters, but the description adds genuine encoding semantics: the mod-103 check symbol for Code 128's numeric subset, and that EAN-13's check digit is computed or verified. These details go beyond the schema's terse field descriptions.

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

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

States a specific verb (generate) and resource (barcode as SVG), and names both supported symbologies (Code 128, EAN-13) plus their input constraints. Explicitly routes QR users to the sibling qr tool, so the agent can distinguish it 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 concrete use cases (shipping labels, product codes, tickets, inventory) and an explicit alternative ('for QR codes use qr'). Provides a worked example (text=AGENT-12345) and notes EAN-13's 12-or-13-digit requirement, so the agent knows exactly when and how to select it.

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, destructive, and idempotent hints, so the bar is lower. The description adds genuinely non-redundant context: missing padding is tolerated, pricing model (first 25 free, $0.01/call, failed calls free), and reinforces non-idempotent cost behavior ('repeats are not free').

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 tolerance, then use cases, then pricing. The pricing sentence is longer than strictly needed but is behaviorally relevant to the calling agent; nothing is wasted on restating the name.

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

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

For a single-parameter utility with no output schema, the description covers input forms (standard/URL-safe, padding tolerant), usage context, and cost behavior. Only the failure mode (what happens on invalid base64) is left implicit.

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

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

Schema coverage is 100% and the single parameter is described as 'The base64 text'. The description goes beyond the schema by noting padding tolerance and giving a concrete invocation example (text=aGVsbG8gd29ybGQ=), which clarifies accepted input forms.

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: 'Decode standard or URL-safe base64 to UTF-8 text', including both variants handled. The sibling base64_encode is implicitly the inverse, and the title/description make the direction of the operation 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?

'Use to read encoded headers, tokens and data URLs' gives concrete use cases, which distinguishes it from base64_encode and hints at where the input comes from. No explicit when-not or named alternative, but the direction (decode vs encode) is clear from the definition.

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=true, destructiveHint=false), so the description's 'reads or computes only' is a mild restatement. The real added value is operational: per-call pricing, a free tier of 25 calls, and that failed calls are not charged — cost behavior an agent cannot get from annotations. It does not describe output formatting details beyond naming the two variants.

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

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

Purpose and second output are front-loaded, and every sentence carries information. The closing sentence is dense, packing pricing, free tier, failure policy and the repetition warning together with an inline '(/credits)' fragment, which slightly hurts readability but does not waste content.

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

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

The tool has one simple parameter and no output schema, and the description compensates by saying exactly what comes back (standard base64 plus URL-safe variant). With annotations covering side-effect behavior and the description covering cost and return shape, 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% for the single 'text' parameter, so the baseline would be 3. The description adds a concrete example ('text=hello world') that clarifies the input is raw, unencoded text rather than an already-encoded string, which is a meaningful disambiguation.

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 UTF-8 text as standard base64') and goes further by naming the second output ('URL-safe variant'). That distinguishes it cleanly from the sibling base64_decode and from other encoding tools like url_encode or hash.

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

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

It gives concrete use cases ('data URLs, headers and basic auth strings') and a worked example, which is enough for an agent to place the tool. It does not explicitly say when to prefer a sibling (e.g. url_encode for percent-encoding) or when not to use it, 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?

Beyond the annotations it discloses the key behavioral caveat — computation is local and does not verify bank existence — plus a concrete pricing/cost model ($0.01/call, 25 free, failures free) that explains the idempotentHint=false annotation ('each call is charged, so repeats are not free'). The 'reads or computes only' line echoes readOnlyHint, but the added cost and local-validation 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 and ISO scope, then routing, then caveats, then pricing — logical order with no wasted preamble. It is dense and on the long side, and the pricing clause is verbose relative to its importance, keeping it just short of a 5.

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

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

No output schema exists, yet the description effectively previews the response by listing the checks performed (institution code, country name, location, branch, head-office flag, test/passive participant). For a single-parameter validation tool, an agent has everything needed to call it and interpret the result.

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

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

With 100% schema coverage and one parameter, the schema already defines 'bic' as an 8- or 11-character code. The description reinforces the 11-character form and supplies a concrete example (bic=DEUTDEFF500) that shows the expected format beyond the schema's terse wording.

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

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

States a specific verb and resource ('Check a BIC (SWIFT code) against the ISO 9362 structure') and enumerates exactly which components are examined (institution, country, location, branch, head-office, test/passive, 11-char form). It also names a sibling it is not ('for account numbers use validate_iban'), so an agent can route without opening any schema.

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

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

Gives both when-to-use ('before an international transfer or to clean payment data') and an explicit alternative with its selection condition ('for account numbers use validate_iban'). The 'checks format and country, not whether the bank exists' line further scopes when this tool is insufficient.

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

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

Adds substantial context beyond the annotations: per-call pricing via x402 USDC or card key, 25 free calls, failed calls free, and the explicit note that repeats are not free — which explains the idempotentHint=false flag that would otherwise look odd for a pure computation. It also confirms read-only behavior ('reads or computes only and changes nothing') and states the UTC default, consistent with readOnlyHint and destructiveHint=false.

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?

Outputs are front-loaded in the opening clause, followed by usage, example, and cost/repeatability caveats. Every sentence carries information an agent needs (what it returns, when to use it, input format, billing behavior); 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 fully specifies the return shape (all derived values), the measurement-date default and override, and the pricing/caching behavior that governs repeated calls. An agent could invoke this correctly and predict its output without opening any other field.

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 value by clarifying that measurement defaults to today in UTC 'or on any date you give' and supplies an example value (birthdate=1990-05-17). It does not restate per-parameter syntax beyond that, so it lands just 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?

Names a specific computation (exact age from a date of birth) and enumerates the outputs: years/months/days, total days lived, weekday of birth, and next-birthday date/countdown. This is specific enough to be told apart from generic date siblings like date_diff or date_info, and the required input (birthdate) is stated up front.

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

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

Gives concrete usage contexts ('age checks, forms and anniversaries') plus a worked example, so an agent knows when the tool fits. It stops short of naming an alternative or an exclusion (e.g., use date_diff for arbitrary date spans), which keeps it at 4 rather than 5.

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

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

Beyond the read-only annotations, it discloses billing behavior: $0.01 per call, first 25 free, failed calls free, and repeats are not free. It also states that the tool only reads or computes and changes nothing, which aligns with and enriches the annotation profile.

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

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

The core purpose and outputs are front-loaded, followed by limitations, usage context, an example, and pricing. It is generally efficient, though the pricing and no-mutation sentences overlap slightly and one sentence reads more like product positioning.

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

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

There is no output schema, so the description carries the burden of explaining return values; it does so by naming BMI, WHO adult category, and the normal weight range. It also states the adult-only and screening-not-diagnosis constraints, making the definition complete for correct use.

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

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

Schema coverage is 100%, so the baseline would be 3 even with no additional detail. The description adds a concrete example (weight=70, height=175) and restates metric/imperial unit conventions, which lightly clarifies invocation but largely duplicates 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 clearly states that it computes body mass index from weight and height and returns the WHO adult category plus the normal weight range for that height. It is specific enough to distinguish from generic calculators, though it does not explicitly compare itself to siblings such as units_convert.

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

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

It gives clear usage context (health, fitness and nutrition apps) and an important limitation (for adults; screening, not diagnosis). It does not name alternatives or say when another sibling tool would be preferable, but the intended use case is clear.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds real behavioral detail beyond them: per-call pricing via x402 USDC or card key, 25 free calls, failed calls free, and the warning that repeats are not free. The constant-rate assumption is also disclosed. It does not describe precision/rounding or units of the yearly balance series, keeping it out of the top band.

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

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

Purpose and input list come first, then usage, then pricing — a sensible front-loaded order. The billing sentence is long and repeats "charged" twice, but every clause carries actionable information for 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 compensates by naming the return contents (future value, total contributed, interest earned, per-year balance). Combined with the pricing and assumption disclosure, an agent has enough to call and interpret results; only numeric precision and formatting of the per-year series remain unspecified.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including the compound enum values and the monthly default of 0. The description largely restates those fields and adds only a worked example (principal=10000, rate=7, years=10) plus the "end of each month" contribution timing, 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?

The description names a specific computation (compound interest future value) and enumerates the inputs it consumes — principal, annual rate, years, compounding frequency, monthly contribution — which cleanly separates it from siblings like calc_loan or calc_tip. An agent can identify the tool's job without reading 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?

"Use for savings goals and investment what-ifs; rates are assumed constant" gives clear usage context and states a modeling assumption (constant rate). It stops short of naming an alternative — e.g. calc_loan for amortization/payoff scenarios — so the agent gets positive guidance but no explicit exclusion rule.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: per-call pricing ($0.01 via x402 USDC or card key, first 25 free, failed calls free) and the modelling assumptions (fixed rate, monthly payments). The 'each call is charged, so repeats are not free' line usefully reinforces, rather than contradicts, idempotentHint=false.

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 what is computed and what is returned, followed by usage and pricing; every clause is informative. The pricing sentence is somewhat dense (mixing x402, card keys, free tier and failure policy) and could be trimmed without losing meaning.

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-shape burden and does so well, enumerating monthly payment, total paid, total interest, and schedule columns (principal, interest, balance). Minor gaps remain: assumed currency and behavior when term is omitted or when both years and months are given.

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

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

Schema description coverage is 100%, so the schema already documents units and defaults for rate, years, months and rows; baseline 3 applies. The description adds only a sample value pair (principal=300000, rate=4.5) and implies that only 'the first months' of the schedule are returned, without clarifying precedence when both years and months are 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 precise verb-and-resource: computes the monthly payment of an amortised loan plus total paid, total interest and the first rows of the repayment schedule. The qualifiers 'fixed rate, monthly payments' and 'amortised' scope it tightly enough that an agent can distinguish it from calc_compound_interest or calc_tip 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?

'Use to compare loan offers or plan a mortgage' gives clear positive usage context, and the worked example (principal=300000, rate=4.5) shows a canonical invocation. However, no alternatives or when-not conditions are named, so the agent gets no routing guidance against the other calc_* siblings.

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, destructiveHint=false and idempotentHint=false, so safety is covered structurally. The description adds genuinely non-structural facts: it is a pure read/compute, each call is billed at $0.01 via x402 USDC or card key, the first 25 are free, and failed calls are free – which is consistent with idempotentHint=false (repeats cost money). It does not spell out the exact response shape, keeping this from 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 core purpose is front-loaded in the first clause and the billing terms follow, which is the right order. The dangling fragment "Example: bill=84.5." is an unfinished sentence that earns nothing, a minor but real waste.

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 makes clear what comes back (tip amount, total, and per-person share, optionally rounded) and covers cost and read-only behavior. A 5 would require explicit statement of the returned fields or default handling when people/percent are omitted.

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 bill, people, percent and roundUp are all already documented in the schema, establishing a baseline of 3. The description's note about rounding each share up restates the roundUp schema wording and adds no new constraints (units, defaults, precision) beyond it.

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 exact computation (tip and total for a bill at a given percentage, split per person, optional per-share rounding) with a concrete resource and scope. No sibling in the toolset (calc_loan, calc_bmi, calc_age) does this, so an agent can route here 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?

"Use for receipts, expense apps and group payments" gives clear situational context for when to pick this tool rather than a generic arithmetic path. It stops short of naming exclusions or an alternative (e.g., splitting without a tip), so it is context-rich but not a full when/when-not rule set.

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

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

Beyond the annotations, the description discloses pricing, payment options, a free tier, that failed calls are free, and that repeated calls are charged. It also confirms the tool only reads/computes and changes nothing, which is useful behavioral context alongside readOnlyHint=true and destructiveHint=false.

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, followed by usage, an example, and cost/behavioral details. The pricing sentence is dense but relevant; overall the description is efficient, though slightly longer than necessary for a simple converter.

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

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

For a two-parameter, read-only converter with full schema coverage and rich annotations, the description is largely complete. It does not explicitly state the return value or error behavior for invalid targets, but the core invocation context is clear.

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 defines both parameters and the accepted target formats. The description adds value with an example mapping text=user profile id and to=camel, and by noting that mixed input like 'userID_value' is handled.

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: converting text or identifiers between named case formats. It lists the supported formats and gives a concrete mixed-input example, making the tool easy to distinguish from unrelated text utilities such as slug or text_stats.

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

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

It gives a clear use context: renaming fields or generating code identifiers. It does not explicitly name when not to use it or compare with nearby siblings such as slug, so the guidance is strong but not complete.

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

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

Beyond the annotations, it discloses the cryptographic random source, return shape, pricing and payment paths, free-call allowance, failed-call behavior, and that repeated calls are charged. It also reinforces the read-only nature consistently with readOnlyHint=true.

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 and return behavior are front-loaded, and the pricing and safety notes are relevant for this paid tool. The example is mildly redundant, but overall the description is efficient rather than padded.

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

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

For a simple one-parameter randomness tool, the description covers purpose, usage context, return shape, cost, failure behavior, and side-effect profile. No output schema is present, but the description says it returns each result and totals.

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

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

The schema already documents the count parameter at 100% coverage, including its intended range and default. The description only adds a simple example and the phrase 'one or more', without reconciling the schema's broader numeric bounds or adding much beyond the schema text.

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

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

The description states a specific verb and resource: flipping one or more fair coins from a cryptographic random source. It is clear what the tool does, but it does not explicitly distinguish itself from sibling randomness tools such as dice or random_number.

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

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

It gives a clear usage context: fair decisions and games, with an example of count=1. It does not state when not to use it or name alternatives, but the intended use is explicit.

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 and destructiveHint=false; the description adds real value on top by explaining cost ('$0.01/call', first 25 free, failed calls free) and clarifying that 'reads or computes only and changes nothing' yet 'each call is charged, so repeats are not free' — which explains the otherwise puzzling idempotentHint=false. It does not describe the shape of the response, which is the main remaining gap.

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

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

Front-loaded with the conversion capability and accepted formats before secondary details (pricing, safety note). The pricing sentence is a little dense and could be tightened, but no sentence is pure filler.

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

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

For a one-parameter tool with no output schema, the description does the important work of naming the returned values (relative luminance and contrast recommendation) and the accepted formats. Without an output schema, a description of the exact response fields would have closed the last gap.

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

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

Schema coverage is 100%, but the schema's own text is just 'The colour', so the description carries the real semantics: it lists #rgb, #rrggbb, rgb(r,g,b) and hsl(h,s%,l%) syntax and gives a concrete example. It does not say what happens with unsupported forms (named colours, alpha channels), leaving a small ambiguity.

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

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

States a specific verb and resource ('Convert a colour between hex, RGB and HSL') and enumerates the accepted input formats plus the derived outputs (relative luminance, black-vs-white text preference). The added 'whether black or white text reads better' overlaps conceptually with the color_contrast sibling without saying so, so the 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?

'Use for theming and design checks' gives concrete usage context, and the worked example (color=#0f6cbd) shows typical invocation. It stops short of naming when to prefer color_contrast or color_palette instead, so there are no explicit 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?

Goes well beyond the annotations by disclosing the billing model: $0.01/call via x402 USDC or card key, first 25 free, failed calls free, and repeats are charged — which explains the idempotentHint=false. The statement "reads or computes only and changes nothing" is consistent with readOnlyHint=true and destructiveHint=false.

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

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

Purpose and result shape are front-loaded, followed by usage and then billing. Every sentence carries information, though the pricing clause is dense enough that it slightly crowds out the core tool 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?

For a two-parameter compute tool with no output schema, the description covers what is computed (ratio plus AA/AAA verdicts at two sizes), input format via example, safety profile, and the cost model. Nothing an agent needs to decide or call 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 both parameters are documented, but the description adds the value format via the example (hex strings like #767676 and #ffffff), which the schema does not specify. That is a genuine increment over structured data, though it doesn't cover alternate formats like rgb() or named colors.

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: computes the WCAG 2 contrast ratio between a text colour and a background colour, plus AA/AAA pass/fail at both text sizes. This is clearly separable from siblings like color_palette, color, or random_color, which do not evaluate accessibility.

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

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

"Use to check that a design is readable" plus a concrete example (fg=#767676, bg=#ffffff) gives a clear usage context. It stops short of naming alternatives or when-not-to-use (e.g. use color_palette to generate colors instead), so it does not reach the top band.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds the auth and cost model ($0.01/call via x402 USDC or a card key at /credits, first 25 free, failed calls free) and warns that repeats are not free, which explains the idempotentHint=false annotation in practical terms. It does not describe ordering or exact shape of the returned harmonies, but the cost/auth disclosure is real value 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?

Front-loaded with the core capability and output inventory in one sentence, followed by use cases, the sibling pointer, and the pricing/behaviour note. Slightly padded by the em-dash stacking of specificity details ('first 25 free; failed calls free') and the commercial pricing pitch, but no sentence is off-topic.

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 a fair job (harmonies and shades as hex codes, plus base HSL). What is still fuzzy is the container format — whether results come back as one string or structured fields — and the ordering of the six shades, which an agent may want to know before formatting the output.

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

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

Schema coverage is 100% and the single `color` parameter already documents hex formats like #3366ff or 36f, so the description's example adds nothing new about the argument itself. The 'hue rotations at the same saturation and lightness' clause adds useful semantics but describes the computation, not the parameter. 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 ('Build a colour palette from one hex colour') and enumerates exactly what is produced: five named harmonies plus six shades plus the base HSL. It also distinguishes itself from the nearest sibling by routing readability checks to color_contrast, so an agent can tell it apart from `color`, `random_color` and `color_contrast` 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?

Gives concrete use cases (UI themes, charts, brand kits, slide decks) and explicitly names the alternative tool with the condition that selects it ('to check text readability on a colour use color_contrast'). The input example and the note that repeated calls are charged further tell the agent how to invoke it efficiently.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true and idempotentHint=false, and the description is consistent with all of them ('Reads or computes only and changes nothing'). It adds information annotations cannot carry: per-call pricing via x402 USDC or card key, 25 free calls, failed calls free, and that repeated calls incur cost again — genuinely useful before an agent loops on it.

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 syntax support, use case, example, then cost. Dense but nearly every clause carries information; the pricing sentence is longish yet relevant to call decisions.

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 state the return is next run times in UTC, plus the syntax accepted for the required parameter and the cost model. Count/from behavior is left to the schema, which adequately documents it, so an agent has enough 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 coverage is 100%, so baseline is 3; the description earns an extra point by spelling out the 5-field cron grammar (minute hour day month weekday) and that ranges, lists, steps and names like MON/JAN are accepted, which is semantics the schema's bare 'The cron expression' does not provide. It says nothing about 'from' or 'count', but those schema descriptions are adequate.

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 ('next run times of a standard 5-field cron expression') and immediately scopes it with the supported syntax and UTC output. No sibling tool covers cron, and the definition makes the scope unmistakable anyway.

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

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

Gives a concrete use case ('check a schedule before deploying it') and a worked example expression. There are no competing cron siblings to route away from, so the absence of explicit exclusions costs little.

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?

With readOnlyHint, openWorldHint, and idempotentHint already declared, the description still adds substantial context: per-call pricing ($0.002 via x402 USDC or card key), first 25 calls free, failed calls free, the 24-hour change sourced from Coinbase where available, and a 'changes nothing' statement. It even explains why repeats are not free, which accounts for the non-idempotent hint.

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

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

Front-loaded with the resource, supported inputs, and limits before the pricing and usage details. Dense but nearly every clause carries information; the pricing/credit sentence is the only slightly tangential element, though it is operationally relevant.

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 indicate what comes back, and it does: current price in each requested currency plus 24-hour change. Combined with input limits, id-source flexibility, and cost expectations, 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 goes further by naming valid CoinGecko id examples (bitcoin, ethereum, solana, usd-coin), noting that tickers such as BTC also work, and stating the 25-id and 5-currency caps. These details add meaning beyond the terse schema strings.

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 ('Current price of up to 25 cryptocurrencies by CoinGecko id ... in up to 5 currencies') with concrete id examples. The clause 'Use to price coins that are not on-chain tokens' implicitly separates it from siblings like token_price and price_token, so an agent can route correctly without opening the schema.

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

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

Gives three concrete use cases: pricing non-on-chain coins, valuing a portfolio in several currencies, and checking a move. It also warns that repeat calls are charged. It doesn't name a sibling to use instead for on-chain tokens, so the exclusion is implicit rather than an explicit alternative.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, non-idempotent), and the description adds genuinely new context: per-call pricing, the 25-free-call allowance, failed calls being free, and the warning that repeats are not free because each call is charged. That pricing/idempotency reinforcement goes 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?

Conversion behavior and the example are front-loaded, and the pricing sentence is compact despite covering several facts. Slightly dense at the end, but every sentence carries information.

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

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

With no output schema, the description correctly explains the return value (array of objects keyed by the header row) and covers input formats. It stops short of edge cases — ragged rows, malformed CSV, empty input — which would matter for an agent handling messy exports.

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

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

Schema coverage is 100%, so both parameters are already documented; the description's note that numbers stay text unless numbers=true largely restates the schema. It does add automatic delimiter detection and quoted-field handling, but those are behaviors rather than parameter semantics. 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 (convert CSV to a JSON array of objects) plus the exact output shape — objects keyed by the first row. This clearly distinguishes it from siblings like json_to_csv, csv_to_markdown and html_table_to_json.

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

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

It offers one concrete usage context ('load spreadsheet exports into an agent'), which is helpful, but never names an alternative or an exclusion — nothing tells the agent when to pick csv_to_markdown or html_table_to_json instead.

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

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

Adds real behavioral detail beyond the annotations: auto-detected delimiters, quoted-field handling, a 100 KB ceiling, and explicit 'reads or computes only and changes nothing' which complements readOnlyHint/destructiveHint. The billing note ('each call is charged, first 25 free, failed calls free') is useful but slightly muddies the picture by hinting at a non-idempotent cost model rather than clarifying behavior.

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?

Conversion semantics are front-loaded in the first sentence, with usage and the sibling alternative following. The inline CSV example and the pricing sentence make it longer than strictly needed for a two-parameter tool, but every element is at least informative.

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 describing the produced table's formatting rules (alignment, escaped pipes, <br>). Together with the input limits and no-side-effect statement, 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, and the description adds value: it documents which delimiters are auto-detected and that quoted fields are supported, plus the default header behavior. It goes modestly beyond the schema rather than substantially re-explaining it.

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 CSV into a GitHub-flavoured Markdown table) and spells out the exact output conventions (right-aligned numbers, escaped pipes, <br> for line breaks). It explicitly names csv_to_json as the sibling for the JSON case, so an agent can route without opening either schema.

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

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

Gives concrete when-to-use scenarios (README, chat reply, issue, report) and an explicit alternative with its selection condition ('for JSON use csv_to_json'). Delimiter support and size limit further delimit applicability.

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

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

Goes well beyond the annotations by disclosing month-end clamping semantics (31 Jan + 1 month = 28/29 Feb), that negative values subtract, weekend skipping for business days, and the billing model (first 25 free, failed calls free, repeats charged). This is substantive behavioral context the annotations do not carry.

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

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

The capability statement is front-loaded and dense with useful detail, and the example is well-placed. The trailing pricing/credits sentences are necessary for cost-sensitive agents but slightly dilute the core message.

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 an 8-parameter computation tool with no output schema, the description covers units, edge-case semantics, an example, and cost, which is everything an agent needs 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 parameters are already documented; the description adds real value on top by explaining negative-value subtraction and the month-end clamping rule that the schema never mentions. It does not explain unit-combination or precision behavior, keeping it just shy 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?

Uses a specific verb (add/subtract) on a specific resource (date components) and enumerates the supported units, including the special businessDays mode. An agent can immediately distinguish it from date_diff or date_business_days siblings.

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?

States the intended use case ('compute due dates and expiries') and provides a concrete example, giving clear context for when to pick this tool. It stops short of explicitly naming the alternative sibling date_business_days or stating when not to use it.

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

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

Annotations already declare readOnly/openWorld/non-idempotent/non-destructive, and the description adds genuinely new context: source of holiday rules ('our statutory rules for US, UK, SE...; Nager.Date for the rest'), the fact that skipped holidays are listed, and that it 'reads or computes only and changes nothing'. Pricing ('$0.01/call', 'first 25 free', 'failed calls free', 'repeats are not free') usefully explains why idempotentHint is false despite being read-only. It stops short of describing response shape or error behavior.

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 primary function and scoping before the alternate mode and billing details, and every clause carries information. It is a single dense mega-sentence, however, and the pricing/payment clause could be split or trimmed for readability.

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

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

For a 4-parameter compute tool with no output schema, the description covers inputs, alternate mode, holiday-calendar sourcing, return content (skipped holidays listed), safety profile, and billing. An agent has everything needed to call it correctly and predict roughly what comes back.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it documents the `country` parameter's underlying data sources and coverage ('over 100 countries, e.g. JP, NZ, CA, AU, IN'), and gives a concrete from=2026-12-01 example. It does not restate the `to` default or the add/to mutual exclusivity, which the schema already covers.

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 ('Count business (working) days between two dates') and immediately scopes it as weekend/holiday-skipping, which cleanly separates it from the plain date_diff sibling. It also declares a second mode ('give add=N for the date N business days after'), so an agent knows both capabilities up front.

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

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

Names concrete use cases (delivery estimates, SLAs, payment terms, payroll dates) and explains the calendar logic that selects this tool over a plain day-difference calculator. It never explicitly says when to use date_diff/date_add instead, and the add=N mode overlaps with date_add without noting the distinction.

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

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

Goes well beyond the annotations: discloses pricing ($0.01/call, first 25 free, failed calls free) and explicitly explains why repeats are not free, which makes the otherwise cryptic idempotentHint=false concrete. It also restates the compute-only, non-mutating nature, so the agent knows no state is touched.

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 return values, then usage, then an example, then billing. Dense but every clause carries information; the pricing sentence is long but load-bearing for a paid, non-idempotent 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?

No output schema exists, yet the description enumerates every return component, and both required params are covered. For a two-parameter read-only computation tool, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so from/to are already documented as start/end date or ISO timestamp. The description adds only a sample value pair (2026-01-01 / 2026-10-18) that confirms the accepted format — helpful but marginal over the schema.

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

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

States a specific verb+resource (time between two dates/timestamps) and enumerates the exact outputs: total days/weeks/hours/minutes/seconds, a years-months-days breakdown, and weekday count. An agent knows precisely what it gets, though it never names the neighbouring tools (date_add, date_business_days, calc_age) it overlaps with.

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

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

"Use for deadlines, ages and durations" plus a concrete from/to example gives clear usage context. It stops short of exclusions or naming alternatives — "ages" overlaps with the sibling calc_age without disambiguation.

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 and destructiveHint=false, and the description reinforces that ('Reads or computes only and changes nothing'). It adds genuinely non-structured context: the $0.01/call x402 USDC or card-key pricing, 25 free calls, and that failed calls are free while repeats are charged, which also explains the idempotentHint=false flag. It does not describe the response shape beyond the field enumeration, hence not a 5.

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

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

Three sentences, front-loaded with the full field list so the agent knows what it gets immediately. The pricing sentence is long and slightly run-on, but every clause (price, free tier, free failures, repeat cost) carries behavioral information rather than filler.

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

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

For a single optional-parameter computation tool with no output schema, the description supplies the returned fields, the input format, the cost model, and a clear read-only guarantee. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and already documents 'Date or ISO timestamp (default today)', so the baseline is 3. The description adds a concrete format example (date=2026-10-18), which disambiguates acceptable input syntax beyond the schema text, justifying a small uplift.

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 enumerates the exact facts computed (weekday, ISO week number and week-year, day of year, quarter, days in month, leap year, Unix timestamp, weekend flag) for any date, which is specific enough to separate it from the many date siblings such as date_add, date_diff, date_zodiac, unix and time. The input example (date=2026-10-18) makes the resource concrete.

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

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

'Use for calendar and reporting logic' gives only implied usage context. No exclusions or explicit alternatives are named, even though the sibling list contains obvious confusables (date_diff, date_business_days, unix, holidays) whose boundary with this tool is left for the agent to infer.

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

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

Beyond the readOnly/destructive annotations it discloses pricing ($0.01/call via x402, first 25 free, failed calls free) and explains why idempotentHint=false in practical terms: each call is charged, so repeats are not free. It also flags a real correctness caveat (January/early-February dates may belong to the previous Chinese animal) that an agent could not infer 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?

Front-loaded with what is returned, then the boundary caveat, then use cases, then pricing. Dense and mostly purposeful, though the pricing sentence runs long and could be trimmed without losing meaning.

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 name the returned components (sign, element, Chinese animal, Chinese element) and the edge-case flag, which covers what an agent needs to decide and call. It stops short of describing the response structure or field names, which would matter given the absent output schema.

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

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

Schema coverage is 100% and already documents the single parameter as YYYY-MM-DD, so the baseline is 3. The inline example (date=1990-08-15) reinforces the format and confirms a full-date string is expected, adding modest value beyond the schema.

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

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

States a specific resource and computation: the western (tropical) sign with element plus the Chinese animal and element for a birth date. It is clearly distinguishable from adjacent siblings such as date_info, calc_age, or holidays 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?

"Use for profile enrichment, greeting cards, games or horoscope-style content" gives concrete usage contexts, and the example date anchors the expected input. It never names an alternative tool or an explicit when-not condition, so routing against siblings like date_info is left implicit.

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

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

Annotations cover safety and idempotency, but the description adds real behavioral context: cryptographic random source, per-roll return shape (every roll, the modifier, the total), and the charging model including that repeats are not free — which meaningfully explains why idempotentHint=false matters. It also states failed calls are free, which matters for retry behavior.

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

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

Front-loaded with the capability, format, and limits, then usage, then pricing. Every sentence carries information, though 'Reads or computes only and changes nothing' overlaps with readOnlyHint=true and the pricing sentence is dense relative to the core 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 one-parameter tool with no output schema, the description covers input format, bounds, what is returned, safety profile, and cost — everything needed to call it correctly and predict the response.

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

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

Schema coverage is 100% with a single documented parameter, so the baseline is 3, and the description adds bounds not present in the schema (up to 100 dice of up to 1000 sides) plus a second notation example. It doesn't restate the default (1d6), which is already in the schema.

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

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

States a specific verb and resource ('Roll dice') plus the exact input format ('standard notation such as 2d6+3 or 1d20') and hard limits (100 dice, 1000 sides). This clearly separates it from siblings like random_number, random_pick, or coin, which don't take dice notation.

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

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

'Use for tabletop games and simulations' plus a concrete example ('roll=2d6+3') gives an agent a clear context for selecting it. It stops short of explicit exclusions or naming an alternative (e.g., 'for a single uniform integer use random_number'), so it isn't a full when/when-not statement.

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

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

Goes well beyond annotations by disclosing the charging model: $0.01/call via x402 USDC or card key, first 25 free, failed calls free, and that repeats are not free. This cost and idempotency consequence (paired with idempotentHint=false) is exactly the operational context an agent needs before calling.

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

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

Front-loads the return value, then usage, then pricing. Four dense sentences with little waste, though the payment sentence packs several clauses that could be trimmed slightly.

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 contract and does so fully (message, length, server time), while also covering cost and safety. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and documents the single message parameter with a 2,000-character limit, so the schema does the work. The description only adds a trivial 'Example: message=hello' and no format or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (returns the message you send) plus the exact payload (length and server time), which no sibling tool does. An agent can distinguish this from text_stats or ping 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?

Explicitly says to use it for testing an x402 client, payment flow, or agent tool wiring end to end, which is a clear context. It does not name an alternative or exclusion, but for a self-evidently unique echo tool none is needed.

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

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

Annotations already declare readOnly, openWorld, and non-destructive behavior, but the description adds what annotations cannot: an explicit pricing model ($0.01/call via x402 USDC or a card key), the free tier of 25 calls, and the failure policy that failed calls are free. It also makes explicit why idempotentHint is false: repeated calls are charged, and it discloses the 90 m resolution, which implies accuracy limits. This is exactly the extra context the 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?

The description is front-loaded with purpose, then use cases, then pricing and safety notes, with every sentence carrying information. The pricing/auth sentence is dense but justified for a paid tool; nothing is filler.

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

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

For a two-parameter read tool with no output schema, the description covers what it returns (elevation in metres), the source, resolution, cost, and side-effect profile. The only unaddressed case is behavior at points with no meaningful terrain value, e.g., open ocean or out-of-coverage coordinates.

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

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

Schema coverage is 100%, and both parameters are fully documented with valid ranges, so the schema already does the heavy lifting. The description only adds a concrete example (lat=59.33, lon=18.07), which confirms decimal formatting but adds no semantics 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 opening states a specific verb and resource: it returns ground elevation in metres above sea level for a lat/lon pair. It also names the underlying dataset (Copernicus 90 m DEM via Open-Meteo), which distinguishes it from sibling geo tools such as geo_distance and ip_geolocate without requiring the schema to be opened.

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

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

The description gives concrete scenarios for using it: route planning, flood or terrain risk sizing, and location data enrichment. It does not mention alternatives or exclusions, such as whether it competes with geo_distance or ip_geolocate, but the positive usage context is clear.

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

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

Annotation coverage is strong, and the description adds accuracy (about 0.5%), billing details ($0.01/call, first 25 free, failed calls free), and the repeat-call charging nuance. It also explicitly confirms the tool reads/computes only and changes nothing.

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, followed by use cases, an example, pricing, and safety behavior. The text is dense but every sentence adds useful operational or behavioral context.

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, but the description fully explains the return components: distances in three units, initial bearing, and midpoint. Accuracy, billing, and safety behavior are also covered.

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 lat/lon semantics are already documented. The description provides a concrete coordinate example, but does not add parameter-level constraints beyond what the schema already states.

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

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

States a specific computation: great-circle distance between two lat/lon points, returning km/miles/nautical miles plus bearing and midpoint. It distinguishes itself from coordinate-lookup tools by directing place-name inputs to geocode first.

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 use cases such as delivery radius, travel/proximity checks, and sorting by distance, and names the geocode prerequisite for place names. It does not explicitly state when not to use the tool, but the intended context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=false and destructiveHint=false. The description adds genuinely new behavioral facts: the data comes from the official HN API, each call is billed ($0.01, first 25 free, failed calls free), and repeats are not free because of per-call charging — which operationalizes the idempotentHint=false in practical terms. It omits freshness/caching behavior and rate limits, so it is strong but not exhaustive.

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

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

The core purpose and returned fields are front-loaded in the first clause, followed by the usage cue and example. The pricing sentence is dense with payment-channel detail (x402 USDC, card key /credits) that is useful but slightly crowds the definition.

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

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

With one optional parameter, no output schema, and annotations covering safety, the description fills the remaining gaps: it lists the return fields, names the upstream source, and discloses the cost model. An agent has everything needed to decide to call it and to set count correctly.

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

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

Schema description coverage is 100% and the single parameter is already documented as "How many (1-20, default 10)". The description only adds an example value (count=5), not new semantics such as how out-of-range values are handled. Baseline 3 is appropriate when the schema carries the meaning.

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

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

"Current top stories on Hacker News" names a specific resource and scope, and the description enumerates exactly what each story carries (title, link, points, comment count, author, age, discussion URL). No sibling in the list covers HN content, so there is nothing to confuse it with.

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

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

"Use to follow what developers are discussing right now" gives a clear situational cue, and "Example: count=5" shows a typical call. It stops short of stating when-not to use it or naming an alternative source for non-HN content, so it is context-rich but not 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 and destructiveHint=false, so 'reads or computes only and changes nothing' is largely redundant. The description does add genuinely useful behavior the annotations cannot convey: the payment model (x402 USDC or card key, first 25 free), that failed calls are free, and why repeats are not free — which explains idempotentHint=false.

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

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

The core operation, algorithm options, and return formats are front-loaded in the first clause, with pricing and safety notes after. The billing detail is dense but operationally relevant; nothing is padding, though the parenthetical list of algorithms partly repeats the title.

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

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

With no output schema, the description correctly compensates by specifying that the digest is returned in both hex and base64. It leaves out any input size limits or error behavior for invalid algorithm values, which is a minor gap for a two-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 baseline would be 3, but the description adds a real constraint not present in the schema: the input is treated as UTF-8 text. It also restates the default algorithm, which is mildly duplicative of the schema's 'sha256 (default)'.

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

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

The description names a specific verb and resource ('SHA256 hash of UTF-8 text') and enumerates the supported algorithms and both output encodings (hex, base64), so the agent knows exactly what comes back. It does not explicitly separate itself from the nearest siblings (hmac, pack_hash_toolbox), which keeps it below 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?

'Use for checksums, cache keys and deduplication' gives concrete usage contexts, which is more than most siblings offer. There are no when-not conditions or pointers to hmac for keyed hashing, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false; the description adds context the annotations cannot: the key is used only for this call and not stored, each call costs $0.002 via x402 USDC or a card key, the first 25 are free, and failed calls are free. The cost-and-repeat warning also explains in plain language why idempotentHint is false.

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 and algorithms, then usage, then privacy and pricing – a sensible order. The pricing sentence is dense but carries real decision-relevant information; only 'Reads or computes only and changes nothing' is largely redundant with the readOnlyHint annotation.

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 partially compensates by stating the digest is returned in hex and base64, though it is slightly ambiguous whether both are always returned or one is selectable. Combined with full parameter documentation and the cost/key-retention disclosure, an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the "sha256 (default)" enumeration. The description only restates the default algorithm and adds a trivial message=hello, key=secret example, which is marginal value beyond the structured fields. Baseline 3 applies.

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

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

The description gives a specific verb+resource (compute an HMAC of a message with a key) and enumerates the supported algorithms and output encodings, so an agent knows exactly what it produces. It does not explicitly distinguish itself from the sibling `hash` tool (keyed vs unkeyed), which is the one remaining ambiguity in a dense sibling list.

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

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

"Use to check webhook signatures" gives a concrete triggering context, which is more than most siblings offer. It stops short of naming alternatives (e.g., use `hash` when no key is involved) or stating exclusions, so the routing guidance is clear but not complete.

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

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

Goes well beyond the annotations by disclosing output construction rules (headers as keys, raw arrays when no header), colspan repetition, entity decoding, caption handling, and a 500 KB input cap. It also explains the billing model and clarifies why repeats are not free, which explains the idempotentHint=false annotation rather than contradicting it.

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

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

Front-loads the core transformation and output shape in the first sentence, then adds usage, then pricing. The pricing sentence is long and packs several facts, but each sentence carries distinct information with no filler.

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

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

No output schema exists, yet the description fully specifies the return shape, including the no-header fallback to raw arrays. For a single-parameter tool with full annotation coverage, 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?

There is only one parameter and schema coverage is 100%, so the schema already documents 'html' fully. The description restates the 500 KB limit and that the HTML itself is the argument but adds no new syntax or format guidance beyond the schema.

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

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

States a specific verb and resource ('Extract every table from an HTML fragment into JSON') and describes the output shape. It is clearly separable from siblings like csv_to_json and html_to_text because the input is HTML tables and the output is structured JSON rows.

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 concrete use cases ('turn web or email tables into data an agent can sort and compute on') and routes the agent elsewhere for fetching a page ('to fetch a page first use extract'). It lacks an explicit when-not-to-use versus html_to_text, and the referenced 'extract' tool does not appear in the sibling list, but the selection context is clear.

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

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

Annotations already cover the safety profile, yet the description still earns its keep by disclosing the output transformation rules (what gets removed, what becomes line breaks or bullets) plus cost behavior — $0.01/call, 25 free, failed calls free, repeats charged. 'Reads or computes only and changes nothing' is consistent with readOnlyHint=true and destructiveHint=false, and the charge-per-call note makes idempotentHint=false understandable to the agent.

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

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

Front-loaded with purpose and transformation behavior, which is the right order. The pricing/call-charging sentence is long and slightly interrupts the technical narrative, but it carries information an agent needs before looping on this 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?

One parameter, no output schema, annotations covering safety — the description supplies exactly what is missing: what the output text looks like, what an agent would use it for, and what each call costs. Nothing needed to invoke it correctly is absent.

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

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

Only one required parameter with 100% schema coverage, so the baseline is 3. The inline example showing html=<h1>Hi</h1><p>A &amp; B</p><ul><li>one</li></ul> adds concrete input-format value beyond the schema's bare 'The HTML'.

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 ('Strip HTML to readable plain text') and then enumerates the exact transformations performed (scripts/styles removed, block elements to line breaks, bullets, entity decoding). This is clearly distinguishable from siblings like html_table_to_json or markdown_to_html, which go in different directions.

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

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

'Use to feed web content or emails to an LLM' gives an explicit intended context, and the worked example anchors the input shape. It stops short of naming alternatives or exclusions (e.g., use html_table_to_json when tabular structure must be preserved), so it is clear context without routing rules.

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 read-only, non-destructive behavior, and the description adds substantive context: pricing at $0.01/call via x402 USDC or a card key, first 25 free, failed calls free, and that repeated calls are not free. It also reinforces that the tool reads or computes only and changes nothing, so an agent understands cost and side-effect behavior before invoking it.

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 purpose and usage, followed by clear cost and behavior notes. It is appropriately sized, though the charging information is slightly redundant between the explicit price and the later 'each call is charged' clause.

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

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

For a one-parameter, read-only lookup tool with annotations covering safety and no output schema, the description supplies everything needed: purpose, usage context, input range, output fields, pricing, and side-effect behavior. Nothing an agent needs in order to call it correctly appears 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?

Although the single parameter is fully described in the schema, the description adds domain meaning beyond the bare 'Status code' field by specifying the valid 1xx-5xx range and calling out specific codes like 402 and 429. The example code=429 further clarifies accepted input.

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

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

The description names a specific resource and output: the name, plain-language meaning, and retry guidance for an HTTP status code. It scopes the input to 1xx-5xx and gives concrete examples, making it unmistakable versus otherwise unrelated sibling tools.

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

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

It explicitly says to use this when handling API errors and provides an example call with code=429. There are no obvious alternative HTTP-status tools to contrast with, but it does not state any exclusions or when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'reads or computes only and changes nothing' is largely redundant; the real added value is the cost model ($0.01/call, first 25 free, failed calls free) and the note that repeats are not free, which explains the non-obvious idempotentHint=false for a pure computation. Rate limits and error behavior are still unstated.

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

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

Output fields are front-loaded in the first sentence, followed by use case, example, pricing, and safety in a compact sequence with no filler. The payment sentence is long but carries decision-relevant information rather than marketing fluff.

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, enumerating the returned fields in the description is exactly the right compensation, and the cost/permission facts make it safe to call. It still omits response format (JSON structure) and failure/error semantics for invalid CIDR strings.

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%: both `cidr` and the optional `ip` membership-test parameter are already documented in the schema. The description reinforces this ('whether a given IP falls inside') and supplies a format example (cidr=192.168.1.0/24), but adds little the schema doesn't already say, 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?

The description names a specific resource (an IPv4 network in CIDR notation) and enumerates exactly what it computes: network/broadcast address, first/last usable host, netmask, address count, and membership test. It never routes the agent away from the sibling `ip_info`, so the boundary between 'CIDR math' and 'IP lookup' is inferred rather than stated.

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

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

'Use for firewall rules and allowlists' plus a concrete example input gives an agent a clear context for reaching for this tool. There are no explicit when-not conditions or named alternatives (e.g., 'use ip_info for geolocation/ASN instead'), so it stops short of full routing guidance.

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

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

Goes well beyond the annotations: names the data source and license (DB-IP City Lite, CC BY 4.0), discloses the accuracy ceiling ('city level at best'), the refusal behavior for private/reserved IPs, and the cost model ($0.01/call, first 25 free, failed calls free). It also explains why repeated calls are not free, which reconciles with idempotentHint=false.

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

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

Front-loaded with the verb, resource and returned fields, then usage, then pricing. It is a single dense paragraph where nearly every sentence earns its place; the payment-channel detail ('x402 USDC or a card key (/credits)') is slightly more than an agent needs to invoke the tool.

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

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

No output schema exists, yet the description enumerates the returned fields, the data provenance and accuracy, and the cost/failure behavior. An agent has everything required to decide whether to call it and what to expect back.

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

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

With only one parameter at 100% schema coverage, the schema already documents 'Public IPv4 or IPv6 address'. The description reinforces the public-only constraint and adds a worked example (ip=8.8.8.8), but supplies no format or edge-case detail beyond what the schema carries. 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 ('Geolocate an IPv4 or IPv6 address') and enumerates the exact outputs (city, region, country code/name, continent, lat/long, address range). It explicitly separates itself from ip_lookup ('for the network owner and registry record use ip_lookup'), so an agent can route between the two without opening either schema.

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

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

Gives concrete use cases ('localise a visitor or caller, pick a region or enrich logs') plus a named alternative with its distinguishing condition ('network owner and registry record' → ip_lookup). It also states an exclusion rule: private and reserved addresses are refused.

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

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

The description says the tool works 'without any lookup' and 'reads or computes only', which describes a purely local computation. The annotations set `openWorldHint: true`, implying interaction with an open world of external entities; that directly conflicts with the description's no-lookup/local-only claim. The cost and idempotency details are otherwise useful, but the structured annotation contradicts the stated behavior.

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

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

The definition is front-loaded with the core classification behavior and the use case. It is mostly efficient, but the pricing sentence and the later 'each call is charged, so repeats are not free' restate the same billing point, adding slight redundancy.

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

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

With one parameter, no output schema, and rich annotations, the description does enough: it lists the returned classifications and computed forms, notes that no lookup occurs, and explains billing. It does not describe the exact response shape, so it is not fully complete, but an agent has enough to call it correctly.

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

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

There is only one parameter and schema description coverage is 100%, so the schema already carries the parameter documentation. The description adds an example (`ip=10.1.2.3`) and says IPv4 or IPv6 is accepted, which is a small but useful addition beyond the schema's generic 'The IP address'. 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 states a specific verb and resource: classify an IPv4 or IPv6 address. It enumerates the exact classifications (version, private, loopback, link-local, CGNAT, public) plus computed forms, so an agent can distinguish it from sibling `ip_cidr` without opening either schema.

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

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

It gives a concrete use case: triage IPs in logs or allowlists. It also clarifies that no external lookup occurs, which helps separate it from DNS or geolocation tools. It does not explicitly name or exclude the sibling `ip_cidr`, so the routing guidance is clear but not exhaustive.

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

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

Adds substantial context beyond the annotations: billing model ($0.01/call via x402 USDC or card key, first 25 free, failed calls free) and an explicit no-side-effect statement that reinforces readOnlyHint. 'Each call is charged, so repeats are not free' meaningfully explains the idempotentHint=false finding rather than leaving the agent to guess. It does not disclose update cadence or caching, which is the remaining gap.

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

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

Front-loads the core payload (what the position includes) in the first clause, then use cases, then commercial terms. Dense but every sentence carries information; the pricing clause is long but is genuinely decision-relevant for a paid 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 does the work of naming the returned fields and the upstream source, which is enough to interpret a result. Missing freshness/latency expectations and whether values are cached, which for a 'current position' tool an agent may care about.

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

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

The single optional 'only' projection parameter is fully documented in the schema at 100% coverage, so the description can rely on it. The description itself adds no meaning about the parameter, which is acceptable at this coverage level but is a missed opportunity for a low-cost optimization hint.

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 resource (International Space Station) and enumerates exactly what is returned: latitude, longitude, altitude, speed, and daylight status. No sibling tool covers orbital/satellite data, so an agent can distinguish it immediately; the data source (wheretheiss.at) is also named.

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 concrete usage contexts (space apps, education bots, sky-watching alerts) which tell an agent the kind of request this fits. It stops short of explicit when-not-to-use guidance or naming an alternative, but with no comparable sibling in the list there is little to disambiguate against.

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

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

Annotations already declare readOnly/destructive/idempotent, but the description adds real value beyond them: the pricing model ($0.01/call, first 25 free, failed calls free) and the explicit explanation that repeats are charged, which reconciles the surprising idempotentHint=false. It does not say what happens on malformed JSON (error vs. repair), the one remaining behavioral gap.

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

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

Front-loaded with purpose, then usage, then example, then commercial terms — logical order with no filler. The pricing sentence is longer than the rest but carries information an agent cannot get elsewhere.

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 states the return value (formatted text) and covers cost and side-effect profile. Only the invalid-input failure mode is left unspecified, which is a modest gap for a pure-transformation tool.

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

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

Schema coverage is 100% and the schema already documents text, indent (2 default, 4 or tab) and sortKeys. The description repeats the same indent options and shows one example object, adding only marginal meaning beyond the structured fields, 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 (format JSON) plus the two axes of behavior (indentation, key sorting) and names the return value. The example input makes it clearly distinguishable from siblings like json_minify, json_validate, json_repair and json_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?

"Use to make machine JSON readable or to normalise it for diffs" gives concrete usage contexts, which is stronger than implied usage. It never names an alternative tool or exclusion (e.g. use json_minify to compact, json_validate to check), so it stops short of explicit when-not guidance.

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

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

Annotations already declare readOnly/destructive=false, but the description adds meaningful context they don't cover: the billing model ($0.01/call, first 25 free, failed calls free) and the explicit warning that repeats are not free. That cost/idempotency nuance is genuinely useful and consistent with idempotentHint=false, though nothing is said about how malformed JSON is handled.

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

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

Front-loaded with the core action and example, then the pricing detail last. The pricing/payment sentence is dense with clauses but each carries information an agent would otherwise have to guess at.

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, annotation-backed transform tool this covers the essentials: what it does, one use case, a format example, the size-delta output, and the cost model. The only real omission is error behavior on invalid JSON input, which the agent must infer.

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

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

Schema coverage is 100% for the single 'text' parameter, so baseline is 3; the inline example text={ "a" : 1 } adds concrete format guidance beyond the terse schema field description, pushing it up one.

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: 'Remove all unnecessary whitespace from JSON', plus the side output ('report the size before and after'). It is distinguishable from siblings like json_format or json_validate by the whitespace-removal framing, though it never names those siblings to sharpen the contrast.

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

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

'Use to shrink payloads or prompts' gives one concrete context, but there is no when-not-to-use guidance and no mention of the near neighbors (json_format, json_repair, pack_json_toolbox) an agent would plausibly confuse this 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so 'reads or computes only and changes nothing' is mostly redundant. The description adds genuinely non-redundant behavior: per-call pricing, first 25 free, failed calls free, and 'each call is charged, so repeats are not free', which explains the idempotentHint=false annotation in practical terms.

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

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

The repair list and usage trigger are front-loaded in the first two sentences, so the critical information is reached immediately. The billing/pricing tail is longer than strictly needed for tool selection, though it is operationally relevant.

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

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

Even without an output schema, the description says what comes back ('the repaired JSON and whether it now parses'), what happens on failure (failed calls free), and confirms no side effects. Nothing an agent needs in order to call this one-parameter tool correctly is missing.

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

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

With one parameter at 100% schema coverage the baseline is 3, and the description adds real value by showing a sample of the 'text' payload (```json fences, single-quoted keys, trailing commas) that demonstrates accepted input rather than just naming the field.

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 ('Fix JSON') and then enumerates the exact failure modes it repairs: fences, prose, comments, trailing commas, single quotes, bare keys, True/False/None, unclosed brackets. The clause 'Use when an LLM's JSON output fails to parse' implicitly separates it from json_format/json_validate, which handle well-formed input.

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

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

Gives an explicit trigger condition — 'Use when an LLM's JSON output fails to parse' — plus a worked example of the input shape it targets. It does not name the closest siblings (json_validate, json_format) as alternatives, so the agent must infer that valid JSON should go elsewhere.

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

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

Beyond the read-only and non-destructive annotations, it discloses that each call is charged, repeats are not free, the first 25 calls are free, failed calls are free, and payment is via x402 USDC or a card key. It also explains what the output contains, including draft version and supported inference features.

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

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

The definition is front-loaded with the core action and inferred output, followed by usage, an example, and billing details. It is somewhat dense because it packs pricing and behavioral notes into the same paragraph, but every sentence carries useful 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 simple one-parameter tool with no output schema, the description covers purpose, output format, usage context, an example input, and billing behavior. An agent has enough information to decide when to call it and what to expect.

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

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

The schema has one parameter with 100% description coverage, so the baseline is 3. The description supplies an example value for the json parameter, which clarifies expected input shape, but it does not add substantial syntax or formatting details beyond that example.

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

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

The description states a specific verb and resource: infer a JSON Schema from an example JSON value. It names the schema draft, the inferred constructs, and distinguishes itself from sibling tools like json_validate and json_format by focusing on schema generation rather than validation or formatting.

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 use cases: documenting an API response or validating later data against the same shape. It does not explicitly state when not to use it or name alternatives such as json_validate, but the intended context is easy to infer.

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

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

Annotations already cover read-only, non-destructive, non-idempotent, open-world, but the description adds the non-obvious parts: per-call billing ($0.01 via x402/card key, first 25 free, failed calls free) and that repeats are not free, which operationalizes idempotentHint=false. It still omits edge behavior such as empty arrays, objects with disjoint keys, or CSV quoting/escaping.

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 transformation and output shape, then usage, then a compact concrete example, then cost caveats. Every sentence carries information the agent needs.

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

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

With no output schema, the description must convey the return format, and it does (header row from all keys, nested values as JSON) while also flagging the pricing model. Missing detail on uneven keys/delimiter escaping is the only real gap for a single-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 baseline 3 applies, but the description adds real meaning: the input must be an array of objects and the header row is the union of all keys, with nested values serialized as JSON. The worked example with two records makes the expected input concrete.

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 both resource types ('Convert a JSON array of objects to CSV') plus the output shape ('header row built from all keys'). This clearly separates it from the reverse sibling csv_to_json and the other json_* tools.

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

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

'Use to export API results to a spreadsheet' gives a concrete triggering scenario. It does not name the inverse tool (csv_to_json) or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations cover the safety profile (readOnly, non-destructive, non-idempotent), and the description adds value beyond them: block-style/no-folding output shape, 100 KB limit, 400-on-invalid-JSON with no charge, pricing and first-25-free, and the note that repeats are charged because each call costs — which coherently explains idempotentHint=false.

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 conversion and format details, then the routing hint, then limits and pricing. It is dense but every sentence conveys actionable information; the pricing/credits clause is a little promotional ('Price $0.01/call via x402 USDC or a card key (/credits)') and could be trimmed without loss.

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

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

For a single-parameter, no-output-schema conversion tool this covers input limits, error semantics, output style, and cost. The only modest gap is a precise statement of what the returned YAML document contains (bare document vs. trailing newline, multi-document handling), though 'block style, no line folding' already sets 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 coverage is 100% with a single required 'json' string parameter, so the baseline is 3. The inline worked example (json={"name":"agent","ports":[80,443],"enabled":true}) usefully shows that the parameter takes a JSON *string* rather than a structured object, which is the one ambiguity the schema type alone leaves.

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 a JSON value into a YAML document'), pins the output style (block style, no line folding), and names the sibling for the reverse direction (yaml_to_json). An agent can distinguish it from json_format, json_minify, and yaml_to_json 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?

Gives the positive condition ('use when a tool or person wants YAML'), the explicit exclusion/alternative ('for the reverse use yaml_to_json'), and names target use cases (config files, K8s manifests, GitHub Actions). Also states the 100 KB input ceiling, which is a real gating condition.

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

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

The description adds meaningful behavior beyond annotations: return values for valid and invalid input, line/column error details, pricing, free failed calls, and the fact that repeated calls are charged. These details are consistent with readOnlyHint=true, destructiveHint=false, and idempotentHint=false.

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

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

The description is front-loaded and mostly efficient, moving from purpose to return format to usage to pricing. The safety sentence partly repeats annotation information, which slightly reduces conciseness.

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 validation tool with no output schema, the description covers purpose, return shape, error reporting, usage context, pricing, and safety. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the single text parameter and its 20,000-character limit are already documented in the schema. The description adds only an example, so the baseline score of 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 states a specific verb and resource: check whether text is valid JSON. It is clear what the tool does, but it does not explicitly distinguish itself from closely related siblings such as json_repair, json_format, or json_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 a clear usage context: use before parsing an LLM's or an API's output. However, it does not specify when to choose this over json_repair or json_format, nor does it state exclusions.

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

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

Annotations already declare readOnlyHint/destructiveHint/idempotentHint, and the description goes well beyond them: signature not verified, the token is not stored, it 'reads or computes only and changes nothing', and each call is charged so repeats are not free — which explains the non-idempotent hint. Pricing details (first 25 free, failed calls free, $0.01/call via x402 USDC or card key) are context the 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 and the critical 'signature not verified' caveat are front-loaded, and the sentence order (what → safety warning → use case → example → cost) is logical. The pricing sentence is dense and slightly run-on, but each clause carries distinct information an agent needs.

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 enumerates the returned fields and their date normalization plus the expiry boolean. Combined with the safety caveat, storage note, and billing model, an agent has everything needed to call this correctly and interpret the result.

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

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

There is a single required parameter at 100% schema description coverage, so the schema already carries the burden. The description adds a worked example token that illustrates the expected compact-serialization format, but nothing about validation, whitespace, or malformed-token handling — baseline 3 fits.

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

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

The opening clause names the exact operation and resource — decoding a JWT's header and payload — and immediately scopes it with 'without a key' and '(the signature is not verified)'. It also enumerates the returned fields (issued-at, not-before, expiry as dates, expired flag), so an agent knows precisely what it gets 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?

'Use to debug auth flows' gives a concrete use case, and 'Do not use the result to trust a token' is an explicit exclusion/warning about misuse. No sibling alternative is named, but no sibling performs JWT decoding, so there is nothing to route away to.

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

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

Goes well past the annotations by disclosing cost mechanics ($0.01/call, first 25 free, failed calls free), explaining why repeats are not free (consistent with idempotentHint=false), and describing output shaping (deduplication, engine-count ranking, question/buying-intent separation, ~200 keyword cap). The 'reads or computes only and changes nothing' line aligns with readOnlyHint=true rather than contradicting it.

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 output description before cost details, and every clause carries information. It is one dense run-on paragraph, and the pricing/payment sentence is bulky relative to the rest, costing a point on structure.

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 conveys the return shape (deduplicated, ranked, question and buying-intent groups, up to 200 items) plus source engines and exclusions. Combined with 100% schema coverage and a full annotation set, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents lang, country, engines, and deep. The description adds some value by explaining what deep actually produces (seed + a-z, how/what/best/vs, up to 200 keywords) and giving a seed example, but leaves lang/country/engines entirely 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 deliverable: 'the search phrases real users type for a seed keyword' pulled from named engines, deduplicated and ranked. It also differentiates from the closest sibling (text_keyword_density) by framing output as new keyword ideas rather than density analysis of supplied text.

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

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

Gives explicit use cases ('plan content, find long-tail and question keywords, or name a product') and a negative boundary ('No search volumes') that prevents misuse. It does not name a sibling alternative for adjacent needs, but the scope statement is clear enough to route correctly.

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

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

Annotations declare readOnlyHint, openWorldHint, destructiveHint=false and idempotentHint=false; the description goes beyond them by explaining *why* it is non-idempotent — every call is charged ($0.01 via x402 USDC or card key, first 25 free, failed calls free) so repeats cost money. That is exactly the kind of cost/auth context annotations cannot convey, and it reinforces 'reads or computes only and changes nothing' consistently.

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

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

Front-loaded with the verb and dataset, then filters, then source, then usage, then billing — a sensible order with no filler sentences. The billing/access clause is dense and runs long, slightly blurring the main purpose on first read.

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 naming the returned fields (input/output price, context length, max output, modalities, computed call cost). For a 9-parameter, zero-required query tool, an agent has everything needed to call it and interpret the response.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters; the description nonetheless clarifies the coupling between inputTokens and outputTokens (they estimate the cost of your call) and restates the filter/sort axes in task terms. It adds modest but real meaning 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?

States a specific verb and resource — 'Compare the API prices of about 450 LLMs' — and enumerates the concrete data returned (USD per million input/output tokens, context length, max output, modalities, per-call cost). The provider list and 'OpenRouter's public model list' source make it unmistakably distinct from siblings like crypto_price or units_convert.

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

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

'Use to pick the cheapest model that fits a job' gives the decision context explicitly, and the description lists the filter/sort axes that select among alternatives. It adds a worked example ('q=llama') and names the sibling-free workflow, leaving little to infer.

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

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

Adds genuinely useful behavior beyond the annotations: pricing ($0.01/call, first 25 free, failed calls free) and the fact that repeat calls are charged, which explains idempotentHint=false. 'Reads or computes only and changes nothing' largely restates readOnlyHint, but the cost and randomness disclosure carry real value.

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, usage, example, and pricing in a compact block. The sentence 'Reads or computes only and changes nothing' is redundant with the readOnlyHint annotation, a minor waste.

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-optional-parameter novelty tool with no output schema, the description covers purpose, random output, cost model, and intended audience. It could be stronger by pointing at yes_no for a deterministic alternative, but nothing essential for calling 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?

With 100% schema coverage and a single optional 'question' parameter, the schema already does the documentation work. The example (question=Will it ship today?) clarifies expected format but adds little beyond what the schema states, 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 ('ask a yes-or-no question and get one of the 20 classic Magic 8-Ball answers, chosen at random'), which is clear and unambiguous. It does not differentiate from the sibling 'yes_no' tool, which is the nearest alternative, so it falls 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?

Gives explicit use context ('For fun only. Use for games and chat bots'), which is more than implied usage. It does not name exclusions or the sibling alternative yes_no for deterministic answers, so no 5.

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

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

Goes beyond the annotations by disclosing that raw HTML in the input is escaped and the result is safe to embed — a security trait nowhere in the structured fields — and explains the non-idempotent hint by noting each call is charged so repeats are not free. It still doesn't describe the return shape (fragment vs. full document) or size limits.

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

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

The core purpose and the feature list are front-loaded in the first sentence, with safety and cost after. The billing sentence is dense and the inline example is clumsily formatted inside a prose sentence, costing some readability without padding the whole.

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 tool with full schema coverage and annotations covering safety, this is nearly complete: purpose, supported syntax, escaping behavior, and pricing are all present. Only the exact form of the returned HTML and any input-size limits are left unstated.

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

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

Schema coverage is 100% for the single 'markdown' parameter, so the baseline is 3. The example ('markdown=# Title ...') illustrates an accepted value but adds nothing about limits, size caps, or encoding that the schema doesn't already cover.

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 both source and target formats ('Convert Markdown ... to HTML') and enumerates the constructs handled, which lets an agent distinguish it from inverse tools like html_to_text or csv_to_markdown 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?

'Use to publish agent-written Markdown on a web page' gives a concrete usage context, and the cost note implies when not to call it redundantly. However, it never names an alternative (e.g. html_to_text for the reverse direction) or any exclusion, so it stops short of explicit 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?

Adds substantial behavior beyond the annotations: the parser is safe and never executes code, there is a 500-character limit, calls cost $0.01, the first 25 are free, failed calls are free, and repeats are not free. The readOnlyHint=true and destructiveHint=false annotations are consistent with 'reads or computes only and changes nothing'.

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

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

Front-loads what the tool computes and what syntax it accepts, then follows with usage, an example, and pricing. Slightly redundant at the end ('each call is charged, so repeats are not free' repeats the $0.01/call point), but every part is relevant.

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

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

The description is thorough on syntax, limits, and billing, but with no output schema it never states the return type or shape (e.g., a number vs. a formatted string, or how rounding is handled). That is a clear gap for a compute tool, though the rest of the entry is complete.

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

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

Schema coverage is 100% and the schema itself includes an example, so parameter semantics are already well served. The description adds useful meaning with the supported operator/function set and the 500-character constraint, which the schema does not state.

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 (evaluate) and resource (arithmetic expression) and enumerates exactly what the parser accepts: operators, constants, and named functions. This clearly separates it from siblings like math_stats, units_convert, and the calc_* helpers.

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

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

Gives an explicit usage condition ('when an agent needs exact arithmetic instead of guessing, for prices, unit maths or formulas') with a concrete example. It does not name the sibling tools an agent should prefer for statistics or unit conversion, but the context is otherwise clear.

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

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

Annotations already declare readOnlyHint/destructiveHint/idempotentHint, but the description adds the non-obvious 'why': each call is billed, so repeats are not free, which explains idempotentHint=false. It also discloses price, the free-tier allowance, the 10,000-number cap, and that failed calls are free — real value beyond the annotations.

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

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

The output list is front-loaded and the example, limits, and pricing follow in a logical order. Slightly dense — the pricing/second sentence is long — but each sentence carries information an agent can act on.

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

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

With no output schema, the description fully compensates by enumerating every returned statistic and the interpolation method for percentiles. Combined with input format, size cap, and cost model, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% for the single parameter, and the schema already documents the separator formats. The description adds the 10,000-number limit and a worked example, but omits the newline separator mentioned in the schema — marginal added meaning, so baseline 3.

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 opening clause names a specific verb (compute descriptive statistics) and a specific resource (a list of numbers), then enumerates the exact outputs (mean, median, variance, quartiles, percentiles). That makes it easy to distinguish from math_evaluate or text_stats by subject matter, though no sibling is named explicitly.

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

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

'Use to summarise measurements, latencies, prices or scores without a spreadsheet' gives concrete, actionable usage context. It does not, however, state when to prefer a sibling such as math_evaluate (expressions) or text_stats (text corpora).

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

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

Beyond annotations, it discloses return behavior ('deleted: false when there was nothing to delete'), retention limits, read-after-write lag, namespace scope, and billing details including repeat-call charges. This is rich behavioral context for a destructive paid operation.

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 action and remains generally efficient. Some clauses are redundant, such as restating expiry rules and pricing, but each major sentence contributes operational context.

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 destructive, paid, two-parameter memory tool with no output schema, the description covers return semantics, billing, scope, expiry, and read lag. Nothing essential for correct invocation 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 coverage is 100%, so the schema already documents both parameters in detail, including namespace secrecy and key length. The description adds a concrete example but mostly reinforces what the schema provides rather than adding new 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?

The description starts with a specific verb and resource: delete the value saved under a key in your namespace. It clearly distinguishes deletion from sibling memory operations such as memory_set and memory_get, and the added usage phrase 'forget a fact or clear task state' reinforces intent.

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

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

It gives a clear use case: 'Use to forget a fact or clear task state.' It does not explicitly contrast with memory_set, memory_get, or memory_list, but the deletion context and scope make the intended usage clear enough for an agent.

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

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

Goes well beyond the annotations: TTL cap of 30 days, cross-region read lag up to a minute, 404-on-miss/expired with no charge, and per-call pricing with 25 free. The note that every call is charged even if repeated directly explains why idempotentHint is false for a read-only tool — genuinely useful context an agent cannot get from structured fields.

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

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

Front-loaded with the action and scoping, then cost/lag caveats, which is the right order. Slightly over-packed: 'failed calls free' duplicates the earlier 'is not charged', and 'changes nothing' restates readOnlyHint, costing a little density.

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 only two required params and no output schema, the description covers everything an agent needs: how to address the record, what comes back (value plus saved and expiry timestamps), failure mode, staleness window, and cost. Nothing material is left to guess.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a worked example (namespace=demo-agent-memory-7f3c9a21, key=user-preferences) that illustrates the expected shapes and reinforces that key is scoped inside namespace. Minor value-add only, since the schema already spells out both fields.

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

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

States a specific verb+resource (read a saved value by namespace+key) and ties it explicitly to its counterpart /memory/set, so the read/write pair with memory_set is unambiguous. The one-line 'Use to recall what an agent saved in an earlier run' pins the intent with no vagueness.

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 situational context ('recall what an agent saved in an earlier run') and a concrete example call with namespace and key. It does not explicitly exclude or route to siblings like memory_list or memory_delete, so an agent must infer when listing beats direct key lookup.

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

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

Goes well beyond the annotations: page size cap (100), cursor chaining, fields returned (size, save time, expiry), a 30-day TTL, and a read-after-write lag of up to a minute. It also explains the billing model and that repeat calls are charged, which is exactly the context an agent needs to avoid wasteful polling, and it is consistent with readOnlyHint=true and idempotentHint=false.

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

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

Front-loads what is listed and what is excluded, then pagination, then lifetime/lag, then pricing — a sensible order. The pricing clause is long and somewhat dense ('$0.002/call via x402 USDC or a card key...') but each sentence carries operational 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?

There is no output schema, and the description compensates by naming the returned fields and explicitly stating values are omitted. With pagination, TTL, consistency lag, and cost all covered, an agent has everything needed to call this repeatedly and 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 behavior not in the schema: prefix restricts keys to those starting with the text, and the cursor is explicitly 'the returned cursor for the next page', clarifying the pagination contract. Namespace semantics (secret, password-like) remain in the schema only.

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

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

Opens with a specific verb+resource+scope: 'List up to 100 keys saved in your namespace', and immediately distinguishes itself from memory_get by stating values are not included. An agent can tell it apart from memory_set/memory_get/memory_delete 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?

'Use to see what an agent has saved' gives a positive trigger and it explicitly routes to /memory/get for values, which is the main alternative an agent would consider. It lacks an explicit 'do not use this for X' exclusion (e.g., content retrieval versus deletion), so it is clear but not fully exhaustive.

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

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

Goes well beyond the annotations: overwrite-of-existing-key semantics, TTL of 1-30 days with a default of 30, values persisting until expiry or deletion, cross-region read lag up to a minute, billing model including free failed calls, and the blast radius ('changes only what you saved in your own memory namespace'). Annotations only supply the readOnly/idempotent/destructive flags, so this is substantial added context.

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

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

The core action and its storage semantics are front-loaded and the paragraph is dense with useful facts. It loses a point for redundancy: TTL/expiry is stated twice ('expires after 1 to 30 days' and 'kept until they expire (at most 30 days)') and pricing is restated at the end.

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 4-parameter write tool with no output schema, the description covers lifetime, consistency, cost, scope of effect, and overwrite behavior, leaving nothing an agent needs in order to call it correctly.

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

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

Schema description coverage is 100% and the schema already documents the key length, value size, days range/default, and the namespace-as-password warning. The description restates the value size and TTL rather than adding new syntax or format guidance, 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 ('Save a value ... under a key in your own namespace') plus the payload limit, and names memory_get as the read counterpart, which separates it from memory_get/memory_list/memory_delete in the sibling set.

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 says when to use it: 'Use to persist what an agent learned for a later call to memory_get,' and warns that each call is charged so repeats are not free. It does not mention the other siblings (memory_list for enumeration, memory_delete for removal), so the routing picture is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false; the description reinforces this with 'reads or computes only and changes nothing.' It adds genuinely non-structured context: per-call pricing ($0.002 x402 USDC / card key), 25 free calls, failed calls free, and the warning that repeats are charged—consistent with idempotentHint=false.

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

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

The core purpose is front-loaded, but billing details ($0.002/call, free tier, failed calls free) are interleaved into the same narrative as functional behavior, making the sentence dense and slightly noisy for a trivial lookup tool. Every clause is relevant, but the mixture of semantics and commerce could be better separated.

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

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

There is no output schema, and the description compensates by describing both return dimensions (content type and inline-display flag). For a one-parameter lookup tool this is nearly sufficient; the only minor gap is not stating how unknown extensions are handled.

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

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

Schema coverage is 100% for the single required 'file' parameter, so baseline is 3. The description goes slightly beyond by demonstrating accepted input form ('Example: file=report.xlsx') and describing the second output dimension (inline display), which helps the agent understand what the input is used for.

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 ('MIME (content) type for a file name or extension') and anchors it with a concrete example ('report.pdf → application/pdf'). This clearly separates it from siblings like base64_encode or hash, which also operate on files/strings but return different artifacts.

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

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

'Use when uploading or serving files' gives a concrete usage context, and the inline-display note signals the serving use case. No explicit exclusions or named alternatives, but no sibling in the list plausibly overlaps (nothing else resolves MIME types), so the lack of routing guidance is low-risk.

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?

With annotations already declaring the safety profile, the description adds genuinely non-redundant context: pay-per-call pricing, first 25 free, failed calls free, and the fact that repeats are charged, which explains why idempotentHint=false. 'Reads or computes only and changes nothing' is largely a restatement of readOnlyHint/destructiveHint, but the cost model is real added value.

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?

Core purpose is front-loaded in the first sentence, but the trailing payments sentence drags in '/credits', 'x402 USDC' and card-key detail that is partially redundant with 'each call is charged, so repeats are not free'. Some of the cost clause earns its place; the payment-rail specifics are clutter.

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

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

For a two-param converter with no output schema, the description covers inputs and cost but never says what comes back (a string, e.g. 'MMXXVI') nor what happens if both or neither argument is supplied. Adequate but leaves behavioural edges to be discovered.

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

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

Schema coverage is 100% and both parameters are documented, so the baseline is 3. The description goes beyond by stating the 1-3999 range for number and clarifying the mutual-exclusivity mode ('Give either number or roman'), which is not expressed in the schema (required: 0).

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 in both directions ('Convert a number (1-3999) to Roman numerals, or Roman numerals back to a number') and gives the valid range, so an agent knows exactly what it does. It does not differentiate itself from the near-neighbour sibling number_words, so it stops 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?

'Use for dates, outlines and puzzles' gives loose context for when the tool applies, and 'Give either number or roman' implies the input-mode choice. There is no explicit when-not guidance and no named alternative among the many siblings.

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 and destructiveHint=false, and the description reinforces that ('reads or computes only and changes nothing'). More valuable is the disclosure that each call is charged ($0.01/call via x402 USDC or card key, first 25 free, failed calls free), which explains why idempotentHint=false — repeats are not free. It stops short of describing output formatting details, but the cost/rate-limit disclosure is real added context.

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

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

Purpose, scope, and the example are front-loaded, and the pricing sentence is dense but earns its place by answering cost and idempotency questions. The example value (number=1234.5) is slightly redundant with the preceding sentence but harmless.

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

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

For a single-parameter conversion tool with no output schema, the description covers input bounds, output shape (words plus cheque form), cost, and safety. Only the exact response structure is left implicit, which is a minor gap for a tool this simple.

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

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

Schema coverage is 100% and the single parameter is already documented as 'decimals allowed'. The description still adds meaning beyond the schema: the upper bound (trillions), that negatives are accepted, and that a decimal amount triggers a cheque-form output with 'and' cents.

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 ('Write a whole number ... out in English words') and immediately bounds the domain (up to trillions, negatives allowed, decimals get a cheque form). This clearly separates it from sibling number_roman, which converts to Roman numerals rather than English words.

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

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

'Use when amounts must be written out in full' plus the cheques/invoices framing gives a concrete usage context. It does not name an alternative tool or state when not to use it, so it falls short of explicit routing guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the description's 'reads or computes only and changes nothing' mostly restates them. It does add genuinely non-schema behavior: automatic decoding when input already looks encoded, and per-call charging (first 25 free, failed calls free) which explains the idempotentHint=false cost implication. The lack of any statement about what the response looks like is the main remaining gap.

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

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

The capability list and use case are front-loaded and every clause names a distinct format, so the long first sentence is dense rather than padded. The trailing pricing sentence is transactional necessity rather than description value, and the 'reads or computes only' clause is mild redundancy against the annotations.

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

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

For a one-parameter, no-output-schema tool this covers inputs, formats produced and billing well enough to call correctly. What is missing is how the result is shaped — whether all encodings are returned together or only those relevant to the input, and how the auto-decode path is signalled — which an agent would need to interpret the response.

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

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

With 100% schema coverage the single 'text' parameter is already documented, including the 20,000-character limit, so the schema carries the load. The description nonetheless adds value by supplying a realistic sample value ('Café & <tags>') that shows the tool expects arbitrary mixed text rather than pre-encoded input.

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

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

States a concrete verb+resource ('every common encoding of one text in a single call') and enumerates the exact formats produced (Base64/Base64url, hex, URL component and full-URL, HTML, ROT13, code points, UTF-8 byte count, Punycode) plus automatic decoding. This clearly distinguishes it from the single-format siblings such as base64_encode, url_encode and text_caesar 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?

'Use to prepare data for headers, URLs and markup, or to work out what an encoded string says' gives both a write-side and a read-side use case with a worked example (text=Café & <tags>). It does not explicitly say when to prefer this over the narrower base64_encode/url_encode siblings, so the boundary is implied rather than stated.

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

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

Annotations already cover read-only, non-destructive and non-idempotent, and the description reinforces that nothing is changed. It adds context the annotations do not carry: per-call pricing ($0.002 via x402 USDC or card key), 25 free calls, failed calls free, and that repeats are billed. Input semantics (UTF-8 vs 0x/hex bytes) are also noted.

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