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

Annotations only flag readOnlyHint: false and idempotentHint: false, but the description goes far beyond them: it warns that re-appending duplicates rows, explains what happens with INSERT_ROWS vs OVERWRITE (data shifts vs writes into free rows), and documents that the response's updates.updatedRange reveals where rows landed. This is exactly the behavioral context that the flat annotation flags cannot convey. 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?

Four dense sentences, all carrying operational value: purpose+mechanism, response behavior, option semantics, and the retry warning. The core purpose is front-loaded and the retry guidance earns its place as critical safety information. Slightly long, but 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?

Complete for a 5-param mutation tool with no output schema: it covers the append mechanism, the return field (updates.updatedRange) since no output schema exists, option semantics, and the retry safety path. The only minor gap is that the alternative write_values is never explicitly named for choosing the right tool in the first place.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value on top: concrete range format examples ('Sheet1!A1:D1' or just 'Sheet1') clarify how the table region is specified, and it explains the behavioral difference between INSERT_ROWS and OVERWRITE beyond the enum labels. The values and spreadsheet_id params are already well-handled 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?

The description states a specific verb+resource combo ('Appends rows after the last row of the data table') and explains the distinguishing mechanism — the API finds the first free row from a table region. This clearly separates it from write_values (targeted range) and batch_write_values without needing to open either sibling's 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?

The description gives explicit guidance for the retry case: 'Never retried after an ambiguous failure... check the sheet first (read_values) before re-sending,' naming the exact alternative tool and the condition for using it. It explains insert_data_option behavior, but it never explicitly contrasts append_values with write_values for the normal case — the 'finds the first free row itself' mechanism implies it, but the sibling distinction isn't made explicit.

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

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

The description discloses overwriting behavior (destructive), idempotent nature (consistent overwrite), and return fields (totalUpdatedCells, responses[]). It explains USER_ENTERED vs RAW and null skipping. These details add value beyond the annotations (destructiveHint, idempotentHint) without 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?

Three sentences, each earning its place: the quota advantage, the input structure and options, and the return value. No fluff, front-loaded with the key differentiator.

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

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

For a multi-range write tool, it covers the alternative (write_values), the input format, the option semantics, null behavior, and return fields. With no output schema, it provides enough for an agent to call it correctly. The mention of returns is sufficient for the given complexity.

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 parameters are well-documented. The description adds a high-level summary of the data structure and explains value_input_option choices, but these are largely redundant with the schema. It provides narrative coherence but no substantial new semantic information.

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 (overwrites several A1 ranges in one call), distinguishes it from looping write_values, and highlights the benefit of a single quota write. It is specific 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?

Explicitly instructs to prefer this over looping write_values, referencing the alternative directly. Also explains value_input_option semantics and null skipping, providing clear context for when to use this tool.

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

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

Annotations already flag destructive=true and readOnly=false, but the description adds valuable beyond-annotation context: 'no undo through the API' and the precise closure that formatting, data validation, notes, conditional formats, and merges all stay. This materially expands what the agent knows about side effects and postcondition state. There is no contradiction with annotations.

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

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

The description is two sentences with zero filler, front-loading the core semantics first and then routing edge cases to alternatives. Every clause earns its place by either refining behavior or disambiguating siblings.

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

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

For a destructive mutation tool with no output schema, the description tells the agent what happens, what does not happen, that it is irreversible, and which sibling to choose for nearby operations. Combined with the fully covered schema and clear annotations, nothing needed to call 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 description coverage is 100%, so the schema already fully documents both parameters, including the A1-notation examples and the spreadsheet URL format. The description's 'one or more A1 ranges in a single call' adds process context but not new parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Empties the VALUES of one or more A1 ranges') and precisely scopes what is affected: cell contents and formulas are removed while formatting, validation, notes, conditional formats, and merges are preserved. This clearly distinguishes the tool from siblings like format_cells, manage_dimensions, and raw_request.

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 names the alternatives for adjacent use cases: 'To also remove formatting use format_cells or raw_request; to delete whole rows/columns... use manage_dimensions action=delete.' This makes the selection criteria concrete and leaves no inference about when clear_values is or is not the right 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 behavior beyond the annotations: the created file's location, the sheet creation behavior with sheet_titles, the default 'Sheet1' fallback, and the returned structure. It also explains a limitation of the Sheets API that affects subsequent operations, which is valuable context not present in the annotations.

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

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

The description is information-dense but well structured: it leads with the core action and return value, then covers file placement and API limitations. Every sentence contributes practical, decision-relevant information without repetition 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?

Because there is no output schema, the description correctly explains the return fields: spreadsheetId, spreadsheetUrl, properties, and sheets[]. It also covers the missing Drive API folder behavior and the lack of a native list endpoint, which are critical for an agent to set correct expectations and handle the returned ID properly.

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

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

Schema description coverage is 100%, so the schema already explains each parameter. The description adds meaningful behavioral semantics beyond that, such as 'sheet_titles creates one tab per title in order' and 'omitted = a single default "Sheet1"', which clarifies how the array parameter affects the result.

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

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

The description states a specific verb and resource: 'Creates a new Google Sheets spreadsheet and returns it...' and enumerates the returned fields. It is immediately distinct from sibling tools like search_spreadsheets or write_values, so an agent can tell what this tool does without ambiguity.

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

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

The description gives practical usage context: the file lands in My Drive root, moving it requires the Drive API which is not covered, and the spreadsheetId should be saved because there is no native Sheets list endpoint. It also names search_spreadsheets as the alternative for finding spreadsheets, while noting the Drive scope requirement.

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

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

It discloses the key behavioral guarantee: 'Only the provided properties are touched — the update mask is computed automatically, so existing formatting outside it survives,' which goes beyond the readOnly/destructive/idempotent annotations. It also clarifies that formatting fields must be supplied and that range coordinates are 0-based. It does not discuss return or error behavior, but the annotations cover the main safety profile.

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

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

Three dense sentences with no filler; the core action and most important side-effect ('only provided properties are touched') are front-loaded. The first sentence is a long enumeration, but that is acceptable given the breadth of 15 formatting 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?

The description covers selection, update behavior, range addressing, required-field constraints, and color format, which is substantial for a mutating formatting tool with no output schema. Remaining omissions such as return value and potential errors are minor against the fully documented input schema and annotations.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond individual field docs: it explains the automatic update mask, the requirement to provide at least one formatting field, and the '#RRGGBB' color convention. This helps the agent understand which optional parameters form a valid call.

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: 'Applies cell formatting to a range,' then enumerates all supported formatting categories such as background color, font styles, alignment, wrap, and number format. This makes it easy to distinguish from sibling tools like write_values, set_borders, and clear_values.

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

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

The description clearly signals this is the tool for styling cells rather than writing values or managing sheets, and adds a concrete validity constraint: 'at least one formatting field is required.' It does not explicitly name alternative tools or state when not to use it, but the context is strong enough for correct selection.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds important behavioral context: by default no cell data is returned, include_grid_data is heavy, and fields is a partial-response mask. This goes beyond the annotations without contradicting them.

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

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

The description is dense but every sentence earns its place: it inventories the returned structure, states the triggering usage rule, and warns about payload weight. It is front-loaded with the most important information and contains 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 read-only metadata tool with no output schema, the description fully covers return shape, default behavior, parameter trade-offs, and when to call it. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds extra meaning: include_grid_data is described as heavy, fields is positioned as a payload-trimming mask, and ranges are explained in A1 notation. This is above the baseline but still not a fully exhaustive parameter contract.

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 ('Returns the spreadsheet's structure') and enumerates the exact payload components, so an agent immediately understands what the tool does. It also distinguishes itself from read_values, which covers cell data retrieval, making sibling differentiation clear.

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

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

The description explicitly says to call this tool FIRST whenever a structural tool needs ids like sheetId, tableId, or chartId, and warns that titles are not addresses. It also directs agents to prefer read_values for cell data, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark destructiveHint=true, and the description adds specifics: delete removes the chart by chart_id, while update REPLACES the entire spec with no partial mutation. It also discloses that spec overrides the simplified fields, which is useful behavioral context beyond the annotations.

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

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

The description is dense but lean, front-loading the tool's purpose and moving through actions in a logical order. Parenthetical definitions compress a lot of parameter meaning. It could be easier to scan with line breaks, but no sentence is 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 12-parameter tool with no output schema, the description covers all key workflow elements: how to describe ranges, how to place the chart, how chart IDs are obtained, and what the add reply returns. The only mild gap is that update does not state whether position fields are honored or ignored, but overall it is sufficient.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The prose adds practical semantics beyond the schema: ranges must be single columns/rows including the header cell, header_count defaults to 1, PIE takes exactly one range, and spec overrides the simplified fields. That extra guidance justifies a 4.

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 'Manages embedded charts' and then enumerates the three selectable actions (add/update/delete), specifying that add builds a chart from chart_type plus data ranges. This clearly distinguishes the tool from sibling spreadsheet tools and from raw_request.

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 action-by-action guidance: add uses chart_type and ranges, update replaces the whole spec and explicitly rules out partial updates, and delete removes by chart_id. It also tells the agent where to find chartIds (get_spreadsheet) and that non-basic chart kinds should go through spec rather than the simplified fields.

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?

Even though annotations already indicate destructive and non-read-only behavior, the description adds meaningful operational detail: first-match-wins evaluation, highest-priority default index 0, update replacing the ENTIRE rule, and index shifting after mutations. This goes well beyond what annotations or schema express.

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

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

The description is dense but every sentence earns its place. It front-loads the core addressing model, then systematically covers add/update/delete semantics without filler or repetition.

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

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

For a complex 11-parameter mutation tool with no output schema, the description covers addressing, state sourcing, side effects, action-specific requirements, condition types, formula usage, and required format fields. Nothing essential for correct invocation 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%, but the description still adds significant semantic value by specifying action-dependent requirements: add needs ranges, condition_type, condition_values, and at least one format field; update/delete require sheet_id + index; CUSTOM_FORMULA needs a '=...' formula; index defaults to 0 for add. This is a strong enhancement over raw 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 a specific verb and resource: 'Manages conditional-format rules that style cells when a condition holds.' It immediately scopes the tool to boolean rules and explicitly routes gradient color scales to raw_request, distinguishing it from siblings.

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

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

The description gives concrete usage context: rules are addressed by sheet + index, current rules are read from get_spreadsheet, and indexes must be re-read after every mutation because add/delete shift later indexes. It also names raw_request as the alternative for gradient color scales, providing clear routing.

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

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

The description adds substantial behavioral detail beyond the annotations: delete is described as irreversible with cell-reference shifts, hide/show explicitly does not touch data, insert explains formatting inheritance direction, and group/ungroup explains nesting behavior. This goes well beyond the destructiveHint and readOnly 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 dense and front-loaded with the core concept, followed by actions separated by semicolons. Every piece of information earns its place, though the long single-sentence structure could be more scannable with bullet points.

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

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

Despite having no output schema, the description fully covers all eight actions, parameter roles, index math, and edge-case behaviors such as irreversibility and formatting inheritance. An agent has all necessary context to invoke the tool correctly on any of the supported operations.

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 all parameters. The description enriches this with concrete examples like 'columns A-C = start 0, end 3', explains the inclusive/exclusive index boundary, and clarifies how action-specific parameters (pixel_size, inherit_from_before) affect behavior.

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 the exact resource ('rows/columns') and the verb ('operations'), then enumerates each action. It differentiates itself from sibling tools like manage_sheets and set_frozen by specifying row/column run semantics rather than sheet-level or formatting operations.

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

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

The scope is clearly stated: this handles row/column operations on a run, with explicit indexing and action semantics. It does not explicitly name alternatives or exclusion conditions, but the context is unambiguous enough for an agent to select this tool for row/column operations.

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

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

Goes well beyond the annotations: discloses that revoke removes access immediately, anyone grants make the link public, a Drive scope is required while Sheets scope fails, pagination is one page per call, and shared-drive pages cap at 100. This is substantial behavioral context beyond destructiveHint and readOnlyHint.

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

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

The description is long but tightly structured around the four actions, with the core purpose and critical auth caveat front-loaded. Every sentence adds necessary information; there is no filler or 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?

For a 12-parameter, four-action tool with no output schema, the description is remarkably complete. It covers all action semantics, parameter combinations, defaults, pagination, auth requirements, destructive behavior, and the boundary with a sibling tool. Nothing essential 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?

Even though schema coverage is 100%, the description adds meaningful semantics: action-specific parameter usage, defaults, pagination flow, and consequences of certain values like domain/anyone. It explains how page_token, permission_id, and send_notification_email behave in practice, which the schema alone does not convey.

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

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

Description states a specific resource (Drive permissions on the spreadsheet) and enumerates each action (list, grant, update, revoke). It explicitly distinguishes itself from the sibling manage_protected_ranges, so an agent can tell exactly what this 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?

Provides explicit per-action usage conditions: which parameters are required for each grantee type, pagination handling with nextPageToken, and defaults for send_notification_email and allow_file_discovery. It also explicitly routes range-protection work to manage_protected_ranges instead.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=true. The description adds important context: action=delete removes protection but keeps data intact, the calling user is NOT automatically added as an editor, and warning_only behavior. It does not explicitly warn about potential data exposure or irreversible updates, but it adds meaningful behavioral detail.

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

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

The description is dense but well-organized: it structures content by action and front-loads the purpose. It is longer than average, but each clause conveys a meaningful behavioral constraint or workflow hint. Some repetition of schema details (emails, editor_groups) could be trimmed, but overall it earns its length.

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 mutating tool with no output schema, the description covers action semantics, required parameters per action, the effect of delete on data, editor authorization rules, and how to discover existing protections. It also hints at the return value (new protectedRangeId). No critical information is missing for an agent to select and use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining action-specific required parameters (protected_range_id for update/delete, named_range_id versus range for add), and clarifies that in update mode provided fields replace old values. It also brings attention to the caller-not-automatically-added nuance that the schema does not express.

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 it manages protections that stop other editors from changing cells, with explicit action=add/update/delete semantics. It distinguishes itself from sibling tools focused on formatting, values, or permissions by naming the resource (protected ranges) and behavioral outcome.

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

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

The description explains when to use each action and provides a pointer to get_spreadsheet for finding protectedRangeIds. It implies this tool is for protecting ranges rather than editing cells or managing general permissions, but does not explicitly mention alternative tools to avoid.

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 mutating/destructive behavior, and the description adds significant specifics: delete is irreversible through the API, deleting the last sheet fails, copies arrive named 'Copy of ...', and the default grid is 1000×26. It also states the output shape (batchUpdate replies with affected sheet properties), which is especially valuable with 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?

The description is longer than average but every sentence conveys a distinct operational constraint or behavior. The action-by-action structure makes it scannable, and the primary purpose is front-loaded.

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

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

This is a polymorphic tool with five actions, one enum, and eight parameters, and the description covers action-specific semantics, parameter requirements, edge cases, and output shape. An agent has enough information to invoke every action correctly even with no 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 100% and property descriptions already encode action-conditional meanings, so the bar for extra value is high. The description still adds useful cross-action guidance, the default grid size, the copy-to naming convention, and the pointer to get_spreadsheet for resolving sheet_id.

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 leads with a specific resource ('sheets (tabs) of a spreadsheet') and then enumerates five distinct verbs (add, duplicate, rename, delete, copy_to), making the tool's scope unmistakable. This clearly separates it from sibling tools like manage_dimensions or manage_charts.

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

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

The description gives actionable cross-tool guidance, notably telling the agent to get sheet_id values from get_spreadsheet and noting that a renamed tab keeps its numeric sheetId so other tools keep working. It does not explicitly state when not to use this tool versus each sibling, but the action list makes the targeted sheet/tab use case obvious.

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 destructiveHint annotation, the description specifies exactly what delete destroys — the table definition only, not cell data — and discloses that expanding the range grows the table and that DROPDOWN adds a dataValidationRule. These are important side effects an agent needs to predict before invoking the 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 dense but organized by action and front-loads the feature identity. The inline JSON example is somewhat long but earns its place by showing the exact expected shape of column_properties, so nothing feels 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?

The description covers all three actions, required parameters, side effects, and how to discover tableIds. Since there is no output schema, the mention of the add reply carrying the new table is helpful, though update/delete response shapes and failure conditions such as duplicate names are not described.

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

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

The description adds significant meaning beyond the schema: it explains action-dependent parameter requirements, gives an explicit JSON example for column_properties, lists the allowed columnType values, and clarifies how the first row becomes the header. This goes well beyond the schema's generic 'raw TableColumnProperties list' 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 the concrete resource — structured tables via the Convert to table feature — and enumerates the distinct actions: add, update, and delete. It clearly distinguishes itself from sibling tools like format_cells or manage_sheets by describing the named-range table feature rather than generic formatting or sheet operations.

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

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

Each action has clear preconditions: add requires a unique name and range, update requires table_id, and delete removes only the table definition. It also directs users to get_spreadsheet for tableIds and notes that cell data must be cleared separately, implying the complement of clear_values, though it never explicitly names an alternative 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?

Beyond the annotations (destructive, open-world, not idempotent), the description discloses that the Bearer token is added automatically, that the method defaults to GET with PUT for values updates, that the path may carry a query string, and that batchUpdate requests are atomic. These details materially affect how an agent invokes the tool and what it should expect.

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

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

The description is dense and front-loaded with purpose, but the list of examples is long. Each example earns its place by illustrating what the typed tools do not cover, yet the sentence could be slightly more compact. Overall, it is well-structured and every sentence contributes 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 generic raw API tool with no output schema, the description covers the key operational aspects: path construction, method selection, body usage, authentication, and scope restriction. It also includes representative use cases that signal to the agent what kinds of operations are possible. Nothing essential is missing for an agent to invoke this correctly.

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

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

The schema already provides 100% coverage for the three parameters, so the baseline is 3. The description adds useful semantic context beyond the schema: an example path format, the body shape for batchUpdate, the note that methods are limited to GET/POST/PUT, and the reminder that body is for POST/PUT only. This is meaningful but not exhaustive, so a 4 is appropriate.

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

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

The description clearly identifies the tool as an escape hatch for arbitrary Google Sheets API v4 paths, with a specific verb ('call any ... path directly') and a clear resource boundary ('Sheets API paths only'). It distinguishes itself from the typed sibling tools by stating it covers requests they don't. The examples further clarify the intended scope.

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

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

The description explicitly states when to use this tool: 'for requests the typed tools don't cover', and provides concrete examples like batchUpdate with mergeCells, slicers, and developer metadata. It also gives an exclusion ('Drive paths are not reachable here') and explains the default method behavior, giving an agent enough to decide between this and a typed sibling.

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 read-only and idempotent, and the description adds meaningful behavioral detail: trailing empty rows/columns are omitted, fully empty ranges omit the values key, and date rendering depends on value_render_option and date_time_render_option. This goes well beyond the structured hints.

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

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

The description is dense but well-organized: the core behavior and quota benefit are front-loaded, followed by return-shape details and then option semantics. Every sentence conveys a distinct, useful fact without redundancy.

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

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

Even with no output schema, the description fully covers return structure, edge cases, option behavior, and quota implications. Combined with the annotations, an agent has everything needed to call this tool correctly across all documented options.

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%, but the description still adds significant meaning: it explains what FORMATTED_VALUE means in terms of display formatting and locale, gives a concrete formula example, and clarifies how UNFORMATTED_VALUE affects date serial numbers. This enriches all option parameters beyond the schema.

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

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

The description states a precise verb and resource: "Reads one or more A1 ranges in a single call." It also explains the return shape (valueRanges[], 2-D arrays), which makes the tool's purpose unmistakable and clearly distinguishes it from sibling write/clear 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 context about batching multiple ranges into one request to conserve quota, which helps an agent decide how to use it efficiently. It does not explicitly name alternatives or state when not to use it, but the purpose is clear enough against siblings like write_values and clear_values.

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 readOnly/idempotent annotations, the description discloses meaningful behavior: results are limited to openable files, trashed files are excluded, ordering is newest-modified first, and the tool uniquely goes through the Drive API. The 403 failure mode without a Drive scope is especially valuable and goes far beyond annotation defaults.

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

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

The description is dense but each sentence earns its place: scope, returned fields, filtering, pagination, and the critical auth caveat. It front-loads the core purpose before the scope requirement, making it efficient for an agent to parse.

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

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

With no output schema, the description compensates by listing the returned fields and default ordering. It covers pagination, filtering, exclusions, and authentication failure modes. For a 4-parameter read-only listing tool, nothing essential 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. The description adds semantic context on top: name_contains is a substring filter with 'omit to list everything', page_token is tied to nextPageToken, and order_by has a documented default. This enriches the schema rather than repeating it.

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

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

The description uses a specific verb ('Finds') and names the exact resource ('Google Sheets spreadsheets the authorized user can open'), including exclusions like trashed files and shared drives. It lists returned fields and default sorting, clearly distinguishing this search/list operation from sibling tools like get_spreadsheet or read_values.

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

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

It gives clear operational guidance: omit name_contains to list everything, use page_token for pagination, and handle the Drive-scope requirement. It does not explicitly contrast with get_spreadsheet or other alternatives, but the search/list context is unmistakable and practical.

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 mutability and destructiveness; the description adds meaningful behavioral context by noting that 'only the provided sides change' and that NONE removes a border. It also clarifies the default color, which is not obvious from the schema alone. No contradiction with the annotations is present.

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

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

The description is compact and front-loaded, with every sentence contributing necessary semantics: range positioning, side grouping, style options, non-destructive behavior, and color format. There is no filler or repetition of the input 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 rich input schema and annotations, the description covers the remaining conceptual gaps: what inner vs outer means, that only specified sides change, that at least one side is required, and how colors are specified. No output schema is present, but the tool's invocation semantics are sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by grouping top/bottom/left/right as outer edges, inner_horizontal/inner_vertical as internal grid lines, explaining the {style, color?} shape, and noting the default black color. This goes beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Draws borders around and/or inside a grid range.' It clearly defines outer vs inner sides, making the tool's scope unambiguous. It does not explicitly differentiate from siblings like format_cells, but the border-specific language is enough to identify its purpose.

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 operational context: it explains which parameters affect outer edges vs inner grid lines, states that only provided sides change, and requires at least one side. It does not name alternatives or spell out when not to use the tool, 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?

Beyond the annotations, the description discloses key behaviors: OMIT condition_type removes validation, overwrites any previous rule, one rule per cell, strict=true rejects vs false warns, and input_message provides help text. This is substantial behavioral context and aligns with destructiveHint=true.

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

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

The description is dense but every sentence contributes operational value: setting, clearing, dropdown behavior, strict mode, input message, and overwrite semantics. The core set/clear behavior is front-loaded, with no filler.

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

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

Given the rich schema, nested range object, and annotations, the description covers all decisions an agent needs: how to configure a rule, when to omit fields to clear, what strict does, and what gets overwritten. No output schema is needed for a mutation tool whose success response is standard.

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

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

Although schema coverage is 100%, the description adds significant meaning: ONE_OF_LIST plus show_custom_ui=true creates the dropdown, ONE_OF_RANGE takes a formula reference, CUSTOM_FORMULA is evaluated per cell, and condition_values shapes are explained with examples. This goes well beyond the raw 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 action ('Sets — or clears — a data-validation rule on a grid range') and names the exact resource and scope. It clearly distinguishes itself from formatting, conditional formats, and sheet-management siblings by focusing entirely on data validation rules.

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

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

The description explains when to use different condition types and how to clear validation, which gives actionable usage guidance. It doesn't explicitly name alternatives, but no sibling tool covers data validation, so the omission is minor.

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

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

Beyond the annotations (idempotent, destructive), the description adds important behavioral detail: 0 unfreezes, omitting one dimension leaves it unchanged, and freezing all rows/columns is prohibited. These are non-obvious state-change semantics that an agent must know to call the tool correctly. There is no contradiction with 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?

Four short sentences pack distinct information: purpose, unfreeze behavior, partial-update semantics, and the boundary condition. The most identifying information appears first, and every sentence earns its place without 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 simple mutation tool with no output schema, the description plus annotations and full parameter schema cover everything needed to invoke it correctly: the action, typical usage, reversal, partial-update behavior, and the key restriction. No material gap remains.

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?

With 100% schema description coverage, the baseline is 3 because the schema already documents each parameter. The description adds value by clarifying the hidden constraint that at least one of frozen_rows or frozen_columns is required, and by giving the typical semantic of frozen_rows=1 for pinning a header.

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

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

The description uses a specific verb and resource: it freezes the first N rows and/or columns of a sheet so they stay visible while scrolling. The concrete example (frozen_rows=1 pins the header) and the distinction between rows and columns make the purpose unambiguous and distinguish it from sibling tools that format cells, manage sheets, or edit data.

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 the intended use case—keeping rows/columns visible while scrolling—and gives a typical scenario for pinning a header. It does not explicitly name alternatives or say when not to use it, but no sibling tool competes for the same freeze action, so 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 mark destructiveHint=true, and the description adds depth: explains anchoring, that cells beyond matrix are untouched, null entries skip (not clear) cells, and the parsing behavior for USER_ENTERED vs RAW. This goes beyond annotations and accurately describes side effects without 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 three sentences with dense, useful information. It front-loads the primary action and return value, then details edge cases and alternatives. Slightly long but every clause earns its place; could be trimmed but remains efficient.

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?

Covers the return fields (updatedRange/updatedRows/updatedColumns/updatedCells), key behaviors, and sibling distinctions. It lacks error-handling details or quota specifics (beyond batch hint), but given no output schema, this is sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description enriches each parameter: range anchoring, null behavior in values, and concrete examples for value_input_option ('=SUM(A1:A10)' becomes formula, '1,234' becomes number/date). This adds meaning that the schema alone does not convey.

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 'Overwrites one A1 range with a 2-D values matrix' – a specific verb and resource. It differentiates from siblings by explicitly mentioning batch_write_values for multiple ranges and clear_values for clearing cells, making its role distinct.

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 explicit usage context: when to use batch_write_values instead of this tool (multiple ranges, quota savings) and when to use clear_values (to empty cells). Also explains the implications of null entries and value_input_option behavior, guiding the agent on when each option is appropriate.

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