Search Google Docs

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

Annotations only supply readOnlyHint and openWorldHint, but the description adds substantial behavioral context: trash/access filtering, word-prefix rather than substring matching (with a concrete 'Prop'/'FYP Proposal' example), Drive's asynchronous indexing lag, and differing result ordering per mode. It also discloses the returned fields and pagination token, which annotations cannot cover.

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 core purpose in the first sentence, then uses a tight bulleted structure for mode-specific behavior, and closes with return fields plus sibling routing. Despite its length, every sentence conveys non-redundant, decision-relevant information.

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?

Although there is no output schema, the description enumerates the return fields (documentId, name, URL, createdTime, modifiedTime) and the nextPageToken pagination mechanism, covering what the output schema would otherwise have to provide. For a 4-parameter read tool with an enum, nothing an agent needs to invoke it 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 coverage is 100%, so the parameter definitions already carry baseline meaning. The description goes beyond that by explaining the semantics of each searchIn value (prefix-matching for name, full-text index for content, relevance ordering for both) and how pageToken pairs with the same query/searchIn — real added value over the schema's terse enum descriptions.

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 ('Search the user's Google Drive for Google Docs by name and/or content') and bounds the result set (only accessible, non-trashed Docs; other file types never included). It explicitly differentiates itself from siblings find_text and list_documents by naming both.

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?

Gives explicit routing: use find_text to locate text inside one specific document, list_documents to list recent documents, and this tool for cross-Drive search. It also explains when each searchIn mode is appropriate and what each returns, so the alternative-selection problem is fully resolved.

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