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

With no annotations, the description carries the full burden. It discloses a key behavioral trait: programmatically-created comments are not anchored to specific text. This is valuable context beyond the basic mutation. It doesn't mention permissions or response behavior, but the anchoring limitation is a significant disclosure.

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

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

Two sentences, front-loaded with the primary purpose and immediately followed by the critical replyTo parameter explanation and API limitation. No wasted words, all information is relevant.

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 sufficiently covers the tool's functionality and key limitations. It addresses the main usage scenarios (comment vs reply) and references the source of replyTo IDs. It doesn't detail error handling or return values, but there is no output schema and the tool's behavior is simple enough that this is not a major 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?

Schema coverage is 50% (only account and replyTo have descriptions). The description compensates by explaining replyTo semantics ('a comment id from list_comments') and the behavior when replyTo is omitted. It does not explicitly describe documentId or content, but these are straightforward and self-evident from the parameter names.

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 verb and resource: 'Add a comment to a Google Doc, or reply to an existing comment thread'. It distinguishes from siblings like list_comments and resolve_comment by describing both operations (comment and reply) and referencing the companion tool list_comments for obtaining replyTo IDs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context on when to use the tool: for adding a comment or replying to an existing thread (by passing replyTo from list_comments). It also explains the limitation of new comments not being anchored. However, it does not explicitly exclude alternatives 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?

The description adds behavioral details beyond the schema by noting the return of the new tabId and the optional nesting behavior. However, with no annotations provided, it does not disclose any side effects, permission requirements, or default behavior (e.g., tab placed at end unless index specified), leaving some ambiguity.

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

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

The description is two sentences, front-loads the primary purpose, and uses no redundant wording. Every sentence contributes essential information.

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

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

For a tool with 5 parameters and no output schema, the description provides the core action and return value but omits details such as the 'account' parameter, default placement behavior, and any prerequisites/errors. It is adequate for a simple add operation but not fully complete.

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

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

The description clarifies the purpose of 'index' and 'parentTabId' by mentioning position and nesting, but these already have descriptions in the schema. It does not add meaning for required parameters 'documentId' and 'title', which lack schema descriptions, leaving a coverage gap.

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

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

The description uses a specific verb ('Add') and resource ('new tab to a Google Doc'), clearly distinguishing from sibling tools like rename_tab and delete_tab. It also mentions the return value (tabId), which clarifies the operation's outcome.

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 the tool adds a tab and optionally allows setting position and parent tab for nesting, providing context for how to use it. However, it does not explicitly mention alternatives or when not to use the tool, so it falls short of full guidance.

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

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

With no annotations, the description fully discloses critical behaviors: atomicity, cluster refusal with status 'incomplete', documentTitle verification with 'wrong_doc', expectedChange validation, and the conflicts array with auto-resolution instructions. This is excellent transparency beyond what any schema could convey.

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

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

Every sentence earns its place, covering the core action, the clustering rule, the document check, expectedChange copying, and conflict behavior. Though longer than a simple tool, the complexity justifies the length, and it is front-loaded with the primary 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 7-parameter tool with no output schema, the description is remarkably complete: it explains all failure statuses, the cluster requirement, the conflicts array, and the workflow from list_suggestions. An agent has everything needed to invoke it correctly.

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

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

The schema already covers parameter descriptions 100%, but the description adds crucial semantic guidance: how to populate expectedChange from the suggestion's preview and that multiple resolutions are needed for clusters. This goes beyond the schema's basic field 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 the action: 'Resolve one or more pending suggestions' and differentiates it from sibling tools like list_suggestions (which lists them). It specifies accept/reject semantics and the atomic nature of the update, making the tool's purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly connects to list_suggestions as the source and explains when multiple resolutions are required (overlapping/adjoining suggestions), even noting that a partially resolved cluster is refused. It doesn't explicitly name alternatives or when not to use, but the context is clear enough for an agent to decide.

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?

No annotations are present, so the description must carry full behavioral weight. It discloses that content is rendered as markdown, default placement is My Drive root, and warns about a real failure mode (silent text loss) with inline content. It doesn't mention return values or auth, but for a create operation it offers solid 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?

Three sentences, each earning its place: core creation purpose, folder placement default, and the critical long-document guidance. Information is front-loaded 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?

Given 6 parameters, no output schema, and no annotations, the description covers creation semantics, folder placement, a parameter trade-off, and a behavioral warning. It doesn't describe return values, but that's not required without an output schema. It lacks only minor details like error handling or prerequisites, but remains strong overall.

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 67%, leaving title and content without descriptions. The description adds meaning to content ('rendered as markdown') and contentFile (server reads directly, preferred for long docs, mutually exclusive with content). It also clarifies folder (URL or id) and default behavior. This compensates well for the schema gaps.

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 new Google Doc' — a specific verb and resource — and clarifies it supports a title, optional markdown content, and optional folder placement. This clearly distinguishes it from siblings like update_doc, overwrite_doc, and read_doc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly recommends contentFile for long documents to avoid silent text dropping, which is an alternative to content. It also implies creation vs. editing by naming the action 'Create' and describing the default My Drive root. It doesn't explicitly contrast with sibling create/update tools, but the usage context is clear.

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

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

With no annotations, the description carries the full burden of disclosure. It transparently reveals cascading deletion of child tabs and the safety verification mechanism using expectTitle. It doesn't mention permanence or permission requirements, but covers the most important destructive behaviors.

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

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

Two sentences, front-loaded with the action and key detail (cascade), followed by the essential safety constraint. Every word earns its place without 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 delete tool with no annotations and no output schema, the description covers the action, the cascade behavior, and a critical prerequisite. It doesn't describe the return value or any cleanup details, but the tool is relatively simple and the provided context is sufficient for correct 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 only 50%, and the description compensates by explaining the purpose and criticality of expectTitle, and clarifying that tabId is the identifier. However, documentId and account parameters lack meaningful explanation beyond the schema, so the value added is partial.

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 ('Delete a tab') and the specific resource (by tabId), and uniquely distinguishes it from sibling tools like add_tab and rename_tab. It also adds the cascading behavior, which is specific to this delete 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 when to use the tool (when deleting a tab) and provides a crucial usage requirement: expectTitle must come from list_tabs. However, it doesn't explicitly mention alternatives or when not to use it, such as if child tabs should be preserved.

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?

With no annotations, the description carries full transparency burden. It discloses the side effect (downloading to local folder), the return value (objectId→filename mapping), and a key integration behavior (correlation with read_doc). It doesn't mention permissions, error behavior, or that the doc itself isn't modified, but 'download' implies non-destructive read from the doc. The transparency is solid without being exhaustive.

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

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

The description is two sentences: the first states the core action, the second explains the return mapping and a crucial correlation with read_doc. Every sentence adds value with no filler or redundancy. 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 that there is no output schema and no annotations, the description successfully communicates the tool's purpose, output, and usage context. It covers the main use case (downloading all images and rewriting references). It doesn't address edge cases like 'no images' or error handling, but those are minor for a download tool; overall it's complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 75% (three of four parameters have descriptions), so the schema does most of the work. The tool description says 'local folder' early on, aligning with the `dir` parameter, but doesn't discuss `documentId`, `tab`, or `account`. It adds no new parameter-level meaning beyond the schema, so a 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 opens with a specific, actionable verb phrase 'Download every embedded image in a Google Doc to a local folder', clearly identifying the resource (images in Google Doc), the action (download to local folder), and the output (objectId-to-filename mapping). It also distinguishes itself from siblings by framing itself as the 'inverse of publishing' and referencing read_doc, setting it apart from mere read or insert operations.

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 workflow context: it explains how the return mapping correlates with read_doc's image markers, indicating when you'd use this tool (to replace remote image references with local paths). However, it doesn't explicitly name alternatives or state when not to use it, so it misses the top-tier 'when-not' guidance.

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

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

With no annotations, the description carries the full burden. It discloses key behaviors: cp preserves formatting that markdown cannot rebuild, ambiguous paths are refused with candidates listed rather than guessed, duplicate names are allowed, and case folding occurs. These are non-obvious and critical traits beyond what the schema or annotations could convey.

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

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

The description is long but every sentence contributes unique value. It is well-structured: overview, then per-command details, path conventions, edge cases, and exclusions. No filler or redundancy; it front-loads the core purpose and flows logically. The density is appropriate for a tool with multiple subcommands.

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

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

For a multi-command filesystem interface with no output schema, the description covers all essential aspects: each command's behavior, path resolution rules, special directories, handling of duplicate names and case folding, disambiguation on ambiguity, and explicit exclusions. It also notes ownership transfer implications indirectly through schema, but the description itself is self-sufficient for a complex 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 description adds substantial meaning beyond the schema for the primary cmd parameter, detailing each subcommand's syntax, defaults, and special flags (e.g., '-p' for mkdir, '-type' for find). It also clarifies the 'args' parameter as positional and provides concrete examples. Even though schema coverage is 80%, the description enriches the semantics of the two most complex parameters (cmd and args) significantly.

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+resource: 'Navigate and reorganise Google Drive with shell commands: ls, find, mkdir, cp, mv.' It immediately distinguishes from sibling tools by stating content editing is done elsewhere ('edit_doc/overwrite_doc, not here') and explicitly notes 'there is no rm.' This precisely defines the tool's scope and differentiates it from sibling content manipulation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive usage context: path syntax ('/shared/<drive name>', '/shared-with-me', '/lost+found'), handling of IDs/URLs ('ids from any other tool can be pasted straight in'), and the nuance of mv with an existing folder. It also explicitly excludes content editing (via edit_doc/overwrite_doc) and warns against expecting rm, making the tool's place among siblings clear.

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

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

With no annotations, the description carries full burden and excels: it discloses markup-tolerance, ambiguity handling ('ambiguous matches return surrounding context'), that new_string supports inline markdown/HTML, and the critical limitation that edits are live text, not suggestions. It also instructs flagging pending reviewer suggestions, adding behavioral nuance beyond the schema.

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

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

Five dense sentences, each earning its place: core action, matching behavior, formatting semantics, alternative tool, and a direct-edit caveat. No fluff, well-structured, front-loaded with the main 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 an 8-parameter tool with no output schema, the description fully covers the essential behavioral aspects: matching, formatting, alternatives, and the suggestions caveat. Remaining parameters are documented in the schema, and the description handles the nontrivial complexities comprehensively.

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 value by explaining old_string's markup-tolerant matching and ambiguity handling, and clarifying that new_string uses the same formatting syntax as read_doc. This goes beyond the schema's terse 'replacement text' and enriches parameter meaning.

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

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

The description uses a specific verb+resource phrase 'Replace an exact unique snippet of text in a Google Doc' and distinguishes from the sibling set_style by explicitly noting when to use that alternative instead. It also clarifies the 'like a local file Edit' analogy, making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear when-to-use context: quoting a unique slice from read_doc, noting markup-tolerant matching, and stating 'To restyle text you are NOT otherwise changing, use set_style instead.' It also warns about the direct-edit nature versus tracked suggestions, giving practical usage guidance.

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

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

With no annotations, the description carries the full transparency burden. It adds meaningful behavioral details: how `op` selects the operation, how `side` controls insert position (with defaults and mapping for rows/columns), and that `side` is ignored for deletes. It also clarifies that deletes remove the row/column containing `cell`. However, it does not discuss side effects like formatting loss or whether insertions copy styles, leaving some gaps.

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: three sentences, front-loaded with the main purpose, then parameter logic, then deletion behavior. No redundant or wordy content; every sentence adds necessary context.

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 8 parameters, 4 enums, and no output schema. The description covers the core operational logic (op, side, cell targeting) and leaves other parameters (tab, page, segment, account) to the schema, which adequately documents them. It does not mention what happens to the document after the edit, but the absence of an output schema reduces that burden. Overall, it provides enough context for correct 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?

The schema already covers 88% of parameters with descriptions. The description adds value by explaining the key role of `cell` as the locator for the target row/column, and clarifies the `side` parameter's mapping and default behavior, which goes beyond the schema's basic description. This is especially useful for selecting the correct table.

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

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

The description clearly states the tool's function: "Structurally edit the table containing the given cell text: insert or delete a row or column." This specifies the verb (edit), resource (table), and scope (insert/delete row/column), and distinguishes it from siblings like set_table_style (styling) and insert_table (new table).

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 structurally modify an existing table identified by a cell's text. It does not explicitly mention alternatives or exclusions, but the context is clear enough that an agent can infer it is for structural edits rather than content or style changes.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that Google renders server-side, lists the return values (local path and byte size), and warns about the 10 MB export restriction. This goes beyond minimal expectations, though it could add details about overwrites or error 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 three sentences, front-loaded with the core purpose, and every sentence adds value: format list, rendering fidelity, return values, and a size restriction. There is no fluff or redundancy.

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

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

Given no output schema and five parameters, the description covers the key runtime behaviors: server-side rendering, page layout fidelity, return results, and the 10 MB file-size limit. It does not explain overwrite behavior or error handling, but the schema handles parameter definitions, so the description is reasonably complete for an export tool.

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

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

Schema coverage is high (80%), so the baseline is 3. The description adds little beyond the schema for parameters; it repeats format defaults and lists options but does not clarify ambiguous fields like documentId. It provides marginal context about the directory creation, but that is already 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 opens with a specific verb ('Export') and resource ('a Google Doc') and clearly states the output ('real file on disk'), enumerating all supported formats. It also distinguishes this from sibling tools like read_doc or download_images by focusing on the export-to-file 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 use case (converting a Google Doc to a downloadable file) and gives a helpful note about the 10 MB limit, but it does not explicitly state when to use this tool over alternatives or mention any exclusions. The context is clear but not prescriptive.

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?

With no annotations, the description carries full burden. It clearly indicates a read (non-mutating) operation, and details return specifics: margins, page size in points, preset names (letter/legal/a4/tabloid), and orientation. It doesn't cover auth or error conditions, but the core behavior is well disclosed.

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

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

Two sentences, front-loaded with the action and resource, followed by a concise use case and sibling relationship. No redundant words, every clause earns its place.

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

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

For a read tool with a small parameter set, the description sufficiently covers what it returns (specific formatting details) and how to use it. No output schema exists, but the description compensates by listing return components. Slight gap: no mention of error behavior or authentication, but not expected for this simple tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds mild value by framing the tool as applying to a doc or tab, which aligns with the 'tab' parameter, but it doesn't add parameter details 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 the verb 'Read' and the resource 'page setup', enumerating specific components (margins, page size, orientation) and noting it works on a doc or tab. It explicitly labels itself as the read counterpart to set_page_setup, distinguishing it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description identifies a specific use case ('mirror another document's layout onto a new doc') and names the complementary tool (set_page_setup). While it doesn't explicitly list when not to use alternatives, the 'read counterpart' framing provides clear placement among siblings.

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?

With no annotations, the description carries full burden. It discloses that the tool reads a project configuration file and shows the effective defaults and file location. 'Show' implies no side effects, and the specificity about output (account/folder and file path) is transparent. It doesn't cover edge cases like a missing config, but for a simple getter this is adequate.

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

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

The description is a single sentence that front-loads the action and then specifies the resource and additional output (file location). Every word earns its place; there is no redundancy, and it is appropriately sized for a tool with no parameters.

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 (no params, no output schema), the description is complete enough. It explains what the tool does and what it shows (defaults and file location), which serves as a high-level return description. It could mention error behavior or fallback defaults, but this is a minor 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 tool has zero parameters, so the baseline is 4. The input schema is empty and fully covers the parameter surface. The description adds no parameter-specific details because none exist, but it clarifies what the tool returns in context of the project configuration.

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 ('Show'), the specific resource ('.gdocs-mcp.json defaults'), and the scope ('current working directory'). It also distinguishes itself from siblings like 'set_project_default' by focusing on the read/display side, and from 'list_accounts' by targeting project-level configuration.

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: when you need to see the effective project defaults (account/folder) and the config file location. It doesn't explicitly name alternatives or exclusions, but the read-only nature is distinguishable from write-style siblings like 'set_project_default'.

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?

With no annotations provided, the description carries the full burden and performs well: it explains the return shape (paragraph style with namedStyleType, alignment, spacing in pt, lineSpacing %, inheritance; text style with bold/italic/underline/strikethrough, fontSize pt, fontFamily, color hex, link) and reveals the behavioral nuance of 'effective (inherited-resolved)' style. It also implies read-only by calling it 'read counterpart to set_style', and provides a concrete diagnostic example.

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

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

Three sentences, front-loaded with the core purpose, then return details, then a diagnostic use case. Every sentence is informative with no filler. The length is justified given the return value complexity and the need to distinguish from siblings.

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 description compensates by enumerating return fields. It also provides context on why to use it (read_doc can't express styles), which sibling to compare with (set_style), and an example of unexpected spacing. The description is complete for a read tool with schema-documented parameters.

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 high (83%), so baseline is 3. The description adds little beyond schema: it repeats 'unique text snippet' which the schema already says as 'exact text to read the style of (quote a unique slice from read_doc)'. No new meaning is added for tab, page, segment, or account parameters, so the description does not enhance parameter understanding 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 the tool reads the effective (inherited-resolved) style at a unique text snippet, differentiating it from read_doc which cannot express such styles, and explicitly identifies it as the read counterpart to set_style. The verb 'Read' and resource 'style at a unique text snippet' are specific, and the mention of sibling tools distinguishes it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: to diagnose things markdown hides, e.g., an unexpected gap between paragraphs is spacing (spaceAfter>0), not a blank line. It also names alternatives and exclusions: it is fixed with set_style's spaceAfter, not edit_doc, and read_doc's markdown can't express these styles. This provides clear when-to-use and when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden. It clearly discloses that table-wide facts apply to the whole table while cell-specific attributes apply to the matched cell, and warns that Docs gives every cell 5pt padding by default. It also promises output shape compatibility with set_table_style, which is a useful behavioral guarantee.

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 longer than a minimal one, but every sentence earns its place: the first states the core function, the second gives use cases, the third addresses output shape, the fourth clarifies scope, and the fifth covers a default caveat. It is front-loaded and not repetitive, though slightly verbose.

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

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

There is no output schema, so the description must explain return values. It does so by listing the specific style attributes and clarifying which are table-wide vs cell-specific. It also handles an edge case (default padding on unstyled tables). For a read tool with nuanced output, this is 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 high (83%), and the description does not add much parameter-level meaning beyond the schema. The cell parameter's role as a locator is already described in the schema ('text of any cell in the target table (locates the table)'), so the description's added value is mostly about output semantics rather than input parameter clarification.

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: 'Read the style of the table containing the given cell text' and enumerates exactly what is read (widths, header rows, cell padding/background/borders). It explicitly positions itself as the read counterpart to set_table_style, distinguishing it from the sibling get_style which likely targets document/paragraph style.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases: 'check a change took, preserve a table’s look while rewriting it, or copy one table’s layout onto another.' It also clarifies that it is the read counterpart to set_table_style, implying when to use the write tool instead.

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?

No annotations are provided, so the description carries the full burden. It discloses that this is a direct edit (not a tracked suggestion), that content is full markdown with the same renderer as create_doc, and that no anchor text is required. It could additionally note behavior like failure on unmatched snippet, but the disclosed traits are useful.

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 five dense sentences with no wasted words. It front-loads the core purpose and packs usage guidance, edge cases, and rendering details efficiently.

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 10-parameter tool with no annotations and no output schema, the description covers purpose, when to use/not use, behavioral traits, and key parameter semantics. It is sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema description coverage is high (90%), so baseline is 3. The description meaningfully adds to the at parameter by defining 'end', 'top', and 'unique text snippet', and clarifies content supports full markdown. Other parameters rely on schema descriptions, which are adequate.

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 the tool inserts new markdown content at a structural position without requiring anchor text. The description distinguishes it from edit_doc by explicitly naming the alternative and defining the at-parameter options (end, top, snippet).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance with edge cases where edit_doc cannot reach (adding after a table at end of doc, appending to empty doc). It also tells when to use edit_doc instead (replacing/extending existing text) and clarifies it is a direct edit, not a suggestion.

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?

Without annotations, the description fully discloses the local file upload workflow (uploaded to Drive, embedded, temp upload removed), states this is a direct edit not a tracked suggestion, and explains the header invisibility behavior — substantial behavioral context.

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

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

Four sentences cover the core behavior, positioning, sizing, alignment, header specifics, edit type, and a limitation — every sentence carries useful information with no redundancy.

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

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

Given 12 parameters and no output schema, the description addresses the main use cases (body and header images), the local file lifecycle, and the API restriction on floating images, making it sufficient for an agent to invoke 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 83%, so the baseline is 3, but the description adds meaningful context to `at` (top/end/unique text anchor) and `segment` (letterhead logo example), going beyond the schema's field descriptions.

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

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

The description opens with a specific verb ('Insert') and resource ('inline image'), and clarifies sources (public URL or local file), distinguishing from siblings like insert_table or insert_content. It clearly states the action and scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides context for segment header as the place for a letterhead logo and notes that floating/text-wrapped images are not supported, giving implicit guidance on when this tool applies. However, it doesn't explicitly name alternative tools for unsupported cases.

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?

With no annotations, the description carries the burden. It discloses the key behavior 'A direct edit, not a tracked suggestion' and explains markdown processing. It stops short of detailing error scenarios or permission requirements, but covers the most critical behavioral trait.

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 three sentences, front-loaded with the core purpose, followed by essential parameter details and a closing behavioral note. Every sentence earns its place without redundancy or 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 13-parameter tool with no output schema, the description covers the fundamental use case and required parameters (rows, columns, documentId implied). It also explains optional data/alignment/position. Advanced options like segment, tab, and account are left to the schema, which is acceptable given the schema's high coverage.

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 77%, so a baseline of 3 applies. The description adds value beyond the schema by clarifying rows/columns as dimensions, noting optional population from a 2D array, and specifying 'at' semantics (top/end/anchor). This complements and enriches 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 clearly states 'Insert a rows×columns table' with a specific verb and resource. It also distinguishes from siblings by noting 'A direct edit, not a tracked suggestion,' which separates it from suggestion-related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides practical usage context: how to specify position ('via at (top/end/or a unique text anchor, default end)'), data format ('2D array of cell text'), and markdown support. It also gives a when-not via 'not a tracked suggestion,' but does not explicitly name alternative 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?

With no annotations, the description carries full responsibility. It clearly indicates a read-only action by using 'List,' and there are no side effects or hidden behaviors to disclose. However, it adds no context beyond the obvious purpose—no mention of what the output looks like, whether accounts are returned as emails, or if authorization status has any caveats. This is a baseline acceptable transparency for a simple read tool.

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

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

The description is a single, concise sentence: 'List the Google accounts that have been authorized for this server.' It is front-loaded with the action verb and resource, contains no filler, and every word earns its place. Properly sized for the tool's trivial parameter surface.

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 zero-parameter tool with no output schema, the description is complete. It tells the AI agent exactly what the tool does, and because there are no parameters to configure or complex return values to explain, no additional information is needed. The context is fully covered by this single sentence.

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 tool has zero parameters, so the schema is trivially complete. The description does not need to explain any parameters. Per the rubric, 0 params receives a baseline of 4, and nothing in the description detracts from this. The description correctly focuses on the tool's purpose rather than inventing parameter detail.

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 'List' with a clear resource: 'Google accounts that have been authorized for this server.' This distinguishes it from sibling list tools like list_folder, list_tabs, or list_comments, which target different resources. The phrasing is unambiguous and matches the title exactly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the many sibling tools, nor does it mention any exclusions or alternatives. It simply restates the purpose without context about scenarios where checking authorized accounts would be appropriate. There is no 'when to use' or 'instead' language.

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

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

The description discloses useful behavioral details: it lists the included fields and explicitly notes that author email is unavailable via the Drive API. This limitation is helpful context beyond a simple 'list comments' statement, though it does not cover pagination 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?

Two concise sentences, front-loaded with the core function and field list, followed by a relevant limitation. 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?

For a read-only list tool with no output schema, the description covers the return contents and a key constraint. It lacks explicit pagination or resolved-comment filtering details, but these are not essential for the agent's basic 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?

The schema already fully documents both parameters (account with default behavior, documentId). The description adds no further parameter semantics, so it meets the baseline for schema-covered parameters.

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

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

The description clearly states a specific action ('List comments') and resource ('a Google Doc'), enumerating the returned fields. It distinguishes itself from sibling comment-related tools like add_comment and resolve_comment by focusing on listing.

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 retrieving comments but provides no explicit guidance on when to choose this over siblings like list_suggestions or read_doc. There are no exclusions or alternative recommendations, so it relies on the agent's interpretation.

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?

With no annotations, the description carries the full burden and does an excellent job. It reveals the structure of each entry (subject), explains the meaning of allowFileDiscovery for non-email subjects, and discloses that a doc may already have a domain grant by default. This is rich behavioral context beyond the basic 'list' operation.

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

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

The description is four sentences long but each sentence adds value: the first states the core purpose, the second explains the subject field format, the third clarifies allowFileDiscovery, and the fourth covers an edge case. It is front-loaded and free of 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 there is no output schema, the description must explain the return format. It does so thoroughly by describing entry fields, special subject values, the allowFileDiscovery behavior, and the default domain grant caveat. This is a complete picture for a listing tool with no additional schema support.

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

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

Schema description coverage is only 50% (account is described, documentId is not). The description adds no parameter-specific guidance, leaving documentId's meaning to be inferred from the tool name. For a required parameter, this is a meaningful gap that the description does not fill.

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 verb 'List' and the resource 'permissions on a Google Doc', specifying the scope (people, groups, domain, anyone-with-link) and that roles are included. It distinguishes itself from sibling sharing tools like share_doc and unshare_doc by focusing on reading the current state.

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 frames the tool as a read-only inspection tool but does not explicitly name alternatives or state when-not-to-use. It provides useful context, such as the note about Workspace domain grants, which helps the user anticipate unexpected results and clarifies the tool's purpose in an audit workflow.

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?

With no annotations provided, the description carries the full transparency burden. It discloses that it lists only pending suggestions, returns diffs in document order, and notes the API exposes no author or timestamp — useful limitations. A minor gap is not explicitly stating it is read-only, but 'list' implies 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 two sentences (plus a short note) and front-loaded with the core purpose in the first sentence. Every sentence earns its place, providing output format, integration guidance, and an API limitation 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?

The tool has 5 parameters and no output schema, so the description must define the output contract. It adequately explains the return structure (title + per-suggestion preview) and the no-author/timestamp limitation. It could also mention what happens when no suggestions exist, but 'pending' clarifies the scope.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning about parameters (documentId, tab, page, account, segment); it only mentions output fields title and preview, which relate to the response, not parameters. The params are well-documented 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 lists pending suggestions (tracked changes) in a Google Doc as before→after diffs in document order. This specific verb+resource+scope distinguishes it from sibling tools like apply_suggestions (which applies them) and list_comments (which handles 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 by explaining the output includes a preview to pass to apply_suggestions, implying usage as a precursor to applying changes. It does not explicitly mention alternatives or when not to use, but the integration hint gives practical guidance.

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

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

With no annotations, the description carries the full burden. It states that the tool lists tabs and returns specific fields, implying a read-only operation, but does not disclose additional behavioral traits such as authentication requirements, errors, or absence of side effects. This is adequate but not rich.

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

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

The description is a single, front-loaded sentence that immediately states the purpose and then adds the return fields in parentheses. Every word is informative, and there is no filler or redundant content.

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

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

For a simple list tool with one required parameter and no output schema, the description covers the return value and core behavior. It lacks parameter explanation but is otherwise complete, making it well-suited for straightforward tasks.

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 50%, with 'account' described but 'documentId' lacking any description in either the schema or the tool description. The description does not compensate by explaining parameter usage, leaving the required parameter ambiguous.

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 ('List') and resource ('tabs in a Google Doc'), and enumerates the returned fields (tabId, title, index, nesting). This distinguishes it from sibling tools like add_tab, rename_tab, and delete_tab, which perform different operations.

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 explicit guidance is given on when to use this tool versus alternatives. The description does not mention exclusions or provide context such as 'use before modifying tabs' or 'instead of read_doc'. Usage is only implied by the name and description.

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?

With no annotations provided, the description carries the full burden and does it well. It discloses destructive behavior (overwrites the body), the refusal condition for comments/suggestions, the force escape hatch, the expectTitle verification mechanism, the contentFile mechanical-reading advantage, and the direct-edit (not tracked-suggestion) nature. This goes well beyond a simple mutation hint.

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 three sentences, with the core action and safety guard front-loaded. Every sentence adds critical information: what it does, when it refuses, how to avoid data loss, and the nature of the edit. No filler or redundancy.

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

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

Given the tool's 8 parameters and no output schema, the description provides a solid operational picture: full replacement semantics, safety hooks, and important usage guidance for the most complex parameters. It could mention side effects beyond comment/suggestion loss (e.g., formatting replacement) or account permissions, but the current description is adequate for an agent to invoke it correctly in most scenarios.

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 high (88%), so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains why contentFile is preferred for long documents (avoids silent text dropping), what expectTitle is used for (confirmation and live verification), and how force bypasses the comment/suggestion guard. This enhances the schema's bare parameter 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 uses a specific verb ('Replace') and resource ('entire body of a doc or one tab') and clarifies the markdown-rendering behavior. It distinguishes itself from sibling tools like edit_doc by explicitly stating this is a full-body replacement and 'a direct edit, not a tracked suggestion.'

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 communicates when to use this tool (full overwrite, including per-tab) and when to prefer alternatives: contentFile for long documents instead of inline content. It also flags a safety condition (refuses if comments/suggestions unless force=true). However, it does not explicitly name edit_doc as the alternative for targeted edits, though this is strongly implied.

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?

With no annotations, the description carries the transparency burden. It discloses a non-obvious behavior: a body read always reports headers/footers and their content, even though that content is not part of the body. It also clarifies how tracked mode renders suggestions as <ins>/<del>. It doesn't explicitly state read-only, but the verb 'Read' implies it.

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

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

Four sentences, front-loaded with the core purpose, then progressively detailed explanations of modes, segments, and the header/footer quirk. Every sentence earns its place; 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?

The description covers the most important behavioral nuances for a read tool: output format, mode semantics, segment options, and the invisible-content quirk. The schema already documents parameters like tab, page, and account, so the description needn't repeat them. For a tool without an output schema, this is adequately 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 substantial meaning to mode ('clean (committed text, default) · tracked (suggestions shown as <ins>/<del>)') and segment ('body plus every header/footer, each labelled'), beyond the bare enum values. Useful context, but not every parameter is enriched.

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 'Read a Google Doc as markdown + inline HTML' – a specific verb, resource, and output format. The modes and segments clarify scope, distinguishing this from sibling mutation tools like edit_doc or overwrite_doc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains modes and segments, giving implicit guidance on when to use each, but it never names alternatives like export_doc for other formats or list_suggestions for suggestion-only queries. Usage context is implied, not 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?

No annotations are provided, so the description carries full responsibility. 'Rename a tab by tabId' discloses the basic action but omits behavioral details such as side effects, permissions, idempotency, error handling, or return values. For a mutation tool, this is a significant gap.

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

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

The description is a single short sentence, appropriately sized for a simple operation. However, it is under-specified and does not fully earn its place, as it largely restates the tool's name.

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 mutation tool with no annotations, no output schema, and only 25% schema coverage, the description is incomplete. It does not explain the role of required parameters like 'title' and 'documentId', nor what happens after renaming. The operation is simple, but the guidance is too thin for an AI agent to invoke it correctly.

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

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

Schema coverage is only 25% (only 'account' has a description). The description only mentions tabId, failing to explain that 'title' is the new tab name or that 'documentId' identifies the containing document. It does not compensate for the low schema coverage; it adds minimal meaning beyond the parameter names.

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 'Rename a tab by tabId' clearly states the action (rename) and the resource (a tab), with the key identifier (tabId). This distinguishes it from sibling tools like delete_tab, add_tab, and list_tabs.

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?

There is no guidance on when to use this tool versus alternatives or any exclusions. The description simply states what it does without contextualizing its use relative to other tab operations.

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

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

The description discloses a key safety behavior: expectQuote is verified against the live comment so a wrong/stale id is refused, preventing accidental resolution of the wrong thread. This goes beyond the basic action, though it does not cover permissions or return values.

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

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

The description is a single sentence, front-loaded with the core purpose followed by a concise explanation of the verification parameter. No unnecessary words or repetition.

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

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

The description covers the primary action, the verification mechanism, and the prerequisite tool for obtaining the quote. It lacks information about return values or error handling, but with no output schema and moderate complexity, it provides sufficient context for an agent to invoke the tool correctly.

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

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

The description adds meaning to expectQuote by explaining its source (list_comments) and its role in confirmation and verification, which the schema only labels as a snippet. It does not elaborate on commentId/documentId, but these are self-evident from context.

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

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

The description starts with 'Resolve (or reopen) a comment thread by comment id,' clearly stating the action and target. It distinguishes this from sibling tools like list_comments or add_comment by specifying the resolve/reopen action and the required comment id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It instructs the user to pass expectQuote, obtained from list_comments, and explains that it is verified, helping the agent know the expected prerequisite workflow. It warns against wrong/stale ids, but does not explicitly contrast with alternative tools or mention 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds critical context: 'A direct change, not a tracked suggestion', unit conventions ('72 pt = 1 inch'), and that orientation 'swaps the page dimensions'. This goes beyond the schema, though it doesn't mention error handling or permissions.

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

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

The description is concise and well-structured: three sentences, each serving a distinct purpose (scope, units/presets, orientation/behavior). No filler or redundant content; every sentence earns its place.

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

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

Given no annotations and no output schema, the description is remarkably complete for a 9-parameter tool. It covers the core purpose, scope, unit system, preset options, orientation effect, and mutation semantics, making it self-sufficient for an agent to select and invoke.

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

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

The schema already documents all 9 parameters (100% coverage), so the baseline is 3. The description adds meaningful value by explaining pageSize presets and explicit dimensions, margin units in points, orientation semantics, and tab defaulting behavior, enriching the parameter understanding.

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

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

The description clearly states a specific action ('Set document-level page setup') and scope ('for a doc (or tab)'), while explicitly distinguishing from the sibling tool set_style ('which set_style can’t reach'). This makes the tool's purpose unambiguous and differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides a clear context for when to use this tool by referencing 'the File > Page setup controls' and directly contrasting it with set_style. It doesn't explicitly say when NOT to use it, but the exclusion of the alternative is strongly implied.

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?

Despite having no annotations, the description discloses the important side effect: writing to `.gdocs-mcp.json` in the current working directory or updating an existing file up the tree. It also clarifies that these are defaults for new docs, which adds meaningful behavioral context beyond the schema.

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

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

Three concise sentences with key information front-loaded. The first sentence captures the core behavior, and the follow-ups add useful parameter semantics 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 simple two-parameter tool, the description covers the main side-effect, file location, scope, and folder-id resolution workflow. It does not explicitly say what happens to existing defaults when a parameter is omitted, but overall completeness is good.

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

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

While the schema already documents both parameters at 100% coverage, the description adds valuable semantics: folder can be a URL or id, and account must be an authorized Google account email. The folder-by-name workaround also adds practical parameter 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 clearly states that the tool writes project defaults to a `.gdocs-mcp.json` file, with a default account and/or folder for new docs. This distinguishes it from sibling tools like `get_project_config` and other set-style tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains when the defaults apply (new docs), and gives concrete workaround for setting a folder by name via `drive({ cmd: 'find' })` and passing its id. It does not explicitly mention when to avoid using this tool or name alternatives, but the use case is clear.

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

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

With no annotations, the description carries full burden. It discloses that this is a 'direct style change, not a tracked suggestion', which is a key behavioral trait. It also clarifies the span semantics for from/to and the in-place (non-content) nature. However, it does not address failure modes (e.g., non-unique snippet) or reversibility, which would further enhance 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 dense but every sentence earns its place: purpose, targeting rules, style list, workflow hint, alternative comparison, and behavioral note. It is front-loaded with the primary action and uses clear structure (semicolons separating the two targeting modes). 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 9-parameter tool with a nested style object and no output schema, the description plus the rich input schema cover the necessary context. It adds sequencing (get_style first) and behavior (direct vs suggestion). It does not explicitly mention segment/page/tab targeting, but those are fully described in the schema, so the description does not need to repeat them.

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, but the description adds real semantics: the from/to span definition ('from the start of the unique from snippet to the end of the unique to snippet'), the mutual exclusivity with whole_document, and a summary of style properties with units (hex, pt, %). This goes beyond the schema's per-parameter hints.

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: 'Apply styling to existing text in place (no content change)'. It clearly distinguishes itself from sibling tools by contrasting with edit_doc ('Prefer this over rewriting the text with edit_doc'), and the 'no content change' phrase uniquely scopes the 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?

Explicit guidance is provided: 'Use get_style first to read current spacing/fonts' and 'Prefer this over rewriting the text with edit_doc'. It also explains the two targeting modes (selection vs whole_document) and notes that retyping text risks silent drops, giving a clear when-to-use rationale.

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?

With no annotations, the description carries the full transparency burden. It discloses that this is a 'direct edit, not a tracked suggestion' — a key behavioral trait. It also clarifies two important edge behaviors: border width 0 makes the table borderless, and headerRows repeats rows on every page. It does not explicitly mention permission requirements or irreversible overwrites, but the direct-edit caveat provides significant 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 three sentences long, front-loaded with the primary purpose, and every sentence contributes information: the first lists the editable properties, the second clarifies scope semantics, and the third provides concrete examples and the direct-edit caveat. There is no fluff or redundancy.

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

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

For a tool with 12 parameters, nested objects, and no output schema, the description covers the essential context: what the tool does, how scope works, and key behavioral caveats. It does not explain every parameter (the schema handles that), but it gives enough operational context for an agent to use it correctly. Minor gaps like ambiguous table matches or error handling are not addressed, but they are not critical for selection.

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

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

Although the schema has high parameter coverage (92%), the description adds meaning beyond the schema. It explains that 'scope selects which cells padding/background/border hit' and elaborates the options (table, row, column, or cell of the matched cell), which the schema only labels as 'default table'. It also gives a practical implication for padding (clipping first letter) and border width, adding contextual 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 ('Edit') with a clear resource ('style/layout of an existing table') and enumerates the exact style properties (padding, background color, borders, column widths, pinned header rows). It also explains how the table is located (by any cell's text), which distinguishes it from generic style tools like set_style or read-style tools like get_table_style.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use this tool — when you need to edit a table's style or layout — and even provides a concrete use-case ('Fixes e.g. thin left padding that clips the first letter of cells'). However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses that sharing may optionally send notifications, that omitting email modifies link sharing, and that role 'none' disables link sharing. It doesn't explicitly state that this is a mutating operation that overwrites existing permissions, but the pointer to unshare_doc for revocation provides useful context about reversibility.

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 tightly written in three sentences: a clear purpose statement, two conditional modes, and a cross-reference to an alternative tool. Every sentence contributes essential information with no redundancy or 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 tool with moderate complexity and no output schema, the description covers the primary use cases and an alternative. It doesn't mention potential failure modes or return values, but those are not critical for a sharing action. The overall behavior is well-scoped and understandable.

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 high (80%), but the description adds significant semantic value beyond the schema by explaining how the presence/absence of email toggles between person and link sharing, and by clarifying the special behavior of role 'none'. This enriches parameter understanding without repeating the schema descriptions verbatim.

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

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

The description opens with a specific verb and resource: 'Grant access to a Google Doc.' It then clearly distinguishes two operational modes (sharing with a person via email vs. setting anyone-with-link access) and explicitly references the sibling unshare_doc for the alternative action of revoking access, making it distinct from related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear when-to-use guidance: it explains the two modes (with/without email) and explicitly tells the user to use unshare_doc for revoking a specific person's access. This is a direct alternative, satisfying the criterion for explicit when/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?

With no annotations, the description carries the full burden and does so thoroughly. It discloses that the operation is irreversible ('recorded nowhere and cannot be restored'), refuses to touch the owner, and verifies the current role before removal so nothing is deleted if the grant changed. This goes well beyond a generic 'revoke access' statement.

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

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

The description is front-loaded with the core action and includes dense, high-value warnings. However, the instruction to run list_permissions first is stated multiple times, and the irreversibility warning is repeated in slightly different forms, adding mild redundancy.

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

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

Given the tool's complexity as an irreversible, potentially destructive operation with no annotations or output schema, the description covers all essential operational context: how to identify the target, the mandatory expectRole check, the domain-grant caveat, and owner protection. No critical gaps remain.

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?

Despite high schema coverage (83%), the description adds significant meaning by mapping email to person/group, permissionId to domain or anyone-with-link grants, and explaining that expectRole is a safety echo from list_permissions. It also clarifies that expectTitle prevents wrong-document revocations, enriching 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 opens with 'Revoke a grant on a Google Doc,' which is a specific verb and resource, and the title 'Remove someone’s access' reinforces the intent. It clearly distinguishes from the sibling share_doc (granting access) and list_permissions (reading permissions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to run list_permissions first, and explains when to use email (person/group) versus permissionId (domain-wide or anyone-with-link grants). It also mandates that expectRole must be echoed from list_permissions, giving clear preconditions and preventing misuse.

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