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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the input constraint ('plain text input') and the size cap ('large inputs are capped by the request size limit'), plus the return shape ('Returns the transformed text or the stats').

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 action enumeration is front-loaded immediately after the one-word purpose statement, followed by return behavior and limits. The dense list is necessary for an enum-less multi-action tool, and no sentence is redundant, though the wall-of-actions format could be more 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?

For a 13-action tool with 4 parameters, no output schema, and only 50% schema coverage, the description adequately covers the action vocabulary, return value, and input limits. It falls short of fully specifying per-action parameters (e.g., width semantics, case variant names), which the agent must otherwise 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?

The schema has only 50% description coverage and no enum on `action`, so the enumerated action list in the description does the heavy lifting by effectively supplying the missing enum. It also ties `width` to wrap and clarifies `text` as a two-element [a, b] list for diff, adding meaning beyond the schema. Minor gaps remain on encode-vs-decode selection and the unnamed case variants ('...').

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

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

The description states the resource (text utilities) and enumerates all supported operations (stats, slugify, case, base64, url encode/decode, html_escape, strip_html, extract_urls, dedupe_lines, sort_lines, wrap, diff), which lets an agent distinguish it from siblings like json_validate, unit_convert, and uuid_hash. It is a multi-action utility tool rather than a single verb+resource, so it stops short of a 5, but scope is unambiguous.

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

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

'Use it for deterministic text transforms' gives a general usage cue, and the action list implies when each operation applies. However, it offers no explicit when-not guidance or contrast against adjacent tools (e.g., json_validate for structured payloads, unit_convert for numbers), leaving the routing decision partly to inference.

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