UK Data: Utilities

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds two things annotations cannot: the per-call credit cost and the fact that the response includes a freshly generated UUID. The UUID detail arguably sits in tension with idempotentHint=true since output varies per call, but that is an output-determinism nuance rather than a claim of side effects, so it does not rise to a contradiction.

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

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

Two compact clauses with zero waste; the operation is front-loaded and the cost disclosure is parenthetically separated so it does not obscure the core purpose.

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

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

For a two-parameter, no-output-schema utility, the description covers purpose, cost, and the shape of the returned value (hash plus UUID), which is exactly the information an agent cannot get from the input schema. The only gap is the absence of any default or guidance for the optional 'algorithm' parameter.

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 'text' and 'algorithm' including the SHA variant list. The description only implies that a text input exists and adds nothing about algorithm selection or defaults, which is the correct baseline when the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('SHA hash of text') and additionally discloses a non-obvious output component ('plus a fresh UUID'). It is unambiguous about what the tool does, though it never mentions a sibling tool or contrasts itself with utilities like text_stats.

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

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

There is no guidance on when to use this versus alternatives, no preconditions, and no exclusions. The only supplementary information is a cost note, which is pricing rather than usage 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so an agent knows this is a safe, repeatable, non-mutating operation. The description adds a genuinely useful billing detail (cost: 1 credit) but says nothing about what is returned or whether a timezone-less input falls back to a default.

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?

One short sentence plus a parenthetical cost note, front-loaded with the action and resource. Nothing is wasteful, though the brevity comes partly from omitting information rather than from tight editing.

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 six parameters and no output schema, the description should explain the returned artifact (ICS text, download URL, or file), yet it is silent on return values. For a builder/generator tool this is a meaningful gap that the annotations cannot fill.

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

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

Schema description coverage is 100%, so all six parameters carry some documentation there, which sets the baseline at 3. The description adds no meaning beyond the schema and does not clarify format expectations such as the ISO datetime layout, IANA timezone examples, or the relationship between start and end.

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?

"Build an .ics calendar event" gives a specific verb and resource (an iCalendar payload), which is clearly distinct from the sibling utility tools such as hash_text, json_validate, and qr_code. It stops short of saying whether the result is a returned ICS string or a stored file, which leaves a small ambiguity about the artifact produced.

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

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

The description offers no when-to-use guidance, no prerequisites, and no alternatives; the only extra context is a cost note. An agent must infer the use case entirely from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld. The description adds genuinely useful context beyond that: the supported validation keyword subset and a 1-credit cost. However, it never says what the call returns (boolean vs. error list) despite there being no output schema, which is the key behavioral fact for a validator.

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

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

A single front-loaded sentence naming the action, the supported keyword scope, and the cost. No filler, no repetition of annotation-declared traits.

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 nesting and no output schema, the description covers inputs and scope adequately, and annotations cover safety. The missing piece is the result shape — an agent cannot tell whether it receives a pass/fail boolean or a list of validation errors, which is central to using a validator 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 would be 3, but the schema's own parameter notes are thin and inconsistent — both params are typed as string while described as 'string or object' and 'object'. The description compensates by making clear that the first param is JSON to be parsed and the second is a JSON Schema defining the validation 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 pair of verbs (parse, validate) and the resource (JSON against a JSON Schema), and enumerates the supported keyword set. It does not explicitly distinguish itself from siblings, but the sibling list (hash_text, qr_code, ssl_check, etc.) makes collisions unlikely, so a 4 is fair.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The parenthetical keyword list ('simple JSON Schema (type, required, properties, items, enum, min/max, pattern)') implicitly signals a scope limit — no $ref, allOf, or format keywords — but the agent must infer that this is the boundary.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered by structured data. The description contributes the non-obvious billing detail (cost: 1 credit) and confirms the return is an image URL, but says nothing about output lifetime, hosting, or what happens with oversized text.

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 compact, front-loaded sentences with no filler. The parenthetical cost note is efficiently packed rather than given its own sentence.

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

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

With no output schema, the description does tell the agent a URL comes back, and parameters are fully documented in the schema. However, for a generation tool it omits what 'size' controls (rendered pixel dimensions) and whether the URL is ephemeral, leaving a real practical 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 description coverage is 100%, so the schema already documents both 'size' (number 64-1024) and 'text'. The description adds only that arbitrary text or links are accepted, which is marginal beyond the schema 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?

The description states the resource produced (a QR code image URL) and the accepted input (any text or link), which distinguishes it from siblings like hash_text or text_stats. It stops short of an explicit verb such as 'generate', but an agent can still infer the purpose immediately.

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

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

There is no guidance about when to use this tool versus alternatives, nor any prerequisites or exclusions. The only contextual hint is the credit cost, which is about pricing rather than selection.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds information the annotations do not: a per-call cost of 1 credit, plus the shape of the result payload (registrar, dates, status, nameservers) in the absence of an output schema. It doesn't cover behavior for unregistered or invalid domains, which keeps it from a 5.

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

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

One front-loaded sentence plus a parenthetical cost note, with zero filler. The returned-field list and the credit cost are the two highest-value facts and both appear immediately.

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, read-only lookup with rich annotations, the description covers purpose, output fields and cost. The only real gap is edge-case behavior (nonexistent domains, malformed input) and rate/credit limits beyond the per-call price.

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 text ('string, required') is uninformative, so the description carries the real semantic load by establishing that the parameter is a domain name looked up via RDAP. It adds no format guidance (TLD handling, IDN, subdomain behavior), so baseline 3 is appropriate.

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

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

The description names a specific resource and protocol ('Domain registration data via RDAP') and enumerates the fields returned (registrar, dates, status, nameservers), so an agent knows exactly what this produces. It doesn't explicitly contrast itself with the nearest sibling, ssl_check, but the resource is distinct enough that confusion is unlikely.

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

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

Usage is implied rather than stated: an agent can infer it should call this to get WHOIS-style registration facts for a domain. There is no explicit when-to-use guidance, no mention of when not to use it, and no pointer to ssl_check or other siblings for related domain queries.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds genuinely new information beyond that: a per-call cost of 1 credit and the shape of the returned data (status, server, HSTS headers), which matters since there is no output schema. It does not say what is returned for a failed/non-HTTPS domain, 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?

One compact sentence plus a parenthetical cost note, with the core purpose front-loaded and zero filler. The phrasing is a noun fragment ('Whether a domain answers...') rather than a direct verb, which slightly weakens immediacy but does not waste space.

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 read tool with no output schema, the description covers purpose, returned fields, and cost, which is enough to call it correctly. It omits edge-case behavior such as non-HTTPS responses, redirects, or timeouts.

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

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

With a single parameter and full schema coverage, the schema is the primary reference, so a 3 baseline applies. The description does confirm the parameter is a domain name and implies the check target, but adds no format or validation guidance beyond that.

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 action and resource: checking whether a domain answers over HTTPS, and names the returned data (status, server, HSTS headers). This clearly separates it from siblings like rdap_lookup or unshorten, though it never explicitly contrasts with 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?

There is no guidance on when to use this versus alternatives, nor any prerequisites or exclusions. The only contextual hint is the credit cost, which is a budget note rather than a use-case rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, so the safety profile is covered; the description adds genuine value by disclosing a per-call cost of 1 credit, which is not in any structured field. It says nothing further about output shape, limits on text size, or language handling, so it stops short of rich behavioral context.

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

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

A single compact fragment that front-loads the metrics and appends the cost in parentheses, with no filler. It is telegraphic rather than a full sentence, but every token carries information.

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

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

For a one-parameter, no-output-schema tool, the description effectively doubles as an output summary by listing the metrics returned, which compensates for the absent output schema. What is missing is modest: no usage context and no input constraints, but annotations carry the safety profile.

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 only a single required-by-semantics 'text' parameter, so baseline is 3. The description adds no meaning about the text parameter itself (size limits, expected language, plain vs. markup) beyond what the schema states.

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

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

The description enumerates the concrete outputs (word/sentence/paragraph counts, reading time, Flesch reading ease, top words), which makes the tool's function unambiguous even though it uses a noun phrase rather than an explicit verb+resource. It does not need sibling differentiation here, since hash_text and the other siblings are clearly unrelated 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?

There is no when-to-use or when-not-to-use guidance, no mention of alternatives, and no prerequisites or input constraints. The agent must infer that this is a pure computation tool to be called on arbitrary text.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact not in structured fields: the cost of 1 credit per call. It does not disclose failure behavior (invalid URL, redirect loops, non-redirecting URLs) or whether intermediate hops are returned.

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 short clauses with the action front-loaded and the cost note parenthetically appended. Nothing is redundant and nothing could be trimmed without losing 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?

For a single-parameter, non-destructive read tool with rich annotations and no output schema, this is close to sufficient. The remaining small gap is that it never says what comes back (final URL string, redirect chain) or how errors surface, but the annotations and trivial schema carry most of that burden.

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 exists and schema description coverage is reported at 100%, so the baseline is 3. The description adds the implicit constraint that the url should be one that redirects, but gives no format, protocol, or length guidance beyond what the schema shows.

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 effect: 'Follow redirects to the final URL.' An agent immediately knows this resolves a shortened/redirecting link to its destination, and the siblings (hash_text, ical_event, qr_code, etc.) are unrelated utilities so no disambiguation is needed. It stops short of naming the input type (shortened URL) explicitly, which keeps it from a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. Usage is only implied by the tool name 'unshorten' and the phrase 'follow redirects', leaving the agent to infer that the input should be a URL that may redirect rather than any URL.

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