drive_delete_file

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds value beyond that: the trash-vs-permanent distinction, the fact that approved arguments (not the second call's arguments) execute, expiry (default 15 min), dedup of identical pending requests, and a 20 req/hour rate limit returning status=rate_limited. It also names auth requirements (connected Google account) and audit logging. No annotation contradiction.

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?

Front-loaded with the purpose and the two-phase model, which is good. However it is long and mixes several distinct concepts (approval channels, expiry, dedup, rate limits, trash semantics, audit log, return shape) into dense prose without structure. Dense but each clause carries information; the cost is readability, not 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 a destructive, human-in-the-loop mutation with no output schema, the description covers execution semantics, safety, recovery path, rate limits, expiry, and auth. An agent has everything needed to call it correctly in both phases and to explain the outcome to a user.

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%, so the schema carries parameter detail. The description reinforces the critical semantic for request_id (execute the approved payload, not the second call's arguments) and notes file_id must come from drive_list_files. This adds real behavioral meaning over the schema for the request_id life-cycle.

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+resource ('Move a Google Drive file to the trash') and disambiguates from siblings like delete_message or delete_folder. The clarification that the file lands in trash (recoverable), not permanent erasure, sharpens the purpose beyond what the name implies.

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 two-phase protocol is spelled out explicitly: first call with no request_id does not execute, gets a request_id; human approval is required out-of-band before a second call executes. It even names what happens if the agent tries to shortcut approval (returns awaiting_approval). The agent knows exactly when to call and how to proceed.

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