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

With no annotations, the description carries the behavioral burden well: it explains that comments stay attached as text moves, ambiguous quotedText matches are refused with match context, and tab/header/footer behavior comes from path and segment. It does not cover permission requirements, notification behavior, or rate limits, so it is strong but not fully 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 dense and front-loads the core behavior, but some sentences are long and pack multiple constraints together. It is appropriately sized for a 7-parameter commenting tool with no annotations, and no sentence is clearly wasted.

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 7 parameters, no annotations, and no output schema, the description is largely complete: it covers the main comment action, reply mode, quoting semantics, tab resolution, and header/footer targeting. It could be slightly more complete by mentioning auth/account expectations or any side effects around comment creation.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful cross-parameter semantics: quotedText is required unless replyTo is given, replyTo takes a comment id from list_comments, path determines the tab, and segment controls body versus header/footer targeting.

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

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

The description states a specific verb and resource: commenting on text in a Google Doc, with a distinct reply mode. It also distinguishes the tool from edit_doc and list_comments, so an agent can identify its role without opening sibling schemas.

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

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

It explicitly explains when to use quotedText versus replyTo, and gives the workaround for overall document feedback because Google Docs lacks whole-doc comments. It also routes agents to list_comments for reply IDs and edit_doc for understanding quotedText matching.

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 well: it explains per-suggestion resolution, accept versus reject effects, how touching suggestions are decided, style-only suggestions, preflight title/context validation with wrong_doc and error statuses, and the all-or-nothing 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 core action is front-loaded in the first clause, and each subsequent sentence adds distinct behavioral or validation information. There is no filler or repetition; the length is justified by the tool's complexity.

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

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

For a mutation tool with no annotations, no output schema, and a fully described input schema, the description is complete enough: it covers preconditions, atomicity, edge cases, and status behavior. Missing permission details are not material here because the schema and tool context supply account/path handling.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces expectTitle and expectContext semantics and verbatim sourcing from list_suggestions, but adds little parameter syntax or meaning beyond the structured schema, making baseline 3 appropriate.

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

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

The description states a specific verb pair (accept/reject), resource (pending suggestions), and scope (in one update), and explicitly ties the tool to list_suggestions. An agent can distinguish it from read/list/comment-resolution siblings without opening the schema.

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

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

It clearly says to use this for pending suggestions from list_suggestions and instructs passing title and each suggestion's context verbatim. It does not explicitly name when not to use it or contrast it with alternatives such as edit_doc or resolve_comment, so it stops short of full when/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 must carry the burden and does disclose the meaningful behavioral facts: it writes files to a local folder and returns an objectId→filename mapping whose format is tied to read_doc's markers. It stays silent on collision/overwrite behavior for existing files and on partial-failure semantics, which are the notable remaining gaps for a filesystem-writing 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?

Two sentences, no filler, with the core action front-loaded and the return-value detail immediately after. Every clause carries information an agent needs.

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 correctly spells out the return value and its downstream use. Combined with the fully documented schema it is nearly complete; only overwrite/error behavior for the target folder is left unstated.

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

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

Schema description coverage is 100%, and the schema already explains path resolution (id/URL, folder/doc/tab), the multi-tab refusal, and that dir is created if missing. The description adds no parameter-level detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource with a clear scope: 'Download every embedded image in a Google Doc to a local folder.' It also positions itself relative to read_doc by naming the exact marker format its output maps to, so an agent can tell what it produces and how it complements a sibling rather than duplicating 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?

Gives a concrete downstream use case: the objectId→filename mapping lets you rewrite `<img src="image:<objectId>">` markers to local paths, framed as 'the inverse of publishing.' That is clear context for when to reach for it, but it never names an alternative (e.g., export_doc) or states when this is the wrong choice (e.g., whole-document export instead of per-image extraction).

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 disclosure burden, and it does: ambiguity is refused with candidates listed rather than guessed, duplicate names and case-folding are called out as deviations from a real filesystem, cp preserves formatting a markdown round-trip would lose, and tabs cannot leave their doc, nor can they be copied. It also flags the non-obvious destructive edge (moving into /shared/ hands ownership to the drive's organisation), matching the schema note without contradicting 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?

Purpose is front-loaded, then commands, then path model, then tab model, then exclusions — a sensible order for a dispatcher tool. It is dense and long, with the tab paragraph packed into a single block, but nearly every clause carries a decision-relevant constraint rather than 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?

For a six-parameter, five-subcommand tool with no annotations and no output schema, the description covers commands, path grammar, the tab model, refusal behavior and out-of-scope operations. It does not describe what ls or find actually return, which is the main remaining gap given the absence of an output schema.

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

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

Schema coverage is 83%, so the baseline is 3, but the description adds real meaning: positional-argument conventions per command, path prefix semantics (/ and ~ for My Drive, /shared/, /shared-with-me, /lost+found), tab-step path continuation, and the rule that a non-prefixed value is treated as a Drive id or URL. It leaves expectName and account to the schema, so it stops short of full coverage.

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

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

The description opens with a specific verb+resource: "Navigate and reorganise Google Drive with shell commands," then enumerates the five subcommands. It explicitly demarcates itself from siblings by stating that content is edited with edit_doc and written with write_doc, not here, and that there is no rm. An agent can distinguish this from read_doc/edit_doc/write_doc without opening any schema.

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

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

It states when to use this tool (navigation, reorganisation, folder creation), when not to (content editing and writing belong to edit_doc/write_doc), and names the alternatives. It also covers the creation path for tabs ("A tab is made by write_doc to a new path") and the absence of deletion, which are exactly the wrong assumptions an agent would otherwise make.

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 behavioral burden and does so extensively: markup-tolerant matching, ambiguity handling, element preservation/deletion/creation, atomic refusal for unsupported constructs, table comparison edits, comment-loss confirmation, and suggestion behavior are all 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?

The first sentence is front-loaded and many details are relevant, but the description is a dense block with no paragraph or heading structure, making key rules hard to scan. It is overlong for easy agent consumption even if much of the content is valuable.

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

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

For a complex, 11-parameter mutation tool with no annotations and no output schema, the description covers creation/insertion, empty-document handoff, headers/footers, table and style editing, refusals, suggestions, and result shape. An agent has enough context to invoke it correctly in the described 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 100%, so the baseline is 3, but the description adds substantial meaning for old_string matching, new_string markdown/HTML, suggest, and confirmLoss. It adds little beyond the schema for page, segment, account, baseDir, or replace_all.

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 opening sentence gives a precise verb and resource: replace an exact unique text snippet in a Google Doc. It also distinguishes the operation from write_doc for empty documents and from read_doc by requiring a quoted slice from a read.

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 names alternatives in several conditions, such as read_doc for quoting and write_doc for empty docs/tabs/headers, and explains suggest:true for review or non-owned docs. However, the when-to-use guidance is spread throughout rather than stated as a concise upfront rule, and there is no broad exclusion beyond empty content.

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

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

With no annotations, the description carries the full burden and does so well: it discloses server-side rendering, the undocumented and rate-limited tab endpoint, a refusal-without-fallback failure mode, and the 10 MB Drive export limit. It also states the return values (local path and byte size), which is important given there is no output schema.

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

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

Despite covering formats, rendering behavior, tab semantics, failure mode, return values, and size limits, every sentence is front-loaded and information-dense with no filler. The ordering moves from what the tool does to how it behaves to what it returns.

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 five-parameter export tool with no output schema and no annotations, the description supplies everything needed: format defaults, tab-path behavior, rate-limit and size constraints, failure semantics, and return values. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that a doc path exports every tab while a tab path exports only that tab, and that pdf is the default format. The remaining parameters (dir, account, filename) are left to 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 and resource ('Export a Google Doc to a real file on disk'), enumerates supported formats, and clearly distinguishes its output from siblings like read_doc by emphasizing a real file on disk. An agent can identify exactly what this tool produces without opening the schema.

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

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

It gives clear context for when to use it (saving a doc as a file with editor-faithful layout) and explains the tab-path vs doc-path distinction. It stops short of explicitly naming alternatives such as read_doc for in-memory reading, so it earns a 4 rather than 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, the description still makes clear this is a read operation and describes the observable result fields and preset matching behavior. It does not cover permissions or error handling, but for a read-only single-object tool the behavioral profile is reasonably 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?

The description is two front-loaded sentences with no wasted text. It states the operation first, then the return details, then the sibling relationship and use case.

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 usefully names the key return values and explains preset-name matching. It is nearly complete for a simple read tool, though it does not describe permissions, error cases, or full response shape.

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 path and account parameters are already well documented in the schema. The description adds only the general notion that the target may be a doc or tab, which is already captured by the path 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 gives a specific verb-resource pair, “Read … page setup,” and immediately enumerates the returned properties: margins, page size, preset name, and orientation. It also explicitly distinguishes itself from sibling set_page_setup by calling itself the read counterpart.

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 names the alternative set_page_setup and gives a concrete use case: mirroring another document’s layout onto a new document. It does not explicitly state when not to use it, but the read/write split is clear from the counterpart framing.

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

With no annotations, the description carries the burden and does well: it discloses that authors are display names never emails, that status is open or resolved, and that comments with a `range` track their text in body/header/footer while rangeless ones came from Drive. It omits permission requirements and whether resolved comments are included by default or any pagination 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?

Lists the returned fields first, then the range/Drive distinction, then the hand-off to sibling tools — well front-loaded with no filler. It is dense to the point of being a long single sentence in places, which slightly taxes parsing but every clause carries 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?

There is no output schema, and the description compensates fully by describing the shape of each returned comment (quotedText, context with ⟦⟧ markers, author, time, open/resolved, body, replies). Combined with the schema-covered inputs, an agent has everything needed to call and interpret the result.

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 both `path` and `account` are already documented in the schema (including the /folder/doc and tab-path forms). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the comments on a Google Doc') and immediately enumerates the returned fields, so an agent knows exactly what it gets. It also names the sibling tools add_comment and resolve_comment and the exact fields that bridge to them, distinguishing it from the write-side 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?

Provides concrete workflow routing: pass a comment's `id` as replyTo to add_comment, and its `quotedText` as expectQuotedText to resolve_comment — effectively telling the agent when to use this tool (discovery before replying/resolving). It does not state explicit exclusions or a when-not-to-use case, 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, the description carries the burden well: it discloses the return model (subject naming scheme), explains the non-obvious allowFileDiscovery semantics, and warns that a doc may already carry a domain grant. It stops short of stating permissions/auth requirements or that the operation is non-mutating, but the read-only nature is strongly implied by 'List'.

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

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

The core action is front-loaded in the first sentence, followed by tightly scoped clarifications on subject formatting and grant semantics. Dense but every sentence adds interpretation the agent needs; only the final 'note' is somewhat peripheral.

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 correctly compensates by explaining the entry shape (subject values, roles, allowFileDiscovery). Little is missing for an agent to call and interpret this tool, though pagination/ordering behavior is unaddressed.

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

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

Schema coverage is 100% and both parameters (path, account) are fully documented in the schema, so baseline is 3. The description adds no parameter-level detail beyond what the schema already provides.

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

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

States a specific verb+resource: 'List the permissions on a Google Doc ... with their roles', and enumerates the grant types (people, groups, domain, anyone-with-link). This clearly differentiates it from the mutating siblings share_doc and unshare_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?

Usage is implied — it's an inspection tool you'd call before/after share_doc or unshare_doc — but the description never explicitly states when to use this versus those alternatives, nor any preconditions. The closing note about pre-existing domain grants hints at a use case without framing it as 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 does the heavy lifting well: it enumerates the returned fields (id, summary, context, author, time, doc title), states ordering, and explains why context exists (to disambiguate identical summaries). It omits any mention of permission requirements or errors, which is the remaining 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?

Front-loaded with the core action and return shape, then chaining guidance, with zero filler. The trailing "segment:" sentence is compressed almost to the point of being a schema echo, but it is short enough not to cost much.

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, and the description compensates by describing return fields, ordering, and the destination tool for the values. Given a 4-param tool with full schema coverage, only edge cases (empty results, suggestion-only tabs) are unaddressed.

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 earns above that by explaining that segment: header or footer scopes the listing to that one tree, and by pairing doc title with expectTitle. It doesn't clarify page/account semantics, but those are covered in-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?

States a specific verb and resource ("List the pending suggestions (tracked changes) in a Google Doc") plus the ordering ("in document order"), which cleanly separates it from list_comments and read_doc. The scope qualifier "pending" and the parenthetical gloss of tracked changes make it 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?

Explicitly routes the agent forward: "Pass the title as expectTitle and each context as expectContext to apply_suggestions," which is actionable chaining guidance rather than vague context. It lacks an explicit exclusion statement (e.g. when to use list_comments instead), which keeps it off 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 to lean on, the description carries the full burden and does so unusually well: it discloses output structure (style block, class-based paragraphs), how every inline element serializes (footnotes, time, chips, dropdowns, rules, column breaks, equations), and explicit limitations ('A table of contents is not read', 'List items show no indent'). It also warns that a body read reports headers/footers because their content is 'NOT part of the body and would otherwise be invisible', which is exactly the non-obvious behavior an agent needs.

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?

It is front-loaded and purposeful, and given there is no output schema most of the format detail earns its place. However it is delivered as one very long run-on paragraph of semicolon-chained clauses with no breaks or structure, making it hard to scan for the parts an agent needs at call time.

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

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

No output schema exists, so the description must define the return format, and it does so exhaustively — styling rules, literal-escaping semantics, every inline element type, and what is deliberately omitted. For a 5-parameter read tool at this complexity, an agent has everything needed to call it and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to the enums that the schema only labels: mode is explained as clean (committed text, default) vs tracked (suggestions as <ins>/<del>) vs accepted/rejected, and segment as body/header/footer/all with 'all' defined as body plus every labelled header/footer. page and account are left entirely to the schema, so it stops short of a 5.

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

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

Opens with a specific verb and resource plus the output contract: 'Read a Google Doc as markdown + inline HTML.' An agent can immediately distinguish this from write_doc, edit_doc, or export_doc without inspecting the schema.

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

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

Usage is only implied: the note that 'an edit that quotes one can give it back' hints at round-tripping with edit_doc, and mode/segment values imply selection contexts, but there is no explicit when-to-use / when-not-to-use guidance or named alternative (e.g., export_doc, get_page_setup). The agent must infer routing from sibling names alone.

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 disclose the key behavioral trait: expectQuotedText is verified against the live comment before mutation, so a stale id is refused rather than resolving the wrong thread. That is genuinely valuable safety context. Remaining gaps, such as required permissions or the shape of the follow-up read, keep it from a 5.

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

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

Three tight sentences, front-loaded with the action and the required-parameter rule; every clause carries usable information and nothing is repeated from the title.

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 and no output schema, the description covers the main correctness risk (wrong thread resolved via stale id) and points to the sibling that produces the required value. It leaves permissions and any returned confirmation unstated, which is a minor but real 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 80%, so most parameters are already documented, but commentId has no schema description and the description supplies its origin (the commentId from list_comments) along with the contract for expectQuotedText. It clarifies why the verification parameter exists and what happens when it fails, adding meaning beyond the schema text rather than restating it.

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

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

States a specific verb and resource ('Resolve (or reopen) a comment thread by comment id'), immediately distinguishing it from the read-only siblings list_comments and add_comment. The title and first sentence together let an agent place it precisely in the comment workflow.

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 routes the agent to list_comments as the source of the required `quotedText`, which is a concrete usage precondition rather than vague context. It doesn't cover access prerequisites or when a resolve should be skipped in favor of add_comment, so it stops short of naming exclusions explicitly.

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 supplied, so the description carries the full burden, and it does disclose real behavioral traits: units (72 pt = 1 inch), that orientation reorders width/height, and that the change is always applied directly with no suggest mode. It does not say whether omitted parameters are left untouched or reset, nor what permissions or return value to expect, which are the remaining 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?

Three tight sentences: purpose first, then units and parameter semantics, then the mutation-mode caveat. No restatement of the tool name and no filler.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers units, enum/object duality, orientation behavior, and mutation semantics adequately. It is only missing what a successful call returns and whether the update is partial or full — the one area the absent output schema would otherwise cover.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining that pageSize accepts a preset name or an explicit {width,height} in points and by clarifying that orientation "swaps the page dimensions" rather than being a no-op. The tab-path disambiguation is left entirely to the schema's path description.

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

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

States a specific verb and resource ("Set document-level page setup") and enumerates exactly what is changed: margins, page size, orientation. The "File > Page setup controls" mapping plus the doc-or-tab scope makes it immediately distinguishable from the read-side sibling get_page_setup.

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 clear context for when this applies (document-level page geometry on a doc or tab) and an explicit exclusion: "there is no suggest option," so the agent knows not to route this through the suggestion workflow used by edit_doc/apply_suggestions. It stops short of naming get_page_setup as the read counterpart, but the scope statement implies 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, the description carries the full burden and does so well: it discloses the on-disk side effect (writes/updates `.gdocs-mcp.json` up the tree), the restart semantics for write_doc's description versus the freshly-read refusal path, and the auth requirement on the account field. That is exactly the behavioral context an agent needs before mutating project state.

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

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

Front-loaded: the write target and file location come first, then behavior, then the how-to. It is dense and mostly earns its space, though the sentence about restart versus fresh-read refusal is tangled and takes a second pass to parse.

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

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

For a two-parameter mutation tool with no annotations and no output schema, the description covers file location, side effects, downstream behavior in write_doc, and the id-lookup workaround. Only the response shape (confirmation of what was written) is left implicit, which 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?

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: folder accepts a URL or id, either parameter alone is sufficient ("and/or"), and a folder given by name must first be resolved to an id via drive({ cmd: 'find' }).

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 concrete verb+resource: it writes the project's defaults to a `.gdocs-mcp.json` file in the cwd or an existing one up the tree. It names exactly what is being set (default account and/or default folder) and how that differs from siblings like get_project_config and set_page_setup.

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

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

It clearly states when the setting takes effect and how to resolve a folder given only a name (use drive({ cmd: 'find' }) and pass the id). It doesn't explicitly contrast with get_project_config for reading, but the usage context is otherwise unambiguous.

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

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

With no annotations provided, the description carries the behavioral burden and does well by disclosing that this is an access-granting mutation, that person sharing can optionally send a notification, and that role "none" disables link sharing. It does not mention required account permissions, idempotence, or what the operation returns, but the core state-changing behavior is clear.

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 tight sentences with no filler. The main action is front-loaded, followed by the person-sharing and link-sharing branches, with the alternative tool noted parenthetically at the end.

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 five-parameter tool with 100% schema description coverage and no output schema, the description supplies the missing behavioral context: the distinction between person and link sharing, notification behavior, and the meaning of role "none". Nothing essential for correct invocation is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema by explaining the `email` presence/absence branching and the effect of role "none" on link sharing. The `notify` behavior for person sharing is also clarified, though `path` and `account` semantics are left to the schema.

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

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

The description states a specific verb and resource: "Grant access to a Google Doc." It clearly distinguishes the person-sharing mode (`email`) from the link-sharing mode (no `email`) and explicitly names the sibling tool for revocation, `unshare_doc`. An agent can identify the tool's function and boundaries without opening the schema.

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

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

Usage is explicitly conditional: provide `email` to share with a person, omit `email` to set anyone-with-link access. It also states that role "none" disables link sharing and directs revocation of a specific person's access to `unshare_doc`, covering both when to use this tool and when to use an alternative.

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: it discloses that revocation is unrecorded and unrecoverable from version history, that expectRole/expectTitle act as verified pre-conditions that fail closed, that the owner is protected, and that hidden domain grants may exist to surprise the agent.

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

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

Front-loaded with the action, then addressing modes, then safety rationale — a sensible order with no filler sentences. It loses a point because the expectRole warning largely restates the schema's own expectRole description, which is mild duplication of structured data.

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 destructive 6-parameter mutation with no annotations and no output schema, the description supplies the pre-conditions, the safety model, the grant-addressing edge cases, and the failure behavior. Nothing material is left for the agent to guess.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it by explaining the email/permissionId routing decision and why expectRole must be echoed from a prior list_permissions call. It adds decision-relevant meaning, not just labels.

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

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

The first sentence gives a specific verb and resource ('Revoke a grant on a Google Doc'), which cleanly separates it from the sibling share_doc. The rest of the paragraph clarifies the two addressing modes, so the agent knows exactly what operation is being selected.

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 states when to use `email` versus `permissionId`, mandates list_permissions first for both the id and the role, and calls out the owner-refusal boundary. That is a full when/when-not/prerequisite statement rather than an implied one.

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: it discloses the two-step refusal/confirmLoss loss-summary protocol, what exactly would be destroyed (comments, suggestions, tab stops, TOC, equations, chips), that replacement resets paragraph styling, that unsupported CSS fails the whole write before anything is sent, and that suggest mode is reversible. This is a genuinely rare level of mutation-risk 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?

Almost every clause earns its place, but the body is a single very long paragraph mixing path semantics, styling rules, chip encoding, refusal behavior, and suggest mode, which makes it hard to scan under context pressure. It is front-loaded correctly (create/replace first), but structure could be improved with grouping.

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 mutation tool with no annotations and no output schema, coverage is strong: creation, replacement, headers/footers, styling, special elements, long-content handling, and suggestion mode are all covered. The only modest gap is that the return value is described in a single clause ('Returns images') without indicating what a successful write otherwise returns.

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 already 100%, but the description adds real semantics on top: path creation rules (absolute/id/URL only, bare names refused with the full path to call), the default-folder second refusal, tab-step nesting rules, segment header/footer behavior including the first/even refusal, page-type behavior, and page-break encodings. Nothing critical is left to schema inference alone.

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

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

Opens with a specific verb+resource: 'Write markdown-rendered content to a path', and immediately establishes the create-vs-replace dichotomy that defines the tool. It also explicitly routes away from the closest sibling ('prefer edit_doc to change a document'), so an agent can distinguish it from edit_doc/read_doc without opening schemas.

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

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

Gives concrete when-to-use rules: use contentFile for long documents, use suggest when the user wants to review or the doc isn't theirs, use edit_doc for in-place changes, and use drive mkdir before creating nested folders. It also states when NOT to act (never pass confirmLoss on your own; ask the user first) and enumerates what gets refused.

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