redact_apply

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

With no annotations, the description must carry behavioral disclosure; it does by warning that the operation is a true deletion and irreversible, and by conditioning invocation on confirmed terms. It could add more about whether the original file is overwritten or what happens on partial matches, but the destructive nature is clearly 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?

Three short sentences cover the core behavior, the required preceding workflow, and the one optional-parameter constraint. There is no filler or repetition of schema 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 destructive tool with no output schema and no annotations, the description supplies the essential safety context: irreversible deletion and the scan/confirmation prerequisite. It still omits return behavior and whether output_path must differ from input_path, but it is strong enough for an agent to call the tool safely in the intended workflow.

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 0%, so the description must compensate; it clarifies that terms are a confirmed list of sensitive words and that logo_templates only supports PDF. However, input_path and output_path are left entirely to their parameter names, with no format, relationship, or overwrite semantics explained.

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 outcome: apply redaction, true deletion, irreversible. It also distinguishes itself from redact_scan by framing scan as a prerequisite rather than the action.

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 says terms must already be a confirmed sensitive-word list and that redact_scan should be called first, with user confirmation, before invoking this tool. It also states logo_templates is PDF-only, which tells the agent when the optional parameter is usable.

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