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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the bar is lower — yet the description adds substantial context: it runs on a Cloudflare Worker, inputs leave the client, no inputs/results/token are stored, no further network call, <10 ms latency, no rate limits. This is exactly the kind of operational detail 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?

Labeled WHAT/WHEN/WHEN NOT/COST/RETURNS/BEHAVIOR/PARAMETERS/EXAMPLE sections make it scannable and front-loaded, with no filler sentences. It is on the long side for a zero-parameter catalog call — the BEHAVIOR block is dense — which keeps it just short of 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?

Output schema exists, so return values need not be spelled out, yet the description still summarizes the return shape and explains the meaning of local:true and the redaction_styles keys. Combined with the cost and latency notes, an agent has everything needed to call this correctly and use its 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?

Zero-parameter tool (baseline 4), but the description goes beyond: it states the call must use an empty object {}, that the catalog is complete and cannot be filtered, and how output values map into other tools' parameters (detector 'type' into entityTypes, redaction_styles keys into redactionStyle). That directly reduces downstream invocation errors.

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?

Opens with a specific verb+resource (catalog of every PII and secret entity type) and enumerates the extra dimensions it covers: local vs paid-Actor coverage, redaction styles, and per-tool pricing. An agent can distinguish this from pii_scan_text / pii_redact_text 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' (before pii_scan_text / pii_redact_text to pick entityTypes, or to explain coverage and costs) and 'WHEN NOT' (to actually scan or redact), each naming the sibling tool that should be used instead. The selection rule is fully determined.

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