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

Adds context the annotations do not convey: the operation is non-mutating despite readOnlyHint=false, and it executes asynchronously in the background with a separate retrieval step. It does not cover repeated-run behavior (relevant since idempotentHint=false) or how long runs persist, which keeps it short of a 5.

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, each carrying distinct information: what is detected, that nothing is mutated yet, and that execution is async with a named reader. The non-mutation constraint is front-loaded before the async detail, 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?

For an async tool with no output schema, the description supplies the essential missing piece: where to get results (get_knowledge_redaction_run) and the mutation boundary. Minor gaps remain around what a run returns at scan time and how prior runs are superseded, but the agent has enough 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 75%, so app_id and notebook_id are already documented. The description adds real meaning for the otherwise undocumented instructions parameter by explaining it as free-form criteria in the owner's words, and ties document_ids to the scanning target, though it says nothing about the 100-item cap or behavior with large batches.

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 (scan) and resource (knowledge documents) plus the two detection modes: personal/sensitive information or criteria given in the owner's instructions. It is clearly separable from apply_knowledge_redaction (the mutation step) and get_knowledge_redaction_run (the result reader), both named in the text.

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 frames the workflow: this tool only finds, apply_knowledge_redaction is what changes anything, and results are read back with get_knowledge_redaction_run. An agent knows both the alternative and the condition that selects it without opening any other definition.

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