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

With no annotations, the description carries the full burden and succeeds: it discloses the two-call dry-run behavior, that the first call deletes nothing, the owner-permission requirement on every file including invisible ones, refusal instead of partial deletion, connector sync source removal, sharing persistence after deletion, and recoverability via content addressing.

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 dense but every sentence adds critical operational informationathe safety protocol is front-loaded, and details like sharing persistence and recoverability are concise yet complete. Structurally, key warnings are emphasized with capitalization and sentence-level separations that are easy to parse.

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?

Despite having no output schema and no annotations, the description covers what the tool deletes, how the confirmation flow works, permission requirements, folder-specific behavior, sharing implications, and recoverability. An agent has enough information to invoke it correctly and to communicate with the user before committing.

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%, but the description adds substantial semantic meaning beyond the schema: it clarifies that location can be a file or directory, that a bare folder name deletes the whole folder, that confirm_delete_folder is required only for whole-folder deletion, and that confirm_token must be omitted on the first call and presented to the user before the second call.

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 resource: 'Delete a document, a directory, or an entire folder.' It clearly defines the scope of deletion and distinguishes file-level vs. folder-level behavior, while also noting that history is content-addressed so the operation is recoverable — separating it from a permanent erase sibling.

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 gives explicit usage protocol: 'TWO CALLS, ALWAYS,' show the first result to the person, get their answer, and never confirm on their behalf. It also explains when confirm_delete_folder is required. It does not explicitly contrast choice vs. erase_org_doc, but it references undo_delete as the restoration path, providing clear operational context.

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