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

readOnlyHint=true already covers the safety profile, so the tool is honest about being a read. Beyond that the description adds no behavior: no indication of how metrics/filters are applied, whether missing group_by means a single total, how limit interacts with ordering, or what happens when both table_name and worksheet data are plausible.

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, which is structurally good. For a 12-parameter aggregation tool, though, this level of brevity crosses into under-specification rather than efficient conciseness.

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?

Twelve parameters, near-zero schema descriptions, no output schema, and a one-line description leave the agent without enough to call this correctly. It lacks any explanation of metric/filter shapes, output shape, or the sheet-vs-table selection logic.

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 roughly 0% schema description coverage across roughly 10 parameters (filters, metrics, group_by, sort_by, sort_desc, limit, row_mode, header_row, table_name, infer_worksheet), the description carries the full explanatory burden and explains none of them. The object-shaped filters/metrics arrays are especially opaque without guidance.

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

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

Names a specific verb ('compute grouped metrics') and resource ('worksheet-shaped data or a native Excel table'), so the general idea of a read-only grouped aggregation is conveyed. However, 'worksheet-shaped data' is vague and nothing distinguishes this from close siblings like query_table, create_pivot_table, or bulk_aggregate_workbooks.

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 sentence says nothing about when to use this tool versus alternatives, no prerequisites (e.g. sheet vs table selection, header row expectations), and no exclusions. An agent must infer routing entirely from the name.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description is not carrying the safety burden. It adds the meaningful framing that this is a pre-mutation impact check. However, it doesn't disclose what the result contains (a list of affected structures? a risk summary?) or how exhaustive the analysis is, which is the core behavioral question for an 'impact' 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?

A single front-loaded sentence with zero filler; the precondition is placed at the end where it reads naturally. It is efficient, though the brevity edges into under-specification given the tool's analytic complexity.

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

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

Three required parameters, no output schema, and only one-third schema description coverage — this description needed to explain the range format and what 'structures' means. It does neither, so an agent can call it but cannot predict or interpret its result.

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

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

Schema coverage is only 33%: filepath is well-documented in the schema, but range_ref and sheet_name have no descriptions at all. The description does not compensate — it never specifies the range_ref notation (A1? sheet-qualified? named range?) or whether sheet_name scopes the analysis or is just context. For a low-coverage schema this is a real gap.

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

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

States a specific verb ('Inspect') and a scoped resource ('workbook structures that overlap a worksheet range'), plus a temporal qualifier ('before mutation'). The ambiguity is that 'structures' is never enumerated — an agent can't tell whether it covers merged cells, tables, named ranges, validation, conditional formats, or formulas — though the aggregate/impact framing does separate it from point-inspection siblings like get_merged_cells or list_named_ranges.

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?

'before mutation' implies the usage context (a pre-write safety check), which is genuine guidance. But no alternative is named, no exclusion is stated, and there's no guidance on which mutation tools it should precede or whether it's required vs. optional.

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?

Annotation already declares destructiveHint=true, and the description adds the useful facts that rows are appended and the table's range is expanded. However, 'safely' is unsubstantiated: nothing explains what 'expand its range' actually changes, what can go wrong, or how the dry_run / allow_structure_change / structure-token guards behave. Safety-profile coverage is inherited from annotations rather than earned.

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; every word is about the action and its effect. It is tight but borders on under-specified rather than 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?

An eight-parameter, destructive, structure-token-guarded mutation with no output schema needs far more description than one sentence. The agent is left without any explanation of the guard parameters or the return shape, which is inadequate for a write operation of this 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 description coverage is only 13% (only filepath is documented), so the description must compensate for eight parameters and does not touch any of them. Critical semantics — the shape/keys of 'rows', what dry_run previews, when expected_structure_token must be supplied, and what allow_structure_change permits — are undisclosed in either the schema or the description.

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

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

States a specific verb ('append rows') and resource ('native Excel table'), plus the side effect of expanding the table range. It does not distinguish itself from siblings append_table_rows or upsert_excel_table_rows, so an agent must guess which append variant to use.

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 no when-to-use context, no prerequisites, and no exclusions. With near-identical siblings (append_table_rows, upsert_excel_table_rows, update_rows_by_key) in the toolset, the absence of routing guidance is a real gap.

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 one genuine behavioral fact — rows are dicts matched against existing worksheet headers — but annotations already flag destructiveHint=true, and the description never explains what makes this destructive, that appending may extend the sheet, or what allow_structure_change/expected_structure_token guard against. For a destructive write with an 8-parameter surface, that is a significant disclosure gap.

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

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

A single front-loaded sentence with no filler; the core mechanism is stated first. Its brevity is efficient, though it borders on under-specification for the tool's complexity rather than being verbose.

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

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

With 8 parameters, a destructive mutation, low schema coverage, and no output schema to explain results, the description leaves the agent without critical context — notably the dry-run preview path and the structure-change safety token. What is present is accurate but far from sufficient for correct invocation.

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

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

Schema description coverage is only 13% (just filepath), so the description must carry the load and largely does not. The phrase 'dictionary-shaped rows by matching worksheet headers' usefully clarifies the required `rows` shape, but dry_run, header_row, include_changes, allow_structure_change, and expected_structure_token get no explanation at all.

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

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

States a specific verb (append), resource (rows), and mechanism (matching worksheet headers), which is enough for an agent to know this writes new records rather than updating existing ones. It does not explicitly distinguish itself from close siblings like append_excel_table_rows or upsert_excel_table_rows, leaving the 'worksheet dataset' vs 'excel table' boundary to be inferred.

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 when-to-use guidance, no statement of when to prefer this over append_excel_table_rows, upsert_excel_table_rows, update_rows_by_key, or write_data_to_excel. Nothing tells the agent when dry_run or expected_structure_token should be employed.

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 destructiveHint annotation already signals mutation, and the description adds useful context that the formula will be written with verification. However, it does not explain whether existing cell content is overwritten, whether recalculation occurs, or how verification failures are surfaced.

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

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

The description is short and front-loaded with the core action. The second sentence is slightly redundant by repeating 'Excel formula', but it adds the verification behavior and does not waste much space.

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 four required parameters, 25% schema coverage, and no output schema, the description is too thin. It omits overwrite behavior, formula evaluation expectations, and error/verification details that an agent would need to invoke it confidently.

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

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

Schema description coverage is only 25%, with meaningful guidance only for filepath. The description does not compensate by explaining the expected format for formula, how cell references should be specified, or how sheet_name interacts with cell.

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: apply an Excel formula to a cell. It is clear enough to distinguish from validation or inspection siblings, but it does not explicitly name or differentiate those alternatives.

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 implies usage for writing a formula into a cell, but gives no guidance on when to use this instead of validate_formula_syntax, write_data_to_excel, or inspect_formula. No exclusions or prerequisites are stated.

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?

Well beyond the destructiveHint=true annotation, the description discloses that conflicts/missing rows/changed premises block the entire batch, that commit demands an identical patch/base plus token and sha256 from a fresh preview, that ChangeSet snapshots and rollback are reused, and that tokens are not authentication. It even quantifies limits (1000 target cells, 50 spans, 50000 cells/64 columns, sample_limit 1-10), giving the agent a full behavioral profile before invoking a destructive operation.

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

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

Purpose and constraints are front-loaded, and nearly every clause carries non-redundant operational detail (validations, blocking rules, commit prerequisites, limits). The middle paragraph is dense and multi-clause, which costs some readability, but it is compact relative to the complexity of an 8-parameter destructive patch tool rather than 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 complex, destructive, nested-object tool with no output schema, the description covers invocation requirements, validations, blocking conditions, and limits thoroughly. The notable gap is what the preview returns (the actual shape of the token, examples, or conflict report), which the agent would need to interpret results — but safety and invocation semantics are fully addressed.

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

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

Schema coverage is only 25% and the critical `patch` parameter is an opaque free-form object in the schema, yet the description fully specifies its required structure (version=1, source={table_name, sheet_name}, nonempty key_fields, explicit read_fields with [] semantics, updates=[{key, values}]) and the constraint that write fields must not be keys or read_fields. It also clarifies mode behavior, what sample_limit bounds, and the role of rebase_token/expected_workbook_sha256 — compensating almost entirely for the sparse 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 first sentence states a specific verb (preview/commit), resource (three-way keyed patch), and target (pinned retained base) in a single well-formed clause. The body enumerates the exact patch shape and operation semantics, making the purpose unmistakable. It stops short of naming a sibling tool it replaces (e.g., apply_workbook_changeset or update_rows_by_key), so differentiation is by capability rather than by explicit routing.

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

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

Usage context is implied through the preview/commit split and the statement that commit requires a fresh preview's rebase_token/expected_workbook_sha256. It also lists blocking conditions (conflicts, missing rows, changed premises). However, there is no explicit 'use this when / use X instead' guidance against the many sibling mutation tools, so the agent must infer the boundary itself.

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 supply only destructiveHint=true, and the description adds real value on top: transactional grouping, an enforced preview→commit handshake bound to a workbook SHA and token, and the fact that snapshot creation defaults to enabled. It stops short of stating rollback/atomicity semantics on partial failure or what happens if the SHA no longer matches.

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

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

Front-loaded with the core action, then the data shapes, then the workflow — three tight paragraphs with no filler. The long enumerations are necessary because the schema does not constrain those object shapes, so every token 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 9-parameter destructive batch tool with no output schema, the description covers the plan format, verification strategy, and commit safety contract. Gaps remain around failure/rollback behavior and what the preview response contains (tokens, samples), which an agent must infer from the parameter names.

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 only 11% schema coverage, the description carries most of the load and does so for the important parameters: the operations element shape ({tool, args}), the valid tool names, the valid assertion types, plus changeset_token and expected_workbook_sha256. It leaves sample_limit and snapshot_filepath unexplained, and mode is only inferable from 'preview or commit'.

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 — preview or commit a group of workbook mutations as a single transaction — and immediately distinguishes itself from the many single-operation siblings (write_data_to_excel, format_range, freeze_panes) by being the batch/transactional entry point. The enumeration of composable tool names makes the scope 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?

"Call preview first. Commit the identical plan with expected_workbook_sha256 and changeset_token from that preview" gives an explicit two-phase workflow with the exact inputs required at each step. It does not state when an agent should prefer this over calling the individual mutation tools directly, which is the one missing routing cue.

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

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

Annotations already declare destructiveHint=true, so the safety profile is partly covered. The description adds useful behavioral context by mentioning dry-run planning and before/after diff output, but it does not explain what kinds of changes are destructive, whether repairs are reversible, or what permissions are needed. The word 'safe' is also somewhat vague against a destructive annotation.

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

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

The description is a single front-loaded sentence with no filler. Every phrase contributes to the stated purpose and safety mechanism.

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 destructive six-parameter tool with no output schema and very low schema description coverage. The one-sentence description is too thin to fully prepare an agent to invoke it correctly; it omits repair scope, parameter meanings, and risk details beyond the dry-run and diff mention.

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

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

Schema description coverage is only 17%, with only filepath documented in the schema. The description does not explain repair_types, sheet_names, header_row, sample_limit, or the dry_run default, so it fails to compensate for the low parameter documentation.

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

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

The description states a specific verb and resource: 'Apply safe workbook repair actions.' An agent can tell this tool mutates workbook repairs rather than reading or planning. It does not explicitly differentiate itself from the sibling plan_workbook_repairs or apply_workbook_changeset, so it misses the top score.

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 mentions dry-run planning but does not explain when to use this tool versus plan_workbook_repairs or apply_workbook_changeset. There is no explicit guidance on prerequisites, when a dry run should be used first, or when to avoid applying repairs directly.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's remaining job is to disclose what the audit actually examines and returns. It does not: no categories of issues, no severity model, no indication of cost or scoping, and no output schema exists to compensate. Only the vague 'high-signal' qualifier is added.

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 or repetition. It is appropriately sized, though the economy comes at the cost of substance rather than through efficient packing of useful detail.

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, three parameters at 33% coverage, and no annotation beyond readOnlyHint, the description should describe what an audit returns and how the two optional tuning parameters change it. Neither is covered, so an agent can select the tool but not invoke or interpret it confidently.

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

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

Schema description coverage is only 33% — only filepath is documented (and that documentation lives in the schema, not the description). header_row and sample_limit carry no explanation anywhere, and the description never mentions them, so an agent cannot tell what header_row=1 means for detection or what sample_limit bounds.

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 ('Audit workbook structure') plus the class of finding ('high-signal issues that affect agent workflows'), so an agent knows roughly what it produces. It does not distinguish itself from near-siblings such as inspect_workbook_contract, profile_workbook, or describe_sheet_layout, leaving overlap unaddressed.

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 over inspect_workbook_contract, profile_workbook, or describe_dataset, nor any prerequisite or exclusion. The phrase 'affects agent workflows' gestures at a use case but never states a condition for 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?

The annotation declares destructiveHint=true, yet the description does not state that this tool mutates and saves the workbook, nor that dry_run exists as a preview escape hatch. 'Based on content width' hints at the algorithm but discloses nothing about persistence, overwrite of existing widths, or reversibility.

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

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

The single sentence is front-loaded and wastes no words, but its brevity here reflects under-specification rather than efficiency given seven parameters and a mutation side effect.

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, 7-parameter mutation tool with no output schema and near-zero schema descriptions, the description should at minimum cover the columns scoping, dry_run preview, and padding/bounds parameters. None of that is present, leaving the agent likely to call it with defaults blindly.

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

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

Schema description coverage is only 14% (only filepath documented), and the description mentions none of the five other parameters: columns, dry_run, padding, min_width, max_width. With the description silent and the schema bare, the agent cannot know how to scope the fit to specific columns or tune width bounds.

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 ('Auto-fit worksheet columns') and gives the basis for sizing ('content width'), so the core action is understandable. However, it never distinguishes itself from the sibling set_column_widths, which an agent could easily confuse with this 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?

There is no guidance on when to auto-fit versus explicitly setting widths via set_column_widths, and no mention of prerequisites such as the sheet needing to exist or be writable. The agent must infer all routing decisions.

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 readOnlyHint annotation establishes that this is a safe read operation, and the description is consistent with that. However, beyond the annotation, the description adds only the scope 'across multiple workbooks' and does not explain output shape, schema handling, limits, or what happens with non-comparable data.

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

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

The description is a single, front-loaded sentence with no filler. It is concise, though extremely sparse given the tool's complexity.

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

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

For a 14-parameter aggregation tool with no output schema and almost no annotation detail, the description is far too thin. An agent cannot reliably infer how to use schema_mode, infer_schema, filters, metrics, grouping, sorting, or row modes.

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?

There are 14 parameters with 0% schema description coverage, so the description must compensate for parameter semantics. It explains none of them: filters, metrics, group_by, sort_by, row_mode, schema_mode, infer_schema, source_sample_limit, header_row, sheet_name, and table_name are all left undocumented.

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: aggregate comparable worksheet or table data across multiple workbooks. It is clear enough for an agent to grasp the core operation, but it does not distinguish this tool from siblings such as aggregate_table, union_tables, or cross_workbook_lookup.

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

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

The description implies usage by mentioning multiple workbooks, but it gives no explicit when-to-use or when-not-to-use guidance. It also fails to name alternatives like aggregate_table, bulk_filter_workbooks, or query_table.

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, so the safety profile is covered. Beyond that the description discloses almost nothing: it doesn't explain what happens when schemas differ across files, how schema_mode 'strict' vs 'infer_schema' changes behavior, or what source_sample_limit and include_source_columns do to the result.

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 with zero filler, and the core action is front-loaded. The brevity is efficient rather than padded, though it comes at the cost of the missing detail noted above.

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 14-parameter, cross-workbook aggregation tool with no output schema, the definition is far too thin. Schema reconciliation behavior, output shape (concatenated rows? per-file grouping?), and error handling for mismatched workbooks are all unstated, so an agent cannot confidently predict results.

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 0% across 14 parameters, so only 'filepaths' carries any documentation at all. The description's only semantic contribution is pointing to query_table for filter operator syntax; it says nothing about limit, select, row_mode, sort_by/sort_desc, header_row, schema_mode, infer_schema, or source_sample_limit, leaving most parameters undocumented in both places.

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 ('Filter ... worksheet or table data') plus the multi-workbook scope, and names the sibling whose semantics it mirrors (query_table). An agent can distinguish it from query_table on the single-vs-multiple-workbook axis. The adjective 'comparable' is left unexplained, which slightly weakens the boundary.

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 clause 'Uses the same filter operators and aliases as query_table' implies this is the batch counterpart to that tool, which is useful routing context. However, there is no explicit when-to-use/when-not statement and nothing about which path to take when the workbooks are not in fact comparable.

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 declare destructiveHint=true, so the agent knows this is a mutation, but the description does not disclose what gets destroyed or overwritten. It does not explain that copying to an occupied target may replace existing cell contents, which is critical behavioral context for a destructive operation.

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

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

The single sentence is front-loaded and free of filler, but it is under-specified for a seven-parameter destructive mutation. Conciseness is not the issue; the description is too thin for the tool's complexity.

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

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

With no output schema, sparse annotations, and very low schema description coverage, the description should carry more weight. It omits overwrite behavior, range format expectations, dry_run semantics, and target sheet defaults, leaving significant gaps for correct invocation.

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

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

Schema description coverage is only 14% across seven parameters, so the description must compensate—but it provides no detail on parameter meaning. It does not specify the expected range notation for source_start, source_end, or target_start, whether target_start is a top-left anchor, or what dry_run does.

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 ("Copy a range of cells") and a destination ("to another location"), which is clear enough to understand the operation. It does not differentiate from sibling tools like copy_worksheet or delete_range, leaving the agent to infer the distinction from names alone.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., target sheet must exist), and no exclusions. The agent is told what it does but not when to choose it over sibling operations.

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

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

The description usefully discloses what content is carried over (tables, rules, charts, names, layout), which goes beyond the destructiveHint=true annotation. However, it never addresses the destructive side: whether an existing target sheet is overwritten, whether the source is consumed, or what happens on name collision — the most important behavioral question for this 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?

A single front-loaded sentence with no filler, but its brevity comes at the cost of under-specification rather than efficiency. For a destructive copy operation with three required parameters, the one-liner is too minimal.

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 destructiveHint=true, 3 required params, 33% schema coverage, and no output schema, the description leaves critical gaps: overwrite semantics, target creation behavior, and whether permissions/protected sheets affect the copy. It names what gets copied but not how the operation behaves.

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

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

Schema description coverage is only 33% — filepath is well documented in the schema, but source_sheet and target_sheet carry names only. The description adds no meaning about these two parameters, such as whether target_sheet must be a new name or an existing sheet, so it fails to compensate for the coverage gap.

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

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

States a specific verb (copy) and resource (worksheet), and enumerates what is carried over: tables, rules, charts, names, layout settings. It implicitly distinguishes itself from copy_range by scoping to the whole sheet, though it never explicitly contrasts with that sibling.

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

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

No guidance on when to use this versus copy_range or create_worksheet, and no prerequisites such as whether target_sheet must already exist or whether an existing sheet is overwritten. The agent must infer the usage context entirely.

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

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

Annotations already declare destructiveHint=true, but the description adds no behavioral context about what may be overwritten (e.g., an existing chart at target_cell), placement side effects, or permissions. It is consistent with the create mutation, so no contradiction, but it does not go beyond the annotation.

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 with the primary purpose front-loaded; the sibling note is useful routing rather than padding. There is essentially no wasted text.

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

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

For a 14-parameter mutation tool with 7% schema coverage and no output schema, the description is too thin. It does not cover required chart_type values, valid series/range forms, placement collision behavior, or output/return expectations.

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

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

Schema description coverage is only 7%; only filepath is documented. The description hints at data_range and series but says nothing about chart_type values, series object shape, placement, target_cell, categories_range, style, width/height, or axes, leaving most of 14 parameters unexplained.

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

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

The first sentence gives a specific verb and resource ('Create chart in worksheet') and explicitly names the two input modes, contiguous range or explicit series. It also distinguishes this tool from sibling create_chart_from_series by calling itself the preferred entry point.

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

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

It states this is the preferred chart authoring entry point and directs legacy explicit-series use to create_chart_from_series. It does not explain when the sibling is actually required rather than merely available, nor when to prefer data_range over series, but the primary routing is explicit.

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

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

Annotations supply only destructiveHint=true; the description adds no behavioral context at all — nothing about where the chart is inserted (placement/target_cell), whether it can overwrite an existing chart, or that it mutates the workbook file. For a 13-parameter mutation tool this leaves almost everything undisclosed.

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 well-formed sentence with the differentiating qualifier front-loaded and no filler. It is efficient, though its brevity is more a symptom of under-specification than of disciplined editing.

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 13 parameters, 8% schema description coverage, no output schema, and only a destructiveHint annotation, the description would need to carry far more. It omits chart_type values, series object shape, placement semantics, and any note on mutation effects, leaving an agent unable to call it confidently.

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

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

Schema description coverage is only 8% (just filepath), and the description only vaguely gestures at two of the thirteen parameters via 'series definitions' and 'non-contiguous ranges' (i.e., series, categories_range). Required parameters like chart_type and sheet_name, plus placement, target_cell, style, and axis labels, get zero semantic guidance and chart_type has no enum.

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 ('Create a chart') and adds a scope qualifier ('from explicit series definitions for non-contiguous ranges') that implicitly distinguishes it from the sibling create_chart. It stops short of naming create_chart, so the contrast must be inferred rather than read.

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

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

'for non-contiguous ranges' implies the selection condition, but the description never says when to prefer create_chart instead, nor does it mention prerequisites such as an existing workbook/sheet or whether the chart is appended vs. placed. Usage is inferable but not stated.

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 only declare destructiveHint=true; the description doesn't explain why creation is destructive or what gets destroyed (e.g., an existing range with the same name), nor does it mention the replace, hidden, or dry_run behaviors. The scope wording adds a little context about name visibility/conflicts, but the heavy behavioral burden for an 8-parameter mutation tool is largely unmet.

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, but it is under-specified rather than appropriately concise given the tool's parameter surface. Nothing is wasted, yet very little is said.

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

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

For an 8-parameter, destructive-annotated mutation tool with 13% schema coverage and no output schema, the description should at minimum explain overwrite/replace behavior, scope semantics, and dry_run. Almost all of that is absent.

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

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

Schema coverage is 13% — only filepath is documented in the schema. The description gestures at scope via 'workbook-level or sheet-scoped' but never clarifies how sheet_name and scope_sheet differ, nor what replace, hidden, or dry_run do. With seven undocumented parameters, the description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Create ... named range') and adds a meaningful scope distinction (workbook-level vs sheet-scoped) that an agent couldn't infer from the name alone. It doesn't explicitly differentiate from siblings like list_named_ranges, inspect_named_range, or delete_named_range, but the create semantics are 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?

No guidance on when to use this versus the other named-range tools, no mention of prerequisites such as whether the workbook must be open/saved, and no explanation of when to prefer sheet-scoped over workbook-level scope. The agent must infer everything from the tool name.

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

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

Annotations declare destructiveHint=true, so the agent knows this is a mutating operation, but the description adds nothing: it doesn't say that replace_existing overwrites an existing pivot at the same location, where the resulting pivot is placed, or whether the source data is touched. For a destructive 8-parameter mutation, that is a substantial gap beyond what the annotation already says.

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?

One short sentence with no filler, but its brevity reflects under-specification rather than economy — the length budget is unused on the information an agent actually 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?

With 8 parameters, 5 of them required, destructiveHint=true, and no output schema, the definition needs to carry serious weight. It says nothing about parameter intent, overwrite semantics, or what is returned, so it is not sufficient to invoke this 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 description coverage is only 13% (filepath alone is documented), leaving rows, values, columns, agg_func, data_range, sheet_name, and replace_existing as bare titles. The description doesn't compensate at all — no mention of expected aggregation keywords for agg_func ('sum' is only a default in the schema), the address format for data_range, or what null columns means.

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 ('Create pivot table') and the target location ('in worksheet'), so the basic operation is identifiable. However, it does not distinguish this from nearby aggregation siblings such as aggregate_table, query_table, or create_table, leaving an agent to guess which one to pick.

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 statement of when to use this tool rather than aggregate_table, query_table, or create_table, and no prerequisites (sheet must exist, must be unprotected). The only framing is the noun 'pivot table', which the agent has to interpret on its own.

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 declare destructiveHint=true, but the description does not explain what may be destroyed, whether an existing table would be overwritten, or any permission/formatting side effects. With this annotation present, the description should at least acknowledge the destructive implications or conditions under which data may be replaced.

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

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

The description is a single, front-loaded sentence with no wasted words. However, its brevity is also the source of missing behavioral and parameter context, which is captured elsewhere.

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

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

For a mutation tool with destructiveHint=true, five parameters, and no output schema, the description is too sparse. It omits overwrite behavior, table naming/style options, and any indication of what the tool returns or how it interacts with existing tables.

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

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

Schema description coverage is only 20%, and the description adds no information about table_name, table_style, or sheet_name. It only vaguely references 'a specified range of data,' leaving four of five parameters undocumented in both schema and 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 states a specific verb and resource: 'Creates a native Excel table from a specified range of data.' It is clear what the tool does, but it does not distinguish this from sibling tools such as create_pivot_table, list_tables, or read_excel_as_table.

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

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

There is no guidance on when to use create_table versus alternatives like create_pivot_table, list_tables, or append_table_rows. No prerequisites, exclusions, or selection criteria are provided.

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

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

Annotations declare destructiveHint=true, which strongly suggests the call can overwrite/clobber an existing file at filepath, yet the description never mentions overwrite behavior, error handling, or what is returned. For a file-creating mutation whose safety profile is flagged destructive, this is a meaningful omission.

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 waste. It is short, though that brevity contributes to the gaps elsewhere rather than reflecting efficient information density.

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

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

No output schema and no annotations describing return values, so the description should say what comes back (workbook object, path, metadata) and whether an existing file is overwritten. Neither is covered, leaving the agent unable to predict side effects of a destructive-flagged call.

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

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

Schema coverage is 50%: filepath has a detailed path-handling description in the schema, but sheet_name has no description there. The description only restates that the sheet name is optional and initial; it adds no format constraints (length, invalid characters, behavior if the sheet name already exists) and doesn't reinforce the path rules.

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?

Clear verb+resource: 'Create a new Excel workbook' with an optional initial worksheet. It is distinguishable from create_worksheet (which adds a sheet to an existing workbook) by implication, though the description never explicitly contrasts them.

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

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

No guidance on when to use this versus create_worksheet, create_workbook_snapshot, or write_data_to_excel. The agent gets no conditions, prerequisites, or alternatives.

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

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

Annotations already flag destructiveHint=true (a file is written), and the description adds a genuinely useful constraint: an existing file will not be overwritten. However, it does not say whether the call errors or silently no-ops when the target exists, what 'verified' checks, or what permissions/paths are required.

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?

One front-loaded sentence with no filler; the non-overwrite constraint is stated up front. The only inefficiency is the unexplained qualifier 'verified', which costs a word without conveying 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?

For a two-parameter file-writing tool with no output schema and no readOnly hint, the definition covers the essential guard (no overwrite) but omits return behavior and failure modes an agent needs to plan around. Adequate, not complete.

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

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

Schema coverage is 100% and both path parameters carry detailed routing guidance (server-relative vs absolute on unrooted stdio), so the schema does the heavy lifting. The description adds no meaning about how filepath and snapshot_filepath relate or whether they may coincide — baseline 3.

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

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

States a specific verb and resource ('create a verified workbook snapshot'), so the action is unambiguous. It does not differentiate itself from neighbors like create_workbook or diff_workbooks, nor does it explain what 'verified' adds, so it stops short of a 5.

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 never says when to snapshot versus copying a workbook, diffing, or committing changes via apply_workbook_changeset. There are no prerequisites or exclusions — only an implicit clue that the call is meant for recording a state before mutation.

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 only annotation is destructiveHint=true, with no readOnlyHint, so the agent knows this mutates state — but the description adds nothing beyond that. It does not say what happens if a sheet with that name already exists, whether the file must be closed, or what write permissions are needed. For a mutation tool with minimal annotation coverage, this leaves significant behavioral gaps.

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

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

The single sentence is front-loaded and waste-free, but its brevity comes at the cost of under-specification rather than genuine economy. It is concise without being informative.

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 file-mutating tool with no output schema, half its parameters undocumented, and no stated duplicate-name behavior, the description is too thin. An agent cannot predict success/failure conditions or the result of the call from this text alone.

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

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

Schema coverage is 50%: filepath has a rich description, but sheet_name is completely bare. The tool description does not compensate — it says nothing about sheet_name uniqueness, the 31-character Excel limit, or invalid characters, which are the most common failure modes for this operation.

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

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

The description gives a specific verb ('Create') and resource ('new worksheet in workbook'), so the agent knows exactly what the tool does. It does not, however, differentiate itself from siblings like copy_worksheet, rename_worksheet, or create_workbook, which all touch sheets in the same workbook.

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

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

There is no guidance on when to use this versus copy_worksheet (to duplicate an existing sheet) or create_workbook (when no workbook exists yet), and no prerequisites are stated. The agent must infer the usage context entirely from the tool name.

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 readOnlyHint annotation only confirms this is a non-mutating read, so the description carries the rest of the burden and discloses almost nothing. With 24 parameters controlling join_type, match_mode, schema_mode, and row_mode -- all of which materially change behavior -- plus no output schema, the description gives no insight into what happens with multiple lookup workbooks, duplicate matches, or schema mismatches.

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 padding and the core operation stated first. It is efficient, though the extreme brevity for a 24-parameter tool suggests under-specification rather than genuine editorial discipline.

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 24 parameters, 4% schema coverage, no output schema, and only a readOnlyHint annotation, the definition leaves far too much unspecified. An agent cannot determine what the enriched result looks like, how multiple lookups compose, or how the mode parameters interact.

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 4%: only source_filepath and lookup_filepaths items carry descriptions, leaving roughly 22 parameters documented by title alone. The phrase 'one or more lookup workbooks' faintly echoes that lookup_filepaths is a list, but the description adds nothing about join_type, match_mode, or the select/limit 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 pairs the specific verb 'Enrich' with the resource 'workbook dataset' and clarifies that the enrichment comes from matching rows in lookup workbooks, so it reads as a join/lookup operation. It is distinguishable from siblings such as union_tables or aggregate_table, though it never names an alternative explicitly.

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 statement of when to use this instead of union_tables, query_table, or bulk_filter_workbooks, and no prerequisites or exclusions. The agent must infer the tool's role from the name and description alone.

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

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

Annotations already declare destructiveHint=true, so the safety profile is carried structurally. The description adds only the scope distinction and says nothing about irreversibility, error behavior when the name is absent, or what a dry run reports — the key behavioral affordances an agent needs for a destructive call.

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 verb and its object appear immediately. Nothing is 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 destructive mutation with four parameters, 25% schema coverage, and no output schema, the description is too thin. It omits dry_run, missing-range behavior, and confirmation/error semantics, leaving the agent to guess on the risky parts of the call.

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

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

Schema description coverage is only 25% (only filepath is documented), so the description must compensate. It partially explains scope_sheet by contrasting 'workbook-level' versus 'sheet-scoped', but leaves 'name' matching semantics and especially 'dry_run' — the most important parameter for a destructive tool — entirely unexplained.

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 (delete a named range) and adds that both workbook-level and sheet-scoped ranges can be targeted. It does not explicitly route against siblings like create_named_range, inspect_named_range, or list_named_ranges, but 'named range' is specific enough that confusion is unlikely.

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 never says when to use this versus list_named_ranges/inspect_named_range first, nor any preconditions (must the range exist, must the sheet exist, does a dry run need to precede it). Usage is only inferable from the verb itself.

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 destructiveHint annotation already flags this as a destructive operation. The description adds useful behavioral context by saying remaining cells shift, but it does not explain the shift_direction option, the dry_run option, or whether the deletion is reversible.

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

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

The description is a single efficient sentence with the core action front-loaded. It does not waste words, though its brevity contributes to gaps in usage and parameter guidance.

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 destructive mutation tool with six parameters, low schema coverage, and no output schema. The description omits important details about shift direction, dry-run behavior, cell address format, and when to choose this tool over row/column deletion siblings.

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

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

Schema description coverage is only 17%, with just filepath documented in the schema. The description does not explain start_cell, end_cell, sheet_name, shift_direction, or dry_run, so it fails to compensate for the sparse schema documentation.

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

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

The description states a specific verb and resource: delete a range of cells. It also notes that remaining cells shift, which clarifies the effect. It is clear on its own but does not distinguish itself from sibling tools such as delete_sheet_rows or delete_sheet_columns.

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 no guidance on when to use this tool versus alternatives like delete_sheet_rows, delete_sheet_columns, or delete_worksheet. It also provides no exclusions or prerequisites for range deletion.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered; the description adds nothing beyond it. It doesn't say that remaining columns shift left, that data in the deleted columns is unrecoverable, or that a `dry_run` option exists to preview the 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?

A single front-loaded sentence with no filler. It is efficient, though the brevity is a byproduct of omission rather than disciplined editing.

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?

A destructive, 5-parameter mutation tool with no output schema and 20% parameter coverage needs more: irreversibility, dry_run behavior, and the column-shift side effect are all absent. An agent could call it correctly on syntax but not safely.

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

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

Schema coverage is only 20% (only `filepath` is documented), so the description carries most of the burden. It does explain `start_col` and `count` ('one or more columns starting at ...'), but leaves `sheet_name` and critically `dry_run` completely unexplained.

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 ('Delete ... columns') plus the positional semantics ('starting at the specified column'), which distinguishes it from insert_columns and delete_sheet_rows. It stops short of naming alternatives explicitly, but the operation is 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?

No guidance on when to use this versus delete_range, delete_sheet_rows, or insert_columns, and no prerequisites (e.g., worksheet protection, whether the sheet must be unprotected). The one decision that matters most for a destructive tool — whether to dry-run first — is never mentioned.

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 disclose destructiveHint=true, so the destructive nature is covered. The description adds useful scope by saying it deletes one or more rows starting at start_row, but it does not explain irreversibility, whether dry_run previews changes, or any permission requirements.

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

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

The description is a single front-loaded sentence with no wasted words. However, for a destructive five-parameter tool, that brevity leaves significant omissions, so it is concise but arguably too sparse.

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 and a destructive operation, the description should clarify dry_run behavior, required filepath/sheet_name context, and consequences of deletion. It leaves those gaps despite annotations only covering destructiveness.

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

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

Schema description coverage is only 20%, and the description compensates only partially by implying that count and start_row define a contiguous row deletion. It does not clarify dry_run, sheet_name, or how filepath should be supplied beyond the schema's filepath note.

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: delete rows, with scope 'starting at the specified row' and 'one or more rows.' It distinguishes itself from delete_sheet_columns by operating on rows, but it does not explicitly name or contrast sibling tools such as delete_range or insert_rows.

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 no guidance on when to use this tool versus alternatives like delete_range, delete_sheet_columns, or insert_rows. It also omits prerequisites or conditions such as confirming a destructive operation or using dry_run first.

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 destructiveHint annotation already flags this as a write/destroy operation. The description adds nothing further: it doesn't say deletion is irreversible, whether data in the sheet is lost, whether it works on the last remaining sheet, or whether the file on disk is modified. For a destructive operation, that is a meaningful gap even with annotations 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 single sentence is front-loaded and free of waste, but it is under-specified rather than concise — brevity here comes at the cost of missing behavioral and parameter detail.

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?

A destructive, two-parameter tool with no output schema and half its parameters undocumented in the schema needs the description to carry more: irreversibility, path handling expectations, and the meaning of sheet_name. Almost all of that is absent.

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

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

Schema coverage is 50%: filepath is well documented in the schema, but sheet_name has no schema description at all. The description never mentions either parameter, so it does not compensate for the undocumented sheet_name (the worksheet tab to remove).

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?

"Delete worksheet from workbook" names a specific verb and resource, so the basic action is unambiguous. But it adds nothing beyond the tool name and title ("Delete Worksheet"), and does not distinguish it from siblings like delete_range, delete_named_range, or delete_sheet_rows that also destroy content.

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

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

There is no guidance on when to use this versus delete_range, delete_sheet_rows, or rename_worksheet, and no prerequisites such as whether the workbook must be saved or the sheet unprotected. The agent must infer all conditions for use.

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 readOnlyHint annotation already establishes that this is a safe read operation, so the description does not need to restate that. It adds that the tool produces a summary for orientation, but it omits behavioral details such as how sample_rows is used, what the summary contains, or how sheet_name and table_name are resolved.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately concise, though the phrase 'agent-friendly orientation' is somewhat vague.

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 six-parameter read tool with only one documented parameter, no output schema, and many overlapping sibling tools. The description does not provide enough context about output, parameter behavior, or tool selection to be 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 only 17%, with just the filepath parameter documented. The description hints that the tool works with either a worksheet or a native Excel table, but it does not explain header_row, sample_rows, read_boundary_mode, or the precedence between sheet_name and table_name, so it does not compensate for the low 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 gives a specific verb and resource: 'Summarize a worksheet or native Excel table.' It is clear enough to distinguish this from raw data-reading tools, but it does not differentiate itself from close siblings such as describe_sheet_layout, get_workbook_metadata, or profile_workbook.

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 phrase 'for agent-friendly orientation' implies a use case, but there is no explicit guidance on when to choose this tool over alternatives. No sibling tools are named, and no when-not-to-use conditions are given.

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

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

The readOnlyHint annotation already tells the agent this is a safe read, and the description's "safe" adds nothing beyond that. It does not disclose what the summary contains, how the free-canvas sampling behaves, or any limits, so almost no behavioral context is added on top of structured fields.

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 short sentence that is front-loaded and wastes no words, but its brevity is under-specification rather than efficiency. There is room to spend words on the return shape and parameters without bloat.

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?

Six parameters, no output schema, and 17% schema coverage mean the description has to explain both inputs and what the layout summary reports. It does neither, leaving the agent unable to predict the response or the effect of the free-canvas and sample settings.

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 17% – only filepath is documented. Five parameters (sheet_name, sample_limit, free_canvas_cols, free_canvas_rows, free_canvas_limit) have no meaning given anywhere, and the description supplies none of the missing semantics. With low coverage the description carries the burden and fails entirely.

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?

"Return a structural worksheet layout summary" states a verb and resource, but "structural layout summary" is opaque about what is actually returned (dimensions? merged cells? occupied regions?). It also fails to differentiate from nearby siblings like describe_dataset, get_workbook_metadata, or inspect_workbook_contract, which an agent could plausibly pick instead.

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?

"for safe dashboard-style edits" implies the workflow (inspect before laying out a dashboard), which is genuine but indirect usage guidance. There are no explicit when-not conditions and no named alternatives, so the agent must infer the pre-flight positioning itself.

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?

readOnlyHint=true already tells the agent this is a safe non-mutating operation, so the description need not re-establish that. It adds the useful scope detail that self-references count as circular, but says nothing about whether the scan covers the whole workbook or a single sheet, how results are reported, or cost on large files.

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 and the key scope qualifier placed immediately. Its brevity is close to under-specification rather than elegance, but nothing is 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?

With no output schema, the description carries the burden of explaining the return shape (list of cycles? paths? cells?) and it does not. Combined with an undocumented sample_limit and no statement of scan scope, an agent cannot fully predict what a call yields.

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

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

Schema coverage is only 50%: filepath is well documented in the schema, but sample_limit has no description anywhere. The tool description says nothing about what sample_limit controls or that its default of 25 bounds the reported cycles, leaving a real gap the description should have closed.

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

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

Specific verb (detect) plus resource (circular workbook formula dependencies) and an explicit scope extension (including self-references). It does not, however, distinguish itself from nearby diagnostic siblings such as validate_formula_syntax, inspect_formula, or audit_workbook, which an agent could plausibly reach for instead.

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 no when-to-use context, no prerequisites, and no routing to alternatives. It never says whether this is the right tool for a full audit versus a single-formula check, even though validate_formula_syntax and audit_workbook are available siblings.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating operation. The description adds one genuine behavioral trait beyond annotations: cell-value changes are "sampled" rather than exhaustive, which explains why results may be partial. It does not state whether both workbooks must be open, what the sampling default is, or how the diff handles renamed/added sheets.

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 resource and the two output categories appear immediately. Nothing is redundant with the title or annotations.

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 carries the burden of explaining return shape, yet it only broadly characterizes results as structural plus sampled value changes without saying how changes are grouped or reported. For a two-file comparison tool with 4 parameters, this is adequate but leaves an agent guessing about the result format.

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

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

Schema coverage is only 50%: the two filepath parameters are documented (server-path conventions, absolute vs relative), but sample_limit and include_cell_changes have no schema descriptions at all. The description's word "sampled" hints at sample_limit's purpose but never explains what is counted, the default of 25, or what include_cell_changes=false suppresses, so the description fails to compensate for the coverage gap.

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

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

The description uses a specific verb ("Diff") with a clear resource ("two workbook files") and states the output categories ("structural changes plus sampled cell-value changes"). No sibling tool performs a file-to-file diff, so an agent can distinguish it from inspect_workbook_contract or explain_recipe_delta, though the description never names that distinction explicitly.

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

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

There is no guidance on when to use this tool versus the many inspection siblings (inspect_workbook_contract, profile_workbook, audit_workbook), nor on prerequisites such as needing both files accessible server-side. The only usage context lives in the schema descriptions for the filepath parameters, not in the tool description.

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

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

Annotations supply only destructiveHint=true, so the description carries the real burden and does: it discloses that comparison never writes output, that commit re-runs full metric checks on the saved workbook under ChangeSet rollback, that stale source requires re-comparison, and it enumerates hard limits (5 alternatives, 8 metrics, 20 guards, 50000 cells, 256KB JSON, sample_limit 1-5). The write behavior on commit is consistent with destructiveHint=true, not contradictory.

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 two-mode framing is front-loaded, and despite the telegraphic, spec-like style every clause carries load: the guard semantics, the commit prerequisites, the rollback re-validation, and the limits all affect correct invocation. It is dense but proportionate to a nested-object tool; minor deduction for the terse phrasing making some constraints harder to parse than they need to be.

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

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

There is no output schema, so the description must imply what the agent gets back, and it does enough by indicating that comparison yields a scenario_token and workbook SHA-256 that commit consumes. For a 7-parameter tool with a deeply nested scenario_set, the documented contract, failure modes, and limits are close to complete; only the concrete shape of the comparison result remains implicit.

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

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

Schema coverage is only 14% (just filepath), so the description must compensate, and it largely does: it spells out scenario_set's required shape (version=1, Recipe v1 restricted to sum/count, key_fields, guards with metric/scope/min/max, scenarios with id/updates), defines bounds as inclusive exact comparisons, and pins sample_limit to 1-5. The remaining gap is the mode parameter, whose accepted values ('compare'/'commit') are only implied by the first sentence rather than stated.

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

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

The opening sentence states a specific verb and resource pair with an explicit two-mode split: 'Compare explicit alternatives read-only, or commit one exact verified outcome.' That is far more specific than a tautology, and the scope (scenario sets over a workbook) is unambiguous. It stops short of 5 because it never names or contrasts the nearest sibling workflows (run_workbook_recipe, apply_workbook_changeset) that an agent might otherwise reach 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?

It gives clear conditions for each mode: compare is read-only and needs only a scenario_set; commit requires 'the identical set, selected_scenario id, scenario_token and expected_workbook_sha256 from comparison,' and source drift forces a new comparison. It also excludes a class of use cases ('No optimization or forecasting'), which is genuine when-not guidance. It loses a point for not routing to or away from any named 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lower. It adds value by disclosing the analysis scope (direct refs plus upstream and downstream traversal), which is genuine context beyond the annotation. It says nothing about traversal cost on large workbooks, how cycles are handled, or what the explanation output looks like.

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, and the three analysis outputs are listed in a logical order. It is arguably undersized for a four-parameter traversal tool, but nothing in it is wasteful.

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

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

With no output schema, the description must carry return-value information, and it does partially by naming the three result categories. It still leaves max_depth behavior, cycle handling, and output shape unspecified, which is a meaningful gap for a graph-traversal explainer.

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

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

Schema description coverage is only 25% – only filepath carries documentation. The description never mentions cell, sheet_name, or max_depth, so it fails to compensate. max_depth is especially consequential (it bounds the upstream chain walk) and is completely unexplained in both schema and 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 (Explain) and resource (formula cell) and enumerates the three things it returns: direct references, upstream formula chain, downstream dependents. That is far more informative than the bare name. It does not, however, contrast itself against close siblings such as inspect_formula, analyze_range_impact, or detect_circular_dependencies, so an agent must infer the boundary.

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 statement of when to use this tool versus the many adjacent inspection tools in the sibling list. No prerequisites, no exclusions, and no alternative is named. The agent is left to guess between this and inspect_formula or detect_circular_dependencies.

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

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

Annotations already declare readOnlyHint=true and the description reinforces it ('without modifying either file'), then adds material context the annotations can't carry: hard limits (50,000 cells, 64 columns, 10,000 result cells per source), exact-decimal numeric evidence, the distinction between numeric_adjustment and business explanation, and the clarification that explanation_token is an integrity fingerprint, not authorization or a commit token.

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

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

Front-loaded with the core action, then organized into prerequisites, outputs, optional-parameter behavior, pinning, and limits. It is dense for a 10-parameter tool and several sentences pack two or three clauses with semicolons, but almost nothing 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 complex tool with no output schema it still describes the return shape (added/removed/updated contributions, group changes, bounded source-row examples, omitted contributions reported) and enumerates operational limits. The remaining gap is that the required `recipe` object — a free-form nested structure — has no field-level guidance anywhere, which is a real risk given 20% schema coverage.

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

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

Schema coverage is only 20%, so the description must compensate, and it does for nearly every parameter: key_fields must be exact headers present and unique on every row, metric selects one exact output alias, group must supply all group_by fields with exact literal values, sample_limit is bounded 1-10 and only affects examples, and the expected_*_sha256 parameters are described via the pin-from-previous-response guidance. Only the shape of the nested recipe object remains unspecified.

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 plus scope: 'Explain sum/count changes by source identity, without modifying either file' and 'Recompute one shared Recipe v1 on two distinct .xlsx source versions.' It implicitly separates itself from diff_workbooks and run_workbook_recipe by requiring two source versions plus a shared recipe, but it never names an alternative explicitly.

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

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

Gives clear preconditions (nonblank unique key_fields on every row, at most 8 sum/count metrics, sha256 pinning from a previous response for repeatable drilldown) and an explicit exclusion list: does not validate saved report cells, infer historical recipes, evaluate formulas, or establish business causes. It stops short of naming a sibling to use instead when those exclusions apply.

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?

readOnlyHint=true already tells the agent this is a safe read, and 'Suggest' is consistent with that. Beyond the annotation the description adds nothing: it does not define what counts as 'free' (empty cells, merged regions, padded gaps) or how candidates are ranked, which is the core behavioral question for this 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?

A single front-loaded sentence with zero filler, so nothing is wasted. But at 12 parameters and 8% schema coverage, this level of brevity is under-specification rather than effective concision.

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 almost no schema descriptions and no output schema, the description should explain search semantics, sizing constraints, and what a returned 'slot' looks like. It covers none of that, leaving an agent unable to invoke it correctly without guessing.

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

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

Schema description coverage is only 8% (only filepath is documented), and the description explains none of the 12 parameters. The meaning of width/height vs min_cols/min_rows, origin_cell, search_rows/search_columns, and padding_rows/padding_columns is left entirely to bare property names.

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

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

States a specific verb and resource ('Suggest free worksheet slots') plus the intended use case ('charts or dashboard blocks'), so the agent knows what it returns. It does not differentiate itself from the closest sibling, describe_sheet_layout, which likely overlaps in layout-awareness.

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 use case implies when it is useful (before placing a chart or dashboard block), but there is no explicit when-to-use/when-not guidance, no prerequisites (workbook open, sheet exists), and no mention of alternatives such as describe_sheet_layout.

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

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

Annotations declare destructiveHint=true, so the safety profile is partly covered. But the description never warns that applying formatting overwrites existing cell formatting, never explains what `dry_run` previews, and never mentions whether `include_changes` returns a diff — all material for a 20-parameter mutation tool. The color-syntax note is useful but is parameter-level detail, not behavioral disclosure.

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

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

Two sentences, zero filler, action front-loaded before the format detail. The efficiency is good, though the brevity edges into under-specification for a tool this large.

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?

A 20-parameter destructive mutation with 5% schema coverage, no output schema, and several nested-object params (protection, conditional_format) is not adequately explained by two sentences. An agent could invoke it, but would be guessing on most of the surface area and on the dry-run/change-reporting workflow.

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 5% across 20 parameters, so the description carries nearly the full burden and mostly fails it. It clarifies color string formats (RRGGBB / #RRGGBB / AARRGGBB / #AARRGGBB) for bg_color, font_color, and border_color, but leaves alignment, number_format, border_style, protection, conditional_format, merge_cells, dry_run, and include_changes entirely unexplained.

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 ("Apply formatting to a range of cells") that an agent can act on immediately. However, it does nothing to distinguish this from the near-identical sibling `format_ranges`, so an agent has no basis for choosing between the singular and plural variants.

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

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

No when-to-use guidance, no prerequisites, and no mention of when to prefer `format_ranges`, `copy_range`, or `read_range_formatting` instead. The `dry_run` parameter strongly implies a preview workflow but the description never says to preview before applying, which is exactly the kind of guidance a destructive tool needs.

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

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

Annotations already declare destructiveHint=true, and the description adds the useful note that all ranges are applied in one pass. However, it never says that existing formatting is overwritten, what dry_run actually previews, or what include_changes returns — the operationally relevant details for a destructive mutation.

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, zero padding, with the core action front-loaded and the format constraint following. Nothing is 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?

No output schema exists, so the description should explain return/preview behavior for a destructive tool, and it does not. Combined with an undocumented ranges item structure and two undocumented flags, an agent can call it but cannot confidently predict the payload shape or effects.

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

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

Schema coverage is only 20% (filepath only), so the description must carry the load. It adds genuine value by listing accepted color encodings (RRGGBB, #RRGGBB, AARRGGBB, #AARRGGBB), but the central 'ranges' array is a bare object with additionalProperties:true and no documented item shape, and dry_run/include_changes are left unexplained.

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 ('Apply formatting to multiple ranges') and scopes it to 'a single workbook pass'. The word 'multiple' implicitly distinguishes it from the single-range sibling format_range, though the sibling is never named.

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

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

Usage is only implied: an agent can infer this is the batch alternative to format_range. There is no explicit when-to-use, no when-not, and no mention of the sibling it competes with or of prerequisites such as sheet existence or protection.

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 destructiveHint annotation already flags that this tool changes worksheet state, and the description aligns with that by mentioning set or clear. However, it adds little behavioral context: it does not explain what is destroyed, how clearing works, or what dry_run and include_changes do.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately concise, though its brevity contributes to the broader underspecification of the tool.

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

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

For a five-parameter mutation tool with only 20% schema description coverage and no output schema, the description is too thin. It omits how to clear panes, what cell format to use, and what dry_run or include_changes change about behavior.

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

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

Schema description coverage is only 20%, so the description must compensate for undocumented parameters, but it provides no parameter-level meaning. It does not explain that cell may control the freeze position or that a null/empty cell may clear panes, and it is silent on dry_run and include_changes.

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: setting or clearing worksheet freeze panes. It is clear enough to distinguish this tool from most siblings, though it does not clarify how freeze panes differ from other worksheet layout 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?

There is no explicit guidance on when to use this tool versus alternatives, nor any prerequisites. The only usage signal is the phrase 'set or clear,' which implies mutation but leaves the choice conditions unstated.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds that it returns a JSON string containing all validation rules, but it does not describe error behavior, empty worksheets, permission needs, or output structure in any depth.

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

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

The description is short and front-loads the core purpose before listing arguments and return value. The middle sentence is somewhat redundant with the opening, but the overall structure is efficient and easy to scan.

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

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

For a simple read-only tool, the description gives enough to understand the basic operation and that the result is a JSON string. However, without an output schema it could do more to describe the returned validation-rule structure, and it leaves the overlap with inspect_data_validation_rules unresolved.

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

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

Schema description coverage is only 50%. The filepath parameter is well described in the schema, but sheet_name has no schema description and the tool description only restates it as 'Name of worksheet', which adds no meaningful semantic detail. The description does not compensate for the missing parameter guidance.

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

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

The description clearly states a specific verb and resource: get all data validation rules in a worksheet. It also explains that the result identifies validated cell ranges and validation types. However, it does not distinguish itself from the very similar sibling tool inspect_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?

Usage is implied by saying it helps identify which ranges have validation rules and what validation types are applied. There is no explicit when-to-use guidance, no exclusions, and no comparison to alternatives such as inspect_data_validation_rules or validate_excel_range.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description is not required to carry the safety burden, but it adds nothing beyond that: no indication of what the return looks like (cell ranges? addresses?), whether unmerged sheets return empty, or how merged regions are scoped. Effectively a restatement of the name.

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?

One short, front-loaded sentence with no filler. It errs toward under-specification rather than verbosity, but every word present 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 no output schema and no description of the result shape, an agent cannot know whether this returns region coordinates, addresses, or a count. For a two-parameter read tool with annotations covering safety, the description should at least sketch the return value.

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

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

Schema coverage is 50%: filepath carries detailed server-path guidance while sheet_name is bare. The description's phrase 'in a worksheet' weakly signals that sheet_name scopes the query, but adds no format or validity details, so it only marginally compensates for the undocumented parameter.

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

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

Specific verb+resource ('Get merged cells in a worksheet') that clearly identifies a read operation on merge metadata. It is distinguishable from the sibling merge_cells/unmerge_cells by the 'get' verb, though it never names those siblings explicitly.

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

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

No statement of when to call this versus alternatives such as describe_sheet_layout, read_range_formatting, or unmerge_cells. An agent must infer usage from the name and the fact that a sheet_name is required.

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, so safety is covered; the description adds genuinely useful context beyond that — it discloses what the output does NOT contain (table inventory) and warns against a specific false inference. It does not describe return shape or cost/latency, which keeps it from a 5.

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

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

The critical disambiguation is front-loaded in the first clause and the warning about missing table names follows immediately. Three short sentences, no filler, though the formatting is slightly choppy.

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 and no annotations beyond readOnlyHint, the description carries the burden of describing what 'metadata' returns, yet it only covers the sheets field and omits include_ranges entirely. An agent can avoid the main pitfall but still doesn't know what it will receive.

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

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

Schema coverage is only 50%: filepath is richly documented in the schema, but include_ranges has no description anywhere, and the tool description adds nothing about either parameter. Since half the parameters are undocumented both places, the description should have explained what include_ranges yields.

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 ('Get workbook metadata') and immediately clarifies that 'sheets' means tab names, not native tables — a distinction no sibling name conveys. It stops short of saying what else the metadata contains (dimensions, properties, counts), so the scope is only partially pinned down.

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 negative rule ('a missing table name in sheets does NOT mean the table is absent') plus the corrective action ('Use list_tables without sheet_name to verify named sources'). It does not address when to prefer list_all_sheets or describe_sheet_layout, leaving a routing gap among similar-sounding siblings.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds only that the result includes option flags, but does not say which flags, what an unprotected sheet returns, or what happens with an invalid sheet name — limited added value against the annotation baseline.

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. It is efficient, though arguably under-specified rather than maximally useful.

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

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

No output schema exists, so the description carries the burden of explaining return values — yet 'option flags' is left undefined (protect contents? protect objects? password-protected?). Combined with undocumented sheet_name, an agent cannot fully anticipate the response.

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

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

Schema coverage is 50%: filepath is documented in the schema, but sheet_name has no description anywhere. The tool description offers no parameter guidance to compensate for that gap (e.g., that sheet_name must match an existing sheet).

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 (get worksheet protection status) plus what is returned (option flags). It is clear which resource it targets, though it never names the write counterpart set_worksheet_protection that an agent could confuse it with.

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

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

No when-to-use guidance is given: nothing says to call this before set_worksheet_protection or to check protection before attempting writes. The read-only nature is implied by the name but the alternative tool is never mentioned.

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 only flag destructiveHint=true; the description adds nothing about the key behavioral consequence that existing cells shift right and referencing formulas may change. It also never mentions the available dry_run safeguard or default count of 1, both of which materially affect how an agent should call a destructive mutation.

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 zero waste, but for a 5-parameter destructive tool it is under-specified rather than tight. Brevity here costs correctness.

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, sparse schema docs, and only a destructiveHint annotation, the description should carry far more: sheet targeting, shift semantics, dry_run usage, and indexing conventions. It leaves all of that to guesswork.

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

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

Schema description coverage is only 20% (only filepath is documented), so the description must compensate and does not: start_col's indexing base (0- vs 1-based), count's default of 1, and dry_run's purpose are all left unexplained.

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