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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely new context: the policy only affects new uploads and 'Originals are always kept', which materially softens the destructive hint and tells the agent the source data survives. It stops short of stating permission requirements or whether existing policies are overwritten.

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?

A single dense sentence that front-loads the action and enumerates the three configurable behaviors, with the reassuring 'Originals are always kept' clause last. The compressed phrasing ('what to find (instructions)') is slightly terse but every clause carries 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 six-parameter destructive mutation with no output schema, the description covers the core semantics and the data-retention guarantee. It omits what happens to documents already in the notebook, whether the call replaces or merges an existing policy, and any permission prerequisites, which an agent would want before invoking a destructive tool.

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 only 33%, so the description must compensate, and it does: it explains enabled as on/off, instructions as 'what to find', and auto_apply as 'whether findings above min_confidence are applied at once', tying two undocumented parameters together. notebook_id and app_id are covered by the schema itself, so the remaining gap is minor.

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 gives a specific verb and resource ('Set a notebook's automatic redaction') and scopes it to 'new uploads', which separates it from get_knowledge_redaction_policy and apply_knowledge_redaction. It does not name those siblings explicitly, so the differentiation is implied rather than stated.

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 phrase 'for new uploads' implies this configures future behavior rather than acting on existing documents, which is useful context. However, it never says when to choose this over apply_knowledge_redaction, scan_knowledge_for_sensitive_data, or revert_knowledge_redaction, leaving the agent to infer the routing.

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