gdrive_trash

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

No annotations exist, so the description carries the behavioral burden. It discloses that the operation is a soft delete ('recoverable from trash') and offers dry_run=True to preview. It stops short of describing permissions or edge cases, but the core mutation behavior is transparent.

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?

At roughly 90 words, it is short, front-loaded with the core action, and uses clear labeled sections for use/not-use and args. The only minor redundancy is dry_run appearing in both the prose and the arg list.

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 three-parameter mutation with no required parameters and an output schema, the description covers discovery, use cases, and dry-run behavior. It leaves minor ambiguity about identifier precedence but is otherwise complete enough for an agent to invoke 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 0%, and the description compensates by explaining all three parameters: file_name names the target, file_id is the 'stable file ID (preferred when known)', and dry_run 'previews the trash without committing.' It does not clarify whether file_name is required when file_id is absent, or the precedence when both are supplied.

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 opening sentence uses a specific verb and resource: 'Move a Google Drive file or folder to trash.' It also clarifies the scope by contrasting with permanent deletion, distinguishing it from any delete-like operation. The sibling list contains no competing trash tool, so it stands apart.

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?

It explicitly scopes use cases: 'Use this for: soft-deleting... Not for: permanently deleting — not supported by this server.' It also provides a discovery prerequisite: run gdrive_search or gdrive_list_folder first to obtain file_name/file_id. This is unambiguous when-to-use guidance.

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