Highland Intel APIs

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

Goes well past the readOnlyHint/openWorldHint annotations: it gives the exact return shapes for both modes, the non-UTF-8 hex fallback, and a pricing model (1 credit = 1 CAD cent per successful call) plus the billing rule that schema-invalid input is rejected before charging. Cost and validation behavior are not derivable from any structured field.

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

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

Three dense sentences: action and scope first, return shapes second, cost/validation last. The middot-delimited return-shape notation packs two result structures into one line 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?

With no output schema, the description takes on the burden of describing returns and does so explicitly for both modes, including the null fields on decode. Cost and rejection-before-billing round out what an agent needs to call this confidently and cheaply.

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 parameter descriptions already carry the semantics and the baseline is 3. The prose restates variant as 'standard or url-safe' and mentions the hex decode path, but adds no format or constraint detail not already present in the schema — notably it never mentions the 48,000-character input cap.

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 — encodes UTF-8 text to standard or url-safe base64, or decodes either form — and adds the edge case that non-UTF-8 binary results are returned as hex. That detail separates it from siblings like hash or text-stats that also take text input.

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

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

The two modes and their accepted input forms are spelled out clearly, so an agent knows what each call path does. It stops short of naming exclusions or a sibling alternative (e.g., when to reach for hash instead), so there is no explicit when-not guidance.

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

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

Annotations already cover the safety profile (readOnlyHint true, openWorldHint false), and the description goes further by disclosing the billing model (1 credit per successful call), the fact that schema-invalid input is rejected before billing, and the exact return shape including what `range` contains when there is no match. That is meaningful operational context an agent cannot get from the structured fields.

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

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

Three sentences, front-loaded with purpose, then output shape, then pricing/validation. No filler, and the cost note is placed last where it belongs rather than crowding the purpose statement.

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 every returned field (ip, version, cloudflare, range, rangesAsOf) and the null case. Combined with one fully-described parameter and clear annotations, nothing an agent needs in order to call or interpret this 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 description coverage is 100% and the single `ip` parameter is fully documented in-schema, including the prohibition on ports and zone ids. The description only restates that it accepts IPv4 or IPv6, adding no format or edge-case detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource — determining whether an IP falls inside Cloudflare's published edge ranges — and adds the scope detail of naming the matching CIDR. This is clearly distinguishable from siblings like dns-lookup, rdap-lookup, and uptime-check without opening any schema.

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

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

The use case is implied clearly by the description, but there is no explicit when-to-use guidance, no named alternative, and no statement of what this tool is not for (e.g. vs. dns-lookup or rdap-lookup when you want ownership rather than range membership). An agent can infer the case but is given no routing rules.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing the full return shape, deterministic SHA-256 ids, the billing model (2 credits per successful call), and the key guarantee that schema-invalid input is rejected before billing. That billing-before-validation detail is exactly the kind of behavior an agent cannot get from structured fields.

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

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

Front-loads the capability, then gives a compact return-shape and pricing statement with zero filler. Slightly dense in the second sentence, but every clause carries information.

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

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

For a 5-parameter, no-output-schema tool, the description covers the output object, determinism, cost, and validation behavior. An agent has everything needed to call it and anticipate 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% and the schema already explains modes, size range, tokenizer families, and the 'overlap under half of size' constraint. The description restates the mode options and overlap but adds no format or interaction detail the schema lacks, so baseline 3 applies.

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

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

States a specific verb plus resource ('Splits text for retrieval') and enumerates the three strategies (tokens, sentences, markdown headings) along with overlap and stable SHA-256 ids. This clearly separates it from counting tools like token-count or text-stats, which measure rather than segment.

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

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

The phrase 'for retrieval' implies the RAG use case, but the description never says when to pick this over siblings such as token-count, dataset-split, or page-markdown, nor does it state exclusions. Usage is inferable but not 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 past the annotations by disclosing the return shape ({ label, labels }), the null-on-no-match behavior, the exact price (3 credits per successful call with a CAD cent conversion), and that schema-invalid input is rejected before billing. That billing-failure semantics is exactly the kind of operational detail an agent cannot infer elsewhere.

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

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

Three tight sentences, front-loaded with the action and constraint, then the return contract, then cost. No filler and nothing restated twice.

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 spends words defining the response shape and the null case. Pricing and pre-billing rejection complete the picture for a metered, read-only tool with only two fully documented parameters.

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 fully documented, and the description repeats the 2-20 / 1-40 bounds rather than adding to them. The one genuinely additive point is that the result is always one of the supplied labels or null, which is a return-value semantic more than a parameter one — baseline 3 applies.

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

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

States a precise verb and outcome: 'Picks one label from your list ... for a piece of text'. The phrase 'from your list' plus the 2-20 constraint clearly separates it from fixed-taxonomy siblings like sentiment or free-form extraction like entity-extract.

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

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

Usage is implied by 'picks ONE label from your list', which implies closed-set single-label classification, but the description never says when to prefer this over sentiment, entity-extract or similarity, nor when not to use it. It supplies hard boundaries (2-20 labels) rather than selection guidance.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond by disclosing the return shape (ok, stats, findings with severity levels and codes, counts), clarifying that 'path' values are line numbers, and stating the billing model (2 credits per successful call, no charge for schema-rejected input). That billing and failure-cost detail is behavior an agent cannot get from structured fields.

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

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

Front-loaded with purpose, then return shape, then billing; every sentence carries information. The inline object notation for the return value is dense but readable; a slightly cleaner enumeration would be ideal, so not 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?

Despite having no output schema, the description fully specifies the return payload, severity taxonomy, the line-number semantics of 'path', and the cost model. For a single-parameter read-only lint tool, nothing an agent needs to call it correctly or interpret results 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 description coverage is 100%, with the schema itself documenting the 60,000-character limit and required 'text'. The description adds no syntactic guidance about the input text beyond restating what gets checked, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Lints a CLAUDE.md') and enumerates the exact check categories (size, structure, @imports, leaked secrets/passwords/emails). This clearly distinguishes it from sibling linters like prompt-lint, openapi-lint, and mcp-config-validate, which target different artifacts.

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

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

The usage context is clear: you pass CLAUDE.md text and get lint findings back, and the description notes invalid input is rejected before billing, which tells the agent to conform to the schema first. It stops short of naming alternatives or stating when not to use it (e.g., for other markdown files), so it does not reach a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful non-schema behavior: per-call pricing (4 credits, with a credit-to-CAD conversion) and the billing guarantee that schema-invalid input is rejected before charging. It doesn't mention latency, truncation of long code, or what happens on model failure, which keeps it short of a 5.

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

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

Three tight sentences: purpose and output first, then the return contract, then pricing/billing. Front-loaded and every clause carries information an agent or caller would otherwise have to guess.

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 assumes responsibility for the return contract and discharges it explicitly with a field-by-field shape. Combined with full schema coverage on inputs and annotations covering the safety profile, 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?

Schema description coverage is 100% and both parameters (code with 6,000-char limit, language with auto-detect) are fully documented in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Reviews a code snippet') and enumerates exactly what it returns (bugs, security, performance, style issues with severity and fix). The inline return shape { language, summary, issues[] } makes the scope unambiguous, and no sibling tool in the list competes for this function.

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

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

Usage is only implied — the description makes clear this is for reviewing code, but never states when to choose it over alternatives or any prerequisites/exclusions. Since no sibling tool overlaps with code review, the omission is tolerable but the guidance is thin.

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 (readOnlyHint=true, openWorldHint=false), the description discloses cost (2 credits), that billing only occurs on successful calls, and that schema-invalid input is rejected before billing — material operational facts an agent won't find in structured fields. It does not discuss determinism or quality of the generated message, but the billing and validation semantics are the more important disclosure.

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

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

Two tight sentences, front-loaded with purpose and return shape, then cost. The pricing clause is dense but justified because it affects invocation decisions; no filler sentences.

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 compensates by listing the returned object's fields ({ message, type, scope, subject, body }), and it covers the single input's constraint and cost model. Complete enough to call correctly without opening anything else.

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 already documents itself ('Unified diff (git diff output), up to 7,000 characters'). The description's 'unified diff' phrasing adds nothing beyond that, 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 opens with a precise verb+resource pair ('Turns a unified diff into a Conventional Commits message') and enumerates the produced fields, so an agent knows exactly what comes back. It does not name or differentiate against any sibling (e.g., text-diff, summarize), which caps it below a 5.

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

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

Usage is only implied by the input type ('Turns a unified diff'), with no explicit when-to-use, when-not-to-use, or pointer to alternatives such as text-diff or summarize. An agent can infer the context but gets no routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description adds genuinely new behavioural facts: cost (1 credit = 1 CAD cent per successful call) and the fact that schema-invalid input is rejected before billing. It also lists the exact response keys, which matters since there is no output schema. It stops short of describing failure modes or rounding conventions, so not a 5.

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

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

The core behaviour leads, followed by the return shape and pricing in a compact three-sentence block with no filler. The inline enumeration of seven return keys is slightly dense but earns its place given the absence of an output 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 two-parameter, deterministic, read-only tool this is nearly complete: inputs are covered by the schema, outputs are enumerated in prose, and billing behaviour is stated. The only remaining omission is what happens on edge cases such as identical colours or invalid-but-matching-pattern values.

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 as hex strings with an explicit pattern. The description adds nothing about accepted hex forms (3- vs 6-digit, optional '#') or which colour plays which role beyond 'two colours', so the baseline 3 applies.

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

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

States a specific verb and resource ("Computes the WCAG 2.2 contrast ratio of two colours") and enumerates the outputs it produces (ratio, AA/AAA pass-fail, nearest passing foreground). No sibling tool covers accessibility or colour maths, and the definition makes that scope unambiguous.

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

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

The use case is implied clearly by the purpose, but there is no explicit 'use when' framing, no statement of alternatives, and no guidance on truncating/suggesting versus just checking. With a sibling list that contains no near-equivalent, the omission is low-risk but still a 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?

With only readOnlyHint given, the description carries real behavioral weight: it discloses that the tool performs live outbound requests, rejects private/loopback/link-local/metadata and own hosts, bills 2 credits per successful call, and does not bill schema-invalid input. That is exactly the kind of cost, safety and eligibility 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-loads the behavior in the first sentence, then gives return shape and price compactly. Dense but every clause earns its place; the result-shape literal is slightly heavy but useful given no output 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?

With no output schema, the description supplies the exact return object (url, finalUrl, origin, status, preflight, headers, allowed, issues), plus pricing and refusal behavior. An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, so all five parameters are already well documented, including the preflight triggers. The description restates the preflight rule at a high level but adds no format, default or edge-case meaning beyond the schema, which is the expected baseline.

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

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

States a specific verb and resource: sends a GET with an Origin header (plus an OPTIONS preflight when needed) and reports Access-Control-* headers with an allowed/blocked verdict. This is clearly distinguishable from nearby siblings like header-audit, http-status or curl-to-code 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?

The description makes the usage context clear: it emulates a browser cross-origin call and returns an allowed/blocked verdict, and it explains that non-simple methods, custom headers or credentials trigger a preflight. It does not name when to prefer a sibling such as header-audit or http-status, so no explicit exclusions are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's real contribution is the commercial and failure behavior: 1 credit per successful call, and schema-invalid input is rejected before billing. That is genuinely non-obvious context an agent needs. It doesn't cover error responses for valid-but-unparseable expressions (e.g. an impossible date), which is the one gap.

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

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

Three sentences: purpose first, return shape second, cost/billing last. Nothing is redundant and every sentence carries information an agent can act on.

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

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

For a single-parameter, read-only transform tool, this covers purpose, dialect, output shape, and billing semantics, with annotations handling the safety profile. No output schema exists, yet the description still names the two returned fields, so 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?

Schema coverage is 100% and the single cron parameter is fully documented in-schema, including the five-field ordering and UTC interpretation. The description restates "5-field" and UTC but adds no syntax hints (ranges, steps, lists, macros) beyond what the schema already says, so baseline 3 applies.

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

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

States a specific verb and resource ("Explains a 5-field cron expression in plain English") and pins the dialect with "UTC, as Cloudflare runs it", which separates it from the cron-to-cf sibling that converts rather than explains. The return shape ({ cron, explanation }) is named directly, so the agent knows exactly what comes back.

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

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

Usage is implied by the verb — you call it when you have a cron expression you need in English — but there are no explicit when/when-not statements and no mention of cron-to-cf as the alternative for conversion. The billing and rejection rules give useful context for deciding to call, but not routing guidance 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?

Annotations only declare readOnly and closed-world; the description adds real behavioral context beyond them: per-call pricing in credits, and that schema-invalid input is rejected before billing. It also discloses that nextRuns is capped at 5 and only applies to standard syntax. Missing only error/edge behavior for valid-but-uncommon expressions.

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

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

Front-loaded with the core action, then return shape, then cost. Dense but every clause carries information; the return-object enumeration is slightly list-heavy but earns its place since no output schema exists.

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 spelling out the returned object fields and the limits on nextRuns. Pricing and pre-billing rejection round out what an agent needs. It stops short of describing error-case output content, which is a minor gap for a validator.

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

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

Schema coverage is 100% and the cron parameter's schema description already documents the 5-field UTC format, weekday 1-7/SUN-SAT convention, and L/W/# support. The description adds nothing parameter-level beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource — checks a cron expression against Cloudflare Cron Trigger syntax — and enumerates the additional outputs (explanation, next runs, wrangler snippet). The Cloudflare qualifier distinguishes it from the generic cron-explain sibling.

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

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

The Cloudflare scoping implies when this tool is the right one, but there is no explicit routing instruction naming cron-explain for generic cron explanation or wrangler-lint for snippet linting. Usage is inferable rather than stated.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=false; the description adds real value beyond them by disclosing the billing model (2 credits per successful call) and that schema-invalid input is rejected before billing. It stops short of describing behavior for input that is schema-valid but not a parseable curl command, which is the main remaining ambiguity.

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 first, return shape second, cost/validation caveat last. Nothing is padded and no sentence repeats the schema.

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

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

For a 2-parameter, single-purpose converter with no output schema, the description covers inputs, outputs, and billing consequences, which is everything an agent needs before invoking it. Return-shape detail is given inline precisely because no output schema exists.

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

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

Schema coverage is 100% and both parameters are already documented, including the enum of target languages and the javascript default. The description restates the language list and adds nothing about curl input format, quoting, or multiline handling beyond 'a curl command line'.

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

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

States a specific verb and both sides of the transformation (curl command -> JavaScript fetch, Python requests, Go net/http, PHP), and names the exact return shape. No sibling in the list performs curl conversion, so the tool is unambiguous in the catalog.

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 infers it should call this when it has a curl command and wants equivalent code. There is no explicit when-not guidance or named alternative, though the pricing sentence at least signals that calls should be deliberate.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, yet the description adds substantial context beyond them: system prompts are relocated between the system message and the top-level field, unconvertible rows are skipped and reported rather than aborting, and pricing is 2 credits per successful call with schema-invalid input rejected before billing. That billing and failure-mode disclosure 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?

Three dense sentences, front-loaded with the core action, followed by behavior and then return shape plus pricing. Every sentence earns its place, though the pricing clause is slightly verbose for the value it delivers.

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 supplies the full return contract ({ from, to, converted, skippedCount, skipped: [{ line, reason }], jsonl }), plus the per-row failure semantics. Nothing an agent needs to invoke or interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond by explaining the semantic effect of conversion choices (system prompt migration between representations) and the alpaca single-turn constraint that also appears in the schema. It adds modest but real meaning rather than repeating the schema.

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

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

The description opens with a specific verb and resource ('Converts JSONL') plus the three concrete formats it handles, so an agent can immediately tell this apart from dataset-validate or dataset-split. It also names the directionality ('between'), which is the key scope fact.

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 alpaca caveat ('takes single user/assistant exchanges only') and the note that unconvertible rows are listed imply when this tool is appropriate, but there is no explicit when-to-use vs. dataset-validate/dataset-split routing or stated prerequisites for this 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?

Beyond the readOnly and openWorld annotations, it discloses determinism, the exact return shape, skipped counts, billing cost, and that schema-invalid input is rejected before billing. These are meaningful operational details 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?

The description is front-loaded with the core purpose, followed by reproducibility, return shape, and billing terms. Each sentence carries useful information with no wasted preamble.

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?

Although there is no output schema, the description enumerates the return object keys and split format. Combined with 100% schema coverage and annotations covering safety, the definition is complete enough to call the 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 description coverage is 100%, so parameter semantics are already fully documented in the schema. The description does not add parameter-level meaning beyond what the schema provides, making 3 the appropriate 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 a specific verb and resource: deterministic seeded shuffle and train/val/test split of JSONL rows. It is clearly distinguishable from sibling dataset tools such as dataset-convert and dataset-validate, which do different jobs.

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

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

It gives a clear usage context: reproducible splitting via the same seed and input. It does not explicitly name alternatives or when-not-to-use cases, so it falls short of a 5, but the intended use 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the billing model (2 credits per successful call, 1 credit = 1 CAD cent), that schema-invalid input is rejected before billing, and that the error list is truncated to the first 100 with errorCount/errorsTruncated flags. Those are exactly the operational facts an agent needs before spending credits on a large payload.

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 before the return shape, and every clause carries information. It is a single dense run-on sentence with semicolons and an inline field dump, which is harder to scan than bulleted lines, but no sentence is filler.

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

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

There is no output schema, and the description compensates by spelling out the full return object including error and duplicate shapes plus truncation flags. Minor gaps remain: it does not say what costEstimate contains when pricePerMillionTokens is omitted, nor how duplicates are matched.

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 jsonl limits, epoch bounds, the format enum values, and pricePerMillionTokens are already fully documented in the schema. The description only restates that cost comes 'from your price' and that token estimates are produced; it adds no syntax, unit, or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (checks/validates) and concrete resource (chat, messages, or Alpaca JSONL) and enumerates the exact checks performed: per-line errors, role order, empty turns, duplicates, token estimates, cost estimate. It is clearly distinct from sibling tools like dataset-convert or dataset-split by the enumeration of checks, but never names those siblings or states the boundary 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?

Usage is implied by the enumerated checks and the format enum, and the pricing sentence hints at a paid-call context, but there is no explicit 'use this when X, use dataset-convert when Y' routing. An agent must infer from the name and format list that this is the pre-flight validation step before splitting or converting.

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

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds real information beyond them: the credit price per successful call and the guarantee that schema-invalid input is rejected before billing. It does not say what happens on a valid-but-failing lookup (NXDOMAIN, resolver error) or whether those are billed, which keeps it short of a 5.

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

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

Three tight sentences: what is fetched, what is returned, what it costs. The return shape and the pricing caveat are both front-loaded with no filler.

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

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

With no output schema, the description usefully spells out the response object shape, and it covers billing and rejection behavior for a single-parameter read tool. The only real gap is failure-mode behavior for lookups that resolve to nothing.

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 full schema description coverage, including the private-suffix and IP-literal refusal rules, so the schema carries the semantics. The description only reinforces 'for a domain' without adding format or normalization guidance of its own – 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?

Names the exact resource (A, AAAA, MX, NS, TXT DNS records for a domain) and the transport mechanism (DNS-over-HTTPS), so the agent knows precisely what comes back and how it is fetched. It is clearly distinguishable from near-neighbors like rdap-lookup or mail-auth.

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

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

Usage is only implied by the subject matter; there is no explicit when-to-use statement and no routing to alternatives such as rdap-lookup (registration data) or mail-auth (SPF/DKIM/DMARC). An agent can infer the fit, but must reason about boundaries itself.

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 readOnlyHint/openWorldHint annotations by disclosing cost (3 credits per successful call), that billing only occurs on success, and that schema-invalid input is rejected before billing. It also names the fixed model and dimension count, so the agent knows the output is deterministic in shape.

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

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

Three compact sentences: capability and model first, return shape second, cost/validation third. No filler, and the most decision-relevant facts (limits, price, failure billing) are all surfaced.

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 supplies the return shape ({ model, dimensions, count, vectors: number[][] }). Combined with cost and validation behavior, an agent has everything needed to call this correctly 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?

There is one parameter and schema coverage is 100%, with the schema already documenting '1 to 16 texts, each up to 2000 characters.' The description's batch bound restates the schema rather than adding new meaning such as truncation behavior for over-length 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 ('Embeds'), the exact resource ('1 to 16 short texts'), the fixed model (@cf/baai/bge-base-en-v1.5) and output dimension count. The stated intent ('for search and clustering') also separates it from comparison siblings like similarity and find-similar.

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

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

'for search and clustering' implies the downstream use case, so an agent can infer this is the vector-generation step. However, it never explicitly says when to pick this over siblings such as similarity or find-similar, nor does it state prerequisites or follow-up steps.

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

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

Goes well beyond the readOnly/openWorld annotations: discloses the exact return shape, hard caps (up to 5 signals, 8 sources), cost (14 credits per successful call, with the credit-to-CAD conversion), and the billing rule that schema-invalid input is rejected before charge. That cost and failure-mode context is exactly what an agent needs before spending credits.

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

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

Three tight sentences, front-loaded with purpose and return shape, then cost and rejection behavior. The inline return-type literal earns its space by eliminating the need for an output schema; no filler.

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

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

With one required parameter, no output schema, and only two annotations, the description fills every real gap: return contents, result caps, cost, and pre-billing validation. Nothing an agent needs in order to call this correctly or budget for 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%, and the schema already documents the domain format, length bounds, and the rejection of IP literals and private suffixes. The description reinforces the 'public' constraint but adds no syntax or format detail beyond what the structured field states. Baseline 3 applies since the schema carries the parameter burden.

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

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

States a specific verb+resource (company profile enrichment) and enumerates the returned fields: name, description, industry, signals, sources. It also bounds the scope explicitly with 'Organisations only, never people', which distinguishes it from a generic entity/search tool. An agent can tell instantly what it produces 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?

Provides a clear when-not ('Organisations only, never people') and a required input contract (public domain, IP literals and private suffixes refused). It doesn't route to any named sibling (e.g. enrich-url, web-search, web-extract) for overlapping needs, so the alternative-selection guidance is incomplete.

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

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

Goes well past the readOnly/openWorld annotations: it discloses the exact billing model (12 credits per successful call, 1 credit = 1 CAD cent), that only successful calls are billed, that schema-invalid input is rejected before any charge, and that contact points are filtered to role mailboxes only. These are material traits an agent cannot derive from annotations or schema and that affect whether it should call at all.

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, then the mailbox caveat, then cost — a sensible order with no filler. The inline return-object literal is dense but justified because no output schema exists to carry it.

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 enrichment tool with no output schema, the description covers purpose, return shape, privacy filtering and billing, which is close to complete. The remaining gap is routing context — nothing tells the agent how this differs from enrich-company or web-extract, which matters given the crowded sibling set.

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 'url' parameter is thoroughly documented in the schema itself (pattern, length bounds, refused address classes), so the baseline is 3. The description adds only the qualifier 'public page' and does not, for example, say anything about redirects or what finalUrl implies for the supplied URL.

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 ('Profiles one public page') and enumerates exactly what is extracted (title, summary, entities, topics, sentiment, contact points), so the output domain is unambiguous. It never names or contrasts the closely related siblings (enrich-company, web-extract, page-markdown, sentiment, entity-extract), so an agent cannot rule those out 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?

There is no explicit statement of when to pick this over the many adjacent tools in the pack (enrich-company for companies, web-extract/page-markdown for raw content, sentiment/entity-extract for single-signal extraction). Usage is only inferable from the word 'Profiles', and no exclusions or preconditions (e.g. page must be publicly reachable and size-limited) are given.

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 readOnlyHint/openWorldHint: discloses the 50-entity cap, that results are substrings of the redacted text, that source PII is redacted first, and the billing model including that schema-invalid input is rejected before charging. These are exactly the operational facts an agent needs before calling 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?

Two dense sentences, front-loaded with purpose then return shape then cost. Slightly packed — type list, output shape, caps, and pricing are compressed into very long clauses — but no sentence 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 present, the description fully specifies the return object and counts, plus the caps, redaction behavior, and billing semantics. Nothing material is left for the agent to guess.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine meaning by stating the nine fixed types default to all and that returned spans are verbatim substrings, a semantic constraint not expressible in the schema. It does not restate the 8,000-character limit, which the schema already carries.

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 ('Named entities ... each found verbatim in your text') and enumerates the exact fixed type set, which alone distinguishes it from generic siblings like keywords, classify, or pii-redact. An agent knows precisely what it gets back without opening the schema.

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

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

The phrase 'fixed types' and the enumerated taxonomy imply scope, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative (e.g. pii-redact, keywords, web-extract). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description's added value is the operational detail it supplies: a hard cap of 10 results, an explicit return shape, per-call credit pricing, and the fact that schema-invalid input is rejected before billing. That last point is genuinely useful pre-call information. It stops short of explaining ranking/scoring behavior or any rate limiting.

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 the tool does, then result shape, then cost. Every sentence carries information an agent needs. It is dense but not padded.

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

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

For a read-only, open-world lookup with no output schema, the description covers the return shape, result cap, and cost model, which is most of what an agent needs before calling. The remaining gap is the absence of any sibling disambiguation, which matters given how many adjacent tools exist here.

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%, including the URL safety restrictions and the 1-10 bounds on numResults, so the schema carries the parameter burden. The description only restates the 'up to 10 results' ceiling and the public-URL requirement, adding little beyond structured data. Baseline 3 applies.

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

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

States a concrete operation and resource: pages similar in meaning to a given public URL, with highlights. It is specific enough to act on immediately. It does not, however, distinguish itself from the sibling 'similarity' or 'web-search' tools, so the agent must infer which one to pick.

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

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

Usage is implied by the input constraint (a public URL) and the exclusion of private/internal addresses, but there is no explicit when-to-use guidance or comparison against alternatives such as 'similarity' (pairwise text comparison) or 'web-search'. The agent must infer the boundary itself.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral facts: the exact response shape, the per-call price (1 credit = 1 CAD cent), and that schema-invalid input is rejected before billing. That billing/validation disclosure is real value beyond the annotations.

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

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

Three sentences, each doing work: what is computed, what is returned, and what it costs. The return shape is front-loaded immediately after the purpose, with zero filler.

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

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

With no output schema, the description supplies the return object structure itself ({ algorithm, hex }) plus casing. Combined with the pricing and validation rules, an agent has everything needed to call it correctly and predict the cost.

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%, including the algorithm enum with its default and the 64,000-character limit, so both parameters are fully documented structurally. The description adds nothing beyond the schema about parameter syntax or edge cases (e.g., whether text is normalized). Baseline 3 applies.

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

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

Names a specific verb (computes hex digest), the exact algorithms supported, the input encoding (UTF-8), and the return shape. This clearly separates it from siblings like base64 (encoding) or uuid (identifier generation). It stops short of naming an alternative sibling explicitly, so it lands at 4 rather than 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?

Usage is only implied by the tool's obvious function; there is no explicit 'use this when...' clause and no alternative tool is named for related tasks (e.g., base64 for reversible encoding). The billing note is an operational constraint, not selection 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?

With readOnlyHint and openWorldHint already set, the description adds genuinely useful context: the returned fields, the A/B/C/F grading scheme, the 3-credit cost, and that schema-invalid input is rejected before billing. It does not say whether redirects are followed or whether the front page must serve HTTPS, which are the remaining behavioral unknowns.

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

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

The purpose and scope are front-loaded, followed by the return shape and billing note. Dense but every sentence carries useful information; no filler.

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

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

For a single-parameter read-only tool with no output schema, the description covers purpose, return object, grading, and cost/billing behavior well. Minor gaps remain around redirect handling and what exactly constitutes the 'front page', but nothing critical to correct invocation is missing.

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

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

Schema coverage is 100%, so the domain parameter's constraints (length, IP literal and private suffix rejection) are fully documented in the schema. The description adds only the implicit 'front page of that domain' framing and no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (audit/sends) and resource (security headers on a site's HTTPS front page), plus the exact output shape and grade scale. An agent can distinguish it from siblings like cors-check, https-redirect, and security-txt 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?

The scope (HTTPS front page security headers) implies when it applies, but the description never names alternatives or exclusions, e.g. redirect behavior or non-header checks handled by https-redirect or cors-check. Usage is inferred 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?

With readOnlyHint=true already declaring a safe read operation, the description adds substantial non-obvious behavior: billing of 2 credits per successful call, rejection before billing on schema mismatch, and the exact shape of the validation result. Nothing contradicts 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 description is two compact sentences. The core purpose and validation scope are front-loaded, and the billing and return-shape details follow without padding.

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

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

The tool is simple: one required input and no output schema. The description compensates by naming exactly what gets validated and by describing the return structure (ok, events, hookCount, findings, counts), so an agent has everything needed to invoke and interpret it.

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

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

There is only one parameter, and the schema fully documents it as a JSON string or object up to 60,000 characters. The description adds the useful scope that the input can be a hooks block or a whole settings.json, but does not otherwise elaborate on the parameter beyond the schema's own 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?

The description states a specific verb (validates) and a clearly scoped resource: a Claude Code hooks block or an entire settings.json. It also enumerates the checked dimensions (events, matchers, hook types, timeouts, risky commands), which distinguishes it from validator siblings such as mcp-config-validate or json-validate.

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

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

Usage is implied by the resource named: use this for Claude Code hooks configuration. However, the description does not explicitly say when to choose it over related siblings (e.g. json-validate, mcp-config-validate, claude-md-lint), nor does it state exclusions or prerequisites.

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 exact return shape, the cost model (1 credit = 1 CAD cent per successful call), and the rejection-before-billing guarantee for malformed input. That billing and failure semantics are things an agent genuinely cannot infer from readOnlyHint/openWorldHint.

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

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

Three short sentences, front-loaded with the operation, then the return shape, then the cost/error contract. Nothing is repeated from the schema and nothing is padding.

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

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

With no output schema, the description compensates by spelling out the returned fields, and it covers billing and invalid-input handling. The only gap for a money tool is how rounding is handled on a tax-included split, which is left unstated.

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

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

Schema description coverage is 100%, so amountCents, rate and included are already fully documented, making 3 the baseline. The description echoes the two modes and adds the CRA rate-confirmation nudge, but no syntax or rounding detail beyond the schema.

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

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

States a specific verb and resource (adds NS HST / splits a tax-included total) and covers both operating modes in one clause. No sibling in the list does tax arithmetic, so the agent can route to 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?

"or splits a tax-included total" plus the schema-linked mode selection gives clear context for which behavior applies, and "Confirm the rate with CRA" flags the one real caveat. It stops short of explicit when-not-to-use guidance (e.g. non-NS provinces), so it is a 4 rather than a 5.

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

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

Annotations already establish readOnlyHint and openWorldHint. The description adds real behavioural detail beyond that: it discloses the return fields, states the per-call price and billing model, and notes that schema-invalid input is rejected before billing. That is genuinely useful context for an agent deciding to call it.

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

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

Front-loaded with the core check and well-sized. There is slight redundancy between the opening sentence and the 'HTTP-to-HTTPS redirect and HSTS status' clause, but otherwise 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, the description responsibly enumerates the returned object fields and documents pricing and input-rejection behaviour. For a single-parameter read-only check, this covers what an agent needs, though it could mention failure/timeout behaviour for unreachable domains.

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 domain parameter, including format and refused suffixes, so the schema does the heavy lifting. The description adds nothing about the parameter beyond what the schema already states, making the baseline 3 correct.

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

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

States a specific verb and resource: checks whether plain HTTP redirects to HTTPS and whether HSTS is set. That is concrete and distinguishable from adjacent tools. It does not name siblings it differs from, though the name makes scope clear.

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

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

Usage is implied by the described check but there is no explicit when-to-use guidance or routing against siblings like header-audit, http-status, or cors-check. An agent must infer the selection context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds genuinely new context: the exact return field set, the 1-credit cost per successful call, and the fact that schema-invalid input is rejected before billing. That billing-on-failure rule is exactly the sort of behavioral detail annotations cannot convey. It stops short of covering error responses for unknown codes (the 'known' field is only implicitly explained).

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

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

Two sentences, both front-loaded with the highest-value information: what you get and what it costs. The pricing sentence also encodes the billing exception, so no sentence is filler.

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

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

Although there is no output schema, the description inlines the full return object shape, and the single parameter is fully documented in the schema. Cost, closed-world scope, and input validation behavior are all covered, leaving nothing an agent needs in order 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?

The input schema has 100% description coverage and already constrains code to 100–599, so the schema does the heavy lifting. The description's only added semantic is that 52x Cloudflare codes are in scope, which is a small but real extension beyond the plain range in the schema. Baseline 3 is appropriate.

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

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

The description names the resource (an HTTP status code) and enumerates exactly what is returned: name, meaning, class, retryability and default cacheability. It even scopes the coverage to Cloudflare's 52x codes, so an agent knows this is the right tool for those non-standard codes. No sibling in the list overlaps with this lookup job.

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/when-not-to-use guidance or named alternative, though the purpose is so narrow that usage is strongly implied by the tool name and description. The Cloudflare 52x mention at least signals the breadth of supported inputs, but an agent gets no routing instructions beyond that.

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 readOnlyHint/openWorldHint annotations by disclosing the return shape for each mode ({ invoice } vs { valid }), the billing model (1 credit = 1 CAD cent per successful call), and the failure policy (schema-invalid input is rejected before billing). These are exactly the facts an agent needs before invoking a paid operation.

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

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

Three tight sentences, front-loaded with the core action and output format, followed by return values and then the cost caveat. No filler or redundancy.

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

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

With no output schema, the description fully covers return values for both modes, the cost, and the billing-failure rule. All four parameters are documented at 100% schema coverage, 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 description adds real meaning by showing how prefix, yyyymm, and sequence compose into the output string (including a five-digit zero-padded sequence and an appended check digit) that the schema itself does not state.

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

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

States a specific verb (formats/validates) and resource (invoice number), and spells out the exact output template PREFIX-YYYYMM-NNNNN-C with a Luhn check digit. The dual formatting/validation mode is disambiguated in the first sentence, so an agent knows precisely what it gets.

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?

Clearly indicates the two usage modes and that they are mutually exclusive by mode ('or validates one'), which the schema reinforces with the validate field ignoring the others. There are no close sibling alternatives in the catalog (uuid, hash serve different purposes), so explicit exclusion guidance is not needed.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations without contradicting them: it discloses the exact response envelope, the null-when-absent contract, the per-call price (3 credits = 3 CAD cents), and that schema-invalid input is rejected before billing. That billing-and-rejection behavior is exactly the kind of context an agent cannot get from annotations.

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

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

Two sentences, front-loaded with the operation and its output contract, followed by pricing. No filler, and the cost caveat lands before the agent commits to a 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?

Despite having no output schema, the description fully specifies the return shape ({ data, found, total }), the null semantics, and the billing/rejection model. Combined with a complete input schema, an agent has everything needed to call this correctly and predict the response.

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

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

Schema coverage is 100%, so both parameters (text, fields) are already documented with limits and patterns, and the baseline is 3. The description corroborates but adds no syntax beyond the schema — the 6,000-character cap and the 30-field cap are only in the schema, not restated or explained here.

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 ("pulls the fields you name out of free text") and grounds it with three concrete input examples (emails, invoices, tickets). It doesn't mention the related siblings (entity-extract, web-extract, json-validate), so an agent must infer the division of labor, but the operation itself 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?

The domain (free text → named fields) implies when to use it, and the "strict JSON" framing hints it is the deterministic counterpart to looser extractors. However there is no explicit when-to-use, when-not, or named alternative such as entity-extract; the agent must reason about siblings on its own.

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

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

Annotations cover the read-only and closed-world profile, and the description layers on genuinely useful behaviour: return shape { valid, errors }, a hard cap of 50 error messages, and a billing rule (1 credit per successful call, invalid input rejected before billing). That last point tells the agent failed validations are free, which is non-obvious and actionable.

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

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

Three tight sentences: what it does, what it returns with the error cap, then the cost model. Zero waste and the core operation is front-loaded.

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

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

With no output schema, the description carries the return contract and does so precisely, including the error cap. Billing and the subset limitation round out an adequate picture for a two-parameter validator.

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

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

Schema description coverage is 100%, with both parameters documented, including the enumerated subset of keywords supported. The description only restates that a subset is accepted and adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: validate a JSON value against a JSON-Schema subset, and lists every error path. The operation is clearly distinct from neighbours like json-extract, tool-schema or dataset-validate. It does not name any sibling explicitly, so it stops short of the top mark.

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?

Nothing is said about when to reach for this versus siblings such as tool-schema or dataset-validate, and no prerequisites or exclusions are given. The single-purpose validator name makes the use case strongly implied, which fits a 3 rather than a 2.

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

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

Goes well past the readOnlyHint/openWorldHint annotations by naming the exact warning conditions (alg none, missing/past exp, future nbf/iat, risky headers), declaring that nothing is verified, and disclosing the billing model including that schema-invalid input is rejected before charging.

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 its safety caveat, then the return shape, then billing. Every clause carries information an agent needs; nothing is redundant filler.

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

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

With no output schema, the description supplies the return shape and the semantics of the `verified: false` and `times.expired` fields, plus cost and rejection behavior. For a single-parameter read tool this is complete enough to invoke confidently.

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 carries the token format, length bounds and the 'do not send production tokens you cannot rotate' warning. The description adds no additional parameter-level meaning, which is the expected baseline here.

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 ('decodes a JWT header and payload') and immediately bounds the scope with 'without verifying it', which separates it from verification-oriented siblings like webhook-verify. An agent knows exactly what it gets and what it does not get.

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: the tool is for inspecting tokens whose signatures you are not checking, and it flags risky claims. There is no explicit 'use this when / use X instead' routing against nearby siblings such as base64 (which can also decode a payload) or webhook-verify.

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 readOnlyHint/openWorldHint annotations: it discloses the model-vs-frequency fallback, the exact return shape { keywords, source }, the per-call price of 10 credits with a CAD-cent conversion, and that schema-invalid input is rejected before billing. Those are the billing and reliability facts an agent needs before spending credits.

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

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

Three dense sentences with no filler: the capability and its verbatim guarantee come first, then the return contract, then cost and failure handling. Slightly packed, but every clause carries information.

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

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

With no output schema, the description supplies the return shape and the `source` discriminator, plus pricing and rejection semantics — everything needed to call it and interpret the result. Nothing material is missing for a two-parameter read-only 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 both `max` and `text` are already fully documented in structured fields, including the 8,000-character cap and redaction behavior. The description only echoes 'up to `max` phrases' and adds nothing about format or syntax beyond the schema, so the baseline 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 the resource concretely: key phrases of the input text, and adds the defining property that each phrase appears verbatim in the source. That distinguishes it in spirit from entity-extract or summarize, but no sibling is named explicitly, 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?

No statement of when to prefer this over the many nearby text tools (entity-extract, summarize, text-stats, find-similar). The only conditional guidance is internal behavior of the tool (fallback to frequency ranking), not tool 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 readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely new behavioral context: a 3-credit cost per successful call and that schema-invalid input is rejected before billing — non-obvious commercial semantics an agent should know before calling.

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

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

Two tight sentences: purpose first, then return shape and cost. Nothing is padded, though the inline field list is dense and could be slightly better separated for scanning.

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 returned fields (domain, spf, dmarc, dmarcPolicy, findings, pass) and discloses billing/rejection behavior. Only the meaning of the 'findings' codes and 'pass' semantics remain unexplained, a minor gap for a read-only check.

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 coverage is 100%, with the schema already explaining that IP literals and private suffixes are refused. The description adds no further detail about the domain argument, so it sits at the baseline for fully documented schemas.

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 the specific resource (a domain) and the exact checks performed: SPF and DMARC presence and DMARC policy strength. An agent can tell this is a DNS-record-focused email auth check rather than a generic lookup. It does not, however, name the nearby siblings (dns-lookup, header-audit) it might be confused with.

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

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

Usage is only implied by the subject matter; there is no explicit statement of when to choose this over dns-lookup or security-txt, nor any prerequisites. The billing note hints at cost consideration but not tool 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?

With readOnlyHint=true already covering safety, the description still adds substantial behavioral context: values are never echoed (privacy/secret handling), input failing schema is rejected before billing, and each successful call costs 2 credits. These are non-obvious traits an agent cannot get from annotations.

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

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

Four tightly written sentences, no filler: purpose first, return shape second, privacy guarantee third, billing fourth. Every sentence carries information the agent needs.

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

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

For a single-parameter validator with no output schema, the description fully compensates by describing the return shape ({ ok, servers, findings, counts }), privacy guarantees, and billing behavior. Nothing needed 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?

There is a single parameter with 100% schema coverage, so the schema already explains the JSON-string-or-object form and the 60,000-character limit. The description adds no further parameter semantics, making the baseline 3 appropriate.

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

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

The description names a specific verb and resource — 'Validates a Claude Code .mcp.json' — and enumerates the facets it checks (transports, commands, URLs, headers, env, literal secrets by path). This clearly separates it from generic siblings like json-validate or tool-schema.

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

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

Usage is implied by the 'Claude Code .mcp.json' scoping, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. json-validate for generic JSON). An agent can infer the context but must reason about it.

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

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

Annotations only cover readOnlyHint and openWorldHint; the description goes well beyond by disclosing the return shape ({ data } vs { data: [...], count }), the cost model (1 credit per successful call), and the billing policy that invalid input is rejected before being charged. That billing/rejection contract is precisely the kind of behavior annotations cannot carry.

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

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

Three compact clauses: what it does, what it returns, what it costs. The distinct value ('field-aware values') is front-loaded and the pricing detail is one tight sentence. Slightly dense but 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, the description correctly supplies the return envelope and enumerates the generated value classes. It also covers the failure/billing interaction. Minor gap: it doesn't note the 20-item cap or how deeply nested schema constructs are handled, though the schema covers the cap.

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 baseline is 3. The description contributes modestly by clarifying that the schema parameter describes 'one response item' and, via the stated return shape, that count > 1 yields an array plus count — but the count bounds, default, and types all come from the schema itself.

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 ('Generates realistic sample JSON from a JSON Schema or OpenAPI schema object') plus the distinguishing quality of output ('field-aware values'). No sibling in the list produces mock data, so an agent can identify this tool's niche from the first sentence 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?

Usage is implied by the input type ('from a JSON Schema or OpenAPI schema object'), which tells an agent the context this tool fits. But there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. uuid, dataset-convert for related data-shaping tasks).

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

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

The description itself is unusually informative: 512 KB fetch cap, exact response shape, credit pricing per successful call, and no billing on schema mismatch. However it states the tool fetches arbitrary public web pages, which directly conflicts with the openWorldHint=false annotation; per the rubric that conflict caps this dimension, even though the deeper behavioral detail 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?

Two sentences, front-loaded with the action and the byte cap, followed by a compact return-field list. The field enumeration is dense but earns its place as a stand-in for the absent output schema; there is no filler.

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

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

With no output schema, the description supplies the return shape, the truncation flag and the size limit, which is the right compensation. Gaps remain around redirect/timeout behavior and whether JavaScript is rendered, but an agent has enough to call it correctly.

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

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

A single parameter fully documented in the schema (pattern, length bounds, refusal of private/loopback/metadata hosts), so the schema carries the semantics. The description still adds the cost model and the truncation behavior that the parameter's value controls.

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 states a specific verb and resource ('Fetches a public page ... returns its link-preview metadata') and then enumerates the exact payload, which cleanly separates it from sibling fetchers such as web-scrape, page-markdown, web-extract or web-contents.

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

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

Usage is only implied by the notion of a 'link preview' plus the schema's restriction to public http(s) URLs; no sibling tool is named and there is no explicit when-to-use/when-not framing (e.g. preview metadata vs. full-page extraction).

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 readOnlyHint and openWorldHint annotations, the description discloses the return shape, the billing model, and that schema-invalid input is rejected before billing. This is unusually transparent for a simple read-only lint tool.

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

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

The description is front-loaded with purpose, then covers return shape and pricing, all in a compact paragraph. Every sentence adds useful information, especially the return-shape details since no output schema exists.

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?

Given a simple one-parameter tool with no output schema, the description supplies the missing return structure and billing behavior. Combined with complete schema coverage and clear read-only annotations, an agent has enough context to invoke it correctly.

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

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

There is one required parameter, and schema description coverage is 100%; the schema already explains that the document must be a JSON object, YAML must be converted first, and request bodies are capped at 64 KiB. The description adds little parameter-specific meaning beyond what the schema provides.

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: it checks an OpenAPI 3.0/3.1 document and enumerates the exact checks performed. This clearly distinguishes it from generic validators like json-validate and from other lint tools aimed at different artifact types.

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 intended use is implied by the resource-specific purpose, but the description does not explicitly say when to use this instead of sibling validators or what preconditions apply beyond the schema shape. No alternatives or exclusions are named.

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, so the safety profile is covered; the description goes further by disclosing the exact return shape, the pricing/credit model, that billing only applies to successful calls, and that schema-invalid input is rejected pre-billing. That is real operational context an agent cannot get from structured fields, though error behavior and JS-heavy page handling remain unstated.

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

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

Front-loaded with the purpose before the mechanics, and the pricing caveat is short and useful. There is minor redundancy — "with title, word and link counts" is restated in the field list — but nothing is padded.

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

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

With no output schema, the description correctly compensates by enumerating the return object, including the `truncated` flag that signals max_chars clipping. Coverage of pricing, host restrictions, and output shape makes it callable without guessing; only failure modes and truncation semantics beyond the field name are absent.

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

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

Schema coverage is 100% — both `url` (public http(s), private hosts refused) and `max_chars` (default 20,000, cap 50,000) are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description uses a specific verb and resource ("Fetches a public page and returns clean, LLM-ready Markdown of the main content") and names the return fields, so the job is unambiguous. It stops short of explicitly naming a sibling such as web-scrape or web-extract, 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?

The only scoping signal is implicit — the page must be public, since "Private and internal hosts are refused" (in the schema). There is no statement of when to choose this over web-contents, web-extract, web-scrape, or enrich-url, all of which fetch or transform web pages, and no guidance on when it is inappropriate.

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 only covering readOnly/openWorld, the description adds substantial non-obvious behavior: local deterministic execution with no model, per-kind placeholder conventions, a concrete credit price with unit conversion, and the key billing rule that schema-invalid input is rejected before billing. That last point materially affects agent retry strategy.

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

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

Three tight sentences that front-load what gets redacted, then execution model, then return shape and billing. No filler, and the highest-value constraints (return shape, price, validation-before-billing) are placed where an agent will read them.

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 text tool with no output schema, the description covers the missing return contract explicitly ({ text, counts } with per-kind breakdown), plus cost and failure behavior. Nothing an agent needs to call it correctly or budget for it is absent.

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

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

Schema coverage is 100%, so both parameters are already documented and the baseline is 3. The description confirms IPv4 redaction and names 'ip' among the returned counts, but it does not explain that the `ip` flag can be turned off, so the toggle semantics stay entirely in the schema.

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

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

Specific verb ('strips') plus an enumerated resource list (emails, phone numbers, card numbers, SINs, IPv4s) makes the operation unmistakable. It is clearly distinguishable from neighbors like entity-extract, prompt-inject-scan, or text-stats, which do different work on similar input.

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

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

The description gives useful context for choosing it ('runs locally, no model') and a cost signal, but never states when to use this versus a sibling like entity-extract or prompt-inject-scan, nor any exclusions. Usage is implied rather than routed.

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

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

Annotations already cover the safety profile (readOnlyHint, closed-world), and the description adds genuinely new behavioral facts: the credit cost per successful call and that schema-invalid input is rejected before billing. It does not discuss detection rules, determinism, or latency, so it stops short of a 5.

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

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

Two dense sentences, front-loaded with purpose and the cost term last. The inline JSON return signature is slightly clunky in prose form, but it earns its space because no output schema exists.

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

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

With no output schema, the description correctly compensates by spelling out the return shape (risk, score, hits with rule/weight/match/index) and the billing model. Minor gaps remain around what the risk thresholds mean in practice and which rule families are covered.

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

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

The single parameter is fully documented in the schema (100% coverage), so the baseline is high. The description adds value by giving concrete examples of what counts as 'untrusted text' (web pages, emails, tool output), which the schema's terse 'Untrusted text' does 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 (scans), a specific resource (untrusted text: web pages, emails, tool output), and a specific target (prompt-injection patterns), plus what it returns. It is clearly distinguished from the neighbouring prompt-lint tool, which implies linting prompts you author rather than scanning third-party content.

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

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

The phrase 'before it reaches your agent' gives clear situational context for when to call it. However, it never names an alternative (e.g. prompt-lint) or states when not to use it, so the agent must infer the boundary itself.

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

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

With annotations already declaring readOnlyHint=true and openWorldHint=false, the description adds substantial behavioral context: it is rule-based, makes no model call, never echoes flagged text, reports findings per line, returns a structured result shape, and charges 1 credit per successful call with schema-invalid input rejected before billing. These details go well 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 description is compact and front-loads the main behavior: what it flags, how it runs, privacy, return shape, and billing. It is dense but not wasteful, though the single long sentence structure makes it slightly harder to scan than shorter separated clauses.

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?

Given a single required parameter, complete schema coverage, read-only annotations, no output schema, and no open-world concerns, the description supplies the missing return-value structure, privacy behavior, billing model, and rejection semantics. Nothing critical for correct invocation appears to be missing.

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

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

There is only one parameter, and schema description coverage is 100%, so the schema already documents the prompt input and its 60,000-character limit. The description does not add meaningful parameter-level constraints beyond what is already in the schema.

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

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

The description clearly states a specific verb and resource: it flags prompt-injection phrasing, chat-template tokens, hidden characters, PII and secrets, and lists {{variables}}. This is specific enough for an agent to understand what the tool does, but it does not explicitly differentiate itself from sibling tools such as prompt-inject-scan or pii-redact.

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 — the tool is for checking prompt or template text for safety issues — but the description gives no explicit when-to-use guidance, no when-not-to-use conditions, and no named alternatives for overlapping sibling tools. It provides billing and schema-rejection context, which helps an agent call it, but not selection guidance.

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

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

Annotations (readOnlyHint=true, openWorldHint=false) correctly signal a pure, non-destructive computation, and the description adds substantial context beyond them: the exact return shape, a per-call credit price with the CAD-cent conversion, and the failure-billing rule (schema-invalid input is rejected before billing). That billing edge case is exactly the kind of thing an agent cannot infer from the structured fields.

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

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

Three sentences, front-loaded with the operation, then the return contract, then commercial terms. Nothing is redundant, and the long return-field enumeration earns its length because no output schema exists.

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 fully compensates by listing every returned field. Combined with the billing rule and the 'no customer details' scope note, an agent has everything needed to invoke it correctly and predict what comes back.

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

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

Schema description coverage is 100%, so the schema already explains qty, sku truncation, unitCents, depositPct and discountPct with ranges and defaults. The description restates that a discount and HST are applied but adds no semantics the schema lacks — notably it never states what HST rate is used, though 'rate' appears in the return list.

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 uses concrete verbs (totals, applies, computes) against a concrete resource (line items, discount, HST, deposit) and enumerates the exact output fields. The scope line 'No customer details taken' draws a clear boundary that separates it from an invoicing tool, and the compounding of discount + HST + deposit makes it read as the full calculator vs. the narrower hst-calc sibling.

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

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

Usage is implied by 'totals line items... computes a deposit' — you call it when you need a priced quote. But there is no explicit when-to-use or when-not statement, and the sibling hst-calc (HST-only) is never named as the alternative for a simpler calculation.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds genuinely useful operational context the annotations do not: a per-call price (2 credits, with the CAD-cent conversion) and the fact that schema-invalid input is rejected before billing. It stops short of failure semantics — what happens on an unregistered domain or an RDAP timeout, and whether those calls are billed.

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

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

Front-loaded with the identity of the tool and its data, with pricing last where it belongs. Minor waste: the field list ('registrar, creation and expiry dates, days to expiry, status codes, nameservers and DNSSEC') is then restated almost verbatim in the return-shape 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 supplies the exact return object shape itself ({ domain, registrar, created, updated, expires, days_to_expiry, status, nameservers, dnssec }), plus cost and validation behavior. For a one-parameter read tool, the only material gap left is error/no-data handling, which is marginal.

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% on the single `domain` parameter, including the format example and the refused private-suffix/IP-literal cases, so the schema carries the semantics. The description adds only the cross-cutting note that schema-mismatched input is rejected pre-billing, which is a billing rule rather than added parameter meaning. Baseline 3 applies.

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

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

The description names a concrete verb+resource ('Modern WHOIS over RDAP') and enumerates the exact registration data returned (registrar, creation/expiry dates, status codes, nameservers, DNSSEC). The WHOIS framing implicitly separates it from dns-lookup, but it never names that sibling or any other, so differentiation is left to inference.

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

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

There is no statement of when to choose this over the obvious neighbors (dns-lookup for records, web-search/web-contents for page data), and no exclusions. The only conditional content is billing/validation behavior, which is not usage 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 readOnlyHint/openWorldHint annotations: it discloses the exact return shape (pattern, flags, literal, explanation, tests, passed, total), the compile-and-test behavior, the cost model (3 credits per successful call, 1 credit = 1 CAD cent), and that schema-invalid input is rejected before billing. Pricing and billing-failure semantics are 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?

Two sentences, front-loaded with the core action, followed by the return contract and billing terms. The inline return-object listing is dense but earns its place because no output schema exists.

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

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

For a 3-param generative tool with no output schema, the description supplies the return structure, the testing behavior, and billing/validation rules, while the schema fully covers inputs. Nothing an agent needs before calling 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 all three parameters are already documented in the schema. The description only gestures at the sample-string arrays via 'your sample strings' and does not explain the expected/got comparison or how mismatches are surfaced, so it adds little beyond the structured fields — baseline 3 applies.

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

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

States a specific verb and resource — writes a JavaScript regex from a plain-English description — and adds that it compiles and tests the result. This inherently distinguishes it from the regex-test sibling, which consumes an existing pattern rather than producing one, so an agent need not open either schema to choose.

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

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

The phrase 'tests it against your sample strings' implies the intended workflow (supply should_match/should_not_match to validate), but there is no explicit when-to-use, when-not, or named alternative such as regex-test. Usage is inferable rather than stated.

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

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

Annotations already cover readOnlyHint and openWorldHint. The description adds real value beyond them: capped result sizes (up to 100 matches), the exact return shape {count, matches}, and pricing behavior including that schema-invalid input is rejected before billing. This is useful behavioral context an agent cannot get from 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?

The description is front-loaded with the core action, then the return shape, then pricing. Every sentence carries information and there is no padding. It is slightly dense with two separate concerns (return format and billing) packed together, but overall efficient.

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

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

There is no output schema, but the description compensates by describing the return object shape ({count, matches}, with match/index/groups). Parameters are fully covered by the schema. What remains missing is only marginal, such as error behavior on invalid regex syntax.

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

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

Schema description coverage is 100%, with each parameter (text, pattern, flags) fully documented in the schema, so the baseline is 3. The description adds the result shape and 'matches and groups' phrasing but no new parameter-level syntax or constraint details beyond the schema.

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

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

The description states a specific verb and resource: 'Runs a JavaScript regex over sample text and returns matches and groups.' An agent can tell this is a regex-testing tool. However, it does not distinguish itself from the sibling regex-from-english, so the agent must infer which to use.

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

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

Usage is only implied by 'Runs a JavaScript regex over sample text.' There is no explicit when-to-use, when-not-to-use, or mention of alternatives like regex-from-english. The billing note adds context but not 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 by disclosing the full result shape, the billing model (1 credit per successful call), that schema-invalid input is rejected before billing, and (via the schema) that private/internal hosts are refused. The only tension is that the tool plainly fetches remote sites while openWorldHint is false; the description is the accurate side there, so no misleading of the agent.

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

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

Front-loaded with what it does, then the enumerated return keys, then pricing. Three dense sentences with no filler; the billing sentence is the longest but carries non-obvious information an agent cannot get elsewhere.

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

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

With no output schema, listing robots_url, robots_status, agent, path, allowed, rule, ai_crawlers and sitemaps compensates well. It does not say how missing or unfetchable robots.txt is reported (presumably via robots_status), leaving one small gap for a network-dependent tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a little framing (URL to fetch, agent default) but also refers to a 'path' that is not a parameter — it is apparently derived from the URL and echoed in the output, which could momentarily suggest a third 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?

Specific verb + resource + outcome: reads a site's robots.txt and reports whether a named crawler may fetch a path, including the matching rule, AI crawler access and sitemaps. That is distinct from every sibling (security-txt, http-status, uptime-check) without needing to open the schema.

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

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

The context of use is clear — answering crawl-permission questions for a URL/agent pair — and the agent default (*) is stated. There is no explicit 'use X instead when…' routing or stated exclusion, so it stops short of a 5.

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

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

Annotations cover read-only and open-world access, and the description adds genuinely new behavior: a 2-credit cost per successful call with a CAD-cent conversion, and the guarantee that schema-invalid input is rejected before billing. It stops short of describing failure modes (DNS failure, timeout) or what 'present: false' costs, but the billing semantics are well disclosed.

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

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

The core action and target path are front-loaded in the first clause, followed by the return shape and then billing. Nearly every sentence earns its place; the return-field list is compact, though the two enumerations of fields ('Contact and Expires' then the response keys) slightly overlap.

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

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

No output schema exists, so the description correctly takes on the job of enumerating the response object and explaining each field's meaning. With a single fully-documented parameter and annotations covering safety, the only real gap is error/timeout behavior and whether a missing file is billed.

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 at 100% schema coverage, so the schema already carries the constraint set (length bounds, IP-literal and private-suffix refusal). The description only echoes 'domain' as part of the return object and adds no input interpretation beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb (fetches) and resource (/.well-known/security.txt) plus the RFC 9116 standard, and immediately names the fields reported. It is trivially distinguishable from adjacent siblings such as robots-check, dns-lookup or mail-auth because the target artifact is named explicitly.

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

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

Usage is only implied by the artifact fetched — an agent can infer this is the tool for checking a domain's security.txt, but there is no explicit 'use this when…' or routing away from siblings like robots-check or header-audit. The one explicit rule given is about billing/rejection, not about when to select the 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?

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing billing ('1 credit per successful call'), the rejection-before-billing rule, and the full return key set. Missing only how 'invalid' entries are reported and what distinguishes 'latest' from 'latest_stable' vs the 'from' field.

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

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

Two sentences, front-loaded with the core behavior; the return-shape and billing sentence carries information not available anywhere else. No filler or restatement of the title.

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

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

With no output schema, the description rightly supplies the return keys, and the billing/rejection semantics close the main operational gap for a single-parameter tool. It stops short of defining the ambiguous fields ('latest' vs 'latest_stable', 'from', 'invalid'), which an agent still has to infer.

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

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

Schema description coverage is 100% and already documents the single 'versions' array including the v-prefix allowance, so the description needn't repeat it. 'SemVer 2.0 precedence' adds real semantic grounding about what forms are accepted, but no detail on handling of build metadata or malformed strings.

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

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

Names a specific verb+resource pair ('Sorts versions by SemVer 2.0 precedence') and enumerates exactly what is computed (latest stable, latest pre-release, next major/minor/patch). No sibling in the list does version resolution, so differentiation isn't needed and the definition 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?

Usage is only implied by the operation described; there is no explicit statement of when to reach for this versus, say, json-validate or tool-schema for version-like strings, and no exclusions. Adequate because no sibling competes, but nothing guides the agent's decision.

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

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

Beyond the readOnly and openWorld annotations, the description discloses pricing (10 credits per successful call, 1 credit = 1 CAD cent), billing exclusion for schema-invalid input, the neutral threshold (below 0.6 confidence), and output field meanings. These are material behavioral traits an agent needs before invoking a paid operation.

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

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

The description is dense but front-loaded with the core purpose (labels, score range, classifier). Every clause adds useful information about output shape, threshold, or billing, though the single long sentence could be split for readability.

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

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

With no output schema, the description responsibly explains the return object fields (label, score, positive, negative, chunks) and the neutral threshold. It also covers billing behavior and redaction, making it complete for this single-parameter paid tool.

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

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

Schema coverage is 100%, and the schema already documents the 1–8,000 character limit and PII redaction. The description largely repeats the length limit and adds no new syntax or formatting guidance, 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 capability: it runs a sentiment classifier over text and returns positive/negative/neutral with a -1 to 1 score. This is clear, but it does not explicitly distinguish itself from sibling tools like classify, entity-extract, or summarize that an agent might also consider for text analysis.

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 guidance on when to choose sentiment over siblings such as classify or entity-extract, nor any exclusions or prerequisites. The agent must infer appropriate use from the purpose alone.

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

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

The description is unusually rich on behavior beyond the annotations: it discloses the exact return shape, the 3-credit price per successful call, that schema-invalid input is rejected before billing, and (via the schema) that private/internal hosts are refused. However, it contradicts the openWorldHint=false annotation, since auditing 'a live page' at an arbitrary public http(s) URL is by definition open-world interaction; the annotation should be true.

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

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

Purpose is front-loaded in the first clause, followed by inspection scope, return shape, and pricing in descending priority. The inline return-key list is long but justified because no output schema exists; a slightly tighter phrasing of the pricing clause would earn 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?

With no output schema, the description carries the return contract itself and does so concretely (url, status, score, checks with id/pass/weight). Combined with the cost model and the fail-before-billing rule, an agent has everything needed to decide to call it and to interpret the result; the only gap is the mis-set openWorldHint.

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 at 100% schema coverage, and the schema already documents the http(s)-only, public-host constraint. The description adds nothing parameter-specific beyond the phrase 'live page', so the baseline of 3 applies.

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

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

States a specific verb and resource ('Audits a live page') and enumerates exactly what is inspected (title/description length, H1s, canonical, robots, lang, viewport, image alts, structured data, links) with a 0-100 score. That enumerated scope distinguishes it from nearby siblings such as robots-check or header-audit, which each cover only one of these signals.

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

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

Usage is only implied by 'audits a live page' and the schema constraint on public URLs; there is no explicit statement of when to pick this over robots-check, header-audit, og-preview or page-markdown, nor any when-not guidance. The billing and pre-billing rejection note does tell the agent the call costs 3 credits only on success, which is useful context but not usage guidance per se.

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 readOnlyHint/openWorldHint annotations, the description adds real behavioral context: the specific embedding model, the exact return shape and ordering, the 3-credit price per successful call, and the fact that schema-invalid input is rejected before billing. That billing-before-validation note is genuinely useful and not derivable from annotations.

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

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

Dense but front-loaded: the operation lead, then return shape, then pricing. Every clause carries information; the pricing sentence is long but includes a unit clarification that prevents a costly misread.

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 fully by spelling out the returned object fields, their ordering, and the scores array's input-order alignment. Combined with the cost model, an agent has everything needed to call and interpret the result.

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

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

Schema description coverage is 100%, so both parameters are already documented with their min/max lengths and item limits. The description echoes the 15-candidate cap but adds no format or semantic detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Ranks ... candidate texts by cosine similarity to a query') and names the underlying model, so the operation is unambiguous. It does not, however, distinguish itself from close siblings like find-similar or embed, which an agent must choose between.

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

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

Usage is only implied by the operation itself (rerank a small candidate set against a query). There is no explicit statement of when to prefer this over find-similar or embed, nor any exclusions, so the agent must infer the routing decision.

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: a billing model (1 credit = 1 CAD cent, charged only on success), validation-before-billing, and an explicit return shape. The word 'Writes' could momentarily read as a disk write against readOnlyHint=true, but the following clause ('save content at path') makes clear nothing is persisted. Not a contradiction, but slightly loose phrasing.

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

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

Three tight sentences: purpose first, return/save instruction second, pricing and validation third. No filler. A slightly clearer lead-in separating 'generates' from the save action would sharpen it, but nothing needs cutting.

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 contract and does so explicitly (path, content, usage plus where to save). It also covers cost and failure behavior, which an agent needs before spending credits. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so every parameter (name, description, allowedTools, argumentHint) is already documented with types, patterns and limits. The description only alludes to frontmatter and $ARGUMENTS without adding syntax or format detail beyond the schema. Baseline 3 is warranted.

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

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

Names a specific verb+resource: producing a ready-to-save Claude Code slash command file with frontmatter, $ARGUMENTS and a step outline. No sibling in the list generates slash commands, so the distinction is immediate. The output triple { path, content, usage } further pins down what the tool produces.

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

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

The description makes the use case obvious (generate a slash command file to save under .claude/commands/<name>.md) and states that malformed input is rejected before billing. It never names an alternative or a when-not-to-use, which for a narrowly scoped generator is a minor gap rather than a blocking one.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description only needs to add context — and it does: it names the exact return shape, states a per-call price (2 credits, 1 credit = 1 CAD cent, charged on success only), and says malformed input is rejected before billing. The only gap is that it never states the query is not executed (that fact lives only in the schema) and leaves 'performance and safety risks' undefined.

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

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

Two sentences, purpose front-loaded, then the return shape and the billing caveat. Every clause carries information an agent needs (output keys, cost, rejection behavior) with no filler.

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

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

No output schema exists, and the description compensates by enumerating the four return fields. Combined with pricing and input-rejection behavior, an agent has everything needed to decide to call it and how to read the result.

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

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

Schema coverage is 100% and there is a single required `sql` parameter whose description already covers length limits and non-execution. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Explains a SQL query step by step') plus the distinctive value it adds: risk flags and index suggestions. No sibling in the list touches SQL, so there is no ambiguity about which tool to pick.

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

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

The description makes the use case clear (analyze a single SQL statement for structure, performance, and safety) and the constraint that input must match the schema. It does not articulate when to prefer a different approach, but the sibling set contains no alternative SQL-analysis tool, so exclusions are unnecessary.

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

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

Goes well past the readOnlyHint/openWorldHint annotations by disclosing PII redaction before the model sees input, the exact return shape, per-call pricing in credits, and that schema-invalid input is rejected before billing. Cost and redaction are behavioral facts an agent cannot infer from structured fields.

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

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

Three short sentences, front-loaded with what the tool produces, then the return value, then billing. Nothing is redundant given that price and rejection policy carry real decision weight.

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 supplies the return shape itself, plus limits, redaction behavior, and cost. Nothing an agent needs in order to call this correctly and predict its bill 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 description coverage, so the schema already documents the 1–8,000 character range and the specific redaction targets. The description restates the length ceiling and redaction but adds no new parameter meaning, making baseline 3 correct.

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

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

States a specific operation and its output shape: a three-bullet summary bounded at 8,000 characters. That is clearly distinct from neighbors like chunk-text or keywords, though it never names an alternative to differentiate itself from 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?

Usage is only implied by the name and the length constraint; there is no explicit statement of when to pick summarize over keywords, entity-extract, or similar text tools, and no exclusions or prerequisites beyond the input limit.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description adds real value: per-call credit cost, the fact that billing occurs only on successful calls, and that schema-invalid input is rejected pre-billing. It also discloses the return shape ({added, removed, diff} and prefix conventions), which no annotation or output schema covers.

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

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

Two dense sentences, front-loaded with the operation and limits, then the return shape and billing terms. No filler; every clause carries information the agent needs.

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

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

With no output schema, the description correctly supplies the return structure and prefix semantics, plus cost and input-rejection behavior. Nothing needed to call this simple two-string tool correctly is missing.

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

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

Schema coverage is 100% and both parameters are already documented with maxLength and 500-line limits. The description only restates the text limit and does not add format or semantic detail beyond the schema, so the baseline 3 applies.

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

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

States the specific operation (line-by-line diff), the exact operands (two texts), and the operating limit (500 lines each), which cleanly separates it from near-siblings like similarity and text-stats. An agent can identify the right tool 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?

Usage is implied by 'diff of two texts', but there is no explicit when-to-use or when-to-prefer-similarity/text-stats guidance, and no statement of prerequisites. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is to add operational context — and it does: per-call credit pricing, the fact that schema-invalid input is rejected before billing, and the output keys. That billing behavior is genuinely useful information not present in 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?

Two tight sentences: what it computes first, then return shape and pricing. Nothing is wasted and the most decision-relevant content is front-loaded.

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

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

With no output schema, the description supplies the return shape itself, plus pricing and input-validation behavior. It is essentially complete for a single-parameter read-only tool, with only sibling differentiation 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?

There is a single parameter at 100% schema description coverage, where the schema already documents 'up to 64,000 characters.' The description restates the output keys rather than adding parameter meaning, so the baseline 3 applies.

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

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

The description names specific outputs (word/sentence/character counts, reading time, Flesch reading-ease) for a text-measurement resource, which lets an agent distinguish it from siblings like token-count, keywords, or sentiment. It also enumerates the exact return shape, removing ambiguity about what 'statistics' means here.

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

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

Usage is implied by the metrics it returns, but there is no explicit 'use this when' or differentiation from near neighbors such as token-count or keywords. The pricing note aids decision-making but is not a usage guideline; the agent must infer selection criteria itself.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds meaningful context beyond those fields: it is deterministic, not exact, returns a specific estimated shape, and bills 1 credit per successful call while rejecting schema-invalid input before billing.

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

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

The description is front-loaded with purpose, then details the return shape and billing behavior. The return-field list is justified because no output schema exists, and no sentence 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?

For a simple one-parameter read-only tool, the description covers purpose, estimation nature, return shape, and billing behavior. With schema coverage complete and no output schema, an agent has enough information to invoke it correctly.

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

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

There is one parameter with 100% schema description coverage, so the schema already explains the text input and its length limits. The description does not add further semantics about the text parameter, which is appropriate but not value-adding beyond the baseline.

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

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

The description states a specific verb and resource: estimating token counts across cl100k-like, o200k-like, Claude-like, and Llama-like tokenizers plus a char/4 baseline. This is concrete enough to distinguish it from sibling tools such as text-stats or chunk-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?

The description implies when to use it by noting that it returns deterministic estimates rather than exact counts, which helps an agent know it is for approximation. However, it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already cover safety (readOnlyHint=true, openWorldHint=false), yet the description adds real operational context the annotations cannot: a 1-credit cost per successful call, the CAD-cent conversion, and the fact that schema-invalid input is rejected before billing. It omits failure modes beyond schema rejection (e.g. what happens on unsupported type strings), which keeps it short of a 5.

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

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

Two sentences, front-loaded with purpose, then return shape, then billing/validation. Every clause carries information an agent would otherwise lack; nothing is padding.

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

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

There is no output schema, and the description compensates by naming the returned keys. Cost and rejection behaviour are disclosed. What's missing is anything about limits on the params map (size, nesting depth) or error output, which matters for a nested-object 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?

Schema description coverage is 100% and the params property already documents the 'type[:extra][!] description' grammar, enum syntax, array item types, and the '!' required marker. The description only alludes to 'a compact parameter spec' without adding syntax or edge-case detail, so it does no more than the schema already does.

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 ('Builds'), the resource ('tool definitions'), the three target platforms (Anthropic, OpenAI, MCP), and the input form ('compact parameter spec'). The return shape { anthropic, openai, mcp } further disambiguates it from siblings like mcp-config-validate or openapi-lint, which validate rather than generate.

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

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

Usage is implied by the input contract: you have a parameter spec and want paste-ready definitions. But there is no explicit when-to-use/when-not, and no pointer away from near-neighbours such as mcp-config-validate (validate an existing config) or slash-command-scaffold. The agent must infer the boundary.

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

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

Beyond readOnlyHint/openWorldHint, the description discloses cost (4 credits, 1 credit = 1 CAD cent), that billing only occurs on successful calls, and that schema-invalid input is rejected pre-billing — genuinely useful economic and failure behavior. It also documents the return shape instead of leaving it opaque. It could still say whether long text is auto-chunked or how failures after billing are handled.

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

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

Information is front-loaded: purpose first, then return shape, then pricing and validation behavior. Every sentence carries content (defaults, output keys, billing), with only mild verbosity in the parenthetical currency conversion.

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

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

For a 3-parameter tool with no output schema, the description supplies the return fields, the billing model and the default language pair, which is close to complete. Remaining gaps are minor: no note on rate limits, text-length handling beyond the schema's 8,000 cap, or behavior on unsupported language codes.

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

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

Schema description coverage is 100%, so the schema already documents text length, redaction, ISO 639-1 patterns and both defaults. The description only restates the default pair, adding no syntax or constraint detail beyond the schema — the correct baseline 3.

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

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

The description names a specific verb and resource ('Translates text between languages') and adds the operative default (en→fr for NS/NB customers), which immediately distinguishes it from nearby siblings like summarize, classify or sentiment. It stops short of naming any alternative tool, so it is clear but not fully self-differentiating.

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 customer-segment default implies typical usage, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as summarize or entity-extract. An agent can infer this is the translation tool but must decide on its own when translation is the right 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?

The annotations declare openWorldHint=false, but the description says the tool performs an HTTPS probe against a public domain, which is an external, open-world interaction. That is a direct inconsistency with the annotation, so this dimension is capped at 1 despite the otherwise useful return-shape and billing details.

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-loaded: it states the core probe, defines the returned fields and edge semantics, then gives billing and validation behavior. Every sentence carries useful information without padding.

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

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

There is no output schema, but the description explicitly explains the return shape and the meaning of up and status, as well as billing and schema-validation behavior. For a two-parameter read-only probe, that gives an agent enough information to call and interpret it correctly.

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

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

Schema description coverage is 100%, and the schema already documents domain and path constraints, including allowed path characters, length limits, and private-suffix refusal. The description adds little parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description names a specific action and resource: one HTTPS probe of a public domain, returning status, latency, and lookup result. It is clear what the tool does, but it does not explicitly distinguish itself from nearby network siblings such as http-status, dns-lookup, or https-redirect.

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

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

The description implies a quick uptime/status probe, but gives no explicit when-to-use or when-not-to-use guidance. With many network-related sibling tools available, an agent is left to infer why this should be chosen over http-status, dns-lookup, or header-audit.

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 readOnlyHint/openWorldHint annotations: discloses that warnings are emitted for credentials, plain http and punycode, that passwords are never echoed, and that billing is 1 credit per successful call with schema-invalid input rejected before billing. That is exactly the kind of rate/cost and safety detail 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 and its components, then the return shape and cost. Slightly redundant in listing the parsed components and then repeating them in the returned object, but every sentence carries information.

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

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

With no output schema, the description compensates by enumerating the full returned object and the warning behavior, plus cost and rejection semantics. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% with a single required 'url' parameter already described as an absolute URL that is not fetched. The description adds nothing about format, length limits, or edge cases beyond the schema, so the baseline of 3 applies.

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

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

States a precise verb and resource: 'Splits a URL into scheme, host, port, path segments, query ... and fragment', with the exact output shape enumerated. An agent knows exactly what transformation happens. It does not name or differentiate from the closest siblings (enrich-url, og-preview, web-extract), so it stops short of a 5.

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

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

There is no explicit statement of when to use this versus alternatives like enrich-url or og-preview, and no exclusion conditions. The only usage cue is the schema note 'It is not fetched', which implies offline parsing but is not framed as guidance.

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