Delete a Drive file

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

Annotations already mark destructiveHint=true, but the description adds critical behavioral nuance: default goes to Trash (recoverable), permanent is irreversible, and confirmation with the user is required. This goes well beyond annotations by explaining the recovery path and the need for explicit user consent, covering the key behavioral aspect of the tool.

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 three sentences, front-loaded with the core action, then details irreversible behavior and usage steps. Every sentence adds value without redundancy. It is efficient and well-structured.

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 delete tool with no output schema, the description is complete: it explains what happens by default, how to make it permanent, which parameters to pass, and the safety caution. It covers all essential information an agent needs to call this tool correctly, even among many similar delete tools.

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% with descriptions for each parameter. The description adds value by instructing to pass fileId from list_drive_files and emphasizing confirm:true, which clarifies that confirm is effectively required even though the schema's required array only lists fileId. This bridges a gap between schema and actual usage.

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 clearly states the action: 'Delete a Drive file.' It specifies the resource and the verb, and distinguishes from siblings like update_drive_file, get_drive_file, and list_drive_files. It also adds nuance about trash vs permanent deletion, making the purpose unmistakable.

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 practical usage hints: 'Pass fileId (from list_drive_files) + confirm:true' and explains the permanent option. It implicitly signals when to use this tool (when deleting a Drive file), though it doesn't explicitly contrast with alternatives. The context is clear and actionable, but lacks an explicit 'when not to use' statement.

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