ShareWatch

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable conditional behavior: if the file is accessible it returns content, otherwise it returns a grant link. It also explains the file_name_hint parameter's role in the picker.

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

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

The description is compact, front-loads the usage trigger, and every sentence adds necessary context about behavior or parameters. The API reference link is supplementary, not 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?

Coupled with the annotations and output schema, the description covers what the tool does, when to use it, what inputs matter, and what happens in both accessible and inaccessible cases. Nothing critical is missing 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 100%, so the parameters are already well documented. The description restates that file_name_hint is used when the user mentions a file name, but does not add meaningful semantic detail 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 resolves a user-provided Google Drive URL and returns either file content or a grant link. It is specific about the resource and action, though it does not explicitly contrast itself with sibling tools like read_file or request_file_access.

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

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

The description gives explicit triggers: when a user shares a Google Drive URL or asks to access a specific file. It does not state exclusions or name alternatives, but the URL-focused guidance is clear enough to route the agent correctly.

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

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

Annotations already signal mutation and non-idempotency via readOnlyHint=false and destructiveHint=true. The description adds useful behavioral context: the target must be an existing Google Sheet, and the new tab's sheetId is returned, which goes 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?

Two clean sentences: the action is front-loaded, the usage condition is explicit, and the return value is stated. There is 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?

This is a low-complexity tool with only two required parameters, no nested objects, and an output schema present. The description covers the action, the prerequisite of an existing sheet, and the returned ID, making it complete for an agent.

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

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

Schema description coverage is 100%, so both parameters are already fully documented in the schema. The description does not add additional semantic detail about spreadsheet_id or sheet_name, which is acceptable given the baseline.

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

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

The description opens with 'Add a new tab to an existing Google Sheet,' using a specific verb, resource, and scope. It clearly distinguishes itself from sibling creation tools like create_spreadsheet by noting this is for adding to an already-created sheet.

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 explicit usage context: 'Use this when you need an additional sheet after creation.' However, it does not name alternatives or give explicit when-not-to-use conditions, so some routing is left to inference.

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

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

Annotations already mark this as destructive and non-read-only, and the description adds substantial context beyond that: blocking does not un-share the file, the name and ID can still appear in listings, there is no unblock tool, and the user must restore access from the dashboard. This gives an agent a realistic model of the operation's side effects and recovery path.

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: the action, the use case, and the critical caveat about irreversibility and the dashboard. The most important behavioral constraint is front-loaded.

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

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

For a two-parameter tool with a full input schema and output schema, this description covers the essential operational context: when to invoke it, what it does and does not do, and what the user must expect afterward. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not need to explain parameters further, and it does not add meaning beyond what the schema provides, which meets the baseline for fully covered schemas.

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 action and resource: "Block MCP access to a file." It also differentiates the behavior from un-sharing or deleting by clarifying that the file name and ID remain in listings, which helps distinguish it from siblings like delete_file and set_file_read_only.

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 gives the trigger condition: "Use when a user says they shared a file by mistake or wants an agent's access stopped." It also warns there is no unblock tool and directs the user to the ShareWatch dashboard, but it does not name specific sibling alternatives or say when not to use this tool.

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

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

The annotations carry only low-information false hints (not read-only, not idempotent, not destructive), so the description shoulders the behavioral burden and delivers: bullets win over body, an unfilled two-column side renders as a blank box when edited, all positioning is placeholder-driven with no manual geometry, and unrecognized layouts are rejected. This is substantial behavioral disclosure beyond the annotations, with no contradiction.

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

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

The description is long (~200 words) but the tool is genuinely complex — 11 layouts, 8 slide fields, precedence rules — and nearly every sentence earns its place. It is front-loaded (purpose, sibling contrast, core mechanic), then organized as a readable layout matrix before behavioral rules and workflow; minor redundancy exists where the early 'fill only the slots' rule is restated by the matrix.

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

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

An output schema exists, so return-value documentation is not the description's job. It covers the behavioral model, slot validity, precedence, and the describe_slides/preview_slides verification loop. The main gap: three of eleven valid PredefinedLayout enum values are not mapped in the description, though the Slides-API knowledge pointer and the fully covered schema partially compensate.

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, but the description adds meaning beyond the per-field schema text: a consolidated layout→slot matrix (TITLE gets a subtitle, SECTION_HEADER does not, TITLE_AND_TWO_COLUMNS must fill both sides or shows a blank box) and the bullets-over-body precedence rule. Only minor deduction because three enum layouts (SECTION_TITLE_AND_DESCRIPTION, ONE_COLUMN_TEXT, CAPTION_ONLY) are absent from the matrix, and field-level semantics are already well covered by 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?

Opens with a specific verb+resource: 'Create a Google Slides deck from a structured outline.' It then explicitly differentiates itself from the closest sibling, create_presentation, by contrasting raw slides against Google's own layouts, so an agent can disambiguate without opening either 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?

Names the alternative (create_presentation) and the condition that selects this tool: 'suits decks meant to look designed.' It also prescribes a post-call workflow — call describe_slides to catch dropped content/overflow/overlap, then preview_slides — telling an agent exactly what to run after this tool and why.

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

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

The annotations already indicate the operation is not read-only, but the description adds valuable behavioral context: it creates a new file, leaves the original unchanged, and requires user confirmation before conversion. This goes beyond what annotations alone provide.

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

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

Every sentence earns its place: the format mapping, the side-effect clarification, and the critical user-consent requirement. The description is concise, scannable, and front-loaded with the primary action.

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 one-parameter tool with an output schema, the description is complete. It covers what gets converted, the resulting formats, the side effect on the original file, and the required user interaction. No critical information for calling the tool 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?

The input schema fully documents the only parameter (file_id) with a description, so the schema carries the semantic burden. The tool description does not add further detail about the parameter, but none is needed given 100% schema coverage.

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

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

The description clearly states a specific verb and resource: converting Office or PDF files to the matching Google-native format. It lists concrete format mappings and distinguishes itself from create-related siblings by emphasizing conversion rather than creation.

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

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

The description gives clear context for when to use the tool: when an Office or PDF file needs to be converted to Google format. It also includes the important instruction to always ask the user before converting. It does not explicitly name alternative tools or state when not to use it, but the conversion use case is well-defined.

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 critical non-obvious behavior: Markdown is inserted literally and not rendered. This goes beyond the annotations, which only indicate mutation and non-idempotence, and prepares the agent for the '**'/'#' side effect.

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 tightly written sentences with no filler. The core action is front-loaded, and the Markdown limitation and the formatting workflow each get exactly one sentence.

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 low-complexity creation tool with a rich output schema and clear annotations, the description covers resource, destination, parameter behavior, and the follow-up tool for formatting. Nothing an agent needs 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?

The schema already documents both parameters fully. The description adds important semantic detail for the content parameter by explaining that it is plain text and that Markdown characters survive literally, going beyond the schema's minimal description.

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

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

The description names a specific verb and resource: create a new Google Doc in the user's Drive. It also calls out the non-rendering of Markdown, which clearly distinguishes this tool from format_document and sibling document-formatting 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 explicitly lays out the decision rule: use this for creating plain-text docs, and call format_document afterward when formatted output is desired. This routes the agent away from an obvious alternative without requiring schema inspection.

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

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

Annotations already indicate mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds the notable side effect that the folder 'can be set as the default location for new files,' which is meaningful behavioral context beyond the annotations. It does not discuss duplicate-name behavior or permissions, but these are secondary for this simple creation 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 three short sentences with no filler. It front-loads the core action, states the primary purpose, and then provides the useful default-location caveat. 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?

For a simple three-parameter creation tool with an output schema, complete parameter documentation, and safety-relevant annotations, the description covers what an agent needs to select and invoke it correctly. It could add caveats about duplicate names or permissions, but these are not critical given the schema and annotation 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 description coverage is 100%: name, parent_id, and set_as_default all have their own descriptions, including the root-folder behavior for parent_id. The free-text description only restates the set_as_default concept at a high level and does not add meaningful parameter detail beyond the schema. 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?

The description states a specific action and object: 'Create a folder in Google Drive.' This clearly distinguishes it from sibling creation tools like create_document or create_spreadsheet. The added purpose 'Use this to organize files' reinforces what the tool is for.

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

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

The description explicitly says 'Use this to organize files,' giving a clear use case. It does not name alternatives or exclusions, but the folder-vs-file distinction among sibling tools makes the appropriate context reasonably evident. This is clear guidance without formal when-not-to-use conditions.

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

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

The annotations already convey that this is a mutating, non-idempotent operation, and the description adds that it creates a brand-new artifact with optional slides. It does not disclose permissions, side effects, or what happens on validation failure, but the high schema coverage and output schema reduce the burden; nothing contradicts the annotations.

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

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

A single front-loaded sentence with no filler: the action, resource, and optionality are all present. It is concise rather than under-specified, though it leaves the sibling relationship unaddressed.

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 creation tool with a rich input schema and an output schema, the description is mostly sufficient. The notable gap is the unaddressed build_presentation sibling, which may leave an agent uncertain whether to select this tool or the alternative for creating slides.

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 slides_json parameter includes a detailed explanation of layouts and rejection behavior, so the schema carries the semantic weight. The description only adds 'optional slides,' which is useful but does not add parameter-level meaning beyond the schema.

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

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

The description uses a specific verb ('Create') and a clear resource ('a new Google Slides presentation'), and notes the optional slides payload. It differentiates from update_presentation and file-type siblings like create_document/create_spreadsheet, but it does not distinguish itself from the sibling build_presentation, which appears to accept the same slide layouts.

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 choose this tool over build_presentation or update_presentation, and no exclusions or prerequisites are stated. The schema mention of build_presentation hints at overlap, but the tool description itself does not route the agent to the correct alternative in any condition.

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

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

Annotations already communicate that this is a mutating, non-destructive, non-idempotent operation. The description adds useful behavioral context: passing sheet_names_json creates multiple tabs in one action, and data_json is written to the first tab. It does not contradict the annotations.

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

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

Two short sentences accomplish everything: the primary purpose is front-loaded, and the optional multi-tab behavior is stated in a compact parenthetical. There is no filler or redundant repetition of the schema.

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

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

Given the output schema and fully documented parameters, the description is mostly complete: it explains the create action and the important multi-tab/data-placement behavior. It is only slightly incomplete in not guiding the agent toward add_sheet_tab or update_spreadsheet for follow-up operations on existing sheets.

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 four parameters. The description adds a brief cross-parameter relationship between sheet_names_json and data_json, but this is largely already present in 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 states a specific verb and resource: 'Create a new Google Sheet.' This clearly distinguishes it from sibling tools like create_document and create_presentation, and from update_spreadsheet for modifications.

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

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

The description implies the tool is for creating new sheets and suggests using sheet_names_json for multi-tab creation, but it never explicitly contrasts with siblings like add_sheet_tab for existing sheets or update_spreadsheet for later edits. No exclusions or alternative-selection conditions are named.

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

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

Annotations already mark the tool destructive and non-read-only. The description adds meaningful behavioral context by emphasizing irreversibility ('cannot be undone') and requiring user confirmation before invocation. This goes beyond what the structured hints alone convey and helps the agent understand the severity and consent requirement.

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 short sentences, front-loaded with the action and permanence, and the confirmation warning is placed where it is likely to be seen. Every word earns its place; there is no filler or redundant restatement of the tool 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 simple one-parameter destructive action, the description covers the core details: what is deleted, that deletion is permanent, that user confirmation is mandatory, and that it cannot be undone. The existence of an output schema and the annotations cover safety and idempotency hints. It does not discuss permission requirements, but this is a minor gap for such a straightforward 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 single file_id parameter is already fully documented. The description names the resource type (Google Drive file) and adds the deletion context, but it does not add new parameter-level details. Baseline 3 is appropriate given complete schema coverage.

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

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

The description states a clear verb and resource: 'Permanently delete a file from Google Drive.' It explicitly signals permanence, which distinguishes this deletion tool from siblings like move_file or block_file. No ambiguity remains about what the tool does.

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

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

The description gives clear operational context: it is for permanent deletion and must not be invoked without prior user confirmation. It does not explicitly name alternative tools for non-permanent actions, so it stops short of a full when/not comparison, but the guidance is unambiguous and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: no image rendering, cheap operation, and specific layout flags for overflow, overlap, and sub-legible fonts.

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 focused sentences communicate purpose, behavior, return contents, cost characteristic, and usage guidance without redundancy. The most distinguishing fact (no image rendering) is front-loaded.

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

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

For a single-parameter, read-only inspection tool with an output schema and strong annotations, the description fully covers what an agent needs to select and invoke it correctly. It also provides the key sibling distinction from preview_slides.

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 only parameter, presentation_id, is already well documented in the schema. The description adds no additional parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Inspect') and names the resource ('layout of every slide'), immediately clarifying scope. It also draws a clear contrast with preview_slides by emphasizing geometry-level readback without rendering images.

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 this tool — 'catch mechanical layout problems while editing' — and points to preview_slides for the final visual pass. This gives the agent direct routing guidance, not just a vague context hint.

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

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

The annotations already mark destructiveHint=true, and the description adds the concrete destructive behavior: passing file_id replaces an existing doc's content. It also clarifies the non-destructive creation path when file_id is omitted and discloses supported formatting constructs, aligning with the non-read-only, non-idempotent annotation profile.

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

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

Two tight sentences carry the full message: what the tool does, which formatting features it supports, when to prefer it over siblings, and how to switch between creating and replacing. There is no filler or repetition of schema details.

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

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

Given the simple three-parameter schema, full schema coverage, existing annotations, and output schema, this description is complete. It gives the agent enough to select the tool, invoke it correctly in both modes, and understand the destructive consequence of providing file_id.

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 input schema already documents all three parameters thoroughly. The description reinforces markdown syntax and the file_id create-vs-replace behavior, but it adds little semantic information beyond what the parameter descriptions already provide.

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

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

The description opens with a specific verb and resource: 'Write markdown content into a Google Doc with full formatting.' It lists the exact formatting features and explicitly distinguishes itself from create_document and update_document, so an agent can immediately tell what this tool does and how it differs from its closest 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?

It gives an explicit selection rule: use this instead of create_document or update_document when content has structure that should be visually formatted. It also explains the two invocation modes — pass file_id to replace existing content, or omit it to create a new doc — covering the key routing decision.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing a safe, non-mutating operation. The description adds meaningful behavioral context beyond annotations: it surfaces setup problems as clear statuses and disambiguates among multiple configured connectors. No contradiction exists between description and annotations.

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

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

The description is three sentences with no filler. The primary purpose is front-loaded, followed by two sentences that add diagnostic context and a multi-connector edge case. Every sentence contributes 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?

For a parameterless, read-only diagnostic tool with an output schema, the description fully covers what the agent needs: the returned fields, the diagnostic role, and the multi-connector scenario. There are no missing prerequisites, side effects, or ambiguous edge cases.

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

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

The tool has 0 parameters, so the description correctly needs no parameter-level explanations. Under the rubric, 0 params warrants a baseline score of 4. The schema fully covers the empty parameter set and the description adds no unnecessary parameter details.

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 ('Report') and names the exact resource ('this user's ShareWatch setup status'), then enumerates the concrete items returned (email, workspace connection status, default folder, org membership, available actions). This clearly distinguishes it from the file-centric sibling tools, none of which provide connection or setup status.

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 tells when to use this tool: when setup problems need to be diagnosed, and notes that such problems appear here clearly rather than as confusing failures in other tools. It also provides a conditional use case for multiple connectors, specifying that this tool identifies the authenticated Google account.

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

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

Beyond the read-only and idempotent annotations, the description discloses the scoping model, the open-world caveat, and the fact that folders appear as entries with parent_folder_id defining hierarchy. These are non-obvious behaviors an agent needs to interpret results correctly.

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

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

Every sentence earns its place: scope, interpretation warning, and structural return details. The most important scoping information is front-loaded, and the description is dense but not bloated.

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

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

With no parameters, a rich annotation set, an output schema, and a description that covers scope, interpretation, and folder behavior, nothing needed to invoke this tool 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?

The tool has zero parameters, so there are no parameter semantics for the description to add. The baseline for parameter-free tools applies here, and the description appropriately focuses on output interpretation instead.

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 scope: 'List the Google Workspace files ShareWatch can see.' It immediately distinguishes this from a general Drive listing and makes clear that it is not showing everything the user owns.

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 interpretation guidance: a short list means a narrow grant, an empty list does not mean an empty Drive, and absence here is not proof of absence. However, it does not explicitly name an alternative like search_files for cases where a broader search is needed.

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

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

Annotations already cover the safety profile with readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the description does not need to restate those. It adds the useful ShareWatch accessibility precondition, but it does not disclose side effects like whether the source location is removed or how name collisions are handled.

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 short, front-loaded sentences convey the action, destination, and a key prerequisite without any filler or repetition of schema details. 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?

For a simple 2-parameter mutation with a full input schema, output schema, and annotations covering the side-effect profile, the description includes the essential precondition. It is complete enough for an agent to invoke correctly, though a sentence about source-folder behavior would make it fully comprehensive.

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

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

The input schema already provides full descriptions for both parameters, file_id ('The file to move') and folder_id ('The destination folder ID'), so schema coverage is 100%. The description adds only high-level context and an access requirement, which does not materially change parameter interpretation.

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 ('Move'), the resource ('a file'), and the destination relationship ('into a different folder'). This clearly distinguishes it from sibling tools like delete_file, upload_file, and create_folder without merely restating the name.

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 a clear usage context: moving a file between folders, with the precondition that both source and destination must be accessible to ShareWatch. It does not explicitly name alternatives or spell out when-not-to-use, but the context is sufficiently 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral detail by specifying that rendered PNG thumbnails are returned for each slide, which goes beyond what the annotations alone 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?

Two concise sentences deliver the core action, the output format, and the intended use case with no filler. The main action is front-loaded and every clause adds value.

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

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

For a simple, read-only tool with one parameter and an output schema, the description is essentially complete. It could have named a sibling like describe_slides for comparison, but the provided use case and return format are sufficient for an agent to invoke it correctly.

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

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

The schema covers the single parameter presentation_id with 100% description coverage. The tool description does not add new parameter-level meaning beyond restating that it operates on a Google Slides presentation, so the schema-driven baseline of 3 is appropriate.

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

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

The description states a specific verb ('Get') and resource ('thumbnail images for all slides in a Google Slides presentation'). It also clarifies the output format ('rendered PNG images'), which distinguishes it from sibling tools like describe_slides that likely provide textual descriptions.

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 a clear usage context: 'Use this for a final visual check of layout and formatting.' It does not explicitly name an alternative tool or state when not to use it, so it falls slightly short of full guidance, but the use case is specific and actionable.

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

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

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds meaningful behavior: format conversion rules, the size-warning behavior for large files, chunking support, and the lifetime and substitution semantics of ShareWatch handoff codes. No contradiction with annotations exists.

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

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

The description is front-loaded with the core behavior and output formats, then adds the secondary handoff-code detail in a separate paragraph. Every sentence contributes useful operational information with no redundancy or filler.

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

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

Given the annotations and output schema, the description covers all essential operational aspects: supported file types, output formats, large-file handling, pagination, and handoff-code behavior. An agent has enough context to invoke read_file correctly and interpret its results appropriately.

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

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

Input schema descriptions already cover all three parameters, so the baseline is solid. The description adds value by explaining the large-file warning behavior, how offset/max_chars work together for chunking, and the important instruction to use the returned real file_id rather than the handoff code in follow-up calls.

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: 'Read the text content of a Google Doc, Sheet, or Slides presentation.' It further clarifies output formats per resource type, which makes the tool's function unmistakable and distinguishes it from sibling create/update/list/search 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 gives clear guidance for large files: a size warning is returned unless max_chars and offset are used to chunk reads. It also advises using the real file_id from results for follow-up calls. It does not explicitly name alternative tools like access_file_by_url, but the context is clear enough for selecting this tool.

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

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

The description discloses meaningful side effects not captured by the annotations: the report is written to the user's own audit log, visible to the user and workspace administrators, and to ShareWatch's operational logs. This clarifies that the tool is not read-only and has persistent visibility.

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 average but every sentence earns its place: purpose, use cases, rationale, side effects, and content constraints. It is front-loaded with the core purpose, though some guidance repeats what is already in the schema's parameter description.

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 bug-reporting tool, the description covers what to report, how to report it, what not to include, and where the report goes. The output schema exists, so return-value details are not needed, and the description gives an agent enough context to select and invoke the tool appropriately.

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

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

Schema description coverage is 100%, so the schema already explains 'tool', 'file_id', and 'description' in detail. The description reinforces the 'description' parameter's intent but does not add essential parameter meaning beyond what is 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?

Purpose is explicit and actionable: 'Tell the ShareWatch developers what this server got wrong' names the verb, resource, and audience. It also distinguishes itself by covering both outright bugs and friction, which is broader than any sibling tool.

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

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

The description clearly states when to use the tool: for outright bugs and for friction like confusing parameters or unhelpful errors. It gives content exclusions ('Write about the tool, never about the user's documents or conversation'), but does not explicitly name alternative tools or a definitive 'do not use this for X' scenario.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so there is no safety contradiction. The description adds the crucial behavioral fact that the tool returns a user-facing authorization URL rather than direct file contents, which is essential for setting agent and user expectations.

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 contain no filler, the trigger condition is front-loaded, and the return behavior follows immediately. 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 one-parameter, non-destructive tool with an output schema and full annotations, the description covers trigger, behavior, and user-visible outcome. No critical call-time information 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?

The single parameter 'reason' is fully documented in the schema with 100% coverage, so the description does not need to add parameter-level detail. It adds no semantics beyond the schema, which meets the baseline for fully documented 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 states a specific trigger ('when a user wants you to access a file that isn't in the file list') and a concrete outcome ('returns a URL the user can open to select and grant access'). This clearly distinguishes it from sibling tools like read_file or access_file_by_url, which operate on already-available files.

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

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

It provides an explicit when-to-use condition: only when a wanted file is absent from the file list. It does not explicitly name alternate tools for files that are already listed, but the exclusion is clear enough for an agent to route correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by noting all parameters are optional and can be combined to narrow results. It does not disclose behavior like pagination or result limits, but those are largely optional given the strong annotation coverage and 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?

The description is three sentences with no wasted words. It front-loads the core function, then provides usage guidance and parameter semantics. 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?

With an output schema available, all parameters documented at 100% coverage, and descriptions covering alternatives and use cases, nothing critical is missing. The tool is simple and the description plus schema fully equip an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter's meaning and constraints. The description adds the useful general note that all parameters are optional and combinable, but it does not go beyond the schema for individual parameter semantics. 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 states a specific verb ('Search') and resource ('files'), and enumerates search dimensions: name, text content, type, and date range. It explicitly differentiates from sibling list_files by positioning search_files as the tool to use when looking for something specific. This is clear and 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 explicitly says to use this tool instead of list_files when the user has many files or is looking for something specific. It also guides on choosing the content parameter when the user remembers content but not the name. This gives clear when-to-use and alternative-selection guidance.

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

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

Annotations already convey mutation, idempotency, and destructiveness, so the bar for added value is lower. The description adds meaningful behavior: read-only files can still be read, enforcement happens at the proxy layer, and it applies regardless of Drive permissions. No contradiction with annotations.

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

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

Three short sentences, each earning its place: the action, the observable consequence, and the enforcement layer. Information is front-loaded and there is no filler.

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

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

For a simple two-parameter tool with a full output schema and annotations, the description covers the essential semantics and even clarifies edge behavior around Google Drive permissions. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and both file_id and read_only are adequately described in the schema. The tool description restates the effect of read_only but does not add much beyond the schema. This matches the baseline-3 expectation when the schema already documents parameters well.

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: 'Mark a file as read-only or read-write.' It clearly conveys the action and both directions of the toggle. It does not explicitly name a sibling alternative, but the semantics are distinct enough from delete_file, move_file, and block_file.

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

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

The description provides clear context: this controls whether files can be updated through ShareWatch, and it operates at the proxy layer independent of Google Drive permissions. It implies when to use it—when ShareWatch-level write protection is needed—but it stops short of explicitly contrasting it with alternatives or stating when not to use it.

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

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

Annotations already flag destructiveHint=true, and the description adds crucial nuance: 'replace' clears all content, 'append' does not, and the result reports the mode actually applied plus character count. This lets an agent verify that a destructive replace happened as intended, which is valuable context beyond the structured annotations.

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

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

Three sentences, no filler, with the core action first and the operational modes second. Every sentence contributes either a concrete capability or a safety-related confirmation behavior.

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 fully documented input schema, the output schema, and annotations covering destructive behavior, the description covers everything essential for correct invocation. It even adds the verification detail about reported mode and character count, which reduces ambiguity without needing to restate return schemas.

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 document_id, content, and mode thoroughly, including default and validation behavior. The tool description mostly paraphrases the mode semantics and adds no new parameter-level meaning beyond emphasizing that the result reports the applied mode.

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: 'Update an existing Google Doc,' and immediately distinguishes the two supported operations (replace all content or append). The mention of 'existing' differentiates it from create_document, and the resource type differentiates it from update_spreadsheet and update_presentation.

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 indicates this tool is for updating a Google Doc and explains the two modes, including the default behavior. It does not explicitly name sibling alternatives or state when-not-to-use, but the resource-specific language provides enough context for an agent to select it appropriately.

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

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

The description goes beyond the destructiveHint annotation by explaining that invalid or incomplete operations are rejected with a message naming the operation, and that nothing is silently skipped. It also discloses Google's alternative spellings are accepted, which is valuable behavioral detail not available from the schema or annotations.

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

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

The description is front-loaded with the core purpose, then progresses logically from structured operations to raw mode. The operation list, examples, rejection behavior, and raw-mode note all earn their place; nothing feels redundant or padded.

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 two modes and a destructive annotation, the description is remarkably complete: it covers accepted operations, alias handling, error behavior, example payloads, and raw-mode usage with documentation. The presence of an output schema means return values need no additional explanation, and the structured-mode rejection guarantees provide sufficient safety context.

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

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

Even though schema coverage is 100%, the description substantially enriches parameter understanding: it lists all valid operations_json values, provides concrete examples for several operations, explains alias acceptance, and documents raw_requests as a BatchUpdatePresentationRequest body with a reference link. This is far more useful than the bare 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 'Modify an existing Google Slides presentation,' a specific verb-action plus resource that clearly distinguishes it from creation, inspection, and preview siblings. It also enumerates the exact structured operations supported, making the tool's scope concrete.

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 frames when to use the tool — modifying an existing presentation — and contrasts the two invocation modes: structured operations for common edits and raw mode for full API access. It does not explicitly name sibling alternatives or say 'use create_presentation for new presentations,' but the 'existing' qualifier provides adequate contextual guidance.

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

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

Annotations establish destructiveHint=true and readOnlyHint=false, but the description goes much further: it discloses that values are stored EXACTLY AS GIVEN by default, that '=B1+B2' becomes literal text unless USER_ENTERED is used, that an error 'Unable to parse range' occurs for unknown tabs, and that the result carries formula_notice. These are non-obvious behavioral details that materially affect invocation and interpretation.

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: purpose, a key prerequisite with an example, failure mode with a routing instruction, the important exact-storage caveat with the fix, and a note about the result payload. The most critical constraints are front-loaded, and there is no filler or repetition of schema 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 destructive write operation, the description covers the core prerequisites, the error path, the behavioral nuance around formulas, the alternative for creating tabs, and the formula_notice in the result. An output schema exists, so return-value documentation is not the description's burden. Nothing essential is missing for correct tool selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema: it gives a concrete tab-name example for range, explicitly connects the range requirement to the add_sheet_tab sibling, and reinforces the formula-storage distinction. This elevates the parameter documentation beyond what the schema alone provides, though not to a 5 given the schema is already thorough.

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

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

The description opens with a specific verb and resource: 'Write data to a range in an existing Google Sheet.' It clearly distinguishes this from siblings like update_document and update_presentation by targeting spreadsheets, and it implies the sheet must already exist, which differentiates it from create_spreadsheet. The purpose is immediately understandable and unambiguous.

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

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

The description gives explicit when-to-use guidance: it states the sheet must already exist, names the failure mode for unknown tabs, and directly instructs the agent to 'call add_sheet_tab first' when creating new tabs. It also tells when to choose value_input_option='USER_ENTERED' instead of the default RAW behavior. This is exemplary routing 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?

Adds two behaviors beyond the annotations: the 'Maximum 20MB decoded' size cap and the convert=true conversion semantics (Office formats → native Google formats). Annotations already signal a non-idempotent write (readOnlyHint=false, idempotentHint=false), and the description is consistent with them; it stops short of describing duplicate-file behavior on repeated calls, but that is partly carried by idempotentHint=false.

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 with no filler: purpose, when-to-use, and the two behavioral caveats (conversion, size limit). The most distinctive fact — base64 ingestion — is front-loaded, and 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 100% parameter coverage, an output schema, and safety annotations, the description covers the remaining decision-relevant facts: allowed source formats, ingestion path, conversion toggle, and the 20MB boundary. Nothing an agent needs to select or invoke this tool 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 all five parameters are already documented; the description mostly restates content_base64, convert, and the 20MB cap found in the schema. It adds modest context via file-type examples and the 'attached spreadsheet' use case, but it does not meaningfully extend parameter semantics beyond what the schema 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 and resource — 'Upload a binary file … to Drive from base64-encoded content' — with concrete format examples (xlsx, pdf, docx, png). The second sentence ('when you have file bytes from the conversation … put them in the user's Drive') clarifies its niche relative to sibling creation tools like create_document or create_spreadsheet, which build files natively rather than ingesting external bytes.

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 an explicit when-to-use condition: 'Use this when you have file bytes from the conversation (e.g. an attached spreadsheet) and need to put them in the user's Drive.' It does not state when-not conditions or explicitly contrast alternatives such as convert_to_google_format, so exclusions are left unstated — clear context but no named alternatives.

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