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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description goes further by disclosing that results are candidates rather than evidence (no matched_text), that truncation yields status PARTIAL with partial_reason max_files, and that a folder's own files precede deeper ones. It does not discuss rate limits or latency, which keeps it short of a 5.

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?

Well front-loaded and organized under headers, but it repeats itself: the max_results/file-vs-folder cap rule appears in the when-to-use block, the closing 'Returns' block, and the schema. The stray 'Citing:' boilerplate is unrelated to the tool and dilutes the payload.

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 carries the return contract itself, listing status, candidates[{file, reason, discovery_method}] and the file fields, plus the PARTIAL truncation signal. Combined with the sibling routing and folder-scoping rules, an agent has everything needed to call and interpret it.

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 baseline is 3, but the description adds genuine meaning: name_pattern is a case-insensitive substring rather than a glob, with a concrete matching example and an explicit anti-example ('*activity*' looks for a literal asterisk). Most other parameter semantics (max_results caps, folder cap, trashed, ISO-8601 bounds) restate the schema, so it lands at 4 rather than 5.

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 ('Recursive metadata discovery' returning SearchCandidate records) and immediately distinguishes itself from siblings by naming drive_ls, drive_grep, and drive_read in the when-not-to-use section. An agent can route between the four tools without opening a schema.

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 an explicit 'When to use' / 'When not to use' pair with named alternatives for each exclusion (contents -> drive_grep, known id -> drive_read, one-level listing -> drive_ls). It also states the preconditions (folder_id inside kb, otherwise AUTHORIZATION_ERROR) and a worked do/don't example.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds deep operational context the annotations cannot: the 20 MB per-file cap, the 200-file per-call limit, deferred_file_ids vs next_cursor stop semantics, AUTHORIZATION_ERROR conditions when file_ids and folder_id conflict, regex timeout and 10,000-expansion limits, and the meaning of EMPTY. This is unusually rich behavioral disclosure for a mutation-free read tool.

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 and sectioned well, but it runs to roughly a thousand words with repeated restatements of the same cursor/deferral logic ('Grep each deferred id on its own,' 'repeat the call') and an out-of-place 'Citing:' block that governs final-answer formatting rather than invocation. Length is partly justified by the pagination complexity, but the redundancy and the off-mission citation paragraph dilute it.

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 compensates by enumerating the return fields (status, files_scanned, bytes_scanned, partial_reason, next_cursor, deferred_file_ids, and the match object shape) plus the whole-line vs per-hit match model for text versus Sheets/Slides/CSV/JSON. For a nine-parameter paged tool, an agent has everything needed to call and resume it 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 description coverage is 100%, so baseline is 3; the description still adds meaning beyond it by explaining when case_sensitive=false is appropriate, when regex=true is legitimate versus a plain phrase, and the performance rationale for passing a single file_id on a ~20 MB file. It also flags INVALID_ARGUMENT on oversized quantified regexes, which the schema does not mention.

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?

Opens with a precise verb+resource+mechanism: 'Deterministic exact match over bytes exported in this call,' then explicitly negates the mechanisms it is not ('Not Drive fullText, not embeddings, not keyword-ranking'). Combined with the sibling references (drive_find, drive_ls), an agent can distinguish this from a filename search or a folder listing without opening any schema.

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 explicit 'When to use' and 'When not to use' sections that name the exact alternatives (drive_find for filenames, drive_ls for listing) and the failure mode of each anti-pattern (passing the whole user question returns EMPTY; semantic synonyms do not match). The do/don't example pair makes the boundary unmistakable.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint and openWorldHint=false, so safety is covered structurally. The description adds real behavioral context beyond that: metadata-only returns, files-before-folders ordering, the COMPLETE/PARTIAL/EMPTY status contract, next_page_token/partial_reason, and AUTHORIZATION_ERROR for folders outside kb. It stops short of a full 5 only because the embedded citation instruction is unrelated to the operation's behavior.

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?

The core is well front-loaded with clear headings, tight bullet lists and paired examples. However, the 'Citing:' paragraph is a foreign output-format instruction that has nothing to do with selecting or invoking this tool and does not earn its place, adding noise to an otherwise economical definition.

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?

No output schema exists, so the description carries the return contract itself — and it does: status enum, the exact child object fields, next_page_token/partial_reason, and ordering. Combined with the routing guidance and parameter semantics, an agent has everything needed to call this 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 description coverage is 100%, so the baseline is 3. The description still adds value: the do/don't examples show a concrete folder_id+max_results invocation, and it ties max_results to the PARTIAL/next_page_token loop so the agent understands the pagination workflow rather than just the field bounds.

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?

Names a specific verb+resource ('List the immediate children of one Drive folder') and adds a scope qualifier ('Metadata only — no file bodies'). The when-not-to-use section explicitly contrasts it with drive_find, drive_grep, and drive_read, so an agent can route correctly without reading sibling schemas.

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 when-to-use conditions (orient a folder, paginate a wide folder with page_token) and explicit exclusions with the named alternative for each (nested descendants → drive_find, file text → drive_grep/drive_read, bare filename → drive_find with name_pattern). The do/don't examples reinforce the boundary case that ls does not search.

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

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

Annotations already cover the read-only, idempotent, non-destructive safety profile, yet the description adds material behavior: no MCP cache so re-read after Drive changes, truncation yields PARTIAL with a prefix, and unsupported types surface as UNSUPPORTED_MIME_TYPE or FILE_NOT_EXPORTABLE rather than an empty success. It also enumerates the return fields, which the absent output schema would otherwise leave unknown.

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 core action, then cleanly sectioned into citing rules, when/when-not, examples, and return shape. It is long, and the copying/citation block is arguably policy rather than tool documentation, but nearly every line carries actionable information for invocation.

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?

Despite no output schema, the description enumerates the returned fields and the failure statuses, covers truncation and format edge cases, and routes to siblings. Nothing an agent needs to call 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema only partially conveys: the default export map per MIME type, the INVALID_ARGUMENT outcome for incompatible formats, and the max_bytes truncation-to-PARTIAL contract. Positive do/don't examples reinforce that a filename or question is not a file_id, though some of that restates the schema's own pattern note.

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 ('Export live text for one file_id from Drive at call time') and immediately distinguishes itself from siblings by naming the file_id provenance (ls/find/grep) and the folder_id exclusion. An agent can tell this apart from drive_grep and drive_find without opening any schema.

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 explicit 'When to use' and 'When not to use' sections, each naming the condition and the alternative (drive_grep is cheaper for phrase existence; discover first if you lack a file_id; folders are not readable). This is the model for routing guidance.

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