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

Goes well beyond the annotations by revealing non-idempotency ('each retry would create another copy'), the fresh-fileId return behavior, default naming quirks, and that comments and permissions are not copied. No contradiction with the annotation hints.

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?

Five dense sentences, with the core action front-loaded. Every sentence earns its place by adding a distinct operational fact—naming defaults, folder exclusion, copied metadata, or retry behavior—with no fluff.

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 3-parameter tool with no output schema, this description provides complete context: return value, supported file types, folder limitation, metadata exclusions, and retry handling. Combined with the schema, the agent has everything needed to invoke 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?

The schema already covers all parameters (100% coverage), and the description adds meaningful detail beyond it: name defaults to the original name (not 'Copy of ...'), and parent_id defaults to the original's parent for My Drive files. This enriches the schema instead of repeating it.

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 'Copies a file and returns the new copy's metadata,' specifying a clear verb and resource. The phrase 'the original is untouched' distinguishes it from move/delete siblings, making its purpose unambiguous.

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-not-to-use guidance: folders cannot be copied, and names the alternative workflow (create_folder + copy_file per file). It also tells the agent to check with search_files before retrying after an ambiguous failure, which is actionable usage guidance.

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?

The annotations already show readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds meaningful behavioral context beyond those flags: duplicate names are allowed in the same parent, the parent_id can target a shared drive, and the tool returns id, name, parents, and webViewLink. This is especially helpful because there is no output schema.

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?

Three sentences deliver the core action, return values, parameter meaning, and duplication warning without any filler. The most important caveat about duplicates and search_files is placed at the end but still earns its place because it prevents harmful duplicate calls.

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 two-parameter create operation with no output schema, the description is complete: it explains what is created, what is returned, how parent_id behaves, and how to avoid unwanted duplicates. The annotations and full parameter coverage fill the remaining operational context.

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% and the parameter descriptions already document that name need not be unique and parent_id is a folder/shared-drive id that defaults to My Drive root. The description mostly restates this, adding only the literal 'root' value and reinforcing the duplicate-name caveat. That is useful but does not substantially exceed the structured 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?

The description states a precise verb and resource: it creates a Drive folder with the mimeType application/vnd.google-apps.folder, and names the returned fields. It also distinguishes itself from the search_files sibling by addressing duplicate-folder handling, so an agent understands exactly what this tool does.

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 gives explicit guidance: if the folder might already exist, search_files should be called first and the existing id reused instead of calling create_folder. This is a clear when-not-to-use condition and identifies the alternative tool.

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?

Annocations already mark this as destructive and non-idempotent, but the description goes much further: no undo, no 30-day grace, folder descendants are deleted with it, and the API returns an empty 204 mapped to {ok:true}. This gives the agent a realistic model of what invoking it actually does.

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?

Every sentence carries meaningful information: the destructive nature is front-loaded, the sibling alternative is named, the permission requirement is explicit, and the return value is specified. Though the description is long, no sentence is wasted for a high-stakes destructive tool.

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?

Given the destructive annotation, the single parameter with complete schema coverage, and no output schema, the description covers all the key operational facts: irreversible action, scope of deletion, authorization need, alternative tool, and return shape. An agent has enough to decide whether to use this tool and what the outcome looks like.

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%: file_id is already documented in detail, including examples of where to find it and notes that folders and shared-drive items count as files. The description adds context about folders and descendants, but does not substantially add new meaning to the parameter itself, so the baseline 3 is appropriate.

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 description clearly states a specific action (permanently delete a file), the resource (file), and the critical scope (bypassing trash with no undo). It explicitly differentiates itself from trash_file, so an agent can distinguish between destructive and reversible deletion without opening 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?

The description gives explicit usage guidance: use trash_file unless the user has confirmed permanent, unrecoverable deletion. It also states the permission prequisite (ownership or organizer on a shared drive), so the agent knows when the tool is callable and when it is not.

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?

Even with readOnly/idempotent annotations, the description adds meaningful behavioral detail: overwrite refusal unless overwrite=true, inline size/type limits, rejection of Google-native files, shortcut resolution, and abuse-download restrictions. No contradictions with annotations.

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 description is front-loaded with the core action, then uses compact conditional clauses to cover modes, exceptions, and edge cases. Every sentence carries essential routing or behavioral information without filler.

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 still tells the agent what to expect in each mode (saved_to/bytes vs inline content) and all relevant caveats. An agent has enough information to decide when and how to invoke the tool, including what to do for Google-native and flagged files.

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 real value beyond the schema: it explains the overwrite refusal behavior and the owner-only constraint on acknowledge_abuse. It could have also clarified file_id, but the schema already documents that adequately.

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 description opens with a specific verb and resource ('Downloads a binary file's bytes') and immediately clarifies the two operating modes. It also explicitly separates itself from export_file for Google-native files, making sibling differentiation clear.

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?

The description gives concrete decision rules: use save_path for writing to disk, inline return for small text files, export_file for Google-native files, and acknowledge_abuse for flagged files. It explicitly names an alternative tool and the condition that selects it.

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?

Beyond the annotations, the description discloses concrete behavior: exports are capped at 10 MB, only small textual exports under 100 KB return inline as content, Sheets exports only the first sheet, and save_path writes output to disk. These are non-obvious behavioral traits an agent needs to invoke the tool correctly.

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 first sentence front-loads the core purpose, and every subsequent segment earns its place. The MIME mapping is dense but necessary and clearly organized by source type. There is no filler or repetition of schema details.

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?

Given no output schema, the description adequately covers return behavior, size limits, unsupported file types, and where to route for alternatives. Combined with the schema's save_path requirement note, an agent has everything needed to call this tool 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?

While the schema has 100% parameter coverage, the description adds critical semantics: the full MIME type mapping per Google file type, the meaning of save_path versus inline return, and the overwrite behavior context. The mime_type schema description even defers to the tool description, making this added meaning essential.

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 description opens with a specific verb and resource: 'Exports (converts) a Google-native file — Doc, Sheet, Slides, Drawing — to a regular format.' It enumerates source types and target formats, and explicitly contrasts itself with download_file for binary files, making sibling differentiation clear.

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?

The description provides explicit routing guidance: 'Binary (non-Google) files are not exportable — use download_file' and 'use the file's exportLinks (get_file) for bigger documents.' It also tells the agent when to use save_path versus relying on inline content.

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 establish read-only/idempotent/non-destructive, so the bar is lower, but the description adds substantial behavior not in annotations: content is never returned, Google-native files lack size/md5Checksum, shortcuts expose target details, and capabilities are included for pre-mutation checks. No contradiction with annotations.

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 core purpose and content exclusion before enumerating return fields. Dense but every segment earns its place, and since there is no output schema the field list is necessary rather than filler.

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?

Given no output schema and a broad metadata surface, the description enumerates all expected fields, flags special cases (Google-native no size/md5, shortcutDetails), and routes content retrieval to named siblings. An agent has enough to invoke correctly without opening any other tool.

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 covers 100% of parameters, so baseline is 3. The description adds a bit beyond schema: it clarifies that fields uses Drive fields syntax and explains the tradeoff of the default projection, and it reinforces file_id semantics. Does not add syntax examples as much as it could, but sufficient bonus.

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?

Description states a specific verb ('Returns a file's metadata'), clearly distinguishes itself from content-fetching siblings by explicitly naming download_file/export_file, and notes Google-native metadata exceptions. Far from tautology; an agent can tell what resource and scope this tool covers.

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?

Explicitly says when not to use it ('never its content — that is download_file/export_file') and tells the agent to check capabilities before mutating, which orients it toward mutation siblings. It also advises using fields projection when the default set is too much or too little, giving a concrete selection criterion.

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, openWorldHint, idempotentHint, and non-destructive behavior, so the bar for additional context is lower. The description adds valuable behavioral context: membership scoping, pagination via nextPageToken, name filtering, and the My Drive exclusion, all beyond what annotations provide.

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?

Three efficient sentences, with the core purpose and output fields front-loaded. Every sentence adds distinct value: scope, downstream usage, filtering, and an exclusion note. No filler or redundancy.

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 appropriately lists the return fields (id, name, createdTime, nextPageToken). It covers pagination, filtering, scope, and how to use the result with sibling tools, making it complete for an agent to call 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 adds meaning beyond the schema by clarifying that name_contains filters by substring and that the output id is meant to be consumed by search_files or as parent_id, giving the parameters practical usage context.

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 description states a specific verb ('Lists'), a precise resource ('shared drives'), and the scope ('the authorized user is a member of'), which unambiguously distinguishes it from the sibling tools like search_files or get_file. It further clarifies that My Drive is not included, eliminating a common point of confusion.

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?

The description provides clear follow-up usage: use the returned drive id as drive_id in search_files or as parent_id to list its root. It also gives an explicit exclusion ('My Drive is not a shared drive and never appears here'), though it does not state when not to use this tool relative to an alternative listing tool.

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?

The description goes well beyond the annotations: it discloses that delete removes comments permanently and is author-only, that quoted_text is display-only with no positional anchoring possible, that deleted comments can appear as tombstones, and that suggestions are untouchable. These caveats align with destructiveHint=true, openWorldHint=true, and idempotentHint=false, with no contradiction.

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 description is dense and front-loaded with the overall purpose followed by per-action behavioral notes. It contains no filler, though it is one long run-on paragraph; breaking the action list into a structured format would improve scanability. Every sentence contributes necessary 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?

For a multi-action tool with 9 parameters and no output schema, the description covers operation semantics, prerequisites, limitations, and the response fields comments carry (author, timestamps, resolved state, quotedFileContent). It does not spell out return shapes for each action, but an agent has enough to select and invoke actions 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 100%, so a baseline of 3 applies, but the description adds conditional-parameter meaning the schema cannot express: which action requires which parameter, that content is a closing note for resolve/reopen rather than body text, and that quoted_text does not actually anchor a comment inside a document. This enriches the static schema 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?

The description opens with a specific verb+resource: 'Manages Drive comments on a file', then enumerates each action (list, get, create, reply, resolve, reopen, delete) with enough detail to distinguish it from any sibling. It also explicitly carves out 'Docs suggestions' as out of scope, so the tool's purpose is unambiguous.

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?

The description gives clear context for when to use each action and notes a key exclusion: 'Not for Docs suggestions — those are a Docs feature this API cannot touch.' It does not point to an alternative tool for suggestions, but it is clear that this tool is the right one for Drive comments and not for that adjacent use case.

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?

The description goes far beyond the annotations, disclosing that user sharing emails by default and can be suppressed, that ownership transfers between personal accounts only invite pendingOwner status until accepted, that changes are live immediately, that removing one's own access is irreversible, and that owner/organizer roles allow permanent deletion. These details align with destructiveHint=true and add critical safety context.

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 description is dense but tightly organized by action, with the core purpose front-loaded and each clause earning its place. Use of semicolons and explicit parameter groupings keeps related information together without unnecessary prose.

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 13-parameter tool with no output schema, the description is remarkably complete: it covers all four actions, parameter prerequisites, notification behavior, ownership-transfer caveats, and destructive consequences. An agent has enough context to invoke any action correctly, including edge cases like shared drives and pending ownership.

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?

Even though schema coverage is 100%, the description adds important operational meaning: send_notification_email defaults to true and must stay true for ownership transfers, allow_file_discovery makes domain/anyone links searchable, expiration_time is unavailable for owners, and fileOrganizer/organizer are shared-drive-only. This meaningfully improves the agent's ability to combine parameters correctly.

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 description opens with 'Manages who can access a file' and then enumerates four concrete actions (list, share, update, remove), each with a clear effect. This unambiguously identifies the resource and operation and distinguishes it from sibling file-management tools like update_file_metadata or manage_comments.

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 clearly explains when each action applies and the prerequisites for each (e.g., update needs permission_id from list, share requires certain type/role combinations). It does not explicitly name alternative sibling tools or exclusion scenarios, but the tool is the only permissions-management tool in the set, so the usage context is clear.

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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds meaningful behavioral detail: the default action removes the file from all current parents, keep_exsisting_parents only adds, shared-drive parent constraints, ownership-rule changes, possible rejection, and even an extra-read cost. This goes well beyond what the annotations alone communicate. No contradiction with annotations; 'destructive' aligns with removing parent relationships and ownership changes.

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 description is compact and front-loaded: the main action and return value are in the first sentence, caveats follow logically, and every sentence earns its place (default behavior, shared-drive exception, ownership/rejection warning, cost note). There is no fluff or repetition of schema descriptions.

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?

Given the operation's complexity, the description explains the return value, the default vs. optional behavior, edge cases (shared drives, ownership, rejection), and performance cost. The input schema already documents parameters, and no output schema exists, so the description's return-value note is necessary and sufficient. An agent has everything needed to decide when and how to call 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?

The schema covers all three parameters at 100%, so the baseline is 3. The description adds value by clarifying the real-world consequence of keep_existing_parents=true and the shared-drive limitation ('files in shared drives always have exactly one parent, so keeping old parents fails there'), which is not fully captured in the schema. It also contextualizes file_id and new_parent_id implicitly via the move semantic. This exceeds the baseline without being redundant.

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 description states a precise verb and resource: 'Moves a file or folder into another folder (or shared drive)' and specifies the return value (id, name, new parents). This clearly distinguishes it from siblings like copy_file, update_file_metadata, and trash_file. The purpose is unambiguous and specific, not a tautology.

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?

The description explains the default move behavior vs. keep_existing_parents=true, and warns that the latter fails in shared drives because they always have exactly one parent. It also mentions that moving between My Drive and a shared drive may be rejected. However, it does not explicitly name alternative tools (e.g., copy_file when the original should be retained), so it stops short of full when-not-to-use guidance.

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?

Beyond the annotations, the description discloses that the Bearer token is added automatically, the method defaults to GET, the response must be JSON, and supportsAllDrives=true must be remembered for shared-drive items. It also includes destructive examples like DELETE drive/v3/files/trash, consistent with destructiveHint=true. No contradiction with annotations.

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 description is dense but every clause adds value: purpose, examples, base URL, auth behavior, method default, and response constraints are all included without filler. The main purpose is front-loaded in the first sentence, followed by useful examples and operational details.

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 generic raw-request tool with no output schema, the description covers base URL construction, query strings, authentication, method defaults, request body semantics, JSON-only responses, and the boundary with binary download tools. Nothing essential is missing for an agent to invoke it correctly and safely.

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?

Although the schema already documents all three parameters, the description adds meaningful context: the path is relative to https://www.googleapis.com, may include a query string, and needs supportsAllDrives for shared drives. It also clarifies that body is for POST/PATCH requests and that method defaults to GET, going well beyond the schema 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?

The description explicitly states this is an 'escape hatch to call any Google Drive API v3 path directly,' with concrete examples such as revisions, changes, trash emptying, generateIds, and resumable uploads. This clearly identifies the resource and scope while distinguishing it from the typed sibling tools it is meant to bypass.

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 says to use this tool 'for requests the typed tools don't cover,' giving a clear selection rule. It also explicitly routes binary media downloads to download_file/export_file, providing a concrete exclusion and pointing to the correct alternatives.

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, 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.

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

The description goes well beyond the annotations by disclosing reversibility, the ~30-day auto-purge window, permission requirements, restore behavior, and the effect on search_files. It also states that trashing a folder includes everything inside, which is important behavioral context the annotations do not 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?

The description is dense but every sentence contributes meaningful information: what the actions do, reversibility and safety, search visibility, permissions, and return values. It front-loads the core action semantics and avoids redundant fluff.

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 two-parameter tool with no output schema, the description is complete: it explains both actions, side effects, permission constraints, visibility in search, and exactly what the response contains. An agent has enough context to invoke the tool correctly and understand the consequences.

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?

The input schema already documents both parameters thoroughly, so the baseline is 3. The description adds extra meaning by explaining folder behavior, the reversible nature of the trash action, and restore's return to the old parent, which enriches the parameter semantics beyond the schema alone.

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 description clearly states a specific action (trash or restore) on a specific resource (files/folders) and explains the two action values. It also distinguishes this tool from delete_file_forever, making its purpose unambiguous relative to siblings.

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?

The description explicitly says trashing is the safe default whenever a user asks to 'delete' something, and instructs that delete_file_forever should only be used when the user explicitly wants permanent deletion. It also provides operational context such as how trashed files behave in search_files, giving clear 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.

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

The description richly discloses behavior: only metadata changes, content is untouched, only provided fields change, at least one field is required, folders are supported, and the return values are listed. This goes well beyond the annotations and clarifies that despite destructiveHint, the file content itself is not modified.

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 description is concise and well-structured: it front-loads the core purpose, then explains scope and exclusions, and ends with return values. Every sentence earns its place and there is no redundant or filler content.

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?

Given there is no output schema, the description appropriately lists the return fields. It also covers edge cases (folders are files), the 'content untouched' caveat, and sibling tool routing. Nothing essential is missing for an agent to use this tool 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 100%, so the schema already documents each parameter. The description adds operation-level semantics by stating 'Only the provided fields change; at least one is required,' which is not otherwise explicit in the schema and helps the agent understand the required combination of optional parameters.

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 description clearly states the tool's function with a specific verb and resource: 'Renames a file and/or updates its description and starred flag — metadata only.' It also explicitly differentiates itself from related operations by noting 'content is untouched' and pointing to move_file and trash_file for other use cases, making the purpose unambiguous.

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?

The description gives explicit usage guidance by stating when this tool is appropriate (metadata-only updates) and when it is not: moving lives in move_file, trashing in trash_file, and uploading content is handled by upload_file. This directly helps an agent select this tool over siblings without ambiguity.

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 only convey readOnly=false, idempotent=false, openWorld=true. The description adds substantial context beyond that: the dual create/replace behavior, the retry-duplicate hazard, the 5 MB multipart cap, the precedence rule that name/parent_id are ignored in replace mode, and the convert_to-to-export_file round trip — all behavioral traits the agent could not infer from annotations alone.

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 and near-zero waste: five sentences cover the split modes, byte source constraint, mime defaults, conversion, size cap, and retry safety. Small deduction because a few phrases (mime defaults, exactly-one constraint) restate what the input schema already documents rather than adding new 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?

For a complex dual-mode tool with 7 params, zero required params in the schema, and no output schema, the description covers all invocation risks: mode disambiguation, conditional requirements, size limit, conversion semantics, and duplicate prevention. The only gap is the return contract — 'returns the file's metadata' names the payload but not its fields, notably the file id, which matters because no output schema exists.

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% and the schema's per-parameter descriptions already state 'required when creating' and 'Exactly one of content/local_path'. The description adds interaction-level semantics the flat schema cannot express — name/parent_id ignored when file_id is present, convert_to producing native Google files, and the 5 MB bound — though some mime_type default text duplicates the schema, so it stops short of a 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?

Opens with a specific verb+resource: 'Uploads content to Drive and returns the file's metadata.' It then discretely separates the create mode (no file_id, name required) from the replace mode (file_id, same id, new bytes), which clearly distinguishes it from siblings like download_file, export_file, copy_file, and update_file_metadata.

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?

Explicit routing to alternatives is present: 'export back with export_file' for converted files, 'larger files need a resumable session via raw_request' past the 5 MB cap, and 'search_files first' before retrying an ambiguous create. Naming the sibling and the condition that selects it leaves nothing to inference.

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