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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the search is performed by file name rather than ID, but it does not disclose additional behavioral nuance such as what counts as 'public link sharing', how the user email is used, or whether only the first match is evaluated. No contradiction with annotations exists.

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 a single, front-loaded sentence with no filler. It communicates the essential action and outcome immediately, and every word contributes to the tool's purpose.

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 strong annotations, 100% schema coverage, and the presence of an output schema, the description covers the core intent well. The only notable gap is the potential ambiguity around what exactly qualifies as 'public link sharing' and whether the tool returns a simple boolean or detailed sharing information, but the output schema likely addresses the return format.

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%, including a notably detailed explanation of the drive_id parameter and its effect on the underlying files.list call. The description itself adds no new parameter-level meaning beyond restating that the tool searches by file name and inspects public link sharing, so the schema carries the load.

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 and resource: 'Searches for a file by name and checks if it has public link sharing enabled.' This clearly distinguishes it from siblings like get_drive_file_permissions or get_drive_shareable_link, since the focus is specifically on detecting public link sharing rather than listing permissions or retrieving links.

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 implies the usage context: use this tool when you need to verify whether a file is publicly shareable via link. However, it does not explicitly state when not to use it or name alternatives such as get_drive_file_permissions or get_drive_shareable_link, leaving the routing decision to the agent's inference.

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 safety profile (non-read-only, non-idempotent, non-destructive), so the bar is lower. The description adds useful context — the copy 'maintains all formatting and content from the original' and can be placed in a new location — but omits copy-specific behavioral caveats such as whether sharing settings or permissions are inherited by the copy, which agents often need for Drive operations. 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?

Three compact sentences with the core purpose front-loaded in the first. The third sentence earns its place by adding the fidelity guarantee (formatting and content preserved), while the second is largely redundant with the first plus the schema — a minor flaw, not a structural problem.

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?

The output schema and 100% parameter coverage give the agent a complete input contract, and annotations cover mutability and safety, so return values need no explanation. What is missing are copy-specific caveats that matter for correct invocation: whether permissions are inherited by the copy, whether a copied native Google file stays in its original format, and the access required on the source file.

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 schema already documents file_id, new_name including the 'Copy of [original name]' default, parent_folder_id defaulting to root, and user_google_email. The description restates 'new location' and 'optional new name' at a high level but adds no meaning beyond what the schema's parameter descriptions already provide.

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 first sentence names a specific verb+resource: 'Creates a copy of an existing Google Drive file,' which clearly separates it from creation tools like create_drive_file. However, it never explicitly names a sibling it is NOT, and the second sentence's reference to 'the template document' slightly muddies whether this operates on one specific template or on any arbitrary Drive file.

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?

No sentence tells an agent when to choose this tool versus alternatives such as create_drive_file (blank new file), import_to_google_doc (converting imports), update_drive_file (editing an existing file), or get_drive_file_content (reading). Among roughly 100 sibling tools, the only routing signal is the word 'copy' itself, which is definitional rather than actual 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?

Annotations already convey the key behavioral traits: non-read-only, non-idempotent, non-destructive, open-world. The description confirms the mutating creation behavior and adds shared-drive support as extra context. It does not detail auth requirements or side effects, but the annotation coverage lowers the burden.

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 a single, front-loaded sentence that states the core action first and adds the shared-drive qualifier without redundancy. It contains no filler and does not repeat schema or annotation 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 straightforward create operation, the description, schema, and annotations together give an agent enough to invoke the tool correctly: required parameters are documented, safety traits are annotated, and an output schema exists. Minor details like permission prerequisites are unstated but are not essential for basic selection and invocation.

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 schema already documents all parameters. The description's shared-drive mention aligns with and echoes the existing parent_folder_id schema note rather than adding materially new parameter meaning.

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 and resource: 'Creates a new folder in Google Drive.' It clearly distinguishes from siblings like create_drive_file by limiting the action to folders, and it adds the meaningful shared-drive capability without ambiguity.

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 the tool: creating folders in Google Drive, including within shared drives. It does not explicitly name alternatives or exclusions, but the resource type is unambiguous enough that an agent can route to this tool for folder creation versus file creation.

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 indicate a write operation (readOnlyHint: false) and non-destructive behavior (destructiveHint: false). The description adds valuable behavioral context: it supports creation within shared drives and accepts either direct content or a fileUrl for fetching content. This goes beyond the structured annotations and helps the agent understand key execution modes, though it could disclose more about side effects (e.g., auto-conversion 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 description is two sentences long, front-loaded with the primary action, and includes only essential details. There is no redundancy or filler, making it easy to parse and act upon.

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 that an output schema exists (so return values are defined) and annotations cover key safety hints, the description covers the main context: what the tool creates, where it can create, and how content is supplied. It does not address edge cases like precedence when both content and fileUrl are provided, but for a creation tool this is minor and leaves the overall description reasonably complete.

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 86%, which is high, so the baseline is 3. The description adds relational meaning that the schema does not explicitly state: 'content' and 'fileUrl' are mutually exclusive alternatives for supplying file content. This clarifies the intended usage of the parameters and earns a point above baseline.

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 action ('Creates a new file in Google Drive') and adds a distinguishing scope ('supporting creation within shared drives'). This differentiates it from siblings like create_drive_folder or copy_drive_file, which create or copy different entity types.

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 implies usage: if you need to create a file in Drive, this is the tool. It mentions support for shared drives and content sources, but does not explicitly contrast with alternatives (e.g., when to use import_to_google_doc or create_resumable_upload_session). While the context is clear, exclusions or explicit alternative references are absent.

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 indicate non-read-only, non-idempotent, non-destructive behavior. The description adds valuable behavioral context: the returned upload_url is used to PUT raw bytes directly to Google, only the short URL travels through MCP, and the bytes bypass MCP transport limits. 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?

Three sentences, front-loaded with the primary purpose, followed by concise operational detail. Every sentence earns its place; 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?

Given the tool's moderate complexity, the presence of an output schema, and annotations, the description is complete: it explains the two-phase upload flow, the reason for the resumable session, and how the returned URL is used. No significant gaps remain for an agent to select and invoke the 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 description coverage is 80%, so the schema already documents most parameters well. The description does not add parameter-level meaning beyond the schema, but it does explain the overall flow with upload_url. This meets the baseline for high schema coverage without compensating for the undocumented user_google_email.

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 statement: 'Creates a Google Drive resumable upload session and returns the upload URL.' This clearly distinguishes it from sibling tools like create_file or import_to_google_doc by focusing on the resumable session and the returned upload_url.

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 states the intended caller (a skill in claude.ai's sandbox) and explains that this tool should be used to bypass MCP transport limits for large content. It gives clear context on when to invoke it, though it does not explicitly name alternative tools or provide when-not-to-use exclusions.

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?

It discloses the critical, non-obvious behavior that 'Indexes shift... so order edits from the END' and warns that 'stale indexes edit the wrong ranges silently.' This goes well beyond the sparse annotations (readOnlyHint false, etc.) by explaining the failure mode and how to prevent it through writeControl.

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 four sentences, each adding substantive value: purpose, accepted types, ordering strategy, and concurrency control. It is front-loaded and contains 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?

For a tool of this complexity, the description covers all essential operational aspects: supported request types, index-shift ordering, the need to fetch current indexes, and optional writeControl for conflict detection. The output schema exists, so it need not describe return values. This is complete and actionable.

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 75% of parameters, but the description adds meaningful semantic detail. It explains that the requests array can contain any Docs API request type, that indexes shift, and that writeControl should carry the revision id from docs_get. The only undocumented param, user_google_email, is self-explanatory by name.

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 'Apply a batch of edit requests to a Google Doc (documents.batchUpdate)', using a specific verb and resource. It also lists the accepted request types (insertText, deleteContentRange, etc.), which distinguishes it from sibling tools like docs_get or docs_replace_all_text.

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 usage context: 'Get current indexes from docs_get first' and 'order edits from the END of the document toward the start, or send one request per call.' It also explains when to use writeControl. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a full 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond that: it details what the returned body.content contains (index ranges for every paragraph/text run) and how to leverage that data. This is useful, non-redundant information that helps the agent use 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 description is two sentences long, front-loads the core action, and each sentence earns its place. The first sentence states the purpose, and the second explains a practical use of the output. There is no filler, redundancy, or unnecessary detail.

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 output schema exists, the description doesn't need to enumerate return values. It adds contextual value by connecting this tool's output to docs_batch_update and docs_replace_all_text, which are sibling tools, and hints at the multi-tab caveat indirectly via includeTabsContent. It lacks explicit info about auth requirements, but openWorldHint suggests external auth is handled elsewhere. Overall, it is complete enough for an agent 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 input schema already provides descriptions for fields, documentId, and includeTabsContent, covering 75% of parameters. The description mentions the body.content structure but does not add new parameter-level semantics. It doesn't explain user_google_email, but the schema omits a description there too. Since the schema does most of the work, this falls at the baseline of 3.

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 ('Read'), a clear resource ('Google Doc's content and structure'), and identifies the underlying API ('documents.get'). This sets it apart from sibling tools like docs_batch_update or get_file_metadata, 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 explains why this tool is valuable—to obtain startIndex/endIndex pairs needed for docs_batch_update requests and to verify edits. While it doesn't explicitly say 'use this instead of X', it clearly conveys the primary use case and the context in which this tool is necessary, which is more than minimal 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 annotations indicating mutation, the description explains that it uses documents.batchUpdate with one replaceAllText request per item and preserves formatting, adding behavioral context not in annotations. This helps the agent understand side effects.

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?

Two sentences, front-loaded with the core function and followed by a key benefit. Every word earns its place.

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?

The description covers the primary use case, behavior, and safety for templates. Given the output schema covers return values and annotations cover mutation flags, no major gaps exist.

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 75% of parameters with descriptions; the description doesn't add parameter-specific details but ties the replacements to replaceAllText semantics. The user_google_email parameter remains undocumented, but the overall schema coverage makes up for 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?

The description clearly states the tool performs find-and-replace across a Google Doc, with a specific verb ('Replace') and resource. It also distinguishes it from broader tools like docs_batch_update by emphasizing placeholder-friendly behavior.

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 notes it preserves surrounding formatting and is the 'safest way to fill placeholders in a template document,' which gives a clear when-to-use context. It doesn't explicitly mention alternatives, but the context implies this over generic batch update.

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?

While annotations already indicate readOnlyHint=true and destructiveHint=false, the description adds valuable behavioral context beyond these flags. It discloses the size limit (DOWNLOAD_FILE_CONTENT_MAX_MB, default 25 MB), the error behavior for oversized files, and the default export formats for Docs/Sheets/Slides. This transparency helps the agent anticipate outcomes and plan fallbacks, going well beyond the structured 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 well-structured, front-loading the core purpose in the first sentence, then using a bullet list for export formats, and a short paragraph for size limits. Every sentence adds value, but it is slightly longer than strictly necessary. The structure aids readability, but a more concise version could achieve the same clarity with fewer words. Overall, it is appropriately sized for the complexity of the 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 tool has 3 parameters, no output schema, and several sibling tools, the description is remarkably complete. It explains the return format (base64 bytes), export format behavior for native files, the original format for other files, the size limit with its error handling, and the fallback to read_file_content or shareable links. No major gaps remain: the agent knows what to expect and how to handle edge cases, making the description sufficient even without an output schema.

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 67%, with fileId and export_format having schema descriptions but user_google_email having none. The description enriches export_format semantics by specifying default export formats (e.g., Docs -> PDF/DOCX, Sheets -> XLSX/PDF/CSV, Slides -> PDF/PPTX), which the schema's simple options list does not provide. However, it does not add any information about user_google_email, leaving that parameter under-described. This is a good but not perfect compensation for the coverage gap.

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 purpose: 'Downloads a Google Drive file and returns its raw bytes as a base64-encoded blob.' It uses a specific verb ('downloads') and resource ('Google Drive file'), and further distinguishes itself by describing export behavior for native Google files and the fallback to read_file_content for large files. This makes it distinct from siblings like read_file_content which handles text extraction.

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 guidance on when to use this tool versus alternatives. For large files, it states that an error 'pointing to read_file_content for text extraction, or a Drive shareable link as a fallback' is returned, directly indicating the alternative. It also explains the export format options for different Google native file types, helping users decide when to specify export_format.

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=true and destructiveHint=false, establishing the safety profile. The description adds the specific scope of 'including sharing permissions,' which clarifies the returned metadata. However, it does not add further behavioral context such as whether the operation requires prior authentication (though openWorldHint is true) or how permissions are represented, so it provides only marginal value beyond the 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 a single, focused sentence that is front-loaded with the action and resource. It contains no redundant information and is appropriately sized for the tool's simplicity.

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 tool has only two parameters, a thorough output schema, and strong annotations (readOnly, idempotent, non-destructive), the description is largely complete for a straightforward read operation. The only gap is the lack of usage guidance, but that is captured under a separate dimension. The description sufficiently conveys what the tool does without needing to describe return values thanks to the output schema.

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 descriptions fully cover both parameters (file_id and user_google_email), so the description does not need to add much. It does not explain any additional meaning beyond the schema, such as how the parameters interact or any format expectations. With 100% schema coverage, the baseline of 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 uses a specific verb ('Gets') and identifies the resource ('detailed metadata about a Google Drive file including sharing permissions'). It clearly states the tool's function, though it does not explicitly distinguish it from sibling tools like get_file_metadata or check_drive_file_public_access, so it misses the top score for sibling differentiation.

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 no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or comparisons with sibling tools such as get_file_metadata or check_drive_file_public_access, leaving the agent without usage context.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds no extra behavioral context beyond the read-only nature already implied by 'Gets' and the annotations, such as whether an existing link is returned or whether additional sharing state is involved.

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?

A single, front-loaded sentence states the exact operation and object with no filler. Every word earns its place, and it is appropriately short for a simple read 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 low complexity, two fully documented parameters, rich annotations, and an available output schema, nothing essential is missing. The description adequately orients an agent toward correct invocation without needing to restate structured information.

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 parameters are already fully documented. The description adds no additional meaning beyond what file_id and user_google_email already convey, so it meets but does not exceed the baseline.

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 uses a specific verb ('Gets') with a specific resource ('the shareable link') and explicitly scopes it to 'a Google Drive file or folder.' This distinguishes it from sibling tools like get_drive_file_download_url and get_drive_file_content without needing to open 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 intended use is implied: use when you need the shareable link for a Drive item. However, there is no explicit guidance on when to choose this over alternatives such as get_drive_file_download_url or get_drive_file_permissions, and no mention of prerequisites or exclusions.

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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'single file by ID' scoping, which is useful, but does not describe authentication requirements, return format, or potential errors. Since annotations carry most of the burden, a 3 is appropriate.

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 a single sentence with no filler. It directly states the action, target, and identifier, earning its place without waste.

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 simple metadata lookup with rich annotations and an output schema, the description is largely sufficient. However, the missing guidance on user_google_email and no explicit tie to sibling tools prevent a perfect score. Overall, it provides enough context for basic correct usage.

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 only 50% (fileId is described, user_google_email is not). The description mentions file ID but adds no further meaning for user_google_email. It does not compensate for the missing schema description, leaving parameter semantics incomplete.

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 ('Returns metadata') on a specific resource ('a single Google Drive file'), identified by ID. This distinguishes it from sibling tools like 'read_file_content' or 'download_file_content', which deal with file content rather than 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?

The description implies usage for fetching metadata when you have a file ID, but it does not explicitly state when to prefer this over alternatives or mention any exclusions. Given the simple scope, context is reasonably clear, but there is no direct guidance on alternate tools.

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 discloses behavioral details such as automatic conversion and preservation of formatting, which are not in the annotations. It also warns about file_path memory limitations and recommends avoiding very large files. However, it does not explicitly state that a new file is created (vs. updating an existing one), though that is implied. Overall, it adds meaningful context beyond the 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 concise, consisting of three short sentences. It conveys all essential information without redundancy or unnecessary detail. The structure is efficient, with the main action stated first and operational hints provided afterward.

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 complexity of the tool (7 parameters) and the presence of an output schema, the description is quite complete. It covers the core function, supported formats, and important caveats about file handling. It does not mention the return value, but that is presumably documented in the output schema. The description sufficiently contextualizes the tool for an agent to use it effectively.

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 provides detailed descriptions for each parameter, including specific guidance for file_path and source_format. The tool description adds an extra hint about preferring file_path for batch operations, which is not in the schema. This supplementary guidance improves parameter understanding beyond the baseline, though the schema is already quite thorough.

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 action ('imports a file') with specific formats (Markdown, DOCX, TXT, HTML, RTF, ODT) and the result (into Google Docs format with automatic conversion). It distinguishes the tool by its conversion capability, which is directly relevant to the tool's function.

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 some guidance on parameter choice ('For batch operations, prefer file_path') but does not explicitly compare this tool to alternatives like create_drive_file or import_to_google_slides. It lacks clear when-to-use vs when-not-to-use guidance beyond a single hint, so it is not fully explicit.

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 cover the read-only, idempotent, non-destructive profile. The description adds meaningful behavioral context about drive_id scoping, folder_id relativity, include_items_from_all_drives behavior, and the shared drive container mode. It does not contradict annotations; minor omission is listing depth (immediate vs recursive).

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?

Four dense sentences with no filler. The main action is front-loaded, and the conditional branches are expressed compactly. Every sentence earns its place.

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 high parameter count and two distinct modes, the description covers the primary scenarios and parameter relationships. Minor gaps like pagination behavior and non-recursive listing are largely handled by the schema and output schema, making it fairly complete.

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 all 13 parameters with 100% description coverage, so baseline is 3. The description adds cross-parameter semantics: it explains how drive_id, folder_id, resource_type, and include_items_from_all_drives interact based on whether drive_id is set, which is more than the sum of individual 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?

Description states a clear verb ('Lists') and distinguishes two modes: files/folders vs shared drive containers. It also explains drive scoping behavior, which differentiates it from siblings like search_drive_files.

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 conditional guidance: if drive_id is specified, list within that drive; if not, list My Drive and accessible shared drives; set resource_type to 'shared_drives' for containers. However, it does not explicitly contrast with search_drive_files or state when not to use this 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds context about spanning all drives and excluding trashed items, which is useful. It does not mention pagination behavior or result size limits, but that's minor given 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?

Single, information-dense sentence. Front-loaded with the verb 'Lists' and clearly structured with scope and exclusion 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 the output schema and annotations, the description covers the essential scope and exclusions. Minor omissions like ordering details and pagination are not critical since schema provides page_token semantics.

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 page_size and page_token with descriptions (67% coverage), but user_google_email lacks a description. The description's phrase 'the user' hints at the email parameter but does not fully compensate for the missing schema description. Moderate coverage, so description adds minimal semantic value.

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 clearly states the tool lists recently modified files, specifies scope ('across all drives') and exclusions ('Excludes trashed items'). This distinguishes it from siblings like search_files and list_drive_items.

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 context that this is for recently modified files, but does not explicitly mention when to use it vs alternatives like search_files or list_drive_items. No exclusions or alternative guidance provided.

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 convey that this is a mutating, destructive operation. The description adds specificity by naming revoke and transfer_owner, which are the destructive actions, but it does not disclose side effects, reversibility, or notification behavior beyond what the schema already documents.

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 two sentences, front-loads the tool's purpose, and contains no filler. Every sentence contributes to understanding what the tool does.

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 14-parameter tool with five action branches, the description is somewhat lean, but the input schema richly documents each parameter and the output schema handles return values. The main gap is unresolved overlap with the sibling set_drive_file_permissions tool, which prevents a higher completeness score.

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%, with each parameter individually documented in the input schema. The description adds no parameter-level detail beyond the schema, so the baseline score of 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 identifies the resource (Google Drive file and folder access permissions) and enumerates the supported operations: granting, batch-granting, updating, revoking permissions, and transferring ownership. It is specific about scope, though it does not explicitly differentiate from the sibling set_drive_file_permissions tool.

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 phrasing 'Consolidated tool' and 'all through a single entry point' gives clear context that this is the intended hub for permission management. However, it does not name alternatives or state when to use get_drive_file_permissions or set_drive_file_permissions instead, so exclusion guidance is missing.

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 important behavioral details: it retries transient Drive eventual-consistency failures with exponential backoff up to ~30s, and it recommends writeControl to guard against clobbering concurrent human edits. These add meaningful context beyond the readOnlyHint/destructiveHint 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 structured into three short paragraphs—purpose, usage instructions, and retry behavior—all of which directly support tool selection and invocation. Every sentence earns its place, with no filler or redundant 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?

For a batch update tool with a rich schema and output schema, the description covers purpose, invocation pattern, request construction, concurrency safety, and retry behavior. The reference to the helper function and the writeControl source provides the necessary context for an agent to invoke the 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?

The schema already covers requests, writeControl, and presentationId at 75% coverage; the description adds practical meaning by specifying that requests should be built with build_link_requests() and that writeControl should contain a requiredRevisionId from presentations_get. The user_google_email parameter remains undescribed, but overall the description enhances parameter understanding.

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 'Apply a batch of update requests to a Google Slides presentation (presentations.batchUpdate)', which is a specific verb+resource that immediately identifies the tool's function. It explicitly names Google Slides and the exact API method, distinguishing it from sibling tools like spreadsheets_batch_update and docs_batch_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?

The description provides concrete usage context: 'Used by the QBR skill to delete chart placeholders and embed LINKED Sheets charts' and explains how to build requests and pass writeControl. It does not explicitly state when not to use the tool or mention alternatives, but the context is clear enough for correct selection.

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, covering the safety profile. The description goes beyond that by explaining how to use the fields parameter for partial responses and the revision guard, adding valuable behavioral nuance.

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: a single sentence stating the core purpose, followed by a tight bullet list of field mask use cases. Every line earns its place without unnecessary 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?

Given the moderate complexity and the presence of an output schema, the description covers the essential usage. It explains the fields parameter in detail and the revision guard, but does not explicitly state behavior when fields is omitted (e.g., returns full presentation). This is a minor gap but not critical.

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 provides basic descriptions for fields and presentationId, but the description enhances understanding significantly by explaining the structure and purpose of the fields mask (e.g., slides(objectId,pageElements(...))). This compensates for the 67% schema coverage and adds practical value.

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 'Read a Google Slides presentation (presentations.get)', which is a specific verb (read) and resource (presentation). It clearly distinguishes from sibling tools like presentations_batch_update, which handles modifications.

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?

Clear context for when to use the tool (reading a presentation) is provided, but it does not explicitly mention when not to use it or name alternatives like presentations_batch_update. The field mask use cases (slot resolution, embed verification, revision guard) add practical 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 discloses detailed behavioral traits beyond annotations: how each file type is processed (e.g., PDFs via pypdf, images as base64), including fallback to a download hint for scanned PDFs and binary note for unreadable files. This adds substantial context beyond the readOnlyHint/idempotentHint 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 well-structured with a clear lead sentence followed by bullet points separated by file type. Every bullet adds specific behavioral detail, and there is no filler or redundancy. The format makes it easy to scan.

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 an output schema present, return values are already defined. The description covers all major file categories, fallback behaviors, and special cases (images, binary), making it complete enough for an agent to anticipate behavior. It does not need to detail error cases.

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 covers only 50% of parameters (fileId only, and minimally). The description fails to compensate: it does not explain user_google_email, which has no schema description, nor does it add meaning about parameter usage beyond implying fileId is needed. This leaves a critical parameter opaque.

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 action ('Retrieves the content of a specific Google Drive file by ID') and distinguishes itself from the sibling tool download_file_content by emphasizing content extraction with format-specific conversion. It also mentions support for shared drives, clarifying scope.

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 by enumerating supported file types and fallback behaviors, which implies when to use this tool. However, it does not explicitly contrast with alternatives like download_file_content or docs_get, so it lacks explicit exclusions or named 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds shared-drive scope but no behavioral details like pagination or search operator caveats. The schema covers those constraints, so the description is not contradictory but offers minimal added 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?

Single sentence, front-loaded with the key action and scope, zero filler. It is as concise as possible while conveying the core purpose.

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?

The tool has 10 parameters and a rich schema with output schema, but the description lacks usage guidance and differentiation from siblings like list_drive_items. It is complete enough to identify the tool but leaves invocation semantics and comparative use entirely to schema and 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 covers 100% of parameters with detailed descriptions, including caveats about shared drive owner queries. The description itself adds no parameter semantics, but the schema carries the full burden 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 states 'Searches for files and folders within a user's Google Drive, including shared drives' – a clear verb+resource+scope. It distinguishes from list_recent_files by emphasizing query-based search, though it doesn't explicitly name alternatives.

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?

No guidance on when to use search_files vs list_drive_items or list_recent_files. The description lacks any 'when to use' or 'use instead' language, leaving the agent to infer from the name and sibling context.

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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the risk profile is covered without description support. The description adds that the tool mutates link-sharing and file-level settings, but it does not disclose consequences such as revoking anonymous access when link sharing is turned off or changes taking effect immediately. This is adequate but not rich behavioral 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?

Four short, front-loaded sentences, each earning its place: primary purpose, high-level positioning, when-to-use, and when-not-to with routing. There is no repetition or filler, and the structure naturally separates what the tool does from how to choose 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?

An output schema exists and the annotations are rich, so the description need not explain return values or safety profiles. The main gap is the unresolved user_google_email requirement, which directly threatens correct invocation given the tool's stated link-sharing purpose; the routing to sibling tools absent from the list is a secondary but real gap. Overall adequate for a well-schema'd tool, but not fully complete.

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% and each parameter (link_sharing, writers_can_share, copy_requires_writer_permission) has a detailed description, so the schema carries the heavy lifting. The description adds high-level framing that most parameters are optional toggles, but it leaves the required user_google_email unexplained — its role conflicts with the link-sharing positioning, and neither the description nor the schema reconciles this.

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?

"Sets file-level sharing settings and controls link sharing for a Google Drive file or folder" provides a specific verb, resource, and scope, making the tool's function immediately clear. The second paragraph reinforces purpose by positioning it as a high-level tool for common permission changes and explicitly excluding granular user/group permission management, distinguishing it from read-oriented siblings like get_drive_file_permissions.

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 when-to-use guidance ("toggle 'anyone with the link' access or configure file-level sharing behavior") and an explicit exclusion ("For managing individual user/group permissions, use share_drive_file or update_drive_permission instead"). However, those named alternatives are absent from the sibling-tools list (which instead contains manage_drive_access), and the required user_google_email parameter blurs the stated boundary between this tool and individual-user permission tools.

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 this is a write operation (readOnlyHint=false). The description adds that it performs a batch of requests and gives examples of non-destructive operations, but does not discuss partial failure behavior, permissions, or reversibility. It adds modest context beyond 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?

Two sentences, front-loaded with the core action and method, followed by a focused use-case and helper-function pointer. No redundant words.

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?

The tool is complex, but the description covers the main use cases and provides a helper for building requests. It omits discussion of other request types and the purpose of user_google_email, but overall it is adequate given the presence of an output schema and annotations.

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 requests and spreadsheetId, but leaves user_google_email undefined. The description compensates for the complex requests parameter by referencing a builder function (build_batch_requests()) and giving examples. It does not clarify user_google_email, but the other two parameters are well-covered.

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 applies a batch of update requests to a Google Sheet, with explicit mention of the underlying API method (spreadsheets.batchUpdate). It distinguishes itself from siblings like docs_batch_update and presentations_batch_update by specifying Google Sheet, and provides concrete example operations (addChart, repeatCell).

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 indicates this is used by the QBR skill for adding charts and setting number formats, giving clear usage context. It does not explicitly name alternatives or exclusions, but the resource type (Google Sheet) clearly separates it from docs/presentations batch update tools.

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, and non-destructive behavior. The description adds useful context about the API call type and specific use cases for the fields mask, such as retrieving sheet IDs and chart specs, without contradicting 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 a compact two sentences. The first sentence states the primary purpose, and the second provides actionable advice on the fields mask. 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?

Given the output schema, annotations, and simple parameter set, the description provides enough context for correct invocation. It could mention alternatives (e.g., for cell data use read_file_content) but is sufficiently complete for a metadata read 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?

The schema already describes fields and spreadsheetId, covering 67% of parameters. The description adds concrete examples of how to use the fields mask with specific field paths, exceeding the schema's generic 'field mask' note, which helps the agent construct correct requests.

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 reads Google Sheet metadata via the specific API method spreadsheets.get, distinguishing it from sibling tools that read file content or update spreadsheets. It also specifies concrete sub-uses: resolving sheet IDs and verifying charts.

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 context for when to use this tool (reading metadata, resolving sheet IDs, verifying charts) but does not explicitly name alternatives or state when not to use it. It offers practical parameter guidance, which supports usage decisions.

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 minimal annotations, the description discloses that this is a legacy OAuth 2.0 tool, disabled when OAuth 2.1 is enabled, and that authentication is normally handled automatically by the system. It also explains the manual tool's role in re-authentication, proactive auth, and retry scenarios, which is rich behavioral 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 well-structured: a clear opening statement, a critical legacy note, a numbered list of use cases, and a closing recommendation. Every sentence carries distinct information without redundancy or 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?

The description thoroughly covers purpose, usage conditions, alternatives, and legacy/automatic behavior, and the output schema can handle return-value documentation. However, it is not fully self-contained because it leaves parameter semantics unexplained, which is a meaningful gap for an agent deciding what to pass as service_name.

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 has 0% parameter description coverage, and the description does not compensate by explaining either parameter. It never names service_name or user_google_email, nor does it clarify expected formats, allowed values, or how to choose the service. The phrase 'different credentials' only weakly hints at user_google_email, leaving the agent to guess at parameter meaning.

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 purpose: 'Manually initiate Google OAuth authentication flow.' It identifies the specific action and resource, and distinguishes itself from the long sibling list by being the explicit authentication entry point for Google Workspace tools.

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 lists when to use the tool with three concrete conditions and directly advises that in most cases the agent should simply call the needed Google Workspace tool instead. It also covers the failure/retry scenario, making the when-to-use and when-not-to-use guidance unambiguous.

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 destructiveHint=true and readOnlyHint=false. The description adds no behavioral context, such as potential data loss from trashing or parent changes. It merely restates the tool's purpose without disclosing consequences beyond what the annotations already 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 a single short sentence with no redundant words, and it is front-loaded with the verb 'Updates'. It is appropriately concise, though it could arguably include a bit more detail without becoming verbose.

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 having 12 parameters and an output schema, the description is very vague about the scope of updates (e.g., rename, trash, permissions, parent changes) and lacks any context for when to use this tool. The schema compensates with parameter descriptions, but the overall tool guidance is incomplete for an AI agent.

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 covers all 12 parameters with descriptions (100% coverage). The description adds no additional parameter semantics; the schema already provides details like 'Whether to move file to/from trash' for the trashed parameter.

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 ('Updates') and resource ('Google Drive file'), clearly indicating it modifies file metadata and properties. However, it does not distinguish from sibling tools like 'set_drive_file_permissions' which also updates file properties, so it lacks explicit differentiation.

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?

No guidance is provided on when to use this tool versus alternatives such as 'create_file', 'copy_drive_file', or 'manage_drive_access'. The description gives no context, prerequisites, or exclusions, leaving the agent to infer the appropriate usage scenario.

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