Agent Data Tools: Developer utilities

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

Annotations already declare readOnly=false, openWorld=true, idempotent=false and destructive=false. The description adds useful context beyond those flags: missing-padding tolerance, UTF-8 output, and the $0.001 USDC/x402 payment requirement per successful call.

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

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

Four short sentences, front-loaded with the core action and followed by input tolerance, use cases, and payment details. Every sentence adds distinct information.

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

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

For a simple one-parameter decode tool with no output schema, the description covers purpose, accepted input formats, output encoding, use cases, and cost/payment. 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?

There is only one parameter with 100% schema description coverage, so baseline is 3. The description adds input-format semantics by stating that both standard and URL-safe base64 are accepted and that missing padding is tolerated.

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

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

States a specific verb (Decode) and resource (standard or URL-safe base64 to UTF-8 text), and names accepted input variants. It distinguishes itself from sibling base64_encode by direction, though it does not explicitly name that sibling.

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

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

Provides concrete use cases: encoded headers, tokens and data URLs. It does not state when not to use it or name alternatives such as url_decode for percent-encoded strings, so it falls short of full routing guidance.

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

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

Annotations cover the safety profile (destructiveHint=false), and the description adds genuinely new behavioral context: it returns both standard and URL-safe variants, and it costs $0.001 in USDC on Base via x402 per successful call. The payment disclosure is a significant trait not derivable from annotations or schema, though error/failure behavior beyond "successful call" is not detailed.

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

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

Three tight sentences, front-loaded with the action, then use cases, then cost. Every sentence carries distinct information with no redundancy.

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

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

For a one-parameter tool with no output schema, the description covers purpose, use cases, cost, and the fact that two variants are returned. It could say more about the exact return shape (e.g., field names), but it is adequate for correct invocation.

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

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

With a single parameter at 100% schema coverage the baseline is 3. The description slightly exceeds it by clarifying that the input is treated as UTF-8 text, which adds encoding semantics beyond the schema's plain "The text to encode."

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 ("Encode UTF-8 text as standard base64") and adds the secondary behavior of returning the URL-safe variant. The encode direction naturally distinguishes it from the base64_decode sibling, but the sibling is never named explicitly, so it falls just short of the top tier.

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 contexts ("data URLs, headers and basic auth strings"), which tells the agent when this tool is appropriate. It does not name alternatives or state when not to use it, so it stops 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds meaningful context beyond those flags: the per-call cost ($0.001 USDC on Base via x402) and that mixed-case input like 'userID_value' is handled. It does not explain why the operation is flagged non-idempotent/non-read-only, but the payment disclosure accounts for the side effect.

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

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

Three front-loaded sentences with zero waste: purpose first, usage second, cost last. Every sentence earns its place and the reader gets the essential facts in order of importance.

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 2-parameter text transformation with full schema coverage, the description covers purpose, usage, edge-case input, and cost. It omits any mention of the return shape, which is a minor gap given there is no output schema, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 100% and the schema already enumerates valid 'to' values, so baseline would be 3. The description adds the mixed-input handling example ('userID_value'), which gives real meaning about accepted input beyond the bare 'The text' schema description.

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

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

States a precise verb ('Convert') and resource (text/identifiers) and enumerates the full set of target cases, so an agent immediately knows what the tool produces. It is clearly distinguishable from siblings like slug or text_stats 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 when renaming fields or generating code identifiers' gives a clear context for invocation. It stops short of naming when NOT to use it or pointing to an alternative sibling (e.g. slug), so it earns a 4 rather than a 5.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds genuinely non-structured context: the cryptographic fairness guarantee, the return shape, and notably the $0.001 USDC/Base x402 payment cost per successful call. That cost/payment detail is material behavioral information an agent needs.

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

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

Three short sentences, front-loaded with what it does, then returns, then cost. No filler; each sentence carries distinct information.

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

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

No output schema exists, and the description compensates by stating the return value ('each result and the totals'). Combined with the cost disclosure and full param coverage, it is nearly complete; only the exact result representation (e.g. heads/tails encoding) is unspecified.

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

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

Schema coverage is 100% with a single, fully documented 'count' parameter (1-100, default 1). The description only restates 'one or more' coins and adds no format or range 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 ('Flip one or more fair coins') and even names the mechanism ('cryptographic random source'), which distinguishes it from deterministic siblings. It does not explicitly name the nearest alternatives (dice, random_number, yes-no), so it stops short of full sibling differentiation.

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

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

'Use for fair decisions and games' gives implied usage context, but there is no when-not guidance and no reference to alternatives like dice or random_number for related randomness needs. Adequate but leaves routing to inference.

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

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

Annotations are present but thin in what they convey, and the description adds material context they do not carry: the exact cost ($0.001 USDC on Base per successful call) and the x402 payment mechanism, which is real behavioral information an agent needs. It does not describe the response shape, but for a stateless converter this is a minor gap.

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

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

Three tight sentences: capability first, accepted inputs second, usage plus the cost caveat last. No filler, and the most decision-relevant information (what it does and what it costs) is front-loaded.

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 trivial one-parameter converter with no output schema, the description covers the operation, input formats, output fields and the payment requirement. Nothing essential is missing, though it could have said whether the call fails or returns an error on an unparseable colour.

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 a single parameter at 100% schema coverage the baseline is already high, and the description genuinely adds value beyond the schema's bare 'The colour' by listing the accepted input formats (#rgb, #rrggbb, rgb(r,g,b), hsl(h,s%,l%)).

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

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

The description states a specific verb and resource ('Convert a colour between hex, RGB and HSL') and even enumerates the outputs it also returns (relative luminance, black/white text recommendation). It is very clear what the tool does, but it never names or distinguishes itself from the close siblings color_contrast and random_color, so an agent gets no sibling routing help.

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' implies a usage context but gives no when-not-to-use guidance and never points at color_contrast for the contrast-specific sibling. The agent must infer the boundary from the purpose statement alone.

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

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

The description discloses something no annotation carries: the $0.001 USDC on Base cost paid via x402 per successful call. That payment/auth requirement is high-value behavioral context, and it plausibly explains why readOnlyHint is false. It does not add further traits (determinism, format handling), so 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?

Two sentences, front-loaded with the core function followed by usage and cost. No filler; every clause carries information.

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

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

No output schema exists, yet the description covers the return shape (AA/AAA pass/fail at both text sizes) and the payment model. The only real gap is accepted colour input formats for a tool whose whole job is parsing colours.

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 fg/bg are already documented, and the description maps them to 'text colour' and 'background colour'. However, neither the schema nor the description specifies accepted colour formats (hex, rgb, named), so no meaning is added beyond the baseline.

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

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

States a precise verb+resource (compute WCAG 2 contrast ratio between text and background colours) and even enumerates the outputs (AA/AAA pass/fail at normal and large sizes). This clearly distinguishes it from the generic 'color' and 'random_color' 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?

'Use to check that a design is readable' gives an implied use context, but there are no exclusions, prerequisites, or named alternatives (e.g. vs. the generic 'color' tool). Minimum viable routing guidance only.

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

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

Adds genuinely valuable behavior beyond the annotations: output is in UTC and each successful call costs $0.001 in USDC on Base via x402. The payment/authorization detail is exactly the kind of context annotations don't carry (and helps explain readOnlyHint=false for what is otherwise a pure computation). It stops short of describing error handling for invalid expressions.

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

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

Two sentences, front-loaded with what the tool returns, followed by the usage cue and cost. Every clause earns its place; nothing is redundant with the schema.

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-value burden, and it does so by stating the output is next run times in UTC. Combined with the payment disclosure and syntax notes, an agent has enough to invoke it correctly; only failure/error semantics 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 coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: the 'expr' field is a standard 5-field expression supporting ranges, lists, steps and names like MON/JAN, and output is UTC. This meaningfully enriches the otherwise terse 'The cron expression' schema description.

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

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

States a specific verb+resource: computing the next run times of a standard 5-field cron expression. No sibling does cron evaluation (unix/time/date_add are distinct), and the description specifies the exact field layout and supported syntax, so an agent can identify it immediately.

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

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

Explicitly tells the agent when to reach for it: 'Use to check a schedule before deploying it.' This gives clear context, though it names no alternative or exclusion conditions (there is no obvious competing sibling, so the omission is minor).

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

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

Annotations only declare flag hints, so the description must carry the substance and it does: automatic delimiter detection, quoted-field support, default numeric coercion behavior, and a per-call price ($0.001 USDC on Base via x402). The payment disclosure is genuinely useful non-structured context. It does not discuss malformed-CSV/error behavior, which keeps it 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?

Tight, front-loaded prose: the conversion behavior comes first, then usage, then cost. The parenthetical delimiter list is dense but directly relevant; nothing is redundant.

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

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

For a stateless two-parameter converter with no output schema, the description supplies the return shape (JSON array of objects keyed by header row), the coercion rule, and billing terms. Only error/edge-case handling is left unstated, which is minor at this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a default that the schema omits — 'Numbers stay as text unless numbers=true' — clarifying the semantics of the optional flag and reinforcing that the first row is used as keys.

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

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

States a precise verb+resource (convert CSV to a JSON array of objects) and pins down scope: accepted delimiters, automatic detection, quoted-field handling, and the first-row-as-keys convention. An agent can distinguish this from json_to_csv 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 a clear selection context — 'Use to load spreadsheet exports into an agent' — which tells the caller which class of task this fits. It stops short of naming alternatives (e.g. json_to_csv for the reverse direction) or stating when not to use it, so it is context without 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?

Beyond the annotations it discloses month-end clamping semantics (31 Jan + 1 month = 28/29 Feb), weekend skipping for business days, the negative-number convention for subtraction, and a concrete cost of $0.001 USDC on Base per successful call paid via x402. The payment side effect is exactly the kind of behavioral context annotations cannot convey.

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

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

The core action is front-loaded, and each following sentence carries distinct necessary information (subtraction convention, business-day behavior, clamping rule, typical use, price). No filler or repetition.

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

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

With no output schema and carry-over annotations, the description supplies the semantics an agent needs (clamping, weekend skipping, cost). It does not state the return shape or timezone handling, a minor gap for a date-arithmetic tool.

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

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

Schema coverage is 100%, so the four parameters are already documented, and the description reinforces the semantics of negatives and weekend skipping. However, it advertises years, weeks, hours and minutes, which do not exist in the schema — an agent could attempt invalid arguments, and that mismatch offsets the added meaning.

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

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

The description states a precise verb+resource (add/subtract offsets to a date) and enumerates the supported units plus the business-day mode, which is immediately distinguishable from the sibling date_diff. An agent can tell what this does 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 compute due dates and expiries" gives clear intended context, and the negative-number note tells the agent how to handle subtraction in the same call. It stops short of naming a when-not case or pointing at alternatives like date_diff, so it 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 behavior the annotations cannot convey: a $0.001 USDC-on-Base charge per successful call via x402, which explains the non-read-only character of an otherwise pure computation. It also describes the return shape (totals plus a Y-M-D breakdown plus weekday count), compensating for the absent output schema.

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

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

Three tight sentences, front-loaded with the output enumeration before usage and pricing. Little waste, though the pricing sentence could arguably be folded more compactly.

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, no-output-schema tool the description covers outputs and payment mechanics well. It could still note date-format edge cases or the inclusive/exclusive counting convention, but nothing critical 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% with only two clearly described parameters (from, to), so the schema already carries the semantics. The description adds no format or edge-case detail (e.g., timezone handling, inclusive/exclusive endpoints) beyond what the schema states.

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

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

States a specific verb+resource (computes the time between two dates/timestamps) and enumerates the exact outputs produced, which an agent can distinguish from siblings like date_add, date_info, unix, and time. The scope is 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 for deadlines, ages and durations" gives implied usage context, but there is no explicit when-not guidance and no named alternative (e.g., date_add for shifting dates). The agent must infer the boundary from the sibling list.

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

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

Annotations exist, but the description adds information they cannot carry: a concrete per-call price ($0.001 USDC on Base) and the x402 payment mechanism, which also explains why readOnlyHint=false for what is otherwise a pure computation. It does not address idempotency or the deterministic nature of the result, 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?

Front-loaded with the return facets, then usage, then cost in three tight sentences with no obvious filler. The cost sentence earns its place by disclosing a paid call. Slightly dense but efficient.

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

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

There is no output schema, and the description compensates by enumerating the returned fields, which is exactly the missing information an agent needs. A one-parameter computation tool with this field list plus payment disclosure is close to 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% — the single parameter already documents "Date or ISO timestamp (default today)" — so the baseline is 3. The description adds "for any date" but no format, range, or timezone detail 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?

The description enumerates exactly what is computed (weekday, ISO week, day of year, quarter, days in month, leap year, Unix timestamp, weekend flag) for a given date, which is more specific than a bare verb+resource. It implicitly separates itself from the arithmetic siblings date_add/date_diff, though it never names them, so it falls short of full sibling differentiation.

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

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

"Use for calendar and reporting logic" implies a context but gives no when-not-to-use guidance and never points to the obvious alternatives (date_add, date_diff, unix, time, cron_next). The usage rule is inferable rather than stated.

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

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

Annotations only declare the read/write/idempotency profile; the description goes well beyond them by disclosing the cryptographic random source, capacity limits (100 dice of up to 1000 sides), the exact shape of the response, and — critically — that each successful call costs $0.001 USDC on Base via x402, which an agent must know before invoking.

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

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

Four dense sentences, each carrying distinct load: notation and limits, output shape, use case, and price. The action is front-loaded and nothing is repeated from the schema or annotations.

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

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

With no output schema, the description correctly compensates by describing the return payload (every roll, modifier, total), and it covers cost and limits. It omits edge behavior such as what happens with malformed notation, which is the only meaningful gap for this simple tool.

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

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

Schema coverage is 100% and the single optional parameter is already documented with a default, so baseline is 3. The description adds genuine meaning by bracketing valid inputs (up to 100 dice of up to 1000 sides) and reinforcing the notation format with examples.

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 in standard notation') with concrete examples (2d6+3, 1d20) and hard limits, so the agent knows exactly what the tool produces. It does not differentiate itself from adjacent randomness siblings such as random_number or random_pick, which is the only thing keeping it from 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 tabletop games and simulations' gives explicit use-case context rather than leaving usage implied. It stops short of naming when NOT to use it or pointing to an alternative generator for non-dice randomness, so it lacks the exclusions a 5 would require.

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

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

Annotations only declare generic hints, so the description carries real weight here and delivers: it discloses the exact price ($0.001 USDC on Base), the payment rail (x402), and that billing is per *successful* call — which also explains the otherwise puzzling idempotentHint=false. It omits payment/auth mechanics (how the x402 header is supplied) and what happens on a failed paid call.

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

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

Three short sentences, front-loaded with what the tool does, then usage, then cost. No filler and nothing buried.

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 correctly compensates by naming the return contents (message, length, server time). For a one-parameter tool with annotation coverage plus explicit pricing, 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?

Single parameter with 100% schema description coverage ('Message, up to 2,000 characters'), so the schema already documents length and type. The description only restates that the message is echoed back, adding no syntax or format detail — 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?

States a concrete verb and resource ('Returns the message you send') and even specifies the payload shape (message, length, server time). It is clearly distinguishable from the ai_* and crypto-query siblings, none of which echo input back.

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

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

Explicitly names the intended use cases — testing an x402 client, a payment flow, or agent tool wiring end to end — which is more routing guidance than most siblings give. It stops short of stating when *not* to use it or naming a cheaper alternative for plain connectivity checks.

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 behavior beyond the annotations: explicit return formats (hex and base64) and, importantly, a per-call cost of $0.001 USDC on Base paid via x402, which is critical for an agent deciding whether to call. It does not explain error behavior or why readOnlyHint/idempotentHint are false for a deterministic digest 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?

Two sentences, zero filler, with the core purpose and algorithm/encoding details front-loaded ahead of the usage and pricing notes.

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 encodings, and it discloses the payment requirement. Minor omissions remain around failure modes and cost/limit behavior, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented; the description only restates the algorithm set and default. Baseline 3 applies since the schema carries the parameter semantics.

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

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

States a specific verb (hash), the input type (UTF-8 text), the supported algorithms with the default, and the output encodings. An agent can tell this apart from sibling hmac (keyed) and base64_encode (encoding) 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 intended uses (checksums, cache keys, deduplication), which is clear context for selection. It does not name alternatives such as hmac for keyed hashing or state when not to use it, so it stops short of full when/when-not guidance.

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

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

Adds genuinely useful context beyond the annotations: the key is used only for the call and not stored, and there is a per-call cost of $0.001 in USDC on Base via x402. This payment/auth requirement is exactly the kind of operational detail the annotations (readOnlyHint=false, openWorldHint=true) do not convey.

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

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

Four short sentences, front-loaded with the operation and its options, followed by use case, privacy note, and cost. Every sentence carries distinct information with no 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 compensates by noting the results are produced in hex and base64. Combined with the privacy and payment details, an agent has enough to call it correctly; a precise return shape is the only minor 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%, so the schema already documents all three parameters including the algorithm options. The description restates the algorithm list and mentions output encodings, adding little beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (compute) and resource (HMAC of a message with a key), enumerates supported algorithms, and names the output encodings (hex and base64). An agent can distinguish this from the sibling hash tool 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?

Provides one concrete use case ('Use to check webhook signatures'), which implies context. However it never says when NOT to use it or routes to alternatives such as the sibling 'hash' tool, so selection between closely related tools is left to inference.

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

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

Annotations mark this non-readOnly and non-idempotent, which is otherwise puzzling for a pure text transform; the description resolves that by disclosing the $0.001 USDC charge paid via x402, and 'per successful call' tells the agent failed calls are free. It still omits what authorization/wallet setup the payment requires and any rate 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?

Three tight sentences: transformation semantics first, use case second, cost last. Every clause carries information an agent needs and nothing is repeated from the schema.

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-input, no-output-schema utility, the description covers behavior, purpose, and cost. The only real gap is failure/edge behavior (invalid or massive HTML, truncation), which an agent might want before invoking on arbitrary fetched pages.

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 carries parameter documentation. The description adds nothing about the input (encoding, size limits, whether a full document or fragment is expected), which is the expected baseline for a single-param tool.

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

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

Specific verb+resource with concrete behavioral detail ('strip HTML to readable plain text'), plus a breakdown of what the transformation does (scripts/styles removed, block elements become line breaks, list items bulleted, entities decoded). An agent can distinguish it from siblings like markdown_to_html, pdf_text, text_extract, and extract_rendered 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 feed web content or emails to an LLM' gives a clear triggering context and intent. It stops short of naming an alternative or stating when-not to use it (e.g., prefer extract_rendered for JS-rendered pages), so it does not reach the explicit routing bar of a 5.

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

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

Annotations cover the safety profile (destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds important behavior beyond that: the tool costs $0.001 USDC on Base per successful call via x402. It also notes that the tool returns retry guidance, which is useful operational context.

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

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

The description is three short, front-loaded sentences. It establishes the return value, usage context, and cost/payment mechanism with no wasted wording.

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 lookup with no output schema, the description is complete: it explains what is returned, when to use it, and the payment model. Nothing an agent needs in order to call the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter. The description still adds value by specifying the valid range (1xx-5xx) and giving examples (402 Payment Required, 429 Too Many Requests) that help the agent populate the parameter correctly.

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 exactly what the tool returns: the name, plain-language meaning, and retry guidance for an HTTP status code. It also scopes the input domain to 1xx-5xx and cites notable codes, so an agent can immediately distinguish it from unrelated lookup 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 gives a clear context for use: handling API errors. It does not name alternatives or state when not to use it, but no sibling tool overlaps with this function, so the guidance is sufficient for 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?

The description adds real behavioral context beyond the annotations: it is a paid call costing $0.001 USDC on Base via x402, and it only charges on successful calls. That is the kind of billing/auth detail annotations do not capture. It does not, however, address the unusual readOnlyHint=false / idempotentHint=false annotations on what is functionally a pure computation, leaving a small inconsistency unclarified.

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, each carrying distinct information (outputs, use case, cost), with the core purpose front-loaded. It is appropriately sized, though the output enumeration is a long clause that could be tightened 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?

With no output schema, the description compensates by enumerating the return fields, and it discloses the payment model. An agent has enough to call this correctly and predict the response shape. The only gap is the unexplained mutation/idempotency annotations for what is otherwise a read-style computation.

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

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

Schema description coverage is 100%, so both parameters (cidr, ip) are already documented in the schema, which sets the baseline at 3. The description's phrase "whether a given IP falls inside" restates the schema's own "test for membership" rather than adding syntax, format, or validation detail. No meaningful value is added over the structured 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?

The description names a specific resource (IPv4 network in CIDR notation) and enumerates exactly what it returns: network/broadcast address, first/last usable host, netmask, address count, and membership test. This is far more concrete than a tautology. It does not explicitly distinguish itself from the sibling ip_info, which is the one nearby tool an agent might confuse it with, 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 firewall rules and allowlists" gives a concrete, actionable context for selecting this tool. There is no statement of when NOT to use it and no explicit routing to alternatives such as ip_info, so it falls short of the full when/when-not/alternatives bar.

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 critical behavioral context beyond the annotations, notably that classification requires no lookup and costs $0.001 in USDC on Base per successful call via x402. This explains the non-read-only payment side effect and sets cost expectations the annotations alone do not convey.

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

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

The description is front-loaded with the core action and outputs, then adds a use case, then a payment note. All three sentences carry unique, useful 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?

With no output schema, the description still lists the return fields an agent can expect: version, address class, and integer plus reverse-DNS forms. It also discloses the payment model, which is essential for correct invocation.

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

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

Schema coverage is 100%, and the schema only documents the parameter as 'The IP address.' The description improves on that by clarifying that both IPv4 and IPv6 inputs are accepted and that no lookup is performed.

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 ('Classify') and resource ('IPv4 or IPv6 address') and enumerates the exact classification outputs, including version, private/loopback/link-local/CGNAT/public, and integer/reverse-DNS forms. The scope 'without any lookup' also distinguishes it from lookup-based network tools such as ping or domain lookups.

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

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

Gives a clear usage context: 'Use to triage IPs in logs or allowlists.' It does not name an alternative sibling such as ip_cidr or state when not to use this tool, but the intended context is explicit and actionable.

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

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

Annotations only cover safety/openness hints; the description adds genuinely new behavioral facts an agent needs: the call costs $0.001 USDC on Base, is paid via x402, and is charged per successful call (implying failures aren't billed). It also states the return is the formatted text. It does not say what happens on malformed JSON input, which would be the remaining useful disclosure.

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

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

Four short sentences, each earning its place: purpose, return value, use case, and cost. The core purpose is front-loaded and nothing is repeated.

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 says it returns the formatted text, and it discloses the payment model for this paid endpoint. The only material gap is error behavior on invalid JSON, which matters given that json_repair and json_validate exist as alternatives.

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 text, indent and sortKeys. The description restates the indent options and sorted-keys flag but adds no syntax detail beyond the schema (e.g. how sortKeys is passed, whether 'tab' is the literal value). Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb+resource (format JSON) plus the concrete operations it performs: indentation with 2/4 spaces or tabs and optional key sorting. This clearly separates it from siblings like json_minify, json_repair and json_validate without needing to open their schemas.

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

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

Gives explicit use context: 'Use to make machine JSON readable or to normalise it for diffs.' That is a clear when-to-use statement, but it offers no exclusions and never routes the agent among the closely related json_minify / json_repair / json_validate 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 cover the safety profile (destructiveHint=false), and the description adds non-derivable operational context: a $0.001 USDC cost on Base via x402, which is critical for an agent to know before calling. It doesn't clarify why readOnlyHint=false for a pure transformation, but that's an annotation issue rather than a description gap.

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

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

Three short sentences, each earning its place: action, use case, then pricing. Front-loaded with the core operation and no redundancy.

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

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

For a simple single-parameter transformation with no output schema, the description covers what it does, when to use it, and its cost/payment mechanism. It also notes the before/after size report, so the agent understands the return content.

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

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

Only one parameter ('text'), and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax or format guidance beyond the schema, which matches the baseline 3 for a single fully-documented parameter.

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

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

States a specific verb and resource ('Remove all unnecessary whitespace from JSON') plus a secondary effect ('report the size before and after'). The minify action is inherently distinguishable from siblings like json_format, json_repair, and json_validate.

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

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

'Use to shrink payloads or prompts' gives clear use-case context, telling the agent when this tool is appropriate. It stops short of naming alternatives or exclusion conditions, so it stays below the explicit when/when-not bar.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, but they say nothing about cost, payment rail, or return shape. The description supplies all three — $0.001 USDC on Base per successful call via x402, and that it returns both the repaired JSON and a parse-success flag. For a paid network-dependent tool this is exactly the missing context. No contradiction with 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?

Front-loaded with the transformation list, then the when-to-use trigger, then cost — a sensible order. The defect enumeration is long but each item is a distinct capability that earns its place; still, it is a dense single sentence that could be tightened 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, yet the description states the return payload (repaired JSON plus parse boolean), and it covers the two things an agent could not infer elsewhere: the LLM-output use case and the x402 payment requirement. 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?

A single parameter with 100% schema description coverage ('The broken JSON text'), so the schema already carries the semantics; baseline for a one-param tool is 4. The description adds context about what kinds of breakage the input may contain, but no syntax or format detail beyond the schema.

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

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

States a specific verb+resource (repair malformed JSON) and enumerates the exact defect classes it handles — code fences, prose, comments, trailing commas, single quotes, bare keys, True/False/None, unclosed brackets. An agent can distinguish this from json_format, json_minify, and json_validate purely from the description.

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,' which implicitly routes validation-only needs to json_validate and formatting needs to json_format. It never names those siblings outright, so the exclusion is inferable rather than stated.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false, so the mutation/safety profile is partially covered. The description adds materially useful context the annotations don't: a per-call cost of $0.001 in USDC on Base paid via x402, which explains the non-idempotent hint and matters for an agent deciding whether to call. It does not state failure behavior for malformed JSON, so 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?

Four tight sentences: transformation behavior front-loaded, then output semantics, then use case, then cost. Nothing is redundant and nothing could be dropped without losing signal.

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 pure transformation with no output schema, the description covers input expectations, output shape, use case, and payment. Only error handling for invalid JSON input and the exact return type (CSV string vs file) are unaddressed, which are minor gaps.

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 'text' is fully described as 'A JSON array of objects'. The description restates that same contract rather than adding format details, so the baseline 3 for schema-covered params 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 a JSON array of objects to CSV') plus the exact output semantics: header row built from all keys, nested values serialized as JSON. The directionality is unambiguous and implicitly distinguishes it from the inverse sibling csv_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?

'Use to export API results to a spreadsheet' gives a concrete use context. It does not name the inverse tool (csv_to_json) or state exclusions, but the mapping is clear enough to route an agent 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?

With annotations present, the bar is lower, and the description still adds real context: it discloses the x402 payment flow, the exact price ($0.001 USDC on Base), and that billing applies only per successful call, plus the return shape including line/column on failure. It does not explain the notable readOnlyHint=false / idempotentHint=false flags, but nothing here contradicts them.

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

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

Three tight sentences: purpose first, then output shape, then usage trigger and cost. Every sentence carries information the agent needs and nothing is 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 one-parameter validation tool with no output schema, the description covers purpose, return values (valid flag, type, size, error location), usage timing, and the cost/payment model. An agent has everything needed to decide and invoke 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 a single parameter and schema coverage is 100%, with the schema itself documenting the 'text' field and its 20,000-character limit. The description adds no syntax or format detail beyond that, 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 states a specific verb and resource ('Check whether text is valid JSON') and even enumerates the result fields, so the agent immediately knows this is a validation/parse-check tool. It does not name the closely related siblings (json_format, json_minify, json_repair) to draw the boundary explicitly, which keeps it out of 5 territory.

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 before parsing an LLM's or an API's output' gives a concrete, actionable trigger for calling the tool. There is no explicit when-not guidance or pointer to json_repair for malformed input, so it falls short of full routing guidance.

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

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

Adds substantial context beyond the annotations: signature is NOT verified, token is not stored, dates are reported and expiry is evaluated, and there is a per-call cost ($0.001 USDC on Base via x402). The annotations (readOnly=false, idempotent=false) sit in mild tension with the emphasis on a non-persisting read, but the paid-call side effect plausibly justifies the non-read-only hint, so this is context-adding rather than contradictory.

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 purpose and keeps every sentence relevant (behavior, safety warning, use case, cost). The pricing sentence packs multiple details (amount, chain, mechanism) but is genuinely useful, so only minor trimming is possible.

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 describing what is returned (header, payload, iat/nbf/exp as dates, expired flag). For a single-parameter decode tool this is nearly complete; error behavior on malformed tokens is the only unaddressed area.

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

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

One parameter with 100% schema description coverage; the schema already documents 'token'. The description adds no format/syntax detail (e.g., whether the JWT prefix is expected), so the baseline of 3 applies.

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

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

States a specific verb (decode) plus resource (JSON Web Token), and delimits scope: it returns header/payload without verifying the signature. This clearly separates it from siblings like base64_decode or token-report; an agent knows exactly what it does without opening the schema.

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

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

Gives clear context ('Use to debug auth flows') and an explicit caution ('Do not use the result to trust a token'), which functions as a when-not-to-use case. It does not name sibling alternatives, so it falls just 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?

Adds a lot beyond the annotations: randomness of the answer (matching idempotentHint=false), novelty/toy nature, and the crucial cost/auth detail of $0.001 USDC on Base per successful call via x402 — which the annotations do not convey at all. It stops short of saying whether payment is required upfront or settled per call, or what happens on failure.

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

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

Three short sentences, zero waste, with the core purpose front-loaded and the cost caveat last. Nothing is padded or repeated.

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 trivial optional-parameter tool the description covers purpose, randomness, and pricing, which is most of what an agent needs. It does not address whether payment failures or unpaid calls behave differently, which is the one meaningful gap given the x402 cost model.

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 question parameter is described there as optional and not stored. The description's framing of a 'yes-or-no question' loosely implies the parameter but adds no format or length 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+resource: ask a yes-or-no question, return one of 20 random Magic 8-Ball answers. Clear enough that an agent knows exactly what comes back, but it never distinguishes itself from nearby siblings like yes_no, dice, or random_pick, so selection between them is left to inference.

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?

"For fun only. Use for games and chat bots" gives implied usage context, but there is no when-not guidance and no reference to the clearly overlapping yes_no sibling. An agent has a rough sense of the domain but no routing 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?

Discloses two traits invisible in annotations: raw HTML in the input is escaped so output is safe to embed (a security-relevant behavior), and each successful call costs $0.001 USDC on Base via x402. The payment note also explains why annotations mark the call non-read-only despite being a pure conversion.

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

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

Three tight sentences: capability first, safety second, usage-and-cost last. No filler, and the most decision-relevant information is front-loaded.

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 implies the return is embeddable HTML but never states the response shape or field name. Everything else an agent needs to call it correctly (input format, safety, cost) is present.

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

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

Schema coverage is 100% but the parameter description is only 'The Markdown', so the description carries the real semantic load by specifying which Markdown features are understood. It does not discuss size limits or how unsupported syntax 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?

States a specific verb and resource ('Convert Markdown ... to HTML') and enumerates the supported constructs (headings, code, lists, tables-adjacent features), so the agent knows exactly what transformation is performed. It is clearly distinguishable from siblings like html_to_text, which does the inverse.

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 usage context: 'Use to publish agent-written Markdown on a web page.' It does not name alternatives (e.g., html_to_text for the opposite direction) or state when-not to use it, but the intended scenario is unambiguous.

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

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

The description goes beyond the annotations by disclosing payment mechanics ($0.001 in USDC on Base via x402, per successful call) and by stating that the result includes an inline-display judgement — neither is captured in the annotation block. The annotations (readOnlyHint=false, idempotentHint=false) sit oddly against a deterministic name→type mapping, but the description makes no explicit claim that they contradict; the tension is noted rather than scored as a contradiction. Unknown-extension/error behavior is not described.

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

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

Three short clauses ordered well: purpose plus example first, usage trigger second, cost last. Nothing is padding, though 'MIME (content) type' restates the concept already implied by the example and the usage sentence is fairly thin.

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 lookup with no output schema, the description carries the necessary load: it says what comes back (type plus inline-display flag) and what the call costs. The only omission is failure behavior for unrecognized input, which is minor at this complexity.

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

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

Schema description coverage is 100% (the 'file' property is documented as 'File name or extension'), so the baseline is 3. The report.pdf → application/pdf example modestly reinforces that full filenames and bare extensions are both accepted, but adds little 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?

The description resolves the cryptic tool name fully: it maps a file name or extension to a MIME type and gives a concrete worked example (report.pdf → application/pdf), plus the secondary 'inline display' output. It is unambiguous and easily separable from numeric/encoding siblings like base64_encode or hash. It lacks a distinct action verb, but the resource and result are stated precisely.

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 states a usage context: 'Use when uploading or serving files.' That is a clear, actionable trigger, not merely implied. It stops short of naming when NOT to use it or pointing at an alternative sibling, so it falls just below 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 the safety profile, but the description adds genuinely useful non-annotation context: the $0.001 USDC cost on Base, x402 payment, and that it is charged only 'per successful call.' That pricing/auth detail is exactly the kind of behavior an agent must know before calling an openWorld paid endpoint.

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

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

Three short sentences, purpose front-loaded ahead of the cost disclosure, with no redundancy. 'Use for dates, outlines and puzzles' is the weakest sentence and edges toward filler, keeping it out of the top band.

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

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

For a two-parameter pure conversion tool with no output schema, the description covers direction, input range, mutual exclusivity, and payment. The only real gap is that it never says what comes back (Roman string vs. integer) or how out-of-range input is 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%, so the baseline is 3; the schema already documents both parameters and the 1-3999 range. The description's 'Give either number or roman' adds a mutual-exclusivity hint that the schema does not encode (both params are optional with no oneOf), so it is slightly above pure repetition but not rich.

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 with explicit bidirectional scope: 'Convert a number (1-3999) to Roman numerals, or Roman numerals back to a number.' The 1-3999 bound makes it distinguishable from the nearby number_words sibling, but that sibling is never named or contrasted.

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' implies usage context but gives no when-not guidance and no reference to alternatives such as number_words. It also tells the agent to supply one of two inputs ('Give either number or roman'), which is invocation help rather than selection help.

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 genuinely useful behavior: accepted range (up to trillions, negatives), that decimals trigger a cheque-form output with 'and' cents, and a per-call cost of $0.001 USDC via x402. The payment/cost detail is significant and not derivable from annotations, though rate limits and error behavior are unstated.

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

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

Three tight sentences, front-loaded with the core purpose and followed by scope, usage cue, and the critical cost note. Every sentence carries information an agent needs and 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?

For a single-parameter, no-output-schema utility, the description covers purpose, input range, decimal handling, output shape, and cost. 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 baseline is 3, but the description adds real constraints the schema omits: the range ceiling (trillions) and that negatives are permitted. The single 'number' parameter is thus better understood than from the schema alone.

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

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

The description gives a specific verb+resource: converting a whole number into English words, with concrete use cases (cheques, invoices). It is easy to distinguish from the nearest sibling number_roman, but it never names or contrasts with that sibling 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 when amounts must be written out in full" states the triggering condition clearly, and the cheque/invoice examples reinforce it. There is no explicit when-not or named alternative, so it stops short of a 5.

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

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

Annotations declare it is not read-only, not idempotent, and open-world, but they do not convey why. The description adds the crucial context: the call moves real money ($0.001 USDC on Base via x402) and is charged per successful call, which explains the non-idempotent, non-read-only flags and warns the agent of financial cost.

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

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

Three short sentences, front-loaded with what the tool does, then when to use it, then the cost. Every sentence earns its place and nothing is repeated from structured fields.

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

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

For a zero-parameter tool with no output schema, the description covers what is returned (pong + server time), why it exists (payment-path verification), and what it costs. Nothing an agent needs in order to decide and 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies there is nothing to configure, and schema coverage is 100% with an empty properties object.

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 ('round-trip check', returns 'pong and the server time') plus the distinguishing trait that it is paid. An agent can tell this apart from sibling utilities like echo or time without opening any schema.

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

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

Explicitly says when to use it: 'to test that an x402 wallet, client or MCP setup can pay and receive a result.' That is a clear, actionable trigger, though it does not name an alternative (e.g., echo for a free round-trip) or state 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 cover only safety hints (readOnly=false, idempotent=false, openWorld=true), which is expected for a generator. The description adds the critical non-annotation detail: each successful call costs $0.001 USDC on Base via x402, and payment is per *successful* call — essential information an agent cannot infer from any structured field.

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

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

Two sentences, front-loaded with the output formats and the tone restriction before the usage cases and the pricing caveat. 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, but the description names the returned formats (hex, RGB, HSL) and discloses cost/billing, which is the main thing an agent needs beyond the schema. It leaves unaddressed the shape of multi-colour responses and what happens when a paid call fails, keeping it just below a 5.

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

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

Schema coverage is 100% and already documents both `tone` (any/pastel/dark) and `count`. The description only restates these ("one or more", "pastel or dark tones") without adding syntax, default behaviour, or edge cases, so the baseline of 3 applies.

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

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

States a specific verb+resource (generate random colours) and the output formats produced (hex, RGB, HSL), plus the optional tone restriction. This distinguishes it from colour-parsing/manipulation siblings like `color` and `color_contrast`, though those siblings are never 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?

"Use for placeholders, avatars and design ideas" gives explicit situational context. It stops short of exclusions or pointing at alternatives (e.g. use `color` when you need a specific colour rather than a random one), so it does not reach the 5 tier.

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 supply the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description clears the lower bar. It adds genuinely useful context beyond them: the cryptographic randomness quality, inclusive range semantics, and a concrete per-call cost of $0.001 USDC on Base via x402, which explains why readOnlyHint is false for a compute-only 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?

Three tight sentences: purpose first, then usage, then cost. Every sentence earns its place and nothing is padded or repeated.

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 what comes back (one or more whole numbers) and discloses the payment model. It stops short of failure behavior or the unique/count interaction, but for a simple 4-parameter generator with full annotation and schema coverage 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%, so the schema already documents min, max, count and unique, putting the baseline at 3. The description adds only the range inclusivity and the "all different" restatement of unique, which largely duplicates the schema's "true for no repeats"; it does not address edge cases such as unique=true with count exceeding the range size.

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: generating one or more random whole numbers within an inclusive range, drawn from a cryptographic source. It implies a distinction from list-based siblings like random_pick or random_shuffle by scoping to a numeric range, but never names or contrasts those siblings explicitly.

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

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

"Use for draws, sampling and games" gives implied usage context, which is more than nothing. However, it offers no when-not conditions and no routing guidance among the many random_* and game-related siblings (random_pick, random_shuffle, random_teams, dice, magic-8-ball).

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 context beyond the annotations: cryptographic random source, nothing stored or logged, and a $0.001 USDC-on-Base x402 payment per successful call. The payment requirement and security guarantee are valuable disclosures not derivable from readOnlyHint/openWorldHint. It does not explain failure/refund behavior on payment, keeping it 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?

Front-loads the purpose, then usage, then cost in four compact sentences with no filler. Slightly dense with a trailing payment clause, but every sentence earns its place.

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

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

With no output schema, the return format (list of password strings) is left implicit, but purpose, usage, security posture, and pricing are all covered, which is sufficient for a zero-required-parameter generator. The only gap is the undocumented return shape.

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 count, length, and symbols, establishing the baseline of 3. The description's 'choose length and character sets' loosely frames the parameter space but omits count and overstates char-set control, since the schema only exposes a symbols toggle.

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?

Specifies a concrete verb+resource ('Generate strong random passwords or passphrase-style strings') and distinguishes itself from neighboring generators such as random_number, random_pick, and uuid. An agent can identify the tool's role 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 when creating accounts or secrets' gives a clear usage context, and 'Generated on demand' implies the interaction model. It does not explicitly name alternatives or exclusions (e.g., uuid for identifiers, random_pick for selection), 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=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false. The description adds genuinely new behavioral context: a per-call cost of $0.001 USDC on Base via x402, which the agent must know before invoking and which no annotation conveys.

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

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

Two sentences, zero filler, and the core operation is front-loaded before the payment note. Every clause carries information.

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

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

For a simple two-parameter utility with no output schema, the description covers input format, selection constraint, intended use, and payment. It omits edge behavior such as what happens when count exceeds the list length, but nothing critical 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 already documented in the schema. The description reinforces the input format (comma- or line-separated) and the no-repeat guarantee, which is marginally useful, but adds no syntax or bound details 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 ('pick') plus the resource ('items'), the selection mode ('at random'), and a key constraint ('without repeats'). It is easily distinguished from siblings like random_shuffle, random_teams, and 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?

Gives concrete use cases (raffles, choosing who goes first, breaking ties fairly) that make the intended context clear. It stops short of naming alternatives such as random_teams for team division or random_shuffle for ordering.

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

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

Annotations only declare safety flags; the description goes well beyond them by disclosing the algorithm (Fisher-Yates with a cryptographic random source, implying unbiased, non-reproducible output), the payment model ($0.001 USDC on Base), the payment protocol (x402), and that charging happens only per successful call. This is exactly the kind of cost, auth, and determinism context annotations cannot carry.

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

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

Three dense sentences, each earning its place: what it does, when to use it, what it costs. The purpose is front-loaded and no sentence is filler.

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

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

Covers input format, use cases, algorithm, and the unusual payment requirement, which is the highest-risk unknown for an agent. The one gap is the return shape (presumably the shuffled list as a string) and how the x402 payment is actually presented, but with no output schema and simple input, this is close to 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?

Single parameter with 100% schema description coverage, so the schema already documents 'items' as comma-separated. The description adds newline-separated support not present in the schema, which is genuinely useful, but it gives no guidance on delimiters in item content or empty/whitespace handling. Baseline 3 is appropriate given the schema does most of the work.

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 (shuffle) and resource (comma- or line-separated list) plus the exact algorithm and randomness source, so an agent knows precisely what it does. It does not name or contrast any sibling (e.g. random_pick or random_teams), leaving the agent to infer the distinction from the verb alone.

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

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

'Use for draw orders, seating and playlists' gives concrete when-to-use contexts rather than leaving usage implied. There is no guidance on when NOT to use it (e.g. when you want a single pick or a deterministic ordering), so it falls short of explicit alternatives.

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 (destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely new behavioral context beyond annotations: a $0.001 USDC charge on Base via x402, billed only per successful call. It does not disclose failure/payment-failure behavior or the shape of the returned team grouping.

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

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

Three short sentences, front-loaded with the core action, then usage context, then cost. Every sentence carries information, though "Use for games, workshops and classrooms" is the weakest and borders on filler.

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

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

With no output schema, the description carries the burden of explaining what comes back — the team structure, ordering, and how the remainder is distributed — and it says none of this. For a paid, open-world call, payment failure semantics are also unaddressed.

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 both parameters described in-schema, so baseline is 3. The description adds only the behavioral note that teams are evenly sized; it does not address edge cases such as requesting more teams than there are names, nor explains why the schema permits an enormous negative minimum for the team count.

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

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

States a specific verb and resource: split a list of names into N random, evenly sized teams. An agent can immediately tell this apart from random_pick (selects one item) and random_shuffle (reorders a list) on resource grounds, though it never names those siblings explicitly.

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

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

"Use for games, workshops and classrooms" gives implied usage context but no explicit when-not-to-use condition and no routing to random_shuffle or random_pick, which are the closest alternatives. Adequate but leaves the agent to infer the boundary.

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

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

With annotations present, the description still adds meaningful operational context: the $0.001 USDC cost on Base per successful call and the x402 payment mechanism, which is not derivable from the schema or annotations. It doesn't explain the unusual non-read-only/idempotent=false hints, but the payment disclosure is genuinely useful.

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 operation, then the use case, then the billing detail — a sensible ordering with minimal waste. Slightly dense in the first sentence but every clause carries information.

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

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

There is no output schema, so the description carries the burden of describing returns, and it does name the comparison result and the three next-version values. Payment mechanics are also covered; only exact output shape/format remains 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% ('First version', 'Second version'), so the schema already defines both parameters. The description's 'compare two versions ... next versions of the first' does clarify that 'a' is the primary version, a small addition over the schema's neutral 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 ('Compare two semantic versions') plus the exact returns (which is newer, next major/minor/patch of the first) and even covers pre-release handling. No sibling tool overlaps with version comparison, so disambiguation is trivially strong.

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 decide whether an upgrade is a major change' gives a concrete use case, and the pre-release note implies when SemVer rules apply. It does not name alternatives or exclusions, but no sibling is a plausible substitute, so the guidance is adequate.

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

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

The description discloses a material behavioral fact the annotations do not: the per-call cost ($0.001 USDC on Base via x402) and that it applies per successful call. It also spells out the transformation semantics. It does not reconcile the odd idempotentHint=false for an apparently pure function, but overall it adds real context beyond structured fields.

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

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

Three tight sentences, front-loaded with the core behavior, followed by use cases and the payment note. Every sentence carries information, though the payment clause could arguably be tighter.

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

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

For a stateless text transform with no output schema, the description covers input behavior, output form, default separator, and cost. Nothing needed to invoke it correctly is missing; only edge-case handling (length limits, empty input) is unaddressed.

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 in the schema. The description reinforces the separator default ('- by default') and explains what the separator replaces, but this largely restates rather than adds syntax 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?

States a specific verb and resource ('turn any text into a URL-friendly slug') and details the exact transformation (accent removal, lowercasing, separator substitution) with concrete examples. An agent can immediately distinguish it from neighbors like base64_encode, hash, or url_encode.

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 names intended use cases ('file names, URLs and IDs'), which gives implied context for when to reach for it, but there is no explicit when-not guidance or routing to alternatives. Adequate but not directive.

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

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

Annotations only cover safety flags (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false); the description adds genuinely new operational context by stating the tool costs $0.001 in USDC on Base via x402 and is charged 'per successful call'. That payment/reversibility detail is exactly the kind of thing annotations cannot express, though it says nothing about failure modes or latency.

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

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

Three tight sentences: what it does first, when to use it second, cost last. No filler, no repetition of the schema, and the most decision-relevant facts are front-loaded.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so at a useful level ('each line marked as unchanged, removed or added, with counts'). Cost and usage context are covered; the only minor gap is the concrete output format (structured JSON vs. unified diff) for a 2-param tool.

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

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

Schema coverage is 100%, so 'The original text' (a) and 'The new text' (b) are already documented; the description only implies the two-input shape without mapping which parameter is the original versus the new version. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a concrete verb+resource ('Line-by-line difference between two texts') and even previews the output shape (unchanged/removed/added lines with counts), which no sibling (text_stats, text_extract, summarize) shares. It does not explicitly contrast itself with any sibling tool, but the operation is distinctive enough that confusion is unlikely.

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

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

Gives clear context for when to reach for it: 'Use to see what changed between two versions of a document, config or prompt.' It stops short of naming alternatives or exclusions (e.g. when a full text comparison isn't appropriate), so it's clear context without 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 beyond the annotations by disclosing a per-successful-call price ($0.001 USDC on Base paid via x402), which is critical operational context an agent cannot infer from readOnlyHint/openWorldHint/destructiveHint. It also states outputs are de-duplicated per list. It does not cover failure behavior (e.g., no matches found) or rate limits, and notably the mutation hint is false despite this being a read-style extraction.

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

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

Three short sentences, each carrying distinct load: scope of extraction, use case, and cost. Purpose is front-loaded and there is no filler.

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

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

For a one-parameter tool with no output schema, the description effectively enumerates the return categories (one list per entity type, de-duplicated) and discloses the payment requirement. Minor gaps remain: whether lists are always present when empty, and any input-size constraints.

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 and schema description coverage is 100%, so the schema already documents it fully. The description adds only the vague phrase 'in a text', providing no extra semantics such as size limits or encoding expectations — 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 ('Find') and an enumerated resource set: emails, URLs, phone-number-like strings, hashtags, @mentions and numbers, plus the de-duplication guarantee. This distinguishes it from generic siblings like 'extract', 'email' and 'html_to-text' 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 a concrete usage context — 'pull contacts and links out of scraped pages or messages' — which tells the agent when it is the right call. It stops short of naming alternatives (e.g., 'extract' or 'html_to-text') or stating when not to use it, so it lacks 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?

Annotations only declare safety flags, so the description's cost disclosure is real added value: $0.001 USDC on Base, x402, and critically 'per successful call', which tells the agent failed calls are not billed. It does not explain error behavior, latency, or input size limits, but it goes meaningfully beyond the structured fields.

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

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

Three sentences, front-loaded with capabilities, then use case, then the billing sentence that a paid tool needs. No filler. Slightly long enumeration of metrics, but each item maps to a real returned statistic rather than 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?

No output schema exists, and the description compensates by enumerating the returned statistics, so an agent knows what it gets back. The payment rail and language restriction are covered. Missing only failure modes and limits, which is acceptable for a single-parameter read-style 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?

One parameter at 100% schema coverage, whose schema text is only 'The text', so the baseline would be 3. The description adds a genuine semantic constraint the schema lacks ('English text'), which changes how the agent should populate the parameter - i.e. do not pass arbitrary-language drafts.

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

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

Specific verb+resource with an explicit inventory of what is computed (character/word/sentence/paragraph counts, reading and speaking time, Flesch reading-ease and grade level) and a bounded domain ('English text'). No sibling among the large list does text metrics (text_diff, text_extract, html_to-text are all distinct), so differentiation is implicit but 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 check the length and readability of a draft' supplies one concrete use case, which is more than nothing. However, it names no alternatives and no when-not conditions (e.g. non-English input, or pairing with an ai_rewrite call after the draft fails a readability bar), leaving routing largely to inference.

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

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

Annotations only give the generic safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false). The description adds genuinely useful behavioral context beyond them: a metered cost of $0.001 USDC on Base via x402 per successful call, plus precision nuances like kB vs KiB and US cups/gallons. It does not say what happens on an unsupported unit (error vs. fuzzy match) or whether a failed call is still billed.

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

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

Front-loaded with the capability and unit families, then usage, then payment terms — a sensible priority order with no filler sentences. It is somewhat list-dense, but each element (unit families, examples, cost) carries distinct information.

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

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

With no output schema and full schema coverage on inputs, the description covers capability, input vocabulary, and cost. The remaining gap is the return contract — numeric vs. formatted string, rounding precision, and error behavior for unknown units — which an agent calling this blindly would benefit from knowing.

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 labels value/from/to, so the baseline would be 3. The description goes further by supplying real example unit tokens (km, mi, lb, kg, floz, ml, mph, kn, acre, gib, kwh, psi) that tell the agent what string format `from`/`to` accept — meaningful semantics the schema does not provide.

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 (unit conversion) and enumerates the exact quantity families covered, with concrete example units. No sibling tool in the list performs conversion, so the scope is unambiguous and immediately distinguishable.

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 exact conversions matter" gives a clear selection context, and the paid nature implies when not to use it carelessly. It stops short of naming alternatives or stating exclusions (e.g., currency conversion is a separate `fx` tool — that routing is not mentioned).

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 goes well beyond annotations by disclosing the unit auto-detection (seconds vs milliseconds) and, importantly, the paid-call model ($0.001 USDC on Base via x402), which explains why readOnlyHint=false for a pure conversion. It does not explain what happens on invalid input, but the cost/auth context is genuinely valuable.

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

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

Three tightly packed sentences: conversion behavior first, default behavior second, usage and cost last. No filler; every sentence carries load.

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

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

With no output schema, the description helpfully states the return forms (ISO date/time, Unix timestamp, or both for the now case) and covers payment. Edge cases such as invalid input handling and the exact ISO format emitted are the only omissions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the fact that units are detected automatically and that omitting the value yields the current time in both forms — meaning beyond the schema's terse 'default now'.

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

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

States a precise verb+resource pair: converting a Unix timestamp to ISO date/time and the reverse, plus the no-input default. It is distinguishable from most siblings, but the sibling 'time' is never addressed, so an agent cannot fully disambiguate between them from this text alone.

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

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

One clause, 'Use to read timestamps in logs and APIs,' gives a context but no when-not guidance and no routing to the near-identical 'time' sibling. Usage is implied rather than instructed.

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 are sparse and partly counterintuitive (readOnlyHint=false for a pure decode), so the description's disclosure that each successful call costs $0.001 in USDC on Base via x402 is genuinely valuable, agent-relevant context not present in structured fields. It does not address failure/no-charge behavior beyond the word 'successful', but the payment model is the key behavioral fact and it is disclosed.

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

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

Three short sentences, each carrying distinct information (what it does, when to use it, what it costs), with the core action front-loaded. 'Use to read encoded links and form data' is the softest sentence but still adds usage context rather than repeating 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 two-parameter pure transformation with no output schema, the description covers purpose, the non-obvious plus flag, usage context, and the payment requirement. Return value explanation is unnecessary since decoding obviously yields text; only edge-case behavior on invalid input is unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by framing 'plus=true' as form-encoding semantics, clarifying that '+' is only treated as a space under that flag and implying literal handling otherwise.

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: 'Decode percent-encoded text', which is unambiguous against siblings like url_encode and url_parse. It does not explicitly name an alternative, but the verb itself differentiates the inverse operation, so an agent can route correctly.

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 links and form data' states a clear usage context for the tool. It stops short of naming when-not to use it or pointing at url_parse for structured query-string parsing, so it is clear context without 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 cover the safety profile (destructiveHint=false, openWorldHint=true), and the description adds genuinely non-obvious context the annotations lack: the call costs $0.001 USDC on Base via x402 per successful call. It does not disclose output format or failure behavior, but the payment disclosure is the meaningful extra.

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

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

Three short sentences, purpose front-loaded, then usage, then cost. Every sentence earns its place, though the two encoding modes and the usage trigger could be tightened into a single clearer sentence.

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

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

For a single-parameter, pure transform with annotations and no output schema, the description supplies purpose, both encoding modes, a usage trigger, and the payment model. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% with one required string parameter, so the schema already carries the parameter semantics. The description adds nothing beyond restating that text is encoded; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (percent-encode) and resource (text), and disambiguates the two encoding modes via the concrete encoders encodeURIComponent and encodeURI. An agent can tell this apart from url_decode and url_parse by the verb alone.

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

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

"Use when building query strings" gives a clear positive trigger, but there is no exclusion, no mention of when to pick the full-URL mode over the query-value mode, and no pointer to the sibling url_decode. The guidance is implied rather than 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 cover only hints (readOnlyHint=false, openWorldHint=true), so the description usefully adds the critical operational fact that each successful call costs $0.001 in USDC on Base via x402 — a prerequisite an agent must know before invoking. It also describes the return shape, though it does not explain failure/refund behavior for unsuccessful calls.

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

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

Two sentences, both front-loaded and waste-free: the first defines the output decomposition, the second covers usage and cost. The long output enumeration is informative rather than padding, though it is dense enough to be mildly scannable-unfriendly.

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 correctly compensates by enumerating the returned fields and noting the IP-host flag. Combined with the payment disclosure, an agent has what it needs to call the tool correctly; only edge cases (malformed URL handling) are unaddressed.

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% with a single required 'url' parameter already documented in the schema. The description adds no format, encoding, or validity constraints beyond what the schema states, 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 ('Split') plus resource ('a URL') and enumerates the exact decomposition produced: protocol, host, port, path, query params object, hash, origin, plus IP-address detection. An agent can distinguish it immediately from siblings like url_encode, url_decode, and domain 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 read query parameters or check a link's host' gives concrete triggering scenarios, which is more than most definitions offer. It stops short of naming an alternative tool or stating when not to use it, so it does not reach the 5 tier.

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

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

The description discloses behavior the annotations do not: the output is cryptographically random, the count is capped at 100, and each successful call costs $0.001 in USDC on Base via x402, which is critical operational context. It does not describe the response shape, though no output schema exists to cover that.

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

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

Three tight sentences, front-loaded with what it produces, then when to use it, then the cost caveat. No filler or redundancy.

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

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

For a single-parameter generator with no output schema and no annotations covering billing, the description supplies the essential missing pieces: entropy source, range cap, and the paid x402 model. Only the return format (a list vs. single value) 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 'count' parameter is fully documented in the schema; the description only restates the 1-100 range and default of 1. Baseline 3 applies since the schema carries the parameter semantics.

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

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

States a specific verb and resource ('Generate ... version-4 UUIDs') plus the scope (1 to 100) and the entropy source (cryptographic random). This clearly distinguishes it from siblings like random_number, random_password, 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?

Gives concrete use cases ('IDs, idempotency keys and test data'), which is real guidance on when to reach for this tool. It stops short of naming alternatives or exclusions (e.g. when to prefer random_number or a deterministic hash), 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?

Annotations cover the safety profile (destructiveHint=false, openWorldHint=true), and the description adds genuinely non-obvious behavior: the x402 payment of $0.001 USDC on Base, charged 'per successful call,' which explains the non-readOnly/non-idempotent annotations (a transfer occurs). It does not say what is returned on an invalid IBAN (error vs. structured failure), 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?

Two sentences, front-loaded with the action and validation steps, then usage guidance, then the pricing constraint last. No redundant or filler text; every clause carries information an agent needs before calling.

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

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

For a one-parameter validation tool with no output schema, the description covers purpose, when-to-use, the returned format, and the cost model. The only missing piece is failure behavior (what an invalid IBAN yields), which is a minor omission against an otherwise complete definition.

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

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

Single parameter with 100% schema description coverage ('The IBAN, spaces allowed'), so the schema already carries the parameter contract and the baseline is 3. The description's mention of country-specific length and mod-97 describes the checks performed, not additional input semantics, so it does not raise the score.

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 ('Check') plus the exact checks performed (format, country-specific length, mod-97 check digits) and the return shape (formatted in groups of four). An agent can distinguish this from sibling validators like validate_luhn or validate_isbn purely from the description, with no schema reading required.

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 placement guidance: 'Use before saving bank details or paying out,' which tells the agent exactly when to reach for it. No explicit exclusion or named alternative is given, but the sibling set contains no competing IBAN tool, so there is little ambiguity to resolve.

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

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

Annotations only assert the generic flags (readOnly=false, openWorld=true, idempotent=false, destructive=false). The description adds real context beyond them: hyphens and spaces are silently ignored, conversion happens only for valid ISBN-10s, and each successful call costs $0.001 USDC on Base via x402 (implying failed calls are free). It doesn't describe what an invalid input yields, which is a 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?

Four short sentences, front-loaded with the action and followed by input normalization, usage trigger, and cost. No filler, though the pricing clause is dense enough that separating it or moving it later would read slightly better.

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

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

With no output schema, the description carries the burden of explaining return values, and it doesn't: it's unclear whether the result is a validity boolean, the converted ISBN-13, or an error on invalid input. Input semantics, usage, and cost are complete, but the response contract is unspecified.

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

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

Schema coverage is 100%, so the baseline is 3, but the thin schema text ("The ISBN") is surpassed by the description, which specifies accepted formats (ISBN-10 or ISBN-13) and that hyphens/spaces are normalized away. That is genuine input-format guidance the schema does not carry.

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 pair (check ISBN-10/ISBN-13 check digit) and adds the secondary transformation (convert valid ISBN-10s to ISBN-13). This clearly separates it from the other validator siblings (validate_iban, validate_luhn) by naming the exact identifier domain.

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 before cataloguing or ordering books" gives a concrete workflow trigger rather than leaving usage implied. It stops short of naming alternatives such as validate_luhn or validate_iban when the identifier type is uncertain, so it's clear context without 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?

With annotations present the bar is lower, and the description still adds meaningful behavior: no external lookup, format-only checking, and a concrete cost model ($0.001 USDC on Base per successful call via x402). The per-call pricing also explains why the tool is non-idempotent and involves an external payment rail, so it is consistent with readOnlyHint=false and openWorldHint=true rather than contradicting them. It does not describe the shape of the response (boolean vs. check digit vs. both), 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?

Four tightly-scoped sentences, front-loaded with what it does, followed by scope limits, use case, and cost. No filler or repetition; the pricing detail is placed last where it belongs.

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 and existing annotations, the description covers purpose, scope, use case, and cost. It implies the return content ('passes' plus 'compute the check digit') but never states the exact response shape, which is the one thing an agent calling it blind would still wonder 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?

There is a single parameter with 100% schema description coverage ('Digits, spaces and hyphens allowed'), so the schema already carries the parameter semantics. The description adds nothing about the input format beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names a specific verb+resource (check a number against the Luhn mod-10 algorithm) and additionally states the secondary output (compute the check digit to append) plus the domains it applies to (card numbers, IMEI, IDs). It also distinguishes itself from lookup-style siblings by stating 'Only the format is checked; nothing is looked up.'

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 catch typos in card or ID numbers' gives a clear positive trigger, and 'Only the format is checked; nothing is looked up' implicitly sets the boundary for when this is not appropriate (no existence/validity checking). It never names an alternative validator such as validate_iban or validate_isbn, so the when-not side is only implied.

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

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

The annotations cover the safety profile (non-readonly, non-idempotent, openWorld), so the bar is lower. The description still adds genuinely useful behavioral context beyond them: a cryptographic random source and, importantly, that the call costs $0.001 USDC on Base via x402 and is charged only on success. That payment/cost disclosure is exactly the kind of extra trait that helps an agent decide.

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

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

Three short sentences, front-loaded with what the tool is, then when to use it, then the cost. No padding; every sentence earns its place.

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

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

For a zero-parameter tool with no output schema, the description covers what it returns (yes or no), why to choose it, and the payment model. The only mild gap is the absence of any routing note against sibling random/decision tools.

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?

Zero parameters, so per the rubric the baseline is 4. The empty schema is consistent with a no-input tool and the description implies there is nothing to configure.

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 (returns) and resource (a fair random yes/no) plus the mechanism (cryptographic random source). It is clear what the tool does, though it never names the closely-related siblings (coin, magic_8_ball) that an agent would need to disambiguate against.

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?

"For quick decisions when the options are equally good" and "Use to break ties" give a clear triggering context. It stops short of explicit exclusions or alternatives (e.g. coin for heads/tails, magic_8_ball for whimsical answers).

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