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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds privacy behavior ('only returns busy time blocks (not event details)'), permission requirements for other calendars, and the return format. This is useful context 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?

Well-structured with labeled sections (Args, Returns, Requirements, Examples). The main purpose is front-loaded, and every section contributes non-redundant, practical information. Length is appropriate for the tool's complexity.

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 lacking an output schema, the description clearly explains the return format ('For each calendar, a list of busy time blocks') and permission prerequisites. Examples cover both single and multiple calendar scenarios, making the tool fully 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?

Schema description coverage is 100%, so baseline is 3. The description repeats parameter info but adds value with concrete examples (e.g., ISO 8601 format, calendar ID examples) that clarify real-world usage beyond the schema definitions.

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: 'Check availability (free/busy times) for one or more calendars within a time range.' It clearly distinguishes from sibling tools like calendar_list_events by explicitly noting it returns only busy blocks, not event details, for privacy.

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 states a clear use case: 'useful for finding available meeting times across multiple people.' It also lists permission requirements for checking other people's calendars, giving contextual guidance. It stops short of explicitly naming alternatives or when-not-to-use, which would earn 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read. The description adds value by specifying the return contents (description, attendees, conference info) and the default calendar and response format, going 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?

The description is short and well-structured with a clear action line, a bulleted args list, and a returns line. Every sentence serves a purpose with no filler, making it highly concise and scannable.

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?

Since there is no output schema, the description appropriately explains the return value as 'full event details including description, attendees, and conference info'. Combined with complete parameter documentation and informative annotations, the tool description provides sufficient context for an agent to use 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 has 100% coverage with descriptions for all three parameters. The description's 'Args' section essentially restates the schema entries without adding new semantic context, 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 uses the specific verb 'Get' with the resource 'calendar event' and scopes it to 'specific', clearly distinguishing it from sibling list tools like calendar_list_events. It also specifies that it returns full event details, making the tool's function 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 implies usage when you have a specific event_id, but it does not explicitly contrast with alternative tools such as calendar_list_events or calendar_freebusy_query. There is no exclusionary guidance, so the usage context is only slightly implied rather than clearly differentiated.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: it specifies the scope ('accessible to the user'), the return format (IDs, names, access roles), and the response_format parameter options. This goes 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?

The description is extremely concise: a single clear purpose statement, a minimal Args section, and a Returns section. Every sentence earns its place, and the structure is 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?

For a simple read-only list tool with one optional parameter, the description adequately covers the purpose, parameter semantics, and return structure. No output schema is present, but the Returns section explains the output. Minor gaps (e.g., pagination or error behavior) are not significant for this tool's simplicity.

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 the schema already documents response_format with its enum, default, and meaning. The description repeats this information and adds the default value, but provides no additional semantic detail beyond the schema. 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 the tool's purpose: 'List all calendars accessible to the user.' It uses a specific verb and resource, and the return details (IDs, names, access roles) further clarify scope. This distinguishes it from siblings like calendar_list_events, which lists events rather than calendars.

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 context ('when you need the list of accessible calendars') but does not explicitly state when to use this tool over alternatives or provide exclusions. The sibling tools are largely different resources (drive, docs, sheets), so the context is clear, but no direct guidance is given.

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 safe read-only operation. The description adds useful behavioral context: default values for max_results, single_events, order_by, and response_format, along with the return structure (title, time, location, attendees). This goes beyond the minimal safety profile.

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 Args, Returns, and Examples sections. It is slightly repetitive of schema defaults but remains efficient and front-loaded with the core purpose. Examples earn their place by clarifying parameter combinations.

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 9-parameter tool with no output schema, the description covers all parameters, provides a return-value summary, and gives practical examples. It is complete enough for an agent to select and invoke the tool correctly, though it lacks explicit error-handling or auth notes.

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?

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description reinforces parameter meaning by repeating key defaults and providing illustrative examples (e.g., time range format, query usage), adding practical value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List events from a calendar within an optional time range' with a specific verb and resource scope. It distinguishes from sibling tools like calendar_get_event (single event) and calendar_freebusy_query.

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 concrete examples ('Today's events', 'Search meetings', 'Next 7 days') that illustrate common usage. However, it does not explicitly contrast with alternatives 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 indicate destructiveHint=true and readOnlyHint=false. The description adds concrete behavioral detail by showing example request types, including deleteContentRange, insertText, and insertTable, and by exposing the return object with writeControl. This goes beyond the generic annotation to clarify what kinds of mutations are possible and what response to expect.

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 one-line purpose, then clear parameter definitions, followed by c compact examples of request types, and finally the return format. Every section adds value, and the examples are formatted concisely. There is no redundant 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?

For a complex tool without an output schema, the description covers the essentials: input parameters, request type examples, and the return structure. It omits details like request ordering, error handling, and the full API schema, but it provides a solid baseline and directs users to official documentation. Given the complexity, this is 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?

The schema provides only generic descriptions for document_id and requests. The description significantly enriches the 'requests' parameter by supplying five concrete JSON examples for common operations (insertText, deleteContentRange, updateTextStyle, insertInlineImage, insertTable) and a pointer to the full API schema. This transforms a vague array parameter into actionable guidance.

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 starts with a specific, actionable verb phrase 'Apply batch updates to a Google Doc' and lists the exact types of modifications (insert/update/delete text, formatting, images, tables). This clearly distinguishes it from sibling tools like docs_get_document (read-only) and docs_create_document (creation).

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 implicitly defines its use case as modifying an existing Google Doc via batch operations. It does not explicitly mention alternatives or when not to use it, but the list of common request types and the resource mention make the intended usage clear. Sibling tool names reinforce the distinction.

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 indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds useful behavioral context by specifying the return structure (documentId, title, revisionId) and providing examples of creating empty versus content-bearing documents. It does not contradict 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 and concise: a one-sentence summary, a clear argument list, a return type, and practical examples. Every section contributes directly to understanding how to use the tool, with no wasted 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?

Given the tool's simplicity and the rich schema coverage, the description is nearly complete for an agent to invoke it correctly. It includes parameter details and return format. However, it omits any mention of when to use this tool versus alternatives (like docs_batch_update) or any side effects (e.g., the document appears in Drive), which would make it 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 the description lists both parameters with explanations that mirror the schema nearly verbatim. It adds some value through usage examples, but the parameter semantics are already fully captured by the schema, so the description provides no significant new meaning beyond what the schema offers.

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: 'Create a new Google Doc with an optional initial body.' This uses a specific verb ('Create') and resource ('Google Doc'), and it distinguishes from siblings like docs_get_document (read) and docs_batch_update (modify), as well as sheets_create_spreadsheet (different resource type).

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 the tool (creating a new document, with or without content) through the summary and examples. However, it does not explicitly mention alternatives or when not to use this tool versus other sibling tools, so it lacks explicit 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 and idempotentHint=true, so the safe read-only nature is covered. The description adds context by detailing the return structure (title, content, metadata, JSON fields), which helps the agent anticipate the response. 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 well-organized with Args, Returns, and Examples sections. Every line serves a purpose, providing necessary information without unnecessary verbosity. The main purpose is front-loaded, and the example makes usage concrete.

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 of the tool (2 params, simple read operation), the description is complete. It covers input parameters, output structure (including JSON format), and a concrete example. No output schema exists, but the description sufficiently explains what the agent will receive.

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% with both parameters documented. The description adds extra value by specifying that document_id is found in the URL after /d/, and clarifies the response_format default and enum values, which are also in the schema but reinforced with explicit examples.

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 'Retrieve' and resource 'Google Doc content by its ID', clearly distinguishing it from sibling tools like docs_create_document or drive_get_file. The purpose is unambiguous and directly reflects 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 clearly implies when to use this tool: to get the content of a specific Google Doc. It provides context on how to use it via arguments and return values, but does not explicitly exclude alternatives or mention when not to use it. This is clear context without formal 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?

The annotations already declare readOnlyHint=false and destructiveHint=false, so the tool is understood to be a safe write operation. The description adds the return structure (id, name, mimeType, webViewLink) but does not disclose additional behavioral details like permission requirements or side effects. This adds some value but not deep 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-organized with Args, Returns, and Examples sections, making it easy to scan. It is front-loaded with a clear purpose and avoids unnecessary prose. The Args section duplicates schema information slightly, but it is not excessive.

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 simple and the description provides all essential information: purpose, parameters, defaults, return structure, and examples. Although no output schema is provided in the structured data, the Returns field fills that gap. The description is complete for a copy operation.

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 three parameters with full descriptions, so schema coverage is 100%. The description repeats the parameter details and adds usage examples, but does not provide new semantic meaning beyond the schema. This meets the baseline for high coverage.

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 'Create a copy of a file in Google Drive', which clearly states the verb+resource. This distinguishes it from sibling tools like drive_get_file (read) and drive_list_files (list), and it stands apart from sheets_duplicate_sheet which targets sheets.

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 usage is clear from the description and examples (copying with a new name or into a folder), which implies when to use this tool. However, it does not explicitly mention when not to use it or contrast with alternative tools, so it lacks explicit 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 indicate readOnlyHint=false (mutation), idempotentHint=false, and destructiveHint=false. The description adds behavioral context beyond those by explaining the anchored/unanchored behavior and documenting the return object shape. It does not contradict any annotation, and while it omits details like permissions or notification side effects, the description adds meaningful transparency for the core 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 front-loaded with a clear starting sentence and uses structured sections (Args, Returns, Examples) that each earn their place. It is detailed but not bloated, and the examples are concise and illustrative.

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 compensates by including the exact return JSON shape. It covers the required parameters, optional anchoring behavior, and provides two practical examples. For a tool of this complexity (3 parameters, no nested objects), the description is fully sufficient.

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 repeats the parameter descriptions and adds examples, but these examples (anchored vs unanchored) offer only marginal additional meaning beyond the schema's explicit field descriptions. No new parameter semantics are introduced.

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 with a specific verb and resource: 'Add a comment to a Google Doc.' It also distinguishes itself from sibling tools like drive_list_comments, drive_reply_to_comment, drive_resolve_comment, and drive_delete_comment by focusing on the creation action, and clarifies anchored vs unanchored variants.

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 examples of unanchored and anchored usage, which indirectly indicates when to use optional parameters, but it does not explicitly contrast with alternatives or state when-not-to-use. For instance, it does not say 'use drive_list_comments to read comments' or 'use drive_reply_to_comment for replies.' Usage is implied rather than 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 already declare destructiveHint=true and idempotentHint=true. The description adds the explicit warning 'This action cannot be undone,' which reinforces the destructive nature and provides additional context beyond the structured annotations. It does not explain idempotency behavior, but the existing annotation covers that.

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 first line, an Args section, a Returns section, and a warning note. Every sentence earns its place, and it is appropriately sized—neither overlong nor cryptic.

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 purpose, parameters, return value shape, and irreversibility warning. Given the tool's simplicity and strong annotations, this is sufficient for an agent to select and invoke it correctly. No output schema exists, so the Returns example compensates well.

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 provides 100% coverage with clear descriptions for both file_id and comment_id. The description's Args section repeats the schema info without adding new meaning. Per the rubric, baseline for high schema coverage is 3, and no extra value is added here.

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 'Delete a comment from a Google Doc' uses a specific verb and resource, clearly differentiating it from sibling comment tools like create, reply, resolve, and list. It is unambiguous and action-oriented.

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?

Usage is implied by the verb 'delete' and the resource, but no explicit guidance is provided about when to prefer this tool over alternatives. There is no mention of preconditions or exclusions, though the 'cannot be undone' note offers a hint about appropriate caution.

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 as readOnly and idempotent per the hints. The description adds behavioral detail beyond those hints by specifying supported file types (PDFs, images, binary) and that binary content is returned so Claude can read it directly. 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 well-organized with clear Args, Returns, and Examples sections. It is concise, front-loads the main purpose in the first sentence, and every part serves a purpose without 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 single-parameter read-only tool, the description sufficiently covers purpose, input format, and return value. It misses minor details like error handling or behavior for text files, but these are not critical given the tool's simplicity and the strong 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 input schema already covers file_id with 100% description coverage. The description adds practical value by explaining how to extract the file_id from a URL (after /d/) and provides a concrete example, which goes beyond the schema's basic description.

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 ('Download and return the content of a file') and the resource ('Google Drive'). It distinguishes itself from sibling tools like drive_list_files or drive_copy_file by specifying that it retrieves file content, not metadata or copies.

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 a clear context for when to use the tool (when you need the actual file content) and includes examples for extracting file_id from URLs. It doesn't explicitly mention exclusions or alternatives, but the purpose is obvious enough for the agent to select it correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond these annotations, including pagination via page_token, the ability to include deleted comments, and the return structure (comments list and next_page_token). This exceeds the baseline and provides meaningful transparency.

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, starting with a one-sentence summary, followed by organized Args and Returns sections. Every sentence provides useful information, and there is no redundancy or fluff. The front-loaded summary makes the purpose immediately clear.

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 is complete for a read-only list operation. It covers all parameters, defines the return structure, and explains pagination. Since there is no output schema, the inclusion of the Returns section is particularly valuable. The behavior is fully disclosed given the 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?

Schema description coverage is 100%, so the schema already explains each parameter. The description's Args section mostly restates the parameter names and types, with defaults matching the schema. It adds no significant new meaning beyond what the schema provides, though it does give a clear summary of each parameter's purpose.

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 lists comments on a Google Doc with a specific verb ('List') and resource ('comments'). It is easily distinguished from sibling tools like drive_create_comment or drive_delete_comment, and from drive_list_files which lists files, not 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?

The description provides clear context that this tool is for listing comments on a Google Doc, implying when it should be used. It does not explicitly exclude alternatives or mention when not to use it, but the clear naming and description make the usage obvious. Missing explicit alternative guidance prevents 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by explaining pagination (page_token and next_page_token), default sort order, and output format options, which goes 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 well-structured with an Args section and a Returns section, using concise bullets and a JSON example. Every part earns its place: parameters, defaults, and return format are all clearly laid out without unnecessary elaboration.

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 there is no output schema, the description provides a complete return structure including files fields and next_page_token. All five parameters are described with defaults and allowed values. It lacks explicit error-condition handling or rate-limit notes, but for a list tool with rich annotations, it is sufficiently 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 the description largely restates the schema parameters (page_size, page_token, order_by, mime_type, response_format) with their defaults and enums. It adds minimal new semantic meaning beyond what the schema already provides, 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 states 'List files in your Google Drive' with a specific verb and resource. It does not explicitly differentiate from sibling tools like drive_search_files, but the name and basic purpose are 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?

No guidance is provided regarding when to use this tool versus alternatives. There is no mention of drive_search_files for query-based searching or drive_get_file for retrieving a single file by ID. The description only lists parameters and returns.

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 the return object structure, but does not disclose potential side effects, error conditions, or permissions 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?

The description is a single concise purpose statement followed by neatly formatted arguments and return value. All information is essential and front-loaded, with no 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?

For a simple mutation tool with three string parameters and no output schema, the description adequately covers the purpose, parameters, and return format. It lacks when-to-use guidance and error handling, but the tool's simplicity and annotations make it 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?

The input schema provides 100% coverage with descriptions for all three parameters, and the description repeats the same information without adding examples, constraints, or additional semantics. This matches the baseline for high schema coverage.

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 'Reply to an existing comment on a Google Doc' with a specific verb and resource. It distinguishes itself from sibling tools like drive_create_comment (creates a new comment) and drive_delete_comment.

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 tool is for replying to existing comments but does not explicitly state when to use it over alternatives or any exclusions. Sibling tools are listed but no comparative guidance is 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 disclose readOnly=false, destructive=false, and idempotent=true. The description adds that the result sets resolved=true and returns the comment id, which is useful. However, it does not explain side effects (e.g., whether resolution is reversible, permissions needed) or error behavior. The extra context beyond annotations is present but minimal.

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 well-structured: a one-sentence purpose, a clear Args list, and a Returns block. It is front-loaded and every element serves a purpose, with no fluff or redundant text.

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 simple with only two required string parameters and no nested objects. The description provides the return shape, and annotations cover the mutation and idempotency profile. Missing details like error handling or permission requirements are minor and unlikely to mislead an agent for this basic operation.

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 both file_id and comment_id clearly described. The description repeats this information without adding new semantics such as formats, lifecycle constraints, or prerequisites. Therefore it adds no value beyond the structured schema, fitting the baseline 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 opens with 'Mark a comment as resolved on a Google Doc', using a specific verb and resource. This clearly distinguishes it from sibling comment tools (list, create, reply, delete) and leaves no ambiguity about what it 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?

The description implies when to use the tool (when you need to mark a comment resolved), but provides no explicit guidance on when not to use it or alternatives. Sibling tools like drive_delete_comment or drive_reply_to_comment are not mentioned, so the agent must infer the appropriate choice from 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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds the return JSON structure, pagination token, and default values, providing useful 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 well-structured with clear sections: overview, Args, Returns, and Examples. It's long but every part is informative, and the purpose is front-loaded.

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 fully documents the return format including JSON structure and next_page_token. Parameters are completely described with defaults and enums, and examples illustrate 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 has 100% coverage for all 5 parameters, so the baseline is 3. The description repeats parameter info in Args and adds examples, but doesn't add significant new meaning beyond what the schema already provides.

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 'Search for files in your Google Drive by name or content' with a specific verb, resource, and scope. It distinguishes from siblings like drive_list_files by explicitly mentioning content search.

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 makes it clear this is for searching by name or content, which implies when to use it. However, it doesn't explicitly name alternative tools (e.g., drive_list_files) or state when not to use 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?

Annotations declare it's a write operation (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds important behavioral context: draft is saved but not sent, content_type controls plain text vs HTML, and returns a draft ID/message ID/thread ID. 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?

Although detailed, the description is well-structured with Args, Returns, and Examples sections. The first sentence is a clear summary, and each section adds necessary information 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?

The description includes return fields (draftId, messageId, threadId) since there is no output schema, covers all 7 parameters, and provides usage examples. This makes it complete 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?

Schema coverage is 100% and the description repeats parameter definitions, but it adds value through examples (simple draft and reply draft) and clarifies the reply_to_message_id purpose. This goes slightly beyond the baseline schema-only documentation.

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?

Clearly states 'Create a new email draft in Gmail' with a specific verb and resource. The description distinguishes from sibling Gmail tools (which list/get messages/threads) and clarifies the draft is not sent.

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 useful context: the draft is saved but not sent automatically, which tells agents when to use this tool vs a send operation. However, it does not explicitly name alternative tools or state when not to use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail about return types: images are returned directly, while other files provide download info. This goes beyond the annotations and helps the agent anticipate the response format.

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 Args, Returns, and Examples sections. It front-loads the primary purpose and avoids extraneous prose. The example is minimal but helpful. Minor redundancy exists (filename repeated), but overall it is concise and scannable.

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 no output schema, so the return behavior description is essential and provided (images vs. other files). However, it lacks details on error cases, MIME type handling, or what exactly 'download info' contains. The conflicting filename definition also leaves ambiguity. Given the simple nature of the tool, it's adequate but not 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 coverage is 100%, so baseline is 3. The description adds a useful note that attachment_id comes from gmail_list_attachments, and provides an example. However, it contradicts the schema for 'filename': description says 'for display purposes' while schema says 'used for saving'. This inconsistency reduces trust and clarity.

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 'Download an attachment from a Gmail message', which is a specific verb (download) plus resource (Gmail attachment). It clearly differentiates from siblings like gmail_list_attachments (lists attachments) and gmail_get_message (gets message content). The Args list further reinforces the exact inputs needed.

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 workflow by noting attachment_id comes from gmail_list_attachments, which is a useful cross-tool hint. It doesn't explicitly state when not to use this tool or compare alternatives, but the context is clear enough for an agent to know this is the step after listing attachments.

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 as read-only, idempotent, and non-destructive. The description adds value beyond these by specifying the return behavior: 'Full message content including headers and body text' and the default response_format. This is useful since no output schema exists. It does not contradict 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 compact and well-structured: a one-sentence summary, a clear Args list, and a Returns line. Every sentence is informative and there is no redundant filler. It is front-loaded with the tool's 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?

For a simple two-parameter read tool with comprehensive annotations and full schema coverage, the description is sufficient. It clearly conveys input and output. It could be slightly more complete by noting how this differs from thread retrieval or mentioning attachments, but these are not essential for correct tool 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 fully documents both parameters. The description essentially repeats the schema ('message ID to retrieve', output format options) without adding extra meaning. Baseline of 3 is appropriate because the description provides no additional parameter insights.

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 ('Get') and resource ('full content of a specific Gmail message'), making the tool's purpose immediately clear. It distinguishes itself from sibling tools like gmail_list_messages (which lists summaries) and gmail_get_thread (which retrieves a thread) by focusing on a single message's full content.

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 when you have a message ID and need the full content, but it does not explicitly state when to prefer this over gmail_get_thread or gmail_list_messages. No alternatives or exclusions are mentioned, so the guidance is only implied rather than 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 already disclose read-only, idempotent, and non-destructive behavior. The description adds that it returns all messages with full content and shows the response_format default, but does not add significant behavioral context beyond that. Given the strong annotation coverage, this is adequate but not outstanding.

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 front-loaded with the purpose, followed by a clear Args/Returns structure. Every sentence adds value, with no 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?

For a simple read-only tool with good annotations and full schema coverage, the description is nearly complete. It states the return content and format options. It could mention how to obtain a thread_id or note that large threads may be truncated, but these are not essential for basic 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 100%, so the schema already documents both parameters. The description's Args section restates the schema contents (thread_id, response_format) without adding new meaning or examples, providing no extra 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?

The description uses a specific verb and resource: 'Get all messages in a conversation thread.' This clearly distinguishes it from sibling tools like gmail_get_message (single message) and gmail_list_messages (multiple messages across threads).

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 when to use the tool (when you need all messages in a thread), providing clear context. However, it does not explicitly mention alternatives or exclusions, such as 'use gmail_get_message for a single message' or 'use gmail_list_messages to search across threads.'

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, establishing the safety profile. The description adds value by specifying the exact return structure (attachmentId, filename, mimeType, size), which is especially useful given there is no output schema. It does not contradict 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 compact: a one-sentence purpose followed by a concise args list and a return example. Every part serves a purpose; the return block is valuable because no output schema exists. It is front-loaded and 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?

Given the tool's simplicity, the description covers the essential aspects: purpose, parameters, and return format. It compensates for the lack of an output schema by including a detailed return example. Minor gaps such as behavior on empty message or ordering are not critical for a basic list operation.

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 both parameters. The description repeats the parameter details nearly verbatim without adding extra context or nuances, providing minimal additional semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all attachments in a specific Gmail message,' using a specific verb and resource. It distinguishes itself from siblings like 'gmail_get_attachment' (which gets a single attachment) and 'gmail_list_messages' (which lists messages rather than attachments).

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: it is for listing attachments within a specific message. While it does not explicitly name alternatives or exclusions, the purpose is unambiguous enough for an agent to select it over similar 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 read-only, non-destructive, and idempotent. The description adds that it returns label IDs and types, which is useful, but it does not cover potential edge cases like empty results or ordering.

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, with a clear purpose line, an args section, and a returns section. Every sentence is meaningful and there is 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 simple tool with one optional parameter and no output schema, the description adequately covers the return value (list of labels with IDs and types) and the parameter behavior. No missing information for the intended use.

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 fully describes the response_format parameter with enum and default. The description's mention of response_format adds no additional meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'List all labels (folders) in Gmail', which is a specific verb+resource+scope. It clearly distinguishes from sibling message/thread tools by focusing on labels.

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 context is clear: use when you need to list all labels. It does not explicitly mention alternatives or exclusions, but for a simple listing operation the usage is evident from the purpose.

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 idempotentHint=true, and the description does not contradict this. It adds valuable behavioral details beyond those hints, including the return format (Markdown/JSON), pagination via page_token, default max_results, and the output structure (ID, subject, from, date, snippet). This is especially helpful given there is no output schema to define the return value.

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 Args, Returns, and Examples sections. It is slightly verbose due to repeating some schema details, but every section serves a purpose: examples illustrate usage, returns clarifies output, and parameter defaults are restated for readability. Light redundancy with the schema is acceptable here.

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 5 parameters, no output schema, and relies on annotations for safety, the description fills the gaps well. It explains pagination, return fields, defaults, and even provides multiple use-case examples. This is a complete, self-contained description that allows an agent to select and invoke the tool correctly without additional external knowledge.

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 100% coverage with descriptions for all five parameters, so the bar for added value is higher. The description still contributes by showing concrete query syntax (e.g., 'from:boss@company.com is:unread', 'subject:invoice after:2024/01/01') and clarifying response_format with 'markdown' vs 'json'. These examples go beyond the schema's parameter 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 'List messages from Gmail with optional search filters,' which clearly states the verb (list), resource (Gmail messages), and scope (optional filters). It distinguishes from siblings like gmail_get_message (single message) and gmail_list_threads (threads) by explicitly focusing on messages.

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 strong contextual guidance through examples ('Unread emails: query="is:unread"', 'From specific sender'), making it clear this tool is for listing/searching messages. It does not explicitly name alternatives or state when not to use it, but the scope is evident from the examples and sibling tool names.

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, and destructiveHint=false, so the safety profile is well-covered. The description adds the return structure (threads with message count and snippet) and parameter details, but no additional behavioral traits such as pagination behavior, rate limits, or authentication requirements beyond what the annotations imply.

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 an initial purpose statement, an Args section, and a Returns section. It is concise and front-loaded, though the Args section largely duplicates the schema. It avoids unnecessary verbosity while remaining complete.

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 (5 parameters, no output schema), the description adequately covers the input parameters, defaults, and return format. It lacks usage-guidance context (e.g., when to choose this over gmail_list_messages), but this is already scored under usage_guidelines. The description is otherwise complete for a straightforward list operation.

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?

Input schema covers all 5 parameters with descriptions and defaults, giving 100% coverage. The description repeats these parameter names and descriptions, but adds little semantic value beyond the schema, so 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 states a specific verb ('List') and a specific resource ('conversation threads from Gmail'). This clearly distinguishes it from sibling tools like gmail_list_messages, which lists individual messages rather than threads.

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. The description lists parameters and return values but does not mention situations where gmail_list_messages or gmail_get_thread would be more appropriate, nor does it suggest any 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 indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds valuable behavioral context by documenting the return object structure (spreadsheetId, tableRange, updates) and providing examples of value_input_option and insert_data_option semantics. This goes beyond the annotations and schema, offering insight into what the API returns and how options affect 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 well-structured with 'Args', 'Returns', and 'Examples' sections, making it scannable and readable. It is not overly long, but the Args section repeats schema documentation, which is slightly redundant. The front-loaded purpose sentence is clear and concise, and the example is illustrative without being excessive.

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 with 5 parameters, 2 enums, and no output schema, the description provides a good amount of context: it includes a return schema, examples, and default values. It does not explicitly address error cases, authentication, or rate limits, but for this relatively straightforward append operation, the description is sufficient for an agent to use it correctly. However, it could have explicitly contrasted with sheets_update_values or other siblings to fully complete the picture.

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 thoroughly. The description's 'Args' section largely repeats the schema, though it does provide a concrete example ('Append rows: range="Sheet1!A:D", values=[["Alice", 30, "Engineer", "NYC"]]') which adds slight clarity. However, no new semantic information is introduced beyond the schema, so the baseline score of 3 applies.

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 'Append rows of data to the end of a table in a Google Spreadsheet', using a specific verb ('Append') and resource ('Google Spreadsheet table'). This distinguishes it from sibling tools like sheets_update_values or sheets_clear_values, which perform different operations. No ambiguity about the tool's core 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 implies usage for appending rather than overwriting or updating, but does not explicitly state when to use this tool versus alternatives. It lacks explicit exclusions or mention of sibling tools. The context is clear enough that an agent could infer the use case, but the guidance dimension expects more direct comparison to other 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 readOnlyHint, idempotentHint, and destructiveHint, which cover safety. The description adds valuable behavioral context by specifying the output format options (markdown vs JSON) and including an example JSON response structure, which goes beyond 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?

The description is well-structured with Args, Returns, and Examples sections, and it is front-loaded with the main purpose. However, the Args section largely duplicates the schema, making it somewhat repetitive, though not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by providing a full example of the JSON response format and a usage example. It covers all parameters, defaults, and return behaviors, making it sufficiently complete for an agent to correctly select and invoke the 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 input schema covers 100% of parameter descriptions, so the baseline is 3. The description repeats the parameter details and adds a usage example for ranges, but it does not introduce new semantic information beyond the schema's own descriptions and defaults.

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 cell values from multiple ranges in a single request, using a specific verb ('Read') and resource ('cell values from multiple ranges in a Google Spreadsheet'). This distinguishes it from sibling tools like sheets_get_values (single range) and sheets_batch_update (write operation).

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 primary use case ('multiple ranges in a single request') but does not explicitly mention when to prefer this tool over alternatives like sheets_get_values or sheets_batch_update. There is no explicit exclusion or comparison, leaving the agent to infer the batching advantage.

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=false and destructive=true. The description adds a list of destructive operations (e.g., deleteSheet, mergeCells) but does not explicitly warn about permanence or side effects. While it provides some context beyond annotations, it stops short of fully disclosing behavioral implications.

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-organized with clear sections: summary, args, request types, returns, and examples. While the Args section paraphrases schema descriptions, the added request types and examples are valuable. It is appropriately detailed for the tool's complexity, though slightly long.

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 purpose, parameters, common operations, return shape, and includes examples. It defers to external API documentation for full request schema, which is reasonable given the open-world nature. It is complete enough for an agent to understand and invoke the tool, though it lacks explicit error-handling or permission guidance.

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 for 'requests' is an open object with no structure, and the description compensates by listing valid request types (updateCells, addSheet, deleteSheet, etc.) and providing concrete examples (addSheet, repeatCell). This adds substantial meaning beyond the schema, especially for the request construction.

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 clear verb ('Apply batch updates') and specifies the resource (Google Spreadsheet), then enumerates the range of operations (formatting, charts, filters, conditional formatting). This distinguishes it from siblings like sheets_update_values and sheets_append_values, which focus on simple value updates.

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 lists common request types that imply usage for structural/complex changes, but it does not explicitly state when to use this tool over simpler alternatives like sheets_update_values or sheets_append_values. It lacks clear exclusionary guidance 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 indicate destructive and non-read-only behavior. The description adds valuable context: it preserves formatting, shows the return object, and includes examples like clearing an entire sheet with a sheet name. This goes beyond 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?

The description is concise, well-structured (purpose, args, returns, examples), and front-loaded with the main action. Every sentence has purpose and no 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?

For a simple two-parameter tool with strong annotations and schema coverage, the description is complete. It explains behavior, provides return fields, and covers edge cases with examples. No output schema is needed because returns are described in the description.

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?

Input schema covers 100% of parameters with descriptions. The description reinforces these but also adds an example that clarifies the range parameter accepts a sheet name alone for entire-sheet clearing, which is not explicit in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Clear cell values from a specific range in a Google Spreadsheet (keeps formatting).' This uses a specific verb-action and resource, and the formatting note distinguishes it from sibling tools like sheets_update_values or sheets_append_values.

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 when to use the tool (clearing values while preserving formatting) but does not explicitly mention alternatives or exclusions. The context is clear enough for an agent to differentiate, but no explicit 'use this instead of X' guidance is given.

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 declare mutation and non-idempotency, but the description adds only a bit more context: it mentions that omitting destination_sheet_id creates a new sheet. It does not disclose other side effects, permissions, or potential impacts on the spreadsheet beyond the new sheet.

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 long but extremely well-structured with sections for arguments and examples. Each sentence serves a purpose, and the examples clarify complex nested parameters. The length is justified by the tool's complexity, though a brief summary line could improve scannability.

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 high complexity, the description is remarkably complete: it covers all parameter details, defaults, supported enum values, and edge cases. However, it does not describe the return value or output, nor does it mention prerequisites like whether the spreadsheet must already exist, leaving a small completeness gap.

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 is empty, so the description carries the full burden of explaining parameters. It excels: every argument is documented with types, defaults, enums, and nested structures, plus multiple concrete examples. This adds immense meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a pivot table from spreadsheet data', which is a specific verb and resource. It also notes 'full Google Sheets UI feature support', distinguishing it from other Sheets tools like sheets_get_values or sheets_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 implies usage by detailing every parameter and providing examples, but it does not explicitly state when to use this tool versus alternatives (e.g., when a pivot table is needed as opposed to a simple range update). No exclusions or alternative tool mentions are present.

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 this is a mutating operation (readOnlyHint=false) with potential external side effects (openWorldHint=true). The description adds value by detailing the return payload (spreadsheetId, title, spreadsheetUrl, sheets) and providing concrete examples. It doesn't contradict annotations and enriches the agent's understanding of expected outcomes.

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 efficiently structured: a one-sentence summary, then clearly labeled Args, Returns, and Examples. Every section serves a purpose with no fluff. The examples are concise and illustrative, making it easy for an agent to parse.

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 create operation with two parameters, full schema coverage, informative annotations, and an inline return format, the description is complete. It covers the action, parameters, output structure, and example invocations, leaving no critical gaps.

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 fully documents both parameters. The description repeats the parameter names and adds example values, but it doesn't provide additional semantic meaning beyond the schema. Baseline of 3 is appropriate when the schema carries the primary explanation.

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 'Create a new Google Spreadsheet with optional sheet names.' This uses a specific verb ('create') and resource ('spreadsheet'), and explicitly mentions the optional sheet names feature. It distinguishes from sibling tools like sheets_get_spreadsheet or sheets_update_values by focusing on the creation action.

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 makes it clear this is for creating a new spreadsheet, which is an obvious use case. It doesn't explicitly mention alternatives or when-not-to-use, but the context is unambiguous given the tool name and title. No exclusions are stated, so it meets the criteria for 'clear context, no exclusions' (score 4).

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 communicate that this is a non-read-only, non-destructive write operation. The description adds helpful behavioral detail such as the default name for the new sheet and the structure of the returned object, without contradicting 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 well-structured with clear Args, Returns, and Examples sections. Every sentence adds value, and the one-sentence purpose is direct and sufficient.

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 tool with two required parameters, no output schema, and strong annotations, the description provides enough context: examples, default behavior, output shape, and a pointer to a related tool. It is complete without being over-engineered.

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 descriptions cover all three parameters at 100%, including the default-name behavior and the hint to use sheets_get_spreadsheet. The description repeats these details rather than adding new semantic information, 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 uses the specific verb 'Duplicate' with the resource 'a sheet within the same spreadsheet', making the tool's exact scope clear. This distinguishes it from sibling tools such as sheets_create_spreadsheet and drive_copy_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?

The description clearly establishes when to use the tool (duplicating a sheet inside the same spreadsheet) and even directs users to sheets_get_spreadsheet for finding sheet IDs. It lacks an explicit 'when not to use' or direct alternative comparison, but the context is 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context beyond annotations by warning that include_grid_data 'can be large' and detailing the exact JSON return structure, which is valuable for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with Args, Returns, and Examples. The purpose is front-loaded. It is slightly long but every section contributes meaningful information, 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 read-only get tool, it provides a detailed return format and example. The main gap is the lack of explicit comparison to sheets_get_values, but the description still covers the core functionality and edge cases (large grid data).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds extra value: for spreadsheet_id it specifies 'found in the URL after /d/', and for include_grid_data it warns 'can be large', both 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?

Specific verb 'retrieve' with resource 'Google Spreadsheet' and clarifies it can optionally include cell data. Distinguishes from siblings like sheets_get_values (which focuses on values) and docs_get_document (different resource).

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?

Does not explicitly name alternatives or when-to-use. The phrase 'optionally cell data' implies that for pure cell data, sheets_get_values might be more appropriate, but this is not stated. Lacks explicit 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 establish this as a safe, idempotent read operation. The description adds transparency about return formats (markdown/json) and the structure of JSON responses, which is beyond the annotations. It also documents default parameter values, but doesn't address edge cases like invalid ranges.

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 clear sections for arguments, returns, and examples. It is concise and front-loaded with the core purpose, with no redundant 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 the tool's simplicity and rich annotations, the description is mostly complete. It covers all parameters, provides examples, and describes the JSON return structure. The markdown output format is only described as 'human-readable' without specifics, and there's no mention of error behavior, leaving minor gaps.

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 all four parameters, so the baseline is 3. The description enhances this by providing explicit examples of range patterns (e.g., 'Sheet1!A:A') and the default values for optional parameters. It also clarifies the output structure for the 'json' response_format, adding 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 clearly states 'Read cell values from a specific range in a Google Spreadsheet' with a specific verb and resource, and differentiates from sibling tools like sheets_batch_get_values by focusing on a single specific range. The inclusion of examples reinforces the exact operation.

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 examples but does not explicitly compare against alternatives such as sheets_batch_get_values for multiple ranges or sheets_get_spreadsheet for metadata. Usage guidance is implied by the operation's simplicity, but there are no explicit when-to-use or when-not-to-use statements.

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 destructiveHint=true and readOnlyHint=false. The description adds behavioral context beyond the annotations: it explains how RAW vs USER_ENTERED affect parsing (e.g., formulas and dates), and describes the return object (updatedRange, updatedCells, etc.). This gives a fuller picture of the mutation behavior without contradicting 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 well-structured: a one-sentence summary, then organized parameter details, a return value section, and concrete examples. Every section earns its place, and it remains clear and scannable despite its richness.

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?

There is no output schema, but the description fully explains the return object. It covers all parameters, provides examples for common cases (plain data and formulas), and explains the input options. For a mutation tool with moderate complexity, this is a highly complete description.

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 baseline is 3. The description adds examples for values and explains the value_input_option enum in more depth (e.g., 'USER_ENTERED' parses formulas, dates work). This enriches parameter understanding 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 clearly states 'Write cell values to a specific range in a Google Spreadsheet', using a specific verb and resource. This distinguishes it from siblings like sheets_append_values (which appends) and sheets_clear_values (which clears), and 'specific range' emphasizes the overwrite 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 provides clear context: use this tool to write/update a defined range. It explains the value_input_option semantics (e.g., formulas with USER_ENTERED) and includes examples. However, it does not explicitly contrast with alternatives like sheets_batch_update or sheets_append_values, so it lacks explicit when-not guidance.

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