Agent Data Tools: Utilities

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

Discloses traits beyond the annotations: padding tolerance, UTF-8 output, pricing model ($0.003/call, first 25 free, failed calls free). Crucially it explains why readOnlyHint=false despite being a pure read — 'not marked read-only because each call is charged' — resolving what would otherwise look like a contradictory annotation.

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

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

Front-loaded with the core action, then padding rule, usage, example, and billing. Every sentence carries information an agent needs (the billing note justifies the odd readOnly annotation), though the description is fairly dense.

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

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

No output schema exists, but the description states the decode target (UTF-8 text) and failure semantics ('failed calls free' implies invalid input can fail). For a single-parameter pure-compute tool this covers everything needed to call it correctly.

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

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

Schema coverage is 100% and there is one parameter, so the baseline is 3. The description adds a concrete example ('text=aGVsbG8gd29ybGQ=') that shows expected input shape, plus the fact that unpadded input is tolerated, which is meaningful 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 precise verb+resource: 'Decode standard or URL-safe base64 to UTF-8 text,' and names both accepted input encodings plus the output encoding. An agent can immediately distinguish this from the sibling base64_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?

Gives concrete usage context ('Use to read encoded headers, tokens and data URLs') and a worked example. It does not explicitly name base64_encode as the inverse or state exclusions, but the decode-vs-encode distinction is clear from the verb.

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, and the description proactively justifies that flag ('Reads or computes only; not marked read-only because each call is charged'), which prevents an agent from misreading the tool as a mutator. It also discloses cost/permission model ($0.003/call via x402 USDC or card key, first 25 free, failed calls free) and the dual return format — real behavioral context beyond the structured fields.

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

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

Front-loaded with the core action and output shape, and the pricing sentence, while long, carries decision-relevant information for a paid tool. The example is slightly redundant given the 100%-covered schema, costing a little density.

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

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

With no output schema, the description compensates by stating what comes back (standard plus URL-safe base64), and it covers the commercial/authorization gate an agent must satisfy. Nothing needed to invoke or interpret the call is missing.

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

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

There is only one parameter and schema coverage is 100%, so the schema fully documents 'text'. The description's 'text=hello world' example adds a small bit of format confirmation but nothing the schema doesn't already imply; baseline 3 is appropriate.

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

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

States a specific verb+resource ('encode UTF-8 text as standard base64') and immediately clarifies the output includes both the standard and URL-safe variants. This cleanly distinguishes it from the sibling base64_decode.

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

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

Gives concrete use cases ('data URLs, headers and basic auth strings') and a worked example ('text=hello world'), which is more than most sibling tools offer. It stops short of naming when to prefer an alternative (e.g., url_encode or base64_decode), so it is clear context without explicit exclusions.

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

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

Goes well beyond the annotations: it discloses the pricing model ($0.003/call, first 25 free), that failed calls are free, and explicitly reconciles the non-obvious readOnlyHint=false by explaining the per-call charge. This is exactly the kind of context annotations cannot convey.

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

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

Purpose and supported formats are front-loaded, followed by usage, example, and pricing. Slightly dense with the pricing sentence, but each sentence carries distinct information the agent needs.

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

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

For a two-parameter pure transform tool with no output schema, the description covers inputs, cost, and failure semantics well. It never states the return shape (a converted string), which is implied but not explicit, leaving a 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 both parameters, setting a baseline of 3. The description adds incremental value by showing mixed-input tolerance ('userID_value') and a concrete call example (text=user profile id, to=camel) that maps values to both parameters.

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

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

States a specific verb (Convert) and resource (text or identifiers) and enumerates all eight target formats, so an agent immediately understands scope. It is clearly distinguishable from siblings like slug or text_stats, which do different transformations.

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 use case ('Use when renaming fields or generating code identifiers'), which gives clear context for selection. It stops short of naming alternatives or exclusions (e.g., when to prefer slug instead), so it does not reach the top band.

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

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

Annotations only say readOnlyHint=false and idempotentHint=false; the description explains the surprising reason ('not marked read-only because each call is charged') and adds pricing, a free-tier quota, and a 'failed calls free' billing rule. It also discloses the return content ('each result and the totals') absent an output schema. This is exactly the 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?

Six short, front-loaded sentences covering purpose, return, usage, example, billing, and read-only rationale; nothing is redundant. The billing sentence is the only one that could be trimmed for a pure-selection decision, but it earns its place by explaining the annotation.

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

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

For a single-optional-parameter tool with no output schema, the description covers purpose, return values, pricing, and the read-only rationale, leaving little for an agent to guess. Only the exact return shape (e.g., per-coin array vs. summary counts) is left slightly loose.

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 count parameter already documents the 1-100 range and default, so the schema does the heavy lifting. The description only restates this with 'Example: count=1' and adds no new semantics such as behavior for count>1 beyond the totals mention.

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 ('Flip one or more fair coins') plus the implementation detail of a cryptographic random source, which separates it from a naive random number generator. It does not explicitly name siblings like dice, random_number, or magic_8_ball, so the agent must infer the boundary from 'fair decisions and games'.

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' implies a domain but gives no when-not guidance or named alternative (e.g., dice for non-binary outcomes, random_number for ranges). The 'Example: count=1' is an invocation hint rather than 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?

The description goes beyond the annotations by explaining WHY readOnlyHint is false ('each call is charged'), which is exactly the kind of non-obvious metadata an agent would otherwise misread. It also discloses pricing ($0.003/call via x402 USDC or card key), the 25-call free tier, and that failed calls are free. It does not explain the openWorldHint=true or idempotentHint=false flags, so it is strong but not complete.

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

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

Front-loaded with the conversion and outputs, then formats, then usage, then commercial terms – a sensible priority order with no filler. The pricing/free-tier sentence is slightly dense but is genuinely decision-relevant information for a paid tool.

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

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

There is no output schema, and the description compensates by naming all three result components (converted values, relative luminance, text-colour recommendation). What is missing is the shape of the returned payload – field names or units for luminance – leaving the agent to discover the response format on first call.

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

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

Schema coverage is 100% but the schema's own parameter text is only 'The colour', so the description carries the real semantic load by enumerating accepted syntaxes (#rgb, #rrggbb, rgb(r,g,b), hsl(h,s%,l%)) and giving a worked example (color=#0f6cbd). That meaningfully exceeds the baseline of 3 for a fully-covered 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?

Specific verb and resource ('Convert a colour between hex, RGB and HSL') plus the derived outputs (relative luminance, black/white text recommendation) and the accepted input formats. It is clear what the tool returns, but it never names color_contrast, the sibling whose purpose most overlaps with the luminance/readability half of this tool.

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

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

'Use for theming and design checks' gives an implied context but no explicit when-to-use versus alternatives, and no exclusions. That is a real gap in a sibling list containing color_contrast (contrast/readability) and random_color (palette generation), which an agent could easily confuse with this conversion tool.

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 annotations: it explains why readOnlyHint is false (each call is charged), discloses the pricing model, the free-tier allotment, that failed calls are free, and the auth mechanisms (x402 USDC or card key). This resolves the one annotation that would otherwise puzzle an agent.

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

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

Front-loads the purpose and example, then handles the read-only caveat and pricing compactly. The pricing clause is long but load-bearing for agent decision-making, so little is wasted.

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

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

With no output schema, the description compensates by stating exactly what is returned (a ratio plus AA/AAA pass/fail at normal and large text sizes). Combined with payment and auth details, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a concrete example (fg=#767676, bg=#ffffff) that demonstrates the expected hex colour format, which the schema's 'Text colour'/'Background colour' labels do not convey.

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

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

States a specific verb and resource: computes the WCAG 2 contrast ratio between a text colour and a background colour, returning AA/AAA pass/fail at normal and large sizes. This clearly distinguishes it from the sibling 'color' and 'random_color' tools, which do not evaluate contrast.

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

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

'Use to check that a design is readable' gives clear intended context, and the fg/bg example shows the calling pattern. It does not state when-not to use it or name an alternative, but for a single-purpose utility the guidance is sufficient to route correctly.

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

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

Goes well beyond the annotations: it discloses the x402 USDC / card-key billing model, that the first 25 calls are free and failed calls are free, and explicitly reconciles the readOnlyHint=false annotation ('not marked read-only because each call is charged'). That reconciliation of an otherwise-confusing annotation is exactly the kind of context the description should supply.

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 the example, then appends pricing and annotation context. It is dense but each sentence carries functional information; the pricing clause is a bit of a non-behavioral addendum but is useful for the caller.

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 compute-only tool with full schema coverage and no output schema, the description covers input format, timezone, return concept, and constraints. A brief note on output shape isn't strictly needed since 'next run times' is self-evident, 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 the baseline is 3, but the description adds real meaning: UTC output, the 5-field format with ranges/lists/steps/names, and a worked example showing expr, count, and from used together. This clarifies format expectations the terse schema labels do not.

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

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

States a specific verb (compute/return) and resource (next run times of a cron expression) with clear scope. It even pins down the accepted cron dialect (5-field, ranges/lists/steps/names) so the agent knows exactly what the tool handles. No sibling overlaps with this behavior.

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

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

Explicitly says to 'check a schedule before deploying it,' giving a concrete use context. There are no sibling tools that compute cron schedules, so no alternative needs to be named, but it stops short of stating when-not-to-use.

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

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

Goes well beyond the annotations by disclosing auth/payment (x402 USDC or card key via /credits), cost ($0.003/call, first 25 free, failed calls free), and explicitly reconciling why readOnlyHint=false despite the operation being read-only ('each call is charged'). That reconciliation is exactly the kind of context annotations cannot convey.

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

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

The inline example with an embedded newline is awkwardly formatted, and pricing/payment details are crammed into the same paragraph as the technical behavior, diluting the front-loaded conversion description. Every element is arguably useful, but structure and flow suffer.

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 utility converter with full schema coverage and no output schema, the description explains the return shape (JSON array of objects, first row as keys), delimiter handling, and quoting. It is complete enough to invoke correctly, lacking only explicit sibling routing.

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 both 'text' and 'numbers'. The description reinforces the numbers=true behavior and gives an example, adding marginal value over the schema, which matches the 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 specific verb (convert) and resource (CSV to a JSON array of objects keyed by the first row), and the direction of conversion distinguishes it from sibling json_to_csv and json_format. An agent can identify it 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 load spreadsheet exports into an agent" gives a clear when-to-use context plus a concrete example. It does not name an alternative or state when not to use it (e.g. vs json_to_csv), 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?

Adds rich behavior beyond annotations: month-end clamping with a concrete rule (31 Jan + 1 month = 28/29 Feb), weekend-skipping for businessDays, the pricing/credit model, the fact that failed calls are free, and an explicit rationale for readOnlyHint=false. This directly explains rather than contradicts the annotation.

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 clamping, use case, example, and cost. Dense and mostly waste-free, though the bundled pricing and read-only justification make the tail heavier than the task-relevant content.

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

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

With no output schema, the description should ideally say what is returned (presumably a date/timestamp), which is its one notable gap. Otherwise, behavior, cost, and parameter meaning are covered adequately for a lightweight compute tool.

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

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

Schema coverage is 100%, so the four parameters are already documented, setting the baseline at 3. The description adds clamping semantics and an example but also mentions years/weeks/hours/minutes, which are NOT accepted by the schema's date/days/months/businessDays parameters, creating mild scope ambiguity.

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

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

States a specific verb and resource (add/subtract time to a date) plus scope (years/months/weeks/days/hours/minutes, business days). It is highly specific, but never names the adjacent siblings date_diff or date_info, so the agent gets no explicit disambiguation from those.

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 application context, and the negative-number note clarifies the subtract case. There is no explicit when-not guidance or pointer to the alternative date_diff for the inverse operation.

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 explaining why readOnlyHint is false ('each call is charged') and disclosing pricing, the free-call allowance, and free failed calls. It also fully describes the computed output. Minor gap: no mention of timestamp format tolerance or error behavior.

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

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

Front-loads the returned computation, then usage, example, and pricing. Efficient and well-ordered, though the pricing/payment sentence is somewhat boilerplate-heavy for an agent selecting a tool.

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

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

With no output schema, the description carries return-value disclosure well by listing every computed field. It is essentially complete for a two-param pure-computation tool, with only format-handling edge cases unspecified.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds a concrete example (from=2026-01-01, to=2026-10-18) but no extra semantics beyond the schema's 'Start/End date or ISO timestamp'. 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 ('Time between two dates or timestamps') and enumerates exactly what is returned (total days, weeks, hours, minutes, seconds, Y-M-D breakdown, weekdays). This cleanly distinguishes it from sibling date tools like date_add and date_info.

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

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

Gives clear use cases ('Use for deadlines, ages and durations') plus a concrete example. However, it never names an alternative sibling (e.g., date_add for arithmetic) or states exclusions, so routing between date tools is left partly 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?

It directly explains an otherwise confusing annotation combination: 'Reads or computes only; not marked read-only because each call is charged,' resolving the apparent tension with readOnlyHint=false. It also discloses cost ($0.003/call), the billing paths (x402 USDC or card key at /credits), the 25 free calls, and that failed calls are free — exactly the kind of context annotations cannot convey.

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

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

Dense and front-loaded: the capabilities come first, then usage, then example, then pricing/auth caveats. The opening sentence is long and list-heavy, but every 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?

With no output schema, the description correctly enumerates the returned fields, and it covers auth, cost, and the read-only annotation rationale. Only timezone/ISO-week edge-case behavior is left unstated for what is a lookup tool.

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

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

Schema coverage is 100% and the schema already says 'Date or ISO timestamp (default today)', so the description need not repeat it. The added example `date=2026-10-18` gives concrete format guidance, but no timezone or edge-case semantics are added beyond the schema.

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

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

The first sentence enumerates exactly what is computed for a date (weekday, ISO week/week-year, day-of-year, quarter, days in month, leap year, Unix timestamp, weekend flag), which is far more specific than a tautology. It does not explicitly contrast itself with siblings like `unix`, `date_add`, or `date_diff`, so an agent must infer the boundary.

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' plus a concrete example implies the usage context, but there is no explicit statement of when NOT to use it or which sibling (`unix`, `date_add`, `date_diff`) covers overlapping needs. Usage is implied rather than directed.

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

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

Goes well beyond the annotations: it names the random source (cryptographic), states the return payload (every roll, the modifier, the total), documents the input bounds, discloses cost and the first-25-free / failed-calls-free policy, and explicitly reconciles the readOnlyHint=false annotation by explaining that charging makes each call non-read-only.

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 behavior and bounds before secondary details, and every sentence carries information. It is dense — the pricing and read-only-justification clause is a lot for one paragraph — but nothing is redundant.

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

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

For a single-parameter tool with no output schema, the description covers input syntax, bounds, randomness guarantees, return contents, and cost. An agent has everything needed to invoke it and set expectations for the response.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real constraints the schema lacks: notation format, the 100-dice/1000-sides caps, and the 1d6 default. That meaningfully extends the field description rather than restating it.

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

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

States a specific verb and resource ('Roll dice in standard notation such as 2d6+3 or 1d20') with hard bounds (up to 100 dice of up to 1000 sides). This clearly separates it from siblings like random_number, coin, and magic_8_ball without needing to open 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 an explicit usage domain ('Use for tabletop games and simulations') and shows a concrete example call. It stops short of naming when NOT to use it or pointing to a sibling alternative, but the intended context is unambiguous.

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

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

Annotations declare destructiveHint=false but readOnlyHint=false, which is a counterintuitive combination; the description resolves exactly that ('Reads or computes only; not marked read-only because each call is charged'). It also discloses pricing ($0.003/call via x402 USDC or card key), the free first 25 calls, and that failed calls are free. This is far more behavioral context than the annotations carry.

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

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

Purpose and return value are front-loaded, followed by usage, example, cost, and the read-only rationale, in descending order of importance. Each sentence earns its place; the pricing detail is directly relevant to an agent deciding whether to invoke a charged tool.

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

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

The tool has one fully documented required parameter, no output schema, and annotations that already cover the safety profile. The description fills the remaining gaps by describing the return payload, the cost model, and the reason for the non-read-only flag, so nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the single 'message' parameter (including the 2,000-character limit) is already fully documented in the schema. The description adds an example ('message=hello') but no additional syntax, constraints, or semantics. Baseline 3 is appropriate 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 gives a specific verb and result set: it returns the sent message plus its length and server time, and it names the concrete testing scenarios (x402 client, payment flow, agent wiring). An agent immediately knows what the call produces without opening the schema. Sibling differentiation from the similar 'ping' tool is only implicit, but the stated use cases make the intent 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?

It states clearly when to reach for this tool ('Use to test an x402 client, payment flow or agent tool wiring end to end'), which is real routing guidance. It stops short of naming an alternative or an exclusion (e.g., when 'ping' would be preferable), so it is clear context without 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?

Proactively explains the one counterintuitive annotation: readOnlyHint=false is justified as 'Reads or computes only; not marked read-only because each call is charged,' which resolves what would otherwise look like an inconsistency. It also discloses pricing ($0.003/call via x402 USDC or card key), a free tier (first 25 free), and failure semantics (failed calls free) — real behavioral context beyond the annotations.

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

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

Front-loads capability, then use cases, then example, then pricing — a sensible priority order with little waste. The pricing/account clause is longer than the rest and slightly crowds the behavioral facts it is meant to support.

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 specifies the return payload as both hex and base64 digests, and it adds the cost and free-tier information an agent needs before calling. Nothing required to invoke or interpret the tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the default note ('SHA-256 default') and the inline example add usable meaning beyond the schema's plain enumeration. No deeper constraint (e.g. case sensitivity of algorithm values or how disallowed values are rejected) is offered, so it is not a 5.

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

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

States a specific verb (Hash) and resource (UTF-8 text) plus the exact supported algorithms (SHA-256 default, SHA-1, SHA-384, SHA-512) and the return formats (hex and base64). An agent can distinguish this from siblings like hmac or base64_encode without opening any schema.

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

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

Gives concrete use cases (checksums, cache keys, deduplication) and a worked example (text=hello, algorithm=sha256), which clarifies the intended call pattern. It does not explicitly route the agent away from the most confusable sibling, hmac, 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?

The description adds substantial context beyond the annotations: the key is used only for this call and not stored, pricing and free-tier terms, and an explicit explanation that it is 'not marked read-only because each call is charged' — which pre-empts confusion over readOnlyHint=false. With no output schema, it also discloses the return encodings (hex and base64).

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

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

Front-loaded with the core operation and algorithm list, then usage, privacy, example, and pricing in that order. Efficient overall, though the pricing/free-tier clauses are denser than the rest and only marginally useful to tool selection.

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 output encodings and the algorithm variants, and it covers the ephemeral key and billing model. Minor gaps remain (no sample output payload, no noted error behavior for invalid algorithm/key), which keeps it from a 5.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantic value: the default algorithm, the inline example (message=hello, key=secret, algorithm=sha256), and the ephemeral nature of the 'key' parameter. The base64/hex output encoding is also specified, which the schema does not cover.

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

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

States a specific verb (compute an HMAC) plus the resource and the full algorithm/output surface ('SHA-256 (default), SHA-1, SHA-384 or SHA-512, in hex and base64'). This distinguishes it from the sibling 'hash' tool (keyed vs unkeyed) 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?

'Use to check webhook signatures' gives a clear, concrete use case so an agent knows when this tool is the right pick. It does not name alternatives (e.g. plain 'hash' or 'jwt_decode') or state when not to use it, so it falls short of a 5.

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

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

With annotations covering safety hints, the description goes further and explains the non-obvious cost model ($0.003/call, 25 free, failed calls free) and preempts the annotation question by explaining why readOnlyHint is false. That is exactly the kind of context structured fields cannot convey.

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

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

Front-loads the core transformation, then usage, then example, then pricing – a sensible ordering with no filler. The pricing/annotation sentence is dense but each clause carries information an agent needs when deciding whether to call.

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

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

No output schema exists, and the description compensates by describing the return format through its transformation rules (plain text, decoded entities, bulleted list items). Combined with the cost and failure behavior, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3; the inline example (html=<h1>Hi</h1>...) usefully demonstrates the expected input shape and the entity-decoding behavior. It adds real illustrative value beyond the terse 'The HTML' 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 and resource (strip HTML to plain text) and enumerates the exact transformations: scripts/styles removed, block elements become line breaks, list items bulleted, entities decoded. That level of specificity distinguishes it from neighbors like markdown_to_html or text_extract without the agent 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 an explicit use case ('feed web content or emails to an LLM'), which is real routing guidance against the many other text tools in the sibling list. It stops short of naming a specific alternative or a when-not condition, so it lands 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 declare readOnlyHint=false with no explanation, and the description supplies it: reads/computes only but is charged per call. It also adds cost behavior ($0.003/call, first 25 free, failed calls free) that annotations cannot convey. It does not address the idempotentHint=false flag, which is the one remaining behavioral question.

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

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

Front-loads the purpose and usage trigger before the pricing detail. It is compact, but the pricing/licensing clause is appended into an already dense sentence and mildly dilutes the core definition.

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

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

For a one-parameter, no-output-schema tool, the description still describes the return contents (name, meaning, retry recommendation) as well as the cost and no-write behavior. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% so the single 'code' parameter is documented as a baseline 3, but the description adds meaning beyond it: the valid 1xx-5xx range (the schema permits any integer down to negative values) and a worked example (code=429).

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

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

States a specific resource (HTTP status code) and what it returns: name, plain-language meaning, and retry guidance. It also scopes the range (1xx-5xx) and calls out notable codes, and no sibling tool overlaps this domain, so an agent can select it unambiguously.

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

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

Gives an explicit trigger ('Use when handling API errors') plus a concrete example (code=429). There is no competing sibling to disambiguate against, so no when-not guidance is needed, but the usage context is clear 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 declare readOnlyHint=false, which would normally mislead for a pure computation; the description explicitly reconciles this ("Reads or computes only; not marked read-only because each call is charged"). It also discloses the payment/auth path (x402 USDC, card key via /credits) and that failed calls are free — real behavioral context beyond the annotations.

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

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

The core purpose and enumerated outputs are front-loaded, followed by usage, example, and billing. Every clause carries information, though the pricing sentence is dense; nothing is wasted but the block is packed.

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 all returned fields (network/broadcast, host range, netmask, count, membership boolean). Billing and the annotation reconciliation round it out; nothing an agent needs to call it is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters; the baseline of 3 is lifted by the concrete example "cidr=192.168.1.0/24, ip=192.168.1.77", which shows expected formats and that ip is combined with cidr.

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

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

States a specific resource (IPv4 network in CIDR notation) and enumerates exactly what it produces: network/broadcast address, first/last usable host, netmask, address count, and IP-membership. This scope is clearly distinct from the sibling ip_info, which looks up a host rather than doing network math, even though it isn't named explicitly.

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

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

"Use for firewall rules and allowlists" gives clear domain context for when the tool applies, plus a worked example. It stops short of naming alternatives (e.g. ip_info) or stating when-not to use it, so no exclusions are offered.

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: the classification is fully offline ('without any lookup'), there is a per-call charge with a free tier and free failed calls, and it explicitly reconciles the readOnlyHint=false annotation ('not marked read-only because each call is charged'). Auth/payment requirements are exactly the kind of extra behavioral detail the rubric rewards.

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

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

Front-loads the core classification, then usage, example, and pricing. Every sentence carries information, though the pricing clause is dense with billing minutiae that could be trimmed; overall appropriately sized for a single-parameter tool.

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

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

With no output schema, the description correctly enumerates what is returned (version, address class, integer form, reverse-DNS). Combined with the usage context, pricing, and annotation reconciliation, 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?

Only one parameter, and the schema already documents it at 100% coverage, establishing the baseline of 3. The description adds a worked example (ip=10.1.2.3) and states IPv4/IPv6 acceptance, which is marginal but real added value.

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 facts returned: version, private/loopback/link-local/CGNAT/public status, integer and reverse-DNS forms. This distinguishes it from the sibling ip_cidr, which does CIDR math rather than address classification.

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

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

Gives a concrete use case ('triage IPs in logs or allowlists') and a worked example, so the agent knows the intended context. It stops short of naming when-not-to-use it or pointing to the closest alternative (ip_cidr), 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?

Goes well beyond the annotations: it discloses pricing ($0.003/call), the free tier (first 25 free, failed calls free), auth options, and explicitly reconciles its read-only nature with the readOnlyHint=false annotation ('Reads or computes only; not marked read-only because each call is charged'). This is exactly the kind of context annotations cannot carry.

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

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

Front-loads purpose, then usage, then example, then commercial terms. Every sentence serves a purpose. The pricing sentence is dense but necessary for a metered tool; nothing is wasted.

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

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

With no output schema, it still states the return value ('Returns the formatted text') and covers billing, auth, and the read-only caveat. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The worked example (text={...}, indent=2, sortKeys=true) reinforces usage but adds little semantic detail beyond the schema's own descriptions.

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

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

States a specific verb (format/pretty-print) and resource (JSON), and the optional sorted-keys behavior scopes it further. It is distinguishable from json_minify and json_validate by intent ('make machine JSON readable'), 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?

Gives clear usage context: 'make machine JSON readable or to normalise it for diffs.' This tells the agent when the tool is appropriate but names no alternatives and states no exclusions (e.g., use json_repair when the input is malformed).

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

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

Goes well beyond the annotations: it discloses pricing ($0.003/call, first 25 free, failed calls free) and payment rails (x402 USDC or card key via /credits). Critically, it explains the otherwise-puzzling readOnlyHint=false by noting the tool only reads/computes and is unmarked solely because each call is charged.

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

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

Front-loaded with purpose, then use case, example, pricing, and the annotation rationale. Every sentence earns its place; the pricing and read-only clarifications are essential context that is packed tightly without waste.

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

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

For a single-parameter transformation tool, all decision-relevant information is present: what it does, when to use it, cost model, and the reason for its annotation values. Although there is no output schema, the description states it returns before/after sizes, filling that 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 single 'text' parameter is already documented, establishing a 3 baseline. The inline example (text={ "a" : 1 }) adds a small amount of format clarity about what the input string should look like, warranting slight credit above baseline.

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

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

States a specific verb ('Remove') and resource ('all unnecessary whitespace from JSON') plus the added output ('report the size before and after'). An agent can distinguish it from siblings like json_format (pretty-print), json_validate, and json_repair 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 shrink payloads or prompts' gives a clear context for when to reach for it. It does not name an alternative (e.g., json_format) or state exclusions, so it falls short of explicit routing, but the intended use case 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?

Discloses pricing ($0.003/call via x402 USDC or card key), a free tier (first 25 free, failed calls free), and the return shape (repaired JSON plus whether it parses). Crucially it explains the non-obvious annotation: 'not marked read-only because each call is charged', reconciling readOnlyHint=false rather than leaving the agent to guess.

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 action and enumerates repairs before the example and billing details, so the agent gets the essence immediately. The billing/pricing sentences are dense and somewhat verbose but each still earns its place by explaining the pricing and the non-read-only annotation.

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

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

With no output schema, the description still covers the return values (repaired JSON and parse success), the usage context, the cost model, and the annotation rationale. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond it with a concrete example input, text=```json {name: 'Ada', tags: ['x',],}, showing the kind of broken input the single 'text' parameter expects, which adds practical meaning over the schema's terse 'The broken JSON text'.

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

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

States a specific verb (Fix/Repair) and resource (JSON) and enumerates the exact transformations performed (fence removal, comments, trailing commas, single quotes, bare keys, True/False/None, bracket closing). This clearly distinguishes it from siblings like json_validate, json_format, and json_minify 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 precise trigger: 'Use when an LLM's JSON output fails to parse.' That is a clear when-to-use condition. It does not explicitly name or exclude alternatives (e.g. json_validate for well-formed input), so it falls just short of the 5 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?

Goes well beyond the annotations by explaining WHY readOnlyHint=false despite a pure read — 'Reads or computes only; not marked read-only because each call is charged' — and discloses pricing ('$0.003/call via x402 USDC or a card key, first 25 free; failed calls free'). Cost/auth/rate context of this kind is exactly what annotations cannot carry.

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

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

Front-loaded with the core behavior, then nested-value rule, use case, example, and cost note — each element earns its place and nothing is padded. The pricing sentence is slightly tangential but operationally relevant.

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

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

For a one-parameter, no-output-schema utility the description covers input format (with example), output format (header row, nested-as-JSON), intended use, and billing — an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a concrete example value showing the expected array-of-objects literal, which clarifies the shape better than the schema's 'A JSON array of objects' 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?

States a specific verb+resource+output shape: 'Convert a JSON array of objects to CSV with a header row built from all keys,' and adds how nested values are serialized. The direction (JSON→CSV) inherently distinguishes it from the csv_to_json sibling, but that sibling is 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?

Gives one usage context ('Use to export API results to a spreadsheet') plus a worked example, which implies when it fits. It never states exclusions, prerequisites (input must be a valid JSON array of objects), or points to the inverse csv_to_json for the opposite direction.

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

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

Adds substantial context beyond the annotations: pricing model ($0.003/call via x402 USDC or card key), the first-25-free allowance, and that failed calls are free. It also explicitly reconciles the readOnlyHint=false annotation by explaining that the call is charged, so the description and annotations are consistent 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-loaded with purpose, then return shape, trigger, example, and pricing in that order. Every sentence carries information, though the pricing/auth sentence is dense and slightly crowds out structural clarity.

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 spells out the return values (valid flag, parsed type/size, error line/column). Combined with cost, auth path, and the free-tier note, an agent has everything needed to decide and invoke.

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 'text' parameter is fully documented there, so the baseline is 3. The inline example (text={"a":1}) and the usage framing add marginal value but no format or syntax detail the schema lacks.

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

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

States a specific verb and resource ('Check whether text is valid JSON') and enumerates the outputs (valid true/false, parsed type and size, error line/column). The purpose is unambiguous, but it never names a sibling (json_repair, json_format) to disambiguate from the other JSON tools in the family.

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

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

Gives a concrete trigger: 'Use before parsing an LLM's or an API's output.' That is a clear when-to-use context. It stops short of stating when not to use it or routing invalid input to a sibling like json_repair.

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

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

Goes well beyond the annotations: it discloses that the token is not stored, that signature verification is skipped, the cost model and auth paths (x402 USDC or card key, first 25 free, failed calls free), and explicitly reconciles the surprising readOnlyHint=false by explaining the flag reflects per-call billing rather than mutation. That reconciliation of an annotation an agent would otherwise misread is exactly the value this dimension rewards.

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

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

Core behavior, safety warning, and use case are front-loaded in the first three sentences. The trailing pricing/auth sentence is dense with commercial detail that slightly dilutes focus, but it is a single compact clause and 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?

Without an output schema, the description carries the return-shape burden and does so by naming the reported fields (header, payload, iat/nbf/exp as dates, expired flag). The only gap is error behavior for a malformed or non-JWT string, which is a minor omission for a single-string-input 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?

With one parameter at 100% schema coverage, the schema already fully documents 'token'. The description adds a worked example token, which clarifies format (three dot-separated segments) but no additional constraint or edge-case semantics. Baseline 3 applies.

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

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

States a specific verb and resource (decode a JWT's header and payload) plus the deliberate limitation (without verifying the signature) and the concrete outputs (iat/nbf/exp as dates, expiry flag). This clearly separates it from siblings like base64_decode, which would also turn a token into text but without JWT semantics.

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 positive use case ('Use to debug auth flows') and an explicit exclusion ('Do not use the result to trust a token'), which prevents the most dangerous misuse. It does not name a sibling alternative (e.g., a verify tool), but none exists in the sibling list, so the guidance is close to complete.

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

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

Directly explains the counter-intuitive annotation state: 'Reads or computes only; not marked read-only because each call is charged,' resolving why readOnlyHint=false and idempotentHint=false for a pure read. It also discloses billing (x402 USDC or card key, 25 free, failed calls free) — exactly the kind of behavior the structured fields cannot convey.

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

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

Front-loaded with what the tool does before branching into fun-use, pricing, and the annotation rationale. Each sentence carries distinct information, though the pricing/credits clause is dense and could be trimmed while staying informative.

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

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

Covers purpose, output nature (random pick from 20 answers), optional input, usage domain, cost model, and the annotation rationale. With no output schema needed and all params documented, an agent has everything required to call and quote this tool correctly.

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

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

Schema coverage is 100% and the single parameter is fully documented there (optional, not stored), so the baseline is 3. The description adds only a usage example ('question=Will it ship today?') rather than new semantics like length limits or handling of non-yes/no input.

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

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

States a specific verb+resource (ask a yes/no question, return a random Magic 8-Ball answer) with the exact output domain ('one of the 20 classic Magic 8-Ball answers, chosen at random'). This clearly separates it from the many randomized siblings (coin, dice, random_pick, yes_no).

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 context ('For fun only. Use for games and chat bots.') which tells the agent the domain and that it is non-serious. However, it never states when NOT to use it or names an alternative (e.g., yes_no for deterministic answers, random_pick for weighted choice), so routing vs siblings is left to inference.

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

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

Goes well beyond annotations: it discloses that raw HTML is escaped (a security/safety trait the agent must know), explains the pricing model including free tier and that failed calls are free, and explicitly reconciles the readOnlyHint=false annotation by noting calls are charged. This is meaningful context the structured fields do not carry.

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

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

Front-loads the conversion and supported features, then adds behavior and pricing. Mostly efficient, though the inline example is crammed together and the pricing sentence is a run-on that slightly muddies the structure.

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

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

For a single-parameter, no-output-schema tool, the description covers purpose, supported syntax, safety behavior, and billing. Nothing critical for correct invocation is missing.

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

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

There is a single required parameter with 100% schema coverage, so the schema already documents it. The description's example illustrates usage but adds no new syntactic meaning beyond 'The Markdown'.

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 ('Convert Markdown ... to HTML') and enumerates the supported Markdown constructs, making the transformation unambiguous. It is clearly distinguishable from the reverse-direction sibling html_to_text.

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

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

Provides an explicit use case ('publish agent-written Markdown on a web page') and a concrete example input. It does not name alternatives or state when-not-to-use, but the context is clear enough to route correctly.

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

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

The annotations already declare openWorldHint=true, idempotentHint=false, destructiveHint=false, and readOnlyHint=false. The description adds important behavioral context beyond those annotations: it explains that the operation only reads/computes, that pricing is $0.003/call with first 25 free and failed calls free, and why readOnlyHint is false despite the read-only nature due to per-call charging. It does not explain idempotency directly, but the pricing/charging rationale materially clarifies the annotation profile.

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

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

The description is compact and front-loads the core purpose before usage context and pricing details. Every sentence contributes either selection guidance, behavioral context, or operational caveats, with no redundant restatement of the title or 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 simple one-parameter utility with no output schema, the description covers what the tool does, when to use it, example input, return concept (MIME type plus inline-display indicator), and charging behavior. 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 description coverage is 100% for the single file parameter, so the schema already defines it as "File name or extension." The description still adds value by giving examples of accepted forms (report.pdf, file=report.xlsx) and showing the mapping output, which clarifies the parameter's practical semantics beyond the schema text.

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

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

The description states a specific resource and operation: mapping a file name or extension to its MIME/content type, with a concrete example (report.pdf → application/pdf). It also distinguishes the adjacent behavior by noting whether browsers display the type inline, so an agent can tell what this tool returns unlike generic conversion utilities.

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

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

It gives a clear usage context: "Use when uploading or serving files," and provides an example call. It does not enumerate when not to use it or alternatives among sibling utilities, but the intended scenario is explicit enough.

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

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

With readOnlyHint=false and idempotentHint=false in the annotations, the description proactively explains the apparent mismatch: "Reads or computes only; not marked read-only because each call is charged." It also discloses cost ($0.003/call via x402 USDC or card key), the free tier, and that failed calls are free — behavioral context annotations cannot express.

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

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

The core conversion semantics are front-loaded in the first clause, followed by usage, an example, then billing. Slightly dense with three semicolon-joined clauses on pricing, but every sentence carries information an agent needs.

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

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

No output schema exists, and the example (number=2026 → roman=MMXXVI) supplies the return format. Range, direction, mutual exclusivity and cost are all covered; the only minor gap is error behavior when an out-of-range number is passed.

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% (baseline 3), but the description adds a worked example (number=2026, roman=MMXXVI) showing the input/output pairing and states that exactly one of the two parameters should be supplied — mutual-exclusion guidance the schema does not 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 precise bidirectional verb+resource: convert a number (1-3999) to Roman numerals or Roman numerals back to a number. The scope and direction are unambiguous and clearly distinct from the sibling number_words, which spells numbers rather than converting to numerals.

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?

"Give either number or roman" tells the agent how to invoke it and implicitly that the two inputs are alternatives, and "Use for dates, outlines and puzzles" gives concrete contexts. It lacks an explicit negative case or a named alternative (e.g. number_words), so it falls short of a 5.

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

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

Adds real context beyond the annotations: it explains why readOnlyHint is false (each call is charged), the pricing model, the free-call allowance, and that failed calls are free. It also discloses the cheque-form secondary output. It stops short of describing pagination/limits, but for a stateless computation tool this is strong.

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 example, then appends the pricing/behavior note. Every sentence carries information, though the pricing clause makes it denser than strictly necessary for tool selection.

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

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

For a one-parameter, no-output-schema tool, it covers scope, decimal behavior, example input, and the non-obvious billing/read-only caveat. 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 already 100% for the single 'number' param, and the description adds genuine meaning: the supported magnitude range, negatives, and that decimals trigger the 'and' cents cheque form. That goes beyond the schema's bare 'decimals allowed'.

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 (write a whole number out in English words), scopes it (up to trillions, negatives allowed), and disambiguates from siblings like number_roman by naming the words/cheque use case.

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 when amounts must be written out in full', e.g. cheques and invoices) and a concrete example input. It does not name an explicit alternative tool or state when NOT to use it, so it falls short of a 5.

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

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

Goes well beyond the annotations by disclosing the price ($0.003/call), payment channels (x402 USDC or card key via /credits), the first-25-free allowance, and that failed calls are free. Critically, it proactively explains the readOnlyHint=false anomaly ('not marked read-only because each call is charged'), reconciling the hint with observed behavior instead of contradicting it.

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

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

Three compact sentences, front-loaded with what it does, then when to use it, then the commercial/behavioral caveats. Every clause earns its place; 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?

There is no output schema, but the description still names the return payload (pong + server time). For a zero-param health/payment probe, the definition covers invocation, cost, failure behavior, and the annotation rationale completely.

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 the schema has nothing to document and there is no semantic gap for the description to fill. Baseline of 4 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 ('returns pong and the server time') and frames it as a paid round-trip check. No sibling in the list does anything remotely similar, so an agent can identify it instantly from the description 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 to test that an x402 wallet, client or MCP setup can pay and receive a result' gives clear triggering context. It does not name exclusions or alternatives, but no sibling tool overlaps functionally, 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?

Goes well beyond the annotations by explaining the pricing model ($0.003/call, first 25 free, failed calls free) and explicitly reconciling the surprising readOnlyHint=false: 'not marked read-only because each call is charged.' That reconciliation is exactly the context an agent needs to interpret the structured flags correctly.

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

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

Three compact sentences: capability, use case plus example, then billing/annotation notes. The pricing sentence is long but earns its place because it justifies the non-read-only flag. Front-loaded with the core capability.

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

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

With no output schema, the description still tells the agent what comes back (hex, RGB and HSL values) and the count ceiling (1-50 in schema, referenced by the example). Billing and annotation rationale are covered, so nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description adds an applied example (count=3, tone=pastel) plus the tone options ('pastel or dark'). It adds usage context but no new semantics beyond the schema, keeping it near baseline with a small bump for the example.

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

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

States a specific operation (generate one or more random colours) with the output formats (hex, RGB, HSL) and the tone constraint, which cleanly separates it from the static 'color' and 'color_contrast' siblings. It never names a sibling to route against, so no explicit differentiation credit.

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 ('placeholders, avatars and design ideas') and a worked example (count=3, tone=pastel). It does not state when NOT to use it or point to an alternative tool such as 'color' for converting an existing colour.

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

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

Goes well beyond the annotations by explaining WHY readOnlyHint=false ('not marked read-only because each call is charged'), disclosing the cryptographic (non-deterministic) source, and detailing the billing model including that failed calls are free. This is unusually rich behavioral context that the structured fields alone could 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?

Front-loaded with the core purpose, then flows to usage, example, pricing, and the annotation rationale. Every sentence carries useful information, though the pricing/payment sentences are dense and slightly lengthen an otherwise tight definition.

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

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

For a no-output-schema tool with 4 fully documented params, the description covers generation semantics, defaults (via schema), pricing, and safety rationale. The only gap is that it does not describe the shape of the returned value (a list vs. scalar), which the absence of an output schema leaves unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a concrete worked example (min=1, max=100, count=3, unique=true) that shows how parameters combine and clarifies that 'unique' is passed as the string 'true'. This is meaningful value beyond the schema's individual field descriptions.

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

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

States a specific verb and resource: generating 'one or more random whole numbers in a range (inclusive)' from a cryptographic source. This is clearly distinguishable from sibling randomness tools like dice, coin, random_pick, and random_shuffle, and the scope (whole numbers in a range, optional uniqueness) is precise.

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 clear usage context ('Use for draws, sampling and games') and an inline example (min=1, max=100, count=3, unique=true). However, it never names or excludes the overlapping siblings (dice, coin, random_pick, magic_8_ball), so an agent must infer which randomness tool to pick.

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

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

Goes well beyond the annotations: cryptographic random source, on-demand generation, nothing stored or logged, and full pricing (per-call cost, first 25 free, failed calls free). It also proactively reconciles the unusual readOnlyHint=false by explaining that charging makes the call non-read-only.

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

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

Purpose and behavior are front-loaded, followed by the usage trigger, example, and pricing. The pricing/key clause is long but operationally relevant; the passphrase mention is the one non-earning phrase.

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 safety profile, cost model, and generation guarantees; parameters are covered by the schema. The only gap is the unsupported passphrase-style capability, which no parameter exposes.

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

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

Schema coverage is 100%, so count/length/symbols are already documented; the description's call example (length=20, symbols=true, count=1) only echoes them. The mention of 'passphrase-style strings' has no corresponding parameter, which adds a small ambiguity rather than 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?

States a specific verb and resource ('Generate strong random passwords or passphrase-style strings') plus the mechanics: length, character sets, cryptographic source. Easily distinguished from siblings such as random_number, random_color, and uuid.

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 positive trigger for selection. It does not, however, say when to prefer uuid or random_pick instead, so there are no explicit exclusions or 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?

Beyond the annotations, it discloses the pricing/auth model ('$0.003/call via x402 USDC or a card key', first 25 free, failed calls free) and explicitly explains why readOnlyHint is false ('not marked read-only because each call is charged'). It also discloses the no-repeat selection behavior. This is exactly the extra context annotations cannot carry.

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

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

The core action and format are front-loaded, and each sentence carries information (purpose, use cases, example, pricing, annotation rationale). Slightly dense with the pricing clause, but nothing is redundant.

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

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

For a 2-parameter tool with no output schema and annotations present, the description covers purpose, usage, cost, and an example. It omits the return shape (the picked subset), but with no output schema this is a 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 baseline is 3, but the description adds genuine value: it notes items may be 'comma- or line-separated' (the schema only says comma-separated) and gives a worked example ('items=Ada,Alan,Grace,Linus, count=1').

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 ('Pick one or more items at random (without repeats)') and clarifies the input format, which distinguishes it from a full shuffle. It does not name a sibling (e.g. random_shuffle) explicitly, so an agent must infer the boundary itself.

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

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

It gives concrete use cases ('raffles, choosing who goes first, or breaking ties fairly') that clearly indicate when to reach for this tool. However, it never states when NOT to use it or names an alternative like random_shuffle for reordering the whole 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?

Goes well beyond the annotations: it explains why readOnlyHint is false ('not marked read-only because each call is charged'), confirms the operation is compute-only, and discloses the algorithm's randomness source plus the full cost model (per-call price, x402/card payment paths, first 25 free, failed calls free). That is exactly the kind of context annotations cannot carry.

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

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

Front-loads what the tool does, follows with use cases and an example, and relegates the pricing detail to the end, so the important content is read first. The pricing sentence is long but earns its place by justifying the non-read-only annotation.

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

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

For a single-parameter, no-output-schema tool, the description covers behaviour, randomness guarantees, input format and cost, and explicitly resolves the only potentially confusing annotation. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning the schema lacks: it accepts line-separated input in addition to comma-separated, and shows a concrete value ('items=1,2,3,4,5').

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

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

States a specific verb and resource ('Shuffle a comma- or line-separated list into a random order') and even names the algorithm, so an agent can tell it apart from siblings like random_pick and random_teams without opening any schema.

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

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

Names concrete use cases ('draw orders, seating and playlists') and gives a literal invocation example, which is clear context for when to reach for this tool. It does not, however, draw an explicit boundary against the neighbouring random_pick/random_teams tools, so it falls short of a 5.

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

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

Goes beyond the annotations by explaining the unusual readOnlyHint=false: 'Reads or computes only; not marked read-only because each call is charged.' It also discloses the pricing model, the free tier, and that failed calls are free — real behavioral context an agent cannot get from the structured fields. It does not cover edge cases (e.g., teams exceeding item count, or the odd negative minimum on 'teams').

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

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

Two tight sentences, front-loaded with the core action, followed by a compact example and pricing note. The pricing sentence is dense but each clause (cost, free tier, failure handling) 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?

For a two-parameter tool with no output schema, the description covers what it produces, how to invoke it, and the billing model. Minor gaps remain around behavior with degenerate inputs (more teams than names, non-positive team counts), but the essentials for correct invocation are present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds an illustrative example that concretizes the comma-separated 'items' format and the 'teams' default, which is more than the schema alone conveys.

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

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

States a specific verb and resource ('Split a list of names into ... teams') with the defining constraint (random, evenly sized) and a concrete example. It is clearly distinguishable from siblings like random_shuffle and random_pick, which reorder or select rather than partition.

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 clear usage context, and the worked example (items=..., teams=2) shows the intended call shape. It stops short of naming an alternative sibling or stating when-not to use it, so it falls short of a 5.

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

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

Goes well beyond the annotations by explaining *why* readOnlyHint is false — the call is charged — which prevents an agent from misreading the flag as a side effect. It also discloses pricing, the x402/card-key payment path, the 25-free-call allowance, and that failed calls are free.

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

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

Front-loaded with the core behavior and the example, with billing details trailing. Dense but every clause carries information; the pricing sentence is long but functionally necessary for an agent deciding whether to call.

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

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

There is no output schema, and the description compensates by enumerating the return values (comparison result plus derived major/minor/patch). Combined with cost, prerelease handling, and the annotation rationale, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: 'the first' identifies which parameter drives the next-version outputs, and the worked example shows both inputs are plain version strings ordered as a vs b.

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') and expands scope precisely: which is newer plus next major/minor/patch of the first. Prerelease handling is called out, and the example (a=1.10.0, b=1.9.3) disambiguates the semantics that trip people 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?

Explicitly frames the use case ('Use to decide whether an upgrade is a major change'), which orients the agent well. It doesn't name an alternative sibling, but none of the listed siblings overlap, so the omission costs little.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, and the description proactively explains the seeming contradiction ('not marked read-only because each call is charged'). It also discloses pricing, the 25-free tier, and that failed calls are free — real behavioral context beyond the annotations. It does not describe output format or rate limits, keeping it below 5.

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

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

Front-loaded with the core transform, then usage, then an example, then commercial terms. Dense and largely waste-free, though the pricing/payment sentence is long and slightly interrupts the technical flow.

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 must carry the return contract; it shows a concrete example output ('Crème Brûlée & Straße!' → slug), which mostly covers this. Behavior, cost, and the annotation rationale are all present, leaving little an agent needs that is missing.

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

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

Schema coverage is 100% and already documents both parameters, so the baseline is 3. The description adds value by clarifying semantics ('- by default') and providing a worked example that demonstrates accent handling with the separator, which the schema does not.

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

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

States a specific verb+resource ('Turn any text into a URL-friendly slug') and enumerates the transformation rules (accent folding, lower case, separator substitution). The sibling list contains adjacent string utilities (case, url_encode), but none are sluggers, so the purpose 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 file names, URLs and IDs' gives clear intended contexts. It does not, however, name an alternative or a when-not-to-use case against siblings like case or url_encode, 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?

It discloses billing behavior (price per call, first 25 free, failed calls free) and explicitly explains the unusual annotation state ('not marked read-only because each call is charged'), which reconciles readOnlyHint=false with a non-destructive compute operation. That is real context beyond what the annotations convey.

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

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

Purpose and output format are front-loaded, and the example is compact. The pricing/credits sentence is slightly tangential but still earns its place by justifying the annotation and setting cost expectations.

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 results and does so ('each line marked as unchanged, removed or added, with counts'). Inputs, use case, cost, and safety profile are all covered, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the inline example (a=one\ntwo\nthree, b=one\n2\nthree\nfour) concretely demonstrates that the inputs are multiline strings and how they pair up. That adds meaning beyond the terse 'original text'/'new text' schema descriptions.

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

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

The description gives a specific verb and resource ('Line-by-line difference between two texts') and even specifies the output shape ('each line marked as unchanged, removed or added, with counts'). This is clearly distinguishable from siblings like text_stats or text_extract, which measure or extract rather than compare.

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

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

It states a clear use context ('see what changed between two versions of a document, config or prompt'), which tells the agent when this tool applies. However, it names no alternative tools and gives no when-not-to-use condition, so it stops short of full routing guidance.

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

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

Goes well beyond the annotations: it explains that the tool reads/computes only yet is deliberately not marked read-only because each call is charged, which resolves the apparent readOnlyHint=false signal. It also discloses billing mechanics ($0.003/call via x402 USDC or card key), a free tier (first 25 free) and that failed calls are free — exactly the operational context an agent needs before invoking.

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

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

Front-loaded with purpose, extraction targets, use case and example before the commercial details, and every sentence is relevant. The pricing/free-tier sentence is longer than strictly necessary but is legitimately operative information for the caller.

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

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

With no output schema, the description carries the return-value burden and does indicate the shape indirectly ("each list de-duplicated"), implying per-category lists. It stops short of naming the result keys or ordering, but for a single-input utility tool it is nearly 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?

With a single required parameter and 100% schema coverage, the schema already names `text`; the description's contribution is the inline example showing the kind of free-form content expected (mixed emails, URLs, hashtags, mentions, phone formats, currency). That adds real meaning to an otherwise 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 specific verb (Find) plus an enumerated set of extracted entity types (emails, URLs, phone-like strings, hashtags, @mentions, numbers), with de-duplication stated. This clearly separates it from adjacent siblings such as text_stats, url_parse and html_to_text without needing to name them.

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

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

"Use to pull contacts and links out of scraped pages or messages" gives a concrete when-to-use context, and the worked example shows the expected input shape. It lacks explicit when-not guidance or named alternatives (e.g. url_parse for structured parsing), so it falls short of a 5.

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

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

With annotations present, the description goes well beyond them: it discloses pricing ($0.003/call via x402 USDC or card key), a free tier (first 25 free), that failed calls are free, and explicitly justifies why readOnlyHint=false despite the tool being compute-only (each call is charged). This is exactly the kind of non-obvious behavioral context annotations cannot express.

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

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

Front-loaded with the operations, then usage, example, and pricing. Every sentence carries information, though the density of commercial detail makes it slightly heavy for a one-parameter tool.

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

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

With no output schema, the description usefully enumerates the metrics returned (counts, timings, Flesch score, grade level), covering the return payload conceptually. It does not describe the response shape, but nothing needed to invoke 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?

There is a single parameter with 100% schema coverage, so the schema already documents it (albeit thinly, as "The text"). The description adds a concrete example value but no format or size constraints, so baseline 3 applies.

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

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

The description states specific verbs and resources: count characters/words/sentences/paragraphs, estimate reading and speaking time, and compute Flesch reading-ease and grade level. That scope is unmistakably distinct from siblings like text_diff, text_extract, and case, which an agent can rule out 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 check the length and readability of a draft" gives a clear context for selection. It does not name alternatives or state when-not to use it (e.g., vs. text_extract for content analysis), 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?

The description directly resolves the counterintuitive readOnlyHint=false annotation by explaining that reads/computes are not marked read-only because each call is charged. It further discloses pricing, a free tier, and that failed calls are free — genuinely useful behavioral context beyond the structured fields.

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

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

Front-loaded with the conversion domain and example units, followed by usage, an example, and pricing. Dense but every sentence is relevant; the pricing sentence is the longest but conveys actionable cost/free-tier 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 low-complexity 3-param conversion tool with no output schema, the description covers domain, usage, example, and cost behavior adequately. It does not describe the return format, but the operation's single-value result is broadly implied.

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 value by listing concrete unit tokens (km, mi, lb, kg, gib, kwh) for params that have no enums, plus a filled-in example. This meaningfully supplements the terse schema descriptions like "Unit to convert to".

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 between units) and enumerates the supported categories and example units (km, mi, lb, ml, mph, gib, psi). No sibling tool performs unit conversion, so there is no risk of confusion with the rest of the toolkit.

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 context for reaching for this tool, and the worked example (value=10, from=km, to=mi) shows the intended call shape. There are no alternative conversion siblings, so the absence of explicit exclusions is not a real gap.

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

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

Explicitly reconciles the unusual readOnlyHint=false annotation, explaining it is 'not marked read-only because each call is charged' — exactly the behavioral disclosure an agent needs. Also discloses pricing, free tier, failed-call policy, and the no-input default behavior.

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

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

Front-loaded with the core conversion behavior, then usage, example, and pricing. The pricing/payment tail is longer than strictly needed but is relevant to the unusual readOnly annotation, so it earns its place.

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

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

Complete for a single-parameter converter: covers both directions, the no-input case, and output forms. No output schema exists, but return formats are described in prose, so nothing essential 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 unit-detection semantics (seconds vs milliseconds auto-detected), the default-now behavior, and a concrete example value, going beyond the schema's terse 'Unix seconds/milliseconds or an ISO date'.

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 bidirectional verb+resource: convert a Unix timestamp to ISO or an ISO date to a timestamp, with units auto-detected. An agent can tell exactly what this does and that it works in both directions.

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

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

Gives one context ('use to read timestamps in logs and APIs') but names no alternatives among the many sibling date tools (date_info, date_add, date_diff). The when-to-use is implied rather than contrasted against 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?

With annotations present, the description goes beyond them by disclosing the pricing model, auth path (x402 USDC / card key), free-tier and failed-call policy, and explicitly explains the non-obvious readOnlyHint=false annotation ('each call is charged'). That is real added context, though idempotency/openWorld behavior is left unaddressed.

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

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

Front-loads purpose and the plus semantics, then example, then billing. Every sentence carries information, though the pricing detail is slightly verbose for a one-line utility.

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-param utility with no output schema, the description covers purpose, parameter interaction, example, and cost/auth context. Return value is not described, but for a decode tool the output is obvious from the purpose.

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 the form-encoding semantic ('+ as a space when plus=true') and a concrete example (text=a%20b%26c, plus=false) that clarifies how the two params combine.

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

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

States a specific verb+resource ('Decode percent-encoded text') and immediately names the plus/space variant, which cleanly separates it from the sibling url_encode. An agent can identify the operation without reading the schema.

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

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

Gives a clear use context ('Use to read encoded links and form data') plus a concrete worked example, so the agent knows when to reach for it. It stops short of naming url_encode as the inverse alternative or stating exclusions, keeping it below a 5.

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

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

Goes well beyond the annotations by disclosing the payment model ($0.003/call via x402 USDC or card key, first 25 free, failed calls free) and explicitly reconciling the readOnlyHint=false annotation (compute-only, but not marked read-only because each call is charged). This is exactly the kind of non-obvious behavior an agent needs.

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

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

Purpose is front-loaded in the first clause, and each subsequent sentence adds distinct information (modes, trigger context, pricing, read-only rationale). The mid-sentence example is slightly awkward, keeping it from a 5.

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

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

For a one-parameter compute tool with annotations covering the safety profile, the description covers purpose, payment, and the read-only caveat. The only minor gap is that the return value (the encoded string) is not stated, but with no output schema and such a trivial result this is nearly negligible.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents "text." The inline example (text=a b&c=d/é) hints at input shape but is not formal syntax or format guidance beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb (percent-encode) and resource (text for URLs), and distinguishes the two modes: encodeURIComponent for query values vs encodeURI for full URLs. This lets an agent tell what it does apart from siblings like url_decode and url_parse without opening schemas.

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

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

Gives explicit context: "Use when building query strings," plus the two supported output modes. It does not name url_decode as the inverse alternative or exclude any scenarios, so it is clear but lacks the exclusions/alternatives that would earn 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?

Goes well beyond the annotations by disclosing pricing ($0.003/call), the payment paths (x402 USDC or card key), the first-25-free allowance, and that failed calls are not charged. It also pre-empts the most confusing annotation by explaining that readOnlyHint=false is due to per-call billing rather than any mutation, which is exactly the kind of context an agent needs.

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

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

Front-loaded with the operation, then usage, then an example, then billing. Every sentence earns its place, though the pricing clause is dense and could be tightened slightly without losing meaning.

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

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

There is no output schema, yet the description effectively enumerates the return fields and calls out the boolean IP-detection result, so an agent knows exactly what it will receive. Billing behavior and error-cost behavior are also covered, leaving nothing material unspecified for a single-parameter tool.

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

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

Schema description coverage is 100% for the single 'url' parameter, so the schema already carries the semantics and the baseline is 3. The description's inline example (url=https://example.com:8080/a/b?x=1&y=2#top) adds mild value by showing an accepted format, but no additional constraints or edge cases.

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/parse) and enumerates the exact output parts: protocol, host, port, path, query object, hash, origin, plus an IP check. It is immediately distinguishable from url_encode/url_decode siblings, which transform rather than decompose a URL.

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 clear usage context, and the worked example removes ambiguity about input format. It stops short of naming alternatives or stating when not to use it (e.g., for encoding/decoding, use url_encode/url_decode).

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

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

Goes well beyond the annotations by disclosing pricing ($0.003/call via x402 USDC or card key), a free tier of 25, that failed calls are free, and explains the non-obvious readOnlyHint=false (each call is charged). The crypto-source detail is useful behavioral context.

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

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

Front-loaded with purpose and range before use cases, example, and billing. Four sentences with little waste, though the pricing sentence is long and could be tightened.

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

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

For a single-parameter generator with no output schema, the description covers purpose, range, entropy guarantee, use cases, and cost model — everything an agent needs to call it correctly.

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

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

Schema coverage is 100% and the schema already documents the count range and default, so the description's restatement of '1 to 100' and 'count=3' example add only marginal value. Baseline 3 is appropriate when 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+resource ('Generate ... version-4 UUIDs'), the exact range (1-100), and the entropy source (cryptographic random). An agent can immediately distinguish this from random_number, random_password, and other randomness 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?

Gives concrete use cases ('IDs, idempotency keys and test data') and a worked example, which is enough context to select it correctly. It does not explicitly name alternatives or exclusions, 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?

Goes well beyond the annotations by justifying the readOnlyHint=false flag ('Reads or computes only; not marked read-only because each call is charged') and by disclosing cost ($0.003/call), payment paths (x402 USDC or card key), the first-25-free allowance, and that failed calls are free. This is exactly the kind of billing/failure context an agent needs before invoking a paid tool.

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

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

Front-loaded with the core validation behavior, and the usage/pricing detail follows in a compact form. The pricing clause is dense but relevant; a couple of sentences pack multiple facts, keeping it readable overall.

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

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

With one required parameter, no output schema, and pricing sensitivity, the description covers what is validated, an input example, when to use it, the output formatting, and the billing/failure rules. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already states spaces are allowed, so the baseline is 3; the description adds a concrete example value ('iban=SE45 5000 0000 0583 9825 7466') that demonstrates the accepted spaced format, a modest but real increment.

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/validate) plus the resource (IBAN) and enumerates exactly what is verified: format, country-specific length, and mod-97 check digits. It also discloses the return transformation (grouped in fours), so it is distinguishable from other validators like validate_isbn or validate_luhn.

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 situation to use it: 'before saving bank details or paying out.' That is clear context, though it gives no when-not guidance or explicit pointer to the sibling validators.

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

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

Goes well beyond the annotations: it discloses per-call pricing ($0.003), the free tier (first 25 free), that failed calls are free, and explicitly reconciles the counterintuitive readOnlyHint=false by explaining the charge-based reason. This is exactly the kind of context annotations cannot convey.

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

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

Purpose and formatting rules are front-loaded, followed by usage, example, and billing. Every sentence carries information, though the pricing clause is dense; overall efficient for the amount of needed disclosure.

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

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

With no output schema, the description should carry the return burden; it implies a check result and ISBN-10→13 conversion but never specifies the response shape (boolean vs. converted string vs. error). Strong on input, billing, and safety context, but the return contract 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 parameter is the only input, so the schema baseline is 3. The description adds real value by stating that hyphens and spaces are ignored and providing a concrete example (isbn=0-306-40615-2), clarifying accepted input formats beyond the schema's bare 'The ISBN'.

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

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

States a specific verb and resource: 'Check an ISBN-10 or ISBN-13 check digit and convert valid ISBN-10s to ISBN-13.' The ISBN resource name inherently separates it from validate_iban and validate_luhn, so an agent can route to it without opening any schema.

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

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

'Use before cataloguing or ordering books' gives a concrete usage context, which is more than most validators offer. It does not name explicit alternatives or exclusions, but the resource-specific framing makes the boundary with sibling validators self-evident.

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?

Explicitly reconciles the non-read-only annotation with behavior: 'Reads or computes only; not marked read-only because each call is charged.' It also discloses pricing, the free-tier limit, and that failed calls are free, all of which are behavioral facts not derivable from annotations or schema.

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

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

Front-loads the core purpose and scope before the operational details. Slightly dense with pricing/billing sentences, but each earns its place for a paid, non-read-only tool.

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

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

With no output schema, the description conveys both outputs (pass/fail result and the check digit to append), which covers the return contract adequately. It does not spell out exact field names or error behavior for malformed input, leaving a small 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% and the schema already documents allowed characters ('Digits, spaces and hyphens allowed'). The description reinforces this with a concrete example value (79927398713), adding a small amount of confirmation beyond the schema but no new format rules.

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 (Luhn/mod-10 check plus check-digit computation) and names the domains it applies to (card numbers, IMEI, IDs). This clearly separates it from sibling validators like validate_iban and validate_isbn, which cover different algorithms.

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 catch typos in card or ID numbers') and a worked example input, plus the constraint 'Only the format is checked; nothing is looked up,' which tells the agent this is not a lookup/verification service. It never names an alternative tool explicitly, so it stops short of a routing statement.

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

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

Goes well beyond the annotations by disclosing pricing ($0.003/call), payment paths (x402 USDC or card key at /credits), a free tier, and free failed calls, plus an explicit justification for readOnlyHint=false. This is exactly the kind of behavioral context annotations can't carry.

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

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

Front-loads the core function before the commercial details in three tight sentences. The billing/annotation-rationale sentence is longer than strictly necessary for selection but earns its place by explaining the non-read-only flag.

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-param, no-output-schema tool, everything an agent needs is present: what it returns, the randomness guarantee, when to use it, and full cost/auth behavior. Nothing material is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter meaning to add or omit.

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 (random yes/no) and the source (cryptographic random), and scopes it to tie-breaking decisions. It doesn't explicitly distinguish itself from close siblings like coin or magic_8_ball, but the 'equal options' framing is enough to separate it from advice-generating 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?

Gives clear usage context ('quick decisions when the options are equally good', 'break ties'). It does not name alternatives (coin, magic_8_ball) or state when not to use it, so it stops short of full routing guidance.

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