Tanod Text

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

Goes well beyond the readOnly/idempotent annotations: input caps (1,000,000 chars, 10,000 cues), truncation behavior (first 1,000 finding details with exact totals), malformed input being a 422 not charged, typical latency under 0.3 s, price and free-tier limits. Provenance of rules (Netflix guides vs Tanod heuristics) is also 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?

Front-loaded with purpose and return shape, and nearly every clause carries operational information. The telegraphic fragments ('No platform approval.', 'First 1,000 finding details, exact totals.') cost a little readability, but 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 full schema descriptions, an output schema, and safety annotations already in structured fields, the description fills remaining gaps: limits, truncation, error behavior, pricing, and rule provenance. An agent has everything needed to call it correctly and interpret cost/limits.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it enumerates the versioned profile IDs and clarifies that counting uses Unicode grapheme clusters, not bytes or display columns. The from_format and intentional_overlaps semantics are left to the schema.

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

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

States a specific verb+resource (check subtitle delivery timing, line length, reading speed) and what it returns (cue-level SRT/WebVTT delivery review). Clear enough to distinguish from siblings like convert_subtitles or text_stats 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?

Scope exclusions are explicit: 'No platform approval', 'No audio alignment or missing-speech detection', so an agent knows what it will not get. It does not explicitly name alternatives (e.g., convert_subtitles for format conversion), which keeps it from 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 cover the read-only, idempotent, non-destructive, closed-world profile, and the description still adds substantial context: heuristic and English-centric algorithm, the 'new is not proof' limitation, no corpus retention, sub-0.5s latency, USD 0.003 price with no free tier, and no logging/storage of submitted text. It even flags returned page text and on-chain strings as untrusted data, which is real operational guidance.

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, verdict vocabulary, and matching logic are front-loaded, and the pricing/privacy/security boilerplate is compressed into short clauses. It is dense and run-on in places (pricing, latency, and safety warnings all crammed into the same paragraph), but virtually every sentence carries decision-relevant 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 4-parameter, fully-documented tool with an output schema, the description supplies everything an agent needs: what it does, what it returns conceptually, its accuracy limits, cost, latency, and data-handling posture. There is no gap an agent would have to guess at before calling it.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the matching model behind the parameters (cosine of words and word pairs at 0.08 threshold with two shared words, or three shared multi-digit numbers) and the 1-50 corpus bound. Some of this overlaps the schema's own threshold description, but it adds interpretable meaning rather than merely restating it.

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

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

States a specific verb and resource ('check whether a draft repeats your earlier texts') and names the exact output verdicts (duplicate, near, new). An agent can distinguish this from near-siblings like text_similarity, diff_text, or compare_documents without opening any schema.

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

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

Gives a clear use context ('before publishing') and an explicit negative constraint that shapes correct use: 'No saved corpus; check every flagged text,' plus the caveat that a 'new' verdict is not proof. It does not name an alternative sibling or when-not-to-use-it, so it falls short of a 5.

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

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

Annotations only declare readOnly/idempotent/non-destructive; the description goes far beyond them. It discloses the exact return fields (type, line, column, offset, confidence, redacted preview), that the secret itself is never returned and how redaction works, that detection is pattern-based with a false-negative caveat, the 422 on blank input (not charged), latency, price and free tier, and that text is never logged.

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

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

Front-loaded with purpose and sibling routing, then operational facts; almost every sentence carries decision-relevant information. The long vendor enumeration (AWS, GitHub, GitLab, Stripe, Slack, Google, OpenAI...) is the one part that runs long, though it usefully signals detection breadth.

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 scanning tool with an output schema, the description already covers everything an agent needs: what is detected, what is returned, error behavior, latency, cost and privacy. Nothing material is left to guesswork.

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 maxLength and the no-logging guarantee, so the description's repetition there earns little. It does add semantic meaning by naming what the input typically is (a log, draft post, message, tool result, config file) and by restating the no-secret-returned contract at the call site.

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 ('Scan text for leaked secrets') and enumerates the exact detection classes (API keys, tokens, private keys, seed phrases). It explicitly distinguishes itself from two named alternatives, redact_pii and check_text_for_prompt_injection, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use-this vs when-to-use-something-else: personal data goes to redact_pii, injected instructions go to check_text_for_prompt_injection. It also frames the trigger context ('before it is posted'). No inference is required to choose the right 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 far beyond the annotations (readOnly/idempotent/openWorld) by disclosing what gets sent to the index ('picked sentences go to the index as quoted queries'), latency (3-15 s, 3 concurrent searches), price (USD 0.08, no free tier), error semantics (422 for no 8+ word sentence, 503/504 not charged), index limitations (Mojeek sample, absence is not proof of originality), and an explicit untrusted-data/prompt-injection warning. This is unusually complete behavioral 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?

Purpose is front-loaded in the first sentence and nearly every clause carries usable information (cost, timing, errors, caveats). It is nonetheless a dense single-block paragraph with several semicolon-chained facts, and a couple of items (equal price for max_sentences) restate schema content, so structure could be cleaner.

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 an output schema present the description need not explain return fields, yet it still sketches them (share_found, sources ranked by sentences held), and it covers cost, latency, error codes, index caveats, and prompt-injection safety. Nothing material for a correct, well-interpreted call is missing.

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

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

Schema description coverage is 100%, so the schema already documents text length, the 8+ word sentence rule, max_sentences bounds and equal pricing, and exclude_domains. The description adds only the behavioral note that picked sentences are forwarded as quoted queries, not additional 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?

States a specific verb and resource ('Check a text for copied sentences: web pages that contain them word for word') and the exact scope of the check (exact-phrase search over the text's most distinctive sentences). It also distinguishes itself from the sibling web_search, so an agent can route correctly without opening the schema.

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

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

Explicitly names the alternative and condition: 'For a general query use web_search,' and warns this is not a general search. It further clarifies what the tool does NOT deliver ('No verdict on who or what wrote it') and how to read negative results, which is actionable usage context, though it does not spell out when the tool should be skipped entirely (e.g. short texts).

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

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

Annotations declare the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial operational detail beyond that: strict parsing with cue-named 422s, limits of 1,000,000 characters and 10,000 cues, free-request behavior, that failures are not charged, negative-shift clamping/dropping, typical latency, and price. This is unusually rich disclosure for a read-only 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 opening sentence front-loads the core action and time shift, and later sentences carry genuinely useful operational facts. It is dense and includes some detail already present in the schema (format detection, shift clamping), but nothing is padding and it stays scannable.

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 an output schema present, the description needn't explain returns, yet it still covers formats, limits, error behavior, latency, pricing, and free-tier rules. An agent has everything needed to call it correctly, and the sibling routing removes the main ambiguity.

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 the shift semantics and the format-detection rule are already documented in the schema. The description largely repeats these ('with an optional time shift in milliseconds', negative-shift behavior) with little added syntax or format detail, 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 (Convert) plus resource (subtitles) and enumerates the formats (SRT, WebVTT, JSON) and the time-shift capability. It also distinguishes itself from transcribe_audio, the sibling that produces subtitles from audio. An agent can identify the tool's function without opening the schema.

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

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

Explicitly routes the from-audio case to transcribe_audio, giving a clear when-to-use boundary. However, it doesn't spell out when to prefer content vs segments (that choice lives only in the schema) nor warn against using convert_data for subtitles. Clear context, but no explicit exclusions beyond the one sibling callout.

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/idempotent annotations: defines the `reliable` flag threshold (20 letters, confidence >= 0.6), the 422 no_text error and that it is not charged, latency expectations including cold-start, price, free daily quota, and that text is never logged or stored. This is unusually rich behavioral 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?

Front-loaded with purpose and alternative routing, then return shape, then edge cases, then operational facts. Dense but every clause carries actionable 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?

Despite an output schema existing, the description still summarizes the return payload (ISO codes, name, confidence, 3 alternatives), plus error, cost, latency, and privacy behavior. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the schema already documents the 20,000-character limit. The description adds input semantics the schema lacks: letterless text yields 422 no_text and short text is often flagged unreliable, which helps the agent predict outcomes from the 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 (detect) and resource (language of a text) and explicitly distinguishes itself from the sibling translate_text. An agent can tell instantly what this does and what it is not.

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?

"To translate use translate_text" gives an explicit alternative for the adjacent use case. It does not state when detection is inappropriate (e.g., very short strings), though the reliability note partially covers that. Clear context, but 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?

Goes well beyond the annotations by disclosing output truncation limits (1,000 hunks / 5,000 change records, then `truncated`), sandboxing ('isolated, resource-limited child process without network'), the failure mode (over-limit input → 422, not charged), latency (~0.5 s), pricing, free-tier quota, and the data-retention guarantee ('never logged or stored'). For a stateless read tool this is unusually complete operational context.

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

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

Front-loads the purpose and the sibling routing rule before operational details, and the density is high with little waste. It is on the long side for a 4-parameter utility — the pricing, quota and docs-link clauses are useful but push it toward a wall of text.

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 an output schema exists, the description needn't explain return values, yet it still summarizes the shapes and truncation behavior. Combined with limits, error semantics, isolation and latency, an agent has everything needed to call this correctly and interpret failure.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents a, b, mode and context. The description adds value the schema cannot: what each mode actually returns (git-compatible unified diff vs. equal/insert/delete/replace records with exact offsets into a and b), which is the key semantic distinction between the enum values.

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 ('Diff two texts') and enumerates the three granularities it supports. It actively distinguishes itself from the closest sibling by name: 'For PDF or Word files use compare_documents.' An agent can route correctly without opening either schema.

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

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

Provides an explicit when-not rule with the alternative named ('For PDF or Word files use compare_documents'), which is the primary ambiguity against this sibling set. The mode descriptions (line = unified diff, word/char = change records with offsets) also imply when each granularity is appropriate.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: content-stripping rules (scripts, styles, nav, footers, forms, embeds dropped; main/article preferred), isolation in a resource-limited child process, 422 html_too_complex thresholds, latency range, and that failed-limit calls are not charged. The untrusted-data warning about page text and on-chain strings is a genuinely valuable operational caveat.

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 routing, with limits, pricing, and caveats in descending order of importance. It is dense and a few clauses duplicate the schema ('nothing is fetched' appears twice, the title sentence is restated), which keeps it short of a 5 for a tool of this simplicity.

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 an output schema exists, return values need not be explained; the description instead covers everything else an agent needs: input constraints, error codes, cost, free-tier quota, execution environment, and latency expectations. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%, including the key html clarification (document itself, max 2 MB, nothing fetched) and base_url's relative-link behavior, so the description largely repeats structured data. It reinforces rather than extends the schema, which lands at the baseline 3.

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

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

States a specific verb and resource ('Convert HTML to Markdown or plain text') and immediately names the two sibling tools it must be distinguished from: render_page for fetching a URL and markdown_to_html for the inverse operation. An agent can pick the right tool 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?

Explicit when-to-use routing: 'To fetch a URL use render_page; for the reverse use markdown_to_html', plus the negative constraint that the input is HTML, never a URL, and nothing is fetched. This is exactly the disambiguation a large sibling list (render_page, extract_pdf, get_page_meta, convert_document_to_markdown) demands.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description layers on substantial extra behavior: transliteration and apostrophe handling, dropping of CJK/Arabic/Hebrew/Indic/Thai/emoji with a `dropped_characters` count, the 422 empty_slug error, latency, price, and a free daily quota.

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

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

Front-loads purpose and the sibling alternative, then packs behavior, error mode, latency, price, quota, and docs into a compact block. Slightly dense for one paragraph, but nearly every clause carries operational value for a priced API.

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?

An output schema exists, so return values need not be explained, yet the description still flags the notable `dropped_characters` output and the 422 failure mode. Combined with pricing, timing, and quota details, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so text, lowercase, separator, and max_length are all already documented with defaults and bounds. The description restates the separator/truncation behavior but adds no syntax or meaning beyond the schema, so the baseline 3 is 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 ('Make a URL slug from text') and immediately distinguishes itself from the sibling text_case for other case styles. An agent can tell exactly what this tool produces without reading the schema.

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

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

Explicitly routes non-slug case conversions to text_case, giving a clear alternative with the condition that selects it. It does not cover when-not-to-use cases beyond that (e.g. non-Latin text that will be dropped), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the exact sanitizer allow-list behavior, link rel rewriting, the 4 MB and input-limit 422s (one 'not charged'), child-process isolation with no network, and sub-0.5s latency.

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

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

Dense but front-loaded: conversion purpose first, then flavor/return behavior, then limits, pricing and docs. Every clause carries information, though the opening restates the title and the pricing/free-tier tail is slightly peripheral to invocation.

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?

Because an output schema exists, return values need not be explained, yet the description still covers sanitization guarantees, size/input failure modes, isolation and cost. Nothing needed to call this 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 the schema already documents both parameters, including the gfm flavor semantics and the 200,000-char cap. The description largely restates what the schema says, adding no syntax or format detail beyond it, so the baseline 3 applies.

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

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

States a specific verb+resource ('Convert Markdown to sanitized HTML') and immediately routes the agent to the reverse sibling ('For the reverse use html_to_text'), so it is distinguishable from html_to_text without opening either schema.

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

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

Names the alternative tool and the condition that selects it (reverse direction). It doesn't spell out when *not* to use this tool beyond that, but for a single-purpose converter the routing context is clear.

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

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

Goes well beyond the annotations: it explains that redacted pages become images so text cannot be copied back, that metadata is removed, and documents the failure modes (413 over 15 MB, 422 on encrypted input, 503 over ~78 s, none charged), typical latency, price and data-retention policy. It also flags returned text as untrusted data, which the annotations do not convey.

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

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

Front-loads the purpose and sibling routing, then packs constraints, limits and pricing into compact clauses with zero filler. It is dense and long, but nearly every clause carries operational information an agent needs.

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

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

An output schema exists, so return values needn't be explained, and the description still covers input preconditions, size/time/encryption limits, pricing, and result-retention caveats. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a real constraint absent from the schema: at least one of terms/patterns/boxes must be supplied (required is empty in the schema). It also clarifies output semantics (base64 file vs a 24 h url link). Marginally above baseline.

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

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

States a specific verb and resource ('Redact a PDF') and enumerates what can be redacted (terms, emails, phone numbers, card numbers, areas), which maps directly onto the terms/patterns/boxes inputs. It explicitly distinguishes itself from the sibling pdf_redaction_check by naming it as the tool for testing files redacted elsewhere.

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

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

Gives the alternative and the condition that selects it ('To test a file redacted elsewhere use pdf_redaction_check'), plus a prerequisite for success ('Matching needs a text layer: OCR scans first or give boxes') and a post-condition ('check the result before sharing'). That is explicit when-to-use and 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 mark this read-only, idempotent and non-destructive, but the description adds substantial context beyond them: the pdfplumber text-layer method, detection of Redact/dark Square annotations, the 200-page ceiling, the 422 for encrypted/damaged files (uncharged), runtime (1-8s / 0.1s per page), price (USD 0.005, no free tier), no-logging guarantee, and the untrusted-data warning.

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

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

Front-loaded with the core purpose and the sibling alternative, then operational details. It is dense and somewhat run-on, but nearly every clause (verdict values, limits, cost, limitations, security note) carries information an agent needs.

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

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

For a paid, network-bound, output-schema-bearing tool, the description covers output shape (page, box in PDF points, character count, hidden text), verdict enum semantics, failure modes, cost and runtime, and privacy handling. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so url, mask, pages and file_base64 are already documented in the schema. The description only echoes the mask behavior ('or only its length with `mask`') and says nothing added about url vs file_base64 selection or page-range syntax, so it does not exceed the baseline.

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

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

States a specific verb and resource: 'Check a PDF for failed redactions: black boxes with the text still under them.' It also explicitly distinguishes itself from the sibling pdf_redact by its contrasting purpose, so an agent can tell the two apart without opening either schema.

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

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

Names the alternative and the selecting condition: 'To redact properly use pdf_redact.' It further scopes expectations with 'clean says nothing beyond that (white text, metadata, images and scans are not examined)', telling the agent when a clean verdict is not conclusive.

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, which only cover safety (readOnly/idempotent/non-destructive). It discloses detection mechanics (RE2 with re-checking, Luhn, mod-97), format caveats (national phone formats need + code), latency (<1s), price, free-tier limit, and a no-logging guarantee.

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

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

Front-loads purpose and the routing to the sibling in the first two sentences; the rest is dense but each clause carries operational value (limits, caveats, docs). Slightly packed, with pricing/docs link tacked onto the tail.

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?

An output schema exists, yet the description still summarizes the return shape (masked text plus per-entity type, offsets, replacement, counts). Combined with detection exclusions, format caveats, and limits, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description still adds practical meaning, notably the phone-format constraint on 'phone' detection and how mask modes affect output, going modestly beyond the schema text.

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

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

States a specific verb+resource ('Redact PII from text') and enumerates exactly which entity types are handled (emails, phones, cards, IBANs, SSNs, IPs, crypto). It also names the sibling that handles the adjacent task, so it is distinguishable without opening a schema.

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

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

Explicitly routes the agent: 'For API keys and tokens use check_text_for_secrets.' It also gives when-not guidance by listing what is left alone (prices, dates, order numbers) and what is not detected (person names, street addresses).

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 this as a safe, read-only, idempotent operation. The description adds meaningful behavioral context beyond the annotations: typical latency under 0.3 s, pricing of USD 0.001, a free daily quota per IP, and a privacy guarantee that submitted text is never logged or stored.

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

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

The description is front-loaded with the core action and examples, followed by alternative guidance, pricing, and privacy notes. It is dense but each clause contributes useful information, though the middle sentence is a long run-on list.

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

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

For a simple two-parameter text transformation with full schema coverage, annotations, and an output schema, the description covers purpose, alternatives, supported values, special title behavior, privacy, cost, and latency. Nothing essential 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 coverage is 100%, so the enum values are already documented. The description still adds useful semantic detail for the 'title' case (small words kept lower-case; iPhone and domains preserved) and for identifier styles splitting camelCase, acronym, and digit boundaries per 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?

The description states a specific verb and resource: 'Convert text case.' It enumerates the available case styles and explicitly distinguishes this tool from make_slug for URL slugs, so the agent can select it correctly without opening the schema.

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

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

It provides clear context by listing supported conversions and names an alternative ('For a URL slug use make_slug') with the condition that selects it. However, it does not give broader when-to-use or when-not-to-use guidance relative to the other text 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?

Beyond readOnlyHint and idempotentHint, the description discloses deduplication and first-seen ordering, RE2 pattern execution with hit re-checks, phone-like vs validated distinction, typical latency, pricing, free-tier limits, and the privacy guarantee that submitted text is never logged or stored. These are material operational details not covered by 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 front-loaded with the core purpose and alternatives before moving into return details, performance, pricing, and privacy. It is dense but every clause carries useful information. It could be structured into shorter sentences for readability, but there is no substantive 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?

Given the tool's complexity, the annotations, and the output schema, the description provides everything an agent needs: extraction scope, sibling alternatives, return ordering and deduplication, caveats, performance, cost, rate limits, and privacy behavior. No critical gaps remain.

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 parameters are already documented. The description still adds meaning by enumerating the extraction types, noting checksum verification for EVM and BTC addresses, and clarifying that phone hits are phone-like digit groups rather than validated numbers. It adds useful semantic context but does not restate max_per_type or types defaults.

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: extract emails, URLs, domains, IPs, dates and crypto addresses from text. It distinguishes itself from siblings by naming redact_pii for masking and extract_entities for names/places. An agent can identify exactly what this tool does without opening the schema.

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

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

It explicitly routes the agent to alternatives: use redact_pii for masking personal data, and extract_entities for names and places. It also specifies the supported extraction types and the phone caveat, making the intended use clear.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real load-bearing context beyond them: latency (~0.3 s), pricing and free-tier limits, and a privacy guarantee that submitted text is never logged or stored. These are exactly the traits 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?

Front-loads the core purpose and the sibling alternative, then layers output, latency, pricing and privacy without redundancy. The pricing/free-tier/docs boilerplate is compact but slightly dilutes the operational core.

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 an output schema present, return values need no explanation, and the description still covers scope, the keyphrase alternative, latency, cost and data handling. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, making 3 the baseline. The description echoes the stop-word language list and the 'n-grams never cross punctuation' rule, which is a useful emphasis but adds little that the schema does not already 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 (Count) and resource (word and n-gram frequencies in a text), and explicitly distinguishes itself from the similar sibling text_keywords. An agent can route between text_frequency, text_keywords and text_stats without opening schemas.

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

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

Gives an explicit alternative ('For scored keyphrases use text_keywords'), which is genuine when-to-use routing. It does not mention text_stats or define exclusions beyond the keyphrase case, so it stops short of full 5-level 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still contributes real behavioral context beyond them: the RAKE scoring method, the sub-0.3 s latency expectation, the per-call price and free daily quota, and the privacy guarantee that submitted text is never logged or stored.

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

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

Front-loaded with purpose and disambiguation, then layered with algorithm, performance, cost and privacy in one dense block. Every sentence earns its place for an agent deciding whether to spend a call, though the price/quota/docs tail makes it longer than strictly minimal.

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?

An output schema exists, so return values need not be explained here, and the description still notes the 'score and count' fields. Combined with cost, latency and privacy disclosures, an agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so all four parameters (text, top_n, language, max_words) are already documented with ranges, defaults and enum values. The description's mention of phrases 'between stop words and punctuation' hints at why the language parameter exists but adds no syntax or constraint 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 ('Extract the keywords and keyphrases of a text') and immediately distinguishes itself from the two nearest siblings, text_frequency and extract_entities. The RAKE gloss clarifies what kind of keyphrases come back.

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

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

Explicitly routes the agent: raw frequencies go to text_frequency, names and places go to extract_entities. That is a concrete when-to-use-this vs when-to-use-alternatives statement, not merely implied 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 read-only, idempotent, non-destructive, closed-world, and the description adds genuinely new behavioral context: deterministic seeded shuffle, stable sort, dedupe keeps the first occurrence, a 200,000-line ceiling, ~0.3 s latency, price, a 10-calls/IP/day free quota, and an explicit statement that submitted text is never logged or stored. These are exactly the rate-limit, cost, and data-handling details that annotations do not carry.

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

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

Front-loaded with purpose, then exclusion, then mechanics, then constraints/pricing in a single dense paragraph with little waste. The 'utilpeek:' prefix and pricing/free-tier boilerplate are mildly extraneous for tool selection but still informative.

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

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

An output schema exists so return values need no explanation, and the description covers limits, latency, operation ordering, and determinism. One small gap: it says 'At most 200,000 lines' while the text parameter caps at 200,000 characters, and it does not describe behavior on over-limit input.

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 beyond the schema by restating the execution order of operations and specifying that dedupe keeps the first occurrence and that shuffle is seeded/repeatable, details the enum entries alone do not convey.

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

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

States a specific verb set (sort, dedupe, trim, shuffle, number) and resource (lines of text), and explicitly disambiguates from the sibling text_replace for find/replace. An agent can tell it apart from text_stats or diff_text without opening the schema.

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

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

Gives an explicit exclusion and alternative: 'For find and replace use text_replace.' However, it does not route the agent away from other overlapping siblings such as text_frequency (despite offering 'most frequent lines with counts') or text_stats, so selection guidance is clear but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description layers on traits they do not carry: determinism tied to `seed` (echoed back), typical latency (<0.3 s), price (USD 0.001) and a free quota (10 calls per IP per UTC day). Those operational constraints are exactly the kind of context annotations cannot express.

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

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

Front-loaded with purpose, then alternative, return shape, inputs, latency, price and quota in a compact block where each sentence is short. Minor redundancy in re-listing the count caps already present in the schema, 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?

An output schema exists, so return values need not be explained, yet the description still characterizes them (lorem vs English filler, echo of `seed`). Combined with defaults, limits, latency, cost and quota, an agent has everything needed to invoke it correctly and decide whether it can afford to.

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 goes one step beyond by stating the empty-body consequence ('an empty body gives 3 paragraphs'), which is derived behavior rather than a restatement of the schema defaults, and by summarizing what `count` is bounded by. It does not add format details for `seed` or `start_with_lorem` 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?

Specific verb (Generate) plus resource (seeded lorem ipsum / English placeholder text) stated in the first sentence. It explicitly disambiguates from the sibling it could be confused with, generate_random, so an agent can route without opening either schema.

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

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

Names the alternative tool and the condition that selects it: 'For random values use generate_random.' It also states the default-call behavior ('an empty body gives 3 paragraphs'), so an agent knows both when to use this and what happens with no arguments.

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 read-only/idempotent/non-destructive, and the description adds substantial extra context: half-even rounding to the minor unit, the 10^36 ceiling, 422 for invalid or out-of-range input (with no charge), typical latency under 0.3 s, price, and a 10-call free tier. That is exactly the beyond-annotation 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-loads the core purpose in the first sentence, then adds operational facts in dense but non-redundant clauses. Slightly packed with pricing/free-tier detail, though each sentence carries usable 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?

An output schema exists, so return-shape documentation is unnecessary; the description supplies input constraints, error behavior, performance, cost, and rate limits. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% so the enum values and defaults are already documented; the description nonetheless adds real semantics such as half-even rounding for currency, the 13-currency scope, and the rationale that value must never be a float to avoid rounding surprises.

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

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

States a precise verb+resource pair (convert numbers to English words / parse number words back) and explicitly differentiates itself from the sibling convert_units. An agent can identify the tool's function and its boundary without opening the schema.

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

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

Explicitly routes unit conversion to convert_units and explains the two modes (to_words vs to_number) and when each applies. It lacks broader guidance on when this tool is preferable to other text utilities, but the key alternative is 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 readOnly/idempotent/non-destructive, so the safety bar is low, yet the description adds real behavioral context: invalid RE2 patterns yield a 422 not charged, replacements capped with limit_reached reporting, typical latency, pricing and free-tier rate limit, and that submitted text is never logged or stored. These are things the annotated schema cannot express.

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

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

Front-loaded with purpose and the alternative tool, followed by dense but relevant operational detail. It is on the long side, but nearly every clause (RE2 guarantees, error semantics, limit reporting, privacy) carries decision-relevant information rather than filler.

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

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

With an output schema present, return values need no explanation, and the description fully covers the remaining decision points: engine choice, replacement syntax, error handling, rate limits, and privacy. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema: replacement syntax (\1, \g<name>), the RE2 no-backreference/lookaround constraint, and the observable limit_reached behavior tied to max_replacements, which the schema does not mention.

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

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

Starts with a specific verb+resource ("Find and replace in text") and immediately scopes it to literal or RE2 regex, then names the sibling text_lines for the adjacent line operations. An agent can distinguish this from text_lines without opening either schema.

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

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

Explicitly routes the agent away: "To sort, dedupe or number lines use text_lines." That is a concrete when-to-use-the-alternative statement. It doesn't enumerate other boundaries (e.g. vs diff_text or text_extract), but the primary sibling collision is resolved.

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

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

Goes well beyond the annotations: it discloses the VADER lexicon-heuristic limitation (misses sarcasm and domain jargon), expected latency (under 1 s), cost (USD 0.001), a free-tier rate limit (10 calls per IP per UTC day), and a privacy guarantee ('never logged or stored'). These are exactly the operational traits 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?

Front-loaded with purpose, then alternatives, then output shape, then caveats/limits. Every sentence carries information, though it is denser than strictly needed and re-states the 'utilpeek' prefix already in 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?

For a two-parameter read-only scoring tool with an output schema and full annotation coverage, the description adds limitations, latency, cost, rate limits, privacy, and a docs link. Nothing an agent needs before calling it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it pins the scope to English input and explains that per-sentence scoring is optional output shaping. The VADER thresholds (positive ≥ 0.05, negative ≤ -0.05) describe the returned label rather than the parameters, so the gain is real but modest.

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 ('Analyze the sentiment of an English text') and explicitly disambiguates from the two nearest siblings ('For your own labels use classify_zero_shot; for counts use text_stats'). An agent can pick this tool over classify_zero_shot or text_stats without opening any schema.

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

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

Names both alternative tools and the exact condition that selects each (custom labels vs. counts). It also scopes applicability by language ('English text') and states the underlying method, so the agent knows when results are appropriate.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds substantial context beyond that: which tokens are skipped (numbers, acronyms, CamelCase, URLs, emails), latency (~1 s, up to 2 s on first language use), price, free-tier limits, and a no-logging/no-storage privacy guarantee.

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 alternative routing, then return shape, limits, latency, price, and privacy. Dense but nearly every clause earns its place; the pricing/docs tail is slightly heavy but still useful for a paid API.

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?

An output schema exists, yet the description still sketches the return payload (dictionary-miss words with offset/line/column and suggestions), and adds availability, cost, and privacy caveats an agent needs before calling. 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%, so all three parameters are already documented with defaults, ranges, and enum values. The description only restates that output includes up to max_suggestions suggestions by edit distance, adding marginal param-level meaning. Baseline 3 applies when the schema carries the load.

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 ('Spellcheck a text with suggestions') and immediately distinguishes itself from the sibling text_stats. An agent can tell exactly what this does versus the neighboring text tools without opening any schema.

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

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

Explicitly routes the agent: 'For counts and readability use text_stats,' and defines the negative boundary ('a dictionary lookup, not grammar or context aware'). This is a clear when-to-use and when-not-to-use statement.

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

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

Beyond the readOnly/idempotent annotations, it discloses concrete behavior: a 422 invalid_lang for unsupported languages, a 422 no_words (not charged) case, undercounting for space-less scripts, heuristic syllable estimates, latency (~0.2s), pricing, free-tier limits, and a no-logging/no-storage guarantee.

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

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

Front-loaded with purpose and the sibling distinction, then packed with operational facts. Every clause carries information (errors, price, privacy), though the density is high and it reads as one long run-on rather than cleanly segmented sections.

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

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

For a two-param read tool with an output schema, the description is more than complete: it covers the return categories, error modes, language limits, cost, rate limits, and privacy, leaving an agent with nothing needed to call it correctly.

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

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

Schema coverage is 100% and the schema already documents both `lang` (ISO 639, English-only scores) and `text` (200,000 char cap). The description adds only marginal semantics, e.g., the 422 invalid_lang consequence and the heuristic-syllable caveat, so the baseline 3 holds.

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 specific verbs and resources: counting words and scoring readability. It explicitly names the sibling it is not for word frequencies and points to text_frequency, so the agent can route without opening schemas.

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

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

Gives one explicit alternative with its selecting condition ('For word frequencies use text_frequency'). Broader when-to-use context is implied by the readability-scoring scope rather than spelled out, and no exclusions beyond that are offered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds substantial context: LexRank extractive method, verbatim sentences kept in original order, no paraphrasing/shortening/fact-checking, typical latency under 0.5s, pricing, free-tier limit, and a no-logging/no-storage privacy guarantee. No contradiction with annotations.

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

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

Front-loads purpose and routing in the first sentence, then layers behavior, performance, cost, and privacy in tight clauses. Every sentence (including pricing and the docs URL) carries information an agent or caller would want; 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 an output schema present, return values need not be enumerated, and the description still notes per-sentence scores and original ordering. Combined with the alternatives routing, cost, limits, and privacy disclosure, nothing an agent needs to select or invoke this 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%, so baseline is 3; the description adds meaning by framing `sentences` and `ratio` as alternative selection mechanisms ('the most central `sentences` (or `ratio` of them)') and characterizing the selection as centrality-based (LexRank). It leaves the mutual-exclusion detail ('ignored when ratio is set') to the schema, but contributes real semantic framing.

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 ('Summarize a text by picking its key sentences') and immediately differentiates itself from siblings paper_digest (abstracts) and text_stats (counts). An agent can identify this as the extractive-summarization 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?

Explicitly names the two nearest alternatives and the condition that selects each ('For paper abstracts use paper_digest; for counts use text_stats'). This is exactly the when-to-use-this-vs-siblings guidance the dimension asks for.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive), and the description adds substantive operational context beyond them: under 1 s latency, USD 0.001 price, 10 free calls per IP per UTC day, and an explicit privacy guarantee that submitted text is never logged or stored. It also enumerates the return categories (risk levels, positions, CVE references, confusables, normalization status).

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

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

Front-loads purpose, then sibling routing, then return detail, then pricing/privacy/docs — a logical order with no filler sentences. It is long, but each clause carries distinct information; only the pricing/rate-limit block extends it beyond strict necessity.

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, idempotent inspection tool with a full output schema and 100% parameter coverage, the definition leaves nothing material unstated: it covers what is detected, return shape, cost, limits, privacy, and performance.

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 every parameter is self-documented in the schema, so the baseline is 3. The description touches on normalize/strip behavior only in passing ('optionally the text normalized or with invisible characters stripped'), adding framing but no syntax or semantics beyond what the schema already states.

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

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

States a specific verb+resource ('Find invisible, bidi and homoglyph Unicode characters in text') and immediately distinguishes itself from the adjacent sibling check_text_for_prompt_injection. An agent can tell what it does and when not to reach for it without opening the schema.

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

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

Explicitly routes the injected-instruction case to check_text_for_prompt_injection, which is the closest competing sibling. It gives clear context but no further when-not guidance (e.g., vs text_stats or redact_pii), so it stops short of full alternative coverage.

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