Search and list files

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

Annotations already declare readOnlyhint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered and the bar is lower. The description adds substantial behavior beyond annotations: trashed files are hidden unless include_trashed=true, names are NOT unique so 'expect several hits and pick by id', incompleteSearch=true means some corpora were skipped, convenience filters are AND-ed with the raw query, and include_all_drives is ignored when drive_id is set. These are exactly the operational edge cases structured hints cannot convey.

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?

Roughly 135 words for a 12-parameter tool with no output schema is appropriately sized, and the first sentence front-loads the core purpose and return fields before the operational caveats follow in logical order. A few details (order_by examples, parent_id 'root', include_trashed default) slightly overlap what the schema already states, but no sentence is filler for a search tool with this many edge cases.

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?

With 12 optional parameters and no output schema, the risk of misuse is high, yet the description covers return format, filter composition, drive scoping, pagination, ordering, trashed-view semantics, name non-uniqueness, and the open-world caveat (incompleteSearch meaning skipped corpora). The openWorldHint annotation is substantiated by concrete guidance to 'narrow the search'. Almost nothing an agent needs to invoke this correctly is missing.

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 description coverage is 100%, establishing a baseline of 3 since each parameter is already documented. The description adds compositional meaning the schema cannot express: the convenience filters (name_contains, full_text_contains, mime_type, parent_id, only_folders) are AND-ed together and with the raw query expression, and it explains the trashed default via the Drive UI's separate trash view. This justifies one point above baseline, though the schema still does most per-parameter heavy lifting.

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 and resource ('Searches and lists files and folders') and enumerates the returned fields (id, name, mimeType, size, parents, driveId, modifiedTime, trashed, starred, webViewLink, shortutDetails, nextPageToken), making the tool's scope unmistakable. This clearly distinguishes it from siblings like get_file (single file by id), list_shared_drives (drives only), and the mutation tools (trash/delete/update).

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?

Provides clear scoping context: parent_id with 'root' targets My Drive's top level, drive_id restricts to one shared drive, include_all_drives=true searches everything, and trashed files require include_trashed=true. It does not explicitly name sibling alternatives such as 'use get_file when you already have the id', though the caveat 'pick by id' implies it — so it falls just short of a 5.

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