Delimit Redact

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

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description adds valuable behavioral details: it is read-only on input text, produces a sanitized copy, calls internal PII redaction services, keeps the token map local, and states that the original cannot be recovered through this tool. This gives an agent a clear safety and privacy model.

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 long but each section earns its place: when-to-use, sibling contrast, side effects, detection scope, and token-map caveat. It is front-loaded with purpose and clearly structured, 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?

Given the full input schema, output schema presence, and annotations, the description is complete for correct invocation. It covers purpose, routing to alternatives, side effects, parameter behavior, and limitations such as the unrecoverable original text.

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 text, action, and categories. The description adds meaning by enumerating detected sensitive-data types (API keys, passwords, emails, SSNs, etc.) and clarifying action='redact' behavior. It does not fully map the detected types to the category enum values, so a 5 is not 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?

The first line states a specific verb ('scan or redact') and resource ('sensitive data from text'), making the core function immediately clear. The sibling contrast explicitly distinguishes it from delimit_secret_* tools, so an agent can tell them apart.

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 explicitly states when to use it (before sending text to external LLMs or publishing output) and when NOT to use it (for managing stored secrets, use delimit_secret_store family). It also provides the sibling contrast explaining that delimit_secret_* manages credentials at rest while this tool scrubs arbitrary text.

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