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

Consistent with the read-only/idempotent annotations ('It changes nothing in Drive or LinkDrop') and adds substantial context the annotations cannot convey: result cap (10), ordering (newest first), duplicate-name caveat, the exact failure modes drive_not_connected and drive_not_granted with their remediation URLs, and an untrusted-content warning about document-authored titles and text.

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-loads the purpose, consumption targets, and scope in the first sentences, then the return shape, then error modes. Dense and largely waste-free, though the two failure-mode sentences are lengthy relative to the rest.

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 no output schema, the description fully specifies the return object (file fields, kind enum, googleEmail) and enumerates the error modes with remediation, so an agent has everything needed to invoke and interpret results.

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%, so the query parameter's syntax and empty-string behavior are already documented; the description reinforces the search semantics and adds the non-obvious alternative that a pasted link is accepted as driveFileId, which is meaning beyond the schema.

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 (find/search) and resource (files in the person's own Google Drive) with explicit scope ('the person's own Google Drive, through the Drive connection they made on LinkDrop's Integrations page') and clarifies 'This tool only lists files.' It also distinguishes itself from downstream siblings by naming lnkdrp_share_pdf and lnkdrp_replace_pdf as consumers of the returned driveFileId.

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?

Clearly states when to use it (finding a file to import into LinkDrop) and notes the alternative path where a pasted Drive/Docs/Slides/Sheets link is accepted as driveFileId with no search. It does not explicitly exclude other scenarios beyond 'only lists files', so it stops just short of full when/when-not routing.

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