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

The description goes far beyond the annotations. Annotations indicate destructiveHint=true and readOnlyHint=false, but the description details the atomic all-or-nothing behavior, pre-validation, single backup, atomic save, verify-after-write, and restore-on-failure. It also clarifies refusal conditions and the 200,000-cell ceiling for write_range. This offers deep behavioral insight that annotations only hint at.

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 rich and detailed, but it is somewhat lengthy. It front-loads the core purpose ('atomic batch') and then provides necessary behavioral details. There is little redundancy, but the density could be slightly reduced for quicker scanning.

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

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

Given the complexity of the tool (1-5 parameters, multiple edit operations), the description covers all critical aspects: atomicity, validation, backup, verify, restoration, limitations, and refusal conditions. It also clarifies return value ('Returns the count of edits applied and cells touched'), even with no output schema. The description is sufficient for an agent to invoke correctly.

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

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

Schema description coverage is only 20%, meaning most parameters (edits, backup, allow_loss, verify_com) are not well described in the schema. The description compensates by explaining the edits structure with op values and their parameters, and clarifies backup/restore behavior for backup and verify. However, it does not detail the precise schema for backup or verify_com beyond defaults, so a slight gap remains.

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 'Apply many addressed edits as ONE atomic batch', specifying the verb (apply), resource (edits), and the atomic batch behavior. It distinguishes itself from siblings like set_cell, write_range, and clear_range by emphasizing the batch atomicity.

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

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

The description explicitly covers when to use it ('Apply many addressed edits as ONE atomic batch'), and implicitly guides away from single-edit tools like set_cell or write_range for multiple edits. It also provides exclusions: 'refuses while the file is open in Excel' and 'A hazardous workbook refuses unless allow_loss is true', which are clear usage conditions.

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

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

Beyond the readOnlyHint annotation, the description discloses substantive behavioral details: it works while the file is open in Excel, reports are capped with exact counts and a truncated flag, and missing_cached_values have the consequence of reading as blank to non-Excel consumers. No contradiction with annotations exists.

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

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

The description is long but dense and front-loaded with the core purpose before enumerating the five reports. The only minor redundancy is read-only being stated twice, once in the first clause and again at the end.

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

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

Given no output schema, the description compensates well by explaining what each report detects, how results are capped, and when to use the tool. The main gap is the lack of explicit parameter mapping and any note about the return container shape.

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

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

With schema_description_coverage at 0%, the description compensates partially by explaining the three scope modes (range, sheet, whole workbook/no scope). However, it never explicitly maps those modes to the path, sheet, and location parameters, leaving that connection to be inferred from parameter names.

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

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

The description names a specific action ('Audit Formulas') and a clear deliverable: 'the formula list plus five safety reports.' It also defines the exact scope options (range, sheet alone, whole workbook), so an agent can distinguish this from read_range, find_cells, or other siblings without opening schemas.

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

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

It provides explicit usage guidance: 'Use it before and after structural edits, and to judge whether cached values can be trusted.' It does not name exclusions or alternatives, but the intended context is concrete and actionable.

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

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

Beyond the destructiveHint annotation, the description discloses a refusal behavior for sheets with no autofilter (NOT_FOUND), the return value (number of unhidden rows), hazardous-workbook gating via allow_loss, auto-backup behavior, atomic verified save, and refusal while open in Excel. This is rich, non-obvious behavioral detail.

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

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

Four sentences, all dense with meaningful informationeb. The core action is front-loaded, and each sentence contributes a distinct fact: behavior, sheet selection, failure mode, return value, safety/backup, and locking. No fluff or redundancy.

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

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

The description covers the main purpose, failure behavior, return value, safety gating, backup details, and lock condition despite no output schema. The only notable gap is the undocumented verify_com parameter, and path is left to assumption, but overall the definition is strong and actionable.

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 0% schema description coverage, the description compensates for several key parameters: location and sheet selection, allow_loss for hazardous workbooks, and backup behavior. However, path and verify_com remain semantically unexplained beyond their names and types, so the compensation is not complete.

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

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

The description opens with a specific verb and resource: 'Remove the autofilter from a sheet and unhide the rows it hid.' It also explicitly labels this as 'the reverse of set_filter,' distinguishing it from the most relevant sibling tool and making the tool's function unambiguous.

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

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

The description gives clear context for when this is applicable: it is the reverse of set_filter, and it explains sheet selection semantics via location or sheet. However, it does not explicitly state alternatives to avoid or conditions like 'use when a filter is active,' though the sibling reference partially covers this.

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

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

The description discloses extensive behavior beyond the destructiveHint annotation: it explains the backup mechanism (auto-backup in .ks4xl-backups with rotation and skip flag), the atomic verified save with rollback, the safety guard for hazardous workbooks (allow_loss required), and the refusal while the file is open in Excel. This is far richer than the annotation's simple true flag and gives an agent a precise mental model of side effects.

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 packed with information but every sentence earns its place. It is front-loaded with the core purpose, then logically flows to exclusions, addressing, safety, backup, and failure conditions. There is no repetition of schema data and no filler, making it an exemplar of efficient technical writing.

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

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

Given the tool's complexity (7 params, no output schema, destructive operation), the description covers the essential aspects: what it does, what it doesn't do, safety, backup, and one failure condition. It omits details on 'sheet' and 'verify_com' behavior, but those are optional with defaults, and the provided information is sufficient for correct invocation in most cases. It earns a strong score but not a perfect one.

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 schema description coverage at 0%, the description must carry parameter meaning. It explains 'what' (contents/formats/all), 'backup' (skips rotation when false), 'allow_loss' (needed for hazardous workbooks), and 'location' (addressed via a location object). However, it does not explain 'sheet' or 'verify_com' at all, leaving two parameters semantically opaque. Since it covers several but not all, a middle score is appropriate.

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

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

The description opens with a clear action and resource: 'Clear a cell or range' and immediately enumerates the three modes (contents/formats/all) with their exact effects. It also explicitly states what the tool does NOT clear (merges, conditional formats, etc.), which distinguishes it from sibling tools like set_merge and manage_hyperlink without needing to name 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?

The description gives strong contextual guidance: it points to other tools for the items it doesn't remove ('those have their own manage tools'), and it states the environment constraint ('Refuses while open in Excel'). It does not explicitly name a preferred alternative for clearing, but the limitation statements effectively tell an agent when not to use it. A minor gap is that it doesn't contrast with write_range or set_cell for zeroing cells, but it is otherwise clear.

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

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

The description goes well beyond the annotations (readOnlyHint=false, destructiveHint=true) by disclosing crucial behaviors: destination is overwritten, source is buffered for safe overlapping pastes, formula reference adjustments with adjust_formulas, refusal on hazardous workbooks unless allow_loss is true, auto-backup to .ks4xl-backups, atomic verified save, and refusal while open in Excel. This is exactly the kind of context that prevents surprise side effects.

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?

Each sentence carries distinct information: purpose, content type, overwrite safety, formula adjustment, loss handling, backup/atomicity, and Excel lock. It is compact and front-loaded with the core action. Minor redundancy like 'may name different sheets' and 'like an Excel copy' are not filler, but the density makes it slightly challenging to parse in one pass.

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

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

For a 9-parameter tool with no output schema, the description provides substantial context about side effects and failure modes, which is commendable. However, it leaves some parameters (verify_com, sheet) and the success response unstated. An agent would still need to consult the schema for several arguments, and there is no mention of what a successful operation returns (e.g., confirmation or status).

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 22%, so the description must compensate. It explains the 'what' values explicitly and mentions adjust_formulas, allow_loss, and backup behavior. However, it does not clarify parameters like verify_com, sheet, or path, and some details are implicit (backup vs. auto-backup). It adds value for several parameters but not all.

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

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

The description states a specific verb and resource: 'Copy a source rectangle to a destination anchor' and further specifies that it can span different sheets and what content to copy ('all', 'values', 'formulas', 'formats'). This clearly distinguishes it from siblings like copy_workbook (whole workbooks), move_range (moving), and read_range (reading).

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

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

No explicit guidance on when to use this tool versus alternatives. It does not mention copy_workbook, move_range, or read_range, nor any conditions that would select this tool over them. The only hint is the action itself, which is not enough to route an agent correctly among the listed 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?

The description details the overwrite behavior, including the rotation into .ks4xl-backups and restoration via source='prev'. This goes well beyond the annotations, which only set destructiveHint=false and readOnlyHint=false. It also clarifies that existing files are untouched unless overwrite=true, providing crucial behavioral context.

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

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

The description is well-structured and front-loaded with the core purpose. Each sentence adds value: the byte-for-byte guarantee, overwrite/backup behavior, return value, and use case. There is no fluff, and the length is appropriate for the 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?

The description covers the return value (destination path), the overwrite and backup mechanism, and the intended use case. It does not mention error conditions (e.g., missing source) or limitations, but for a copy tool with this complexity, the provided information is nearly complete. A minor gap exists regarding edge cases, but it is not critical.

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%, so the description must compensate. It explains the effect of 'overwrite' thoroughly but does not elaborate on 'src' and 'dst' beyond implying they are file paths. The description adds meaning for overwrite but leaves src/dst semantics to inference, which is a gap given zero 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 clearly states the tool copies a workbook file byte-for-byte from src to dst, emphasizing integrity preservation. It distinguishes itself from sibling tools like copy_range by focusing on whole-workbook copying and mentions 'branch a working copy', which is a specific purpose.

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

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

It provides a clear use case: 'Use this to branch a working copy before a risky batch of edits.' However, it does not explicitly mention when not to use it or suggest alternatives (e.g., copy_range for ranges). The context is sufficient but lacks explicit exclusions.

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 provide readOnlyHint=false and destructiveHint=false, which is minimal. The description compensates fully by disclosing key behaviors: refuses overlap with existing tables, rejects duplicate names (tables or defined names), requires allow_loss for hazardous workbooks, performs auto-backup with atomic verified save, and refuses while the workbook is open in Excel. This is rich, actionable context beyond any structured field.

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 dense paragraph that front-loads the core action and then lists options with inline explanations. It is concise without being telegraphic, and each sentence adds distinct information. Minor inefficiency: the phrase 'named name' is slightly awkward, and the backup/atomic save sentence could be separated for readability, but overall it is well-structured.

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 13 parameters, no output schema, and complex behavior, the description is incomplete. It does not mention what the tool returns (e.g., success message, table object), nor does it define how location (string vs object) should be specified, or the meaning of totals_row and verify_com. For a complex mutation tool with zero schema coverage, an agent would need additional investigation to call it correctly.

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

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

Schema coverage is 0%, so the description must explain parameters. It does explain header, style, row_stripes, col_stripes, totals (with example functions), allow_loss, and backup (via auto-backup mention). However, it leaves path, sheet, location, totals_row, and verify_com undefined. For a 13-parameter tool, this partial coverage is adequate but not thorough – it adds meaning for roughly half the 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 opens with a specific verb and resource: 'Turn a range into an Excel table (ListObject) named name.' This clearly distinguishes the tool's action from siblings like get_table (retrieve) or write_range (write values), and the qualifier 'ListObject' adds precision. There is no ambiguity about what the tool does.

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

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

The description does not state when to use this tool versus alternatives. It never mentions sibling tools like get_table for reading tables or write_range for writing raw data, nor does it provide conditions for selection. The only 'when' hints are behavioral refusals (e.g., overlap, name conflicts), not usage context. This leaves an agent without explicit routing guidance.

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

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

Annotations only provide readOnlyHint and destructiveHint flags. The description adds rich behavioral detail: sheet name constraints, default behavior, overwrite rotation to backup, and return value. This fully discloses side effects and prerequisites beyond annotations.

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

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

The description is a few dense sentences with no fluff. It front-loads the core action, then covers constraints and overwrite behavior. Every sentence adds value, making it efficient and well-structured.

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 minimal annotations, the description fully covers creation behavior, constraints, overwrite handling, and return value. Nothing an agent needs to call it correctly is missing.

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

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

Schema has zero descriptions, so the description carries full parameter explanation. It explains the 'sheets' default and constraints, 'overwrite' behavior, and implicitly clarifies 'path' via 'parent directory must already exist'. This compensates for the lack of schema descriptions.

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

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

The description clearly states a specific verb and resource: 'Create a new .xlsx workbook at path' with sheet names. It specifies the default sheet and the exact result (returns file path and sheets created). This is distinct from siblings like copy_workbook or get_workbook_metadata.

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 context on prerequisites (parent directory must exist) and sheet naming constraints, but does not explicitly mention when to prefer this tool over alternatives. It implies usage for creating a new workbook but lacks exclusions or comparisons to siblings.

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

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

With readOnlyHint already true, the description adds substantial behavioral detail: it scans worksheet extLst for x14 conditional formats, sparkline groups, and slicer lists; it explains the openpyxl load-warning fallback for extensions dropped elsewhere; and it explicitly states 'Read-only.' This exceeds what annotations alone provide and includes a known limitation.

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

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

The description is long but dense with necessary behavioral and edge-case information. It front-loads the purpose and verdict semantics, then covers limitations. The metaphor 'surfaced as a health readout' adds color but does not hurt clarity; every subsequent sentence earns its place.

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

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

There is no output schema, but the description enumerates what the readout contains: fragile parts, drop-risk verdict, routing recommendation, and integrity summary. It also explains verdict consequences and a known scan limitation. It is complete enough for an agent to call and interpret the result, though exact response field names are not specified.

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 0%, so the description must compensate for the lone path parameter, but it never explicitly defines the path parameter itself. The prose repeatedly implies the target is the workbook file path ('which fragile parts the workbook holds', 'file-based openpyxl edit'), which adds some meaning beyond the bare schema. However, it does not specify path type, file extension, or remote/local variants, so it falls short of fully compensating.

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

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

The description opens with 'round-trip hazard scan' and states the tool's purpose is to 'check a workbook is safe to edit before mutating it.' This is a specific verb (diagnose/scan) plus a clear resource (workbook), and it distinguishes the tool from siblings like get_workbook_metadata by focusing on edit-safety hazards rather than metadata.

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

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

It explicitly says when to use the tool: before mutating a workbook. It also provides actionable routing guidance: hazards never block reads, a would-lose verdict forces Excel routing or allow_loss:true, and a clean verdict means file-based edits are safe. This is explicit, not merely implied.

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

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

The description goes well beyond annotations: it explains idempotency, that the lite core always stays on, what the result reports, the refusal format for disabled tool calls, and the KS4XL_PACK_POLICY=locked refusal condition. This is rich behavioral disclosure beyond the idempotentHint and destructiveHint annotations.

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

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

The description is dense but every sentence earns its place: purpose, idempotency, result contents, parameter semantics, failure behavior, and policy restriction are all relevant. It is front-loaded with the core purpose and expands into needed details in a logical order.

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

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

For a one-parameter, no-output-schema tool, the description is remarkably complete. It covers what happens, what is returned, how to reference packs, how failures behave, and when the tool refuses. No crucial behavior is left unexplained.

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 0%, so the description must carry the parameter meaning. It does: packs accepts the same names as enable_tools or the special value ['everything'], and it points to the sibling's description for the menu. This compensates well for the bare schema.

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

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

The description opens with a specific verb and resource: 'Disable previously enabled tool packs for this session and reclaim their context.' It clearly distinguishes this from sibling tools, especially enable_tools, by defining the opposite action and scope.

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

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

The description gives strong contextual usage guidance: it targets previously enabled packs, names enable_tools as the counterpart for re-enabling, and explains the refusal behavior when a disabled tool is called. It does not explicitly state 'use this when you want to free context' but the purpose implies it clearly.

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

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

Annotations already cover idempotency and non-destructiveness; the description adds beyond that: it 'reports tokens added', 'Refuses under KS4XL_PACK_POLICY=locked', is reversible by disable_tools, and for the com pack guarantees 'never touches your open Excel session'. These are valuable behavioral disclosures not present in annotations.

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

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

The description is well-structured and front-loaded with a summary, but it is quite long and contains some duplication (task map entries repeat features listed in each pack's description). It is not wastefully verbose, but not as tight as it could 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?

For a tool with one simple array parameter and no output schema, the description covers the essential points: what packs exist, what each pack includes, the 'everything' option, the policy refusal, required platform for com, and the return behavior (reports tokens added). No critical information is missing.

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

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

Schema coverage is 0%, so the description carries the full burden. It defines the valid pack values (design, io, com), the 'everything' alias, approximate token costs, and a task map that tells the agent which pack name to put in the array. This fully compensates for the schema's silence.

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

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

The description opens with a clear verb+resource: 'Enable optional tool packs mid-session,' explaining that sessions start lite. It distinguishes this from sibling disable_tools by naming it as the reverse operation, and the list of pack names and task map further clarify scope.

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

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

It explicitly says when to use it: when optional tool packs are needed because sessions start lite. It names disable_tools as the alternative and provides a task-to-pack mapping (e.g., 'conditional formatting ... -> design') to guide pack selection, plus a policy condition that will cause refusal.

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 ends with 'Read-only', but annotations set destructiveHint: true, which is a direct contradiction. The description also details overwriting existing files with a .bak backup, which implies destructive behavior. This inconsistency is a serious transparency failure.

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

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

The description is dense and information-rich, with each sentence adding a distinct point. It avoids fluff and organizes content logically from action to parameters to safety. While slightly long, it remains efficient.

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

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

Despite covering many behaviors, the contradiction with annotations ('Read-only' vs destructiveHint: true) creates a major gap. There is no mention of the inline return format or error handling, and no output schema to fill the gap. For a 9-parameter tool, this is incomplete.

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 0% schema description coverage, the description compensates by explaining key parameters: location (defaults to true used range), values (cached|formula|both), out_file (file vs inline), and the target guard. However, it omits details for fmt, sheet, header, records, and path, leaving some parameters under-specified.

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 (export) and resource (range, table, sheet) along with output formats (CSV, TSV, JSON). It also distinguishes behavior for tables and defaults for location, making the tool's purpose clear and distinct from siblings like read_range or get_cells.

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

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

Provides guidance on parameter usage (location defaults, values modes, out_file vs inline) and notes that multi-sheet exports use a different tool (export_file, io pack). It does not explicitly contrast with similar read tools, but the export purpose is inherently distinct.

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

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

Beyond the readOnlyHint annotation, the description discloses timeout-guarded regex, the last-cached-value behavior for formula cells, pagination with limit/offset and total match count, and that it works while the file is open in Excel. These are material behavioral details an agent cannot derive from annotations or schema.

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

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

The description is dense but every clause adds information: scope, match modes, regex timeout, look_in values, cached formula behavior, pagination, and read-only/open-file compatibility. The most important purpose and distinguishing trait are front-loaded.

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

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

For a 9-parameter tool with no output schema, the description covers many behavioral essentials and return semantics, but it omits the expected shape of the result payload and the meaning of the location parameter. This is a meaningful gap, but the core calling pattern is still well specified.

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%, so the description must compensate; it does explain match, look_in, limit, and offset semantics. However, it leaves location, match_case, sheet, query, and path to inference, and location is a non-trivial union of string/object/null that needs more 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 states a specific verb (search) and resource (cell values/formulas), scopes the search to a workbook, sheet, or range, and emphasizes that it returns EVERY match with an unambiguous address. This clearly separates it from a single-target location selector, even though the sibling is not named 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?

The description implies usage through the plural-sibling contrast and the read-only note, but it does not explicitly say when to prefer this over alternatives like query_range or get_cells, nor does it give exclusions. The context is clear enough for an inferred use case, but explicit routing guidance is missing.

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

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

Annotations already indicate destructiveHint=true. The description adds concrete behavioral details: hazard-gating with allow_loss override, auto-backup, atomic verified save, and refusal while the file is open in Excel. These go beyond the annotations and inform the agent of safety and failure modes.

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

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

The description is dense but organized: it starts with the core action, then enumerates parameter structures, then lists behavioral guarantees. Every sentence adds value, though it could be split into clearer subsections for readability.

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 11 parameters, no output schema, and a destructive annotation, the description covers the essential formatting object structures, safety behaviors, and the Excel-open refusal. Missing details on required parameters like path/location are minor, as they are common across siblings, but a fully complete description would address them.

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

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

The schema provides no parameter descriptions (0% coverage). The description compensates by detailing the structure of number_format, font, fill, border, and alignment, including field names and hex color format. However, it leaves path, location, sheet, backup, allow_loss, and verify_com unexplained, so coverage is incomplete.

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

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

Clearly states the action (apply formatting) and the target (a range), and explains the merging behavior that preserves unspecified attributes. This distinguishes it from data-writing tools like set_cell or write_range, making its purpose unambiguous.

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

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

The description implies a formatting use case but does not explicitly contrast with alternative formatting tools (e.g., set_merge, set_dimensions). It mentions that named styles and conditional formats are a 'design pack,' hinting at limitations, but gives no direct when-to-use vs. when-not-to-use guidance.

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

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

Annotations carry only readOnlyHint=true and openWorldHint=false. The description adds substantial behavioral context beyond these: the values options (cached, formula, both), the honest labeling scheme (cached/absent/formula/value) so a formula without a cached value is never passed off as blank, and that it works while the file is open in Excel. This is rich, non-redundant 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?

A single dense paragraph that front-loads purpose and differentiation, then the ceiling, then the values/labeling semantics, then the read-only and open-file behavior. Every clause earns its place; the only minor issue is that it reads as one long run-on sentence, slightly hurting scannability.

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

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

For a read-only tool with readOnlyHint=true and no output schema, the description covers the essential call constraints: the 1,000-cell ceiling, values behavior, labeling semantics, and open-file operation. It does not state behavior when the ceiling is exceeded, but the ceiling itself is flagged. The labeling detail partially compensates for the absent output schema.

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

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

Schema coverage is only 25% (only 'cells' has a description), so the burden falls on the description. It clarifies the two semantically interesting parameters: 'cells' (A1 strings or location objects, each resolving to one cell, 1,000-cell ceiling) and 'values' (cached, formula, or both). However, 'path' and 'sheet' receive no explanation in either the schema or the description, leaving a gap for the two least-parameterized arguments.

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 (read) and resource (individually addressed cells) and immediately differentiates itself as the 'scatter complement' to read_range. An agent can distinguish it from the 38 siblings without opening any schema.

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

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

Names the alternative (read_range) and the contrasting selection criterion (scatter vs rectangular), and discloses the 1,000-cell ceiling that bounds valid use. It stops short of listing explicit exclusions (e.g., use read_range for contiguous blocks), but the context is clear enough to route correctly.

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

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

Rich behavioral detail beyond the readOnlyHint annotation: values='cached' vs 'formula', the florin character for uncached formula cells, pagination caps and truncation flags, merged-range listing, formula_cells mapping, stale-anchor behavior, and the fact that it works while the file is open in Excel. It also explicitly confirms read-only behavior, consistent with annotations.

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

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

The description is long but densely informative, with the core purpose front-loaded and every sentence contributing operational value. The logical order moves from what the view is, to parameters, to output details, to usage with apply_edits, which makes it easy for an agent to parse.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers the markdown output, A1 addressing, formula markers, merged ranges, dimensions, hazard summary, pagination, truncation flags, anchor token semantics, and staleness behavior. The only minor omissions are path/sheet formats, but these do not undermine callability.

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 0% schema description coverage, the description compensates substantially by explaining location defaults, values modes, and max_rows/max_cols caps. However, it does not explain the required 'path' parameter or the 'sheet' parameter semantics, so an agent still has to infer those from context.

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

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

The description opens with a precise statement: a compact, token-efficient projection of a sheet or range, and enumerates exactly what the view contains (used range, markdown table, A1 addressing, formula/merged-cell markers, dimensions, hazard summary). It clearly distinguishes this from a per-cell JSON dump and positions it against sibling tools like read_range and apply_edits.

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

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

The description gives clear usage context: use this to see the grid efficiently without a per-cell JSON dump, defaults to the sheet's used range, and pairs with apply_edits for editing. It does not explicitly name alternatives or state when not to use it, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true; the description goes beyond by adding that it 'touches no file' and needs no workbook, plus a valuable privacy disclosure: path sandboxing reports 'a count, never the paths.' This is substantive behavioral context beyond what annotations convey, and it does not contradict them.

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

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

The description is a single dense paragraph, front-loaded with the primary subject and then layering details. Every sentence earns its place — no filler. It is slightly long, but for a parameterless tool where the description is the sole information source, the length is justified.

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 parameters, the description carries the full burden of explaining the return value, and it does so thoroughly: build version, tool surface with count and token bill, packs, platform, Python, and install config. Nothing an agent needs to interpret the result is missing, though the precise data types of each field are left 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?

With zero parameters, the baseline is 4, and the description appropriately spends its space explaining what the tool returns rather than parameter syntax. It compensates fully for the absence of a schema by describing each reported field (version, tool count, token bill, packs, platform, Python, sandbox count, deep-verify).

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

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

The description opens with a specific verb and resource ('Report the KitchenSink4XL server build') and enumerates the exact items reported: version, tool surface, packs, platform, Python, and config. This is unambiguous and clearly distinct from all 40 siblings, which are workbook-level operations; nothing else queries the server itself.

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

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

The description states an explicit use case: 'use it to confirm the server is up and see which packs are loaded.' It also notes it 'needs no workbook and touches no file,' which signals when to reach for it vs. workbook-scoped siblings. It stops short of naming exclusions, but with zero parameters and a unique server-level scope, no realistic alternative exists.

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 readOnlyHint=true, and the description reinforces it with 'Read-only; nothing is written.' It also adds the behavior of excluding the header/totals row, which is not in annotations, and explains the 'values' caching semantics, going beyond what annotations provide.

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

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

The description is dense and packed with information in a few sentences, but it's slightly long and could be better structured with clearer separation of concepts. However, it doesn't waste words and front-loads the purpose.

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

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

Given the tool's moderate complexity (5 params, output schema absent), the description covers return values, parameter behavior, and read-only nature. It also hints at performance concerns for large tables, which is valuable for correct invocation. Minor gaps like pagination details are handled by referencing query_range.

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 compensates by explaining the key parameters: 'columns' for projection, 'values' for caching modes, and 'records' for row object formatting. Although it doesn't detail 'path' and 'name', they are self-evident, and the description does add meaning to the less obvious ones.

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

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

The description clearly states the tool reads table data by name, specifies case-insensitivity, and describes the returned elements (table ref, column names, data rows). It distinguishes itself from sibling tools like query_range and manage_table by noting that advanced operations are handled elsewhere.

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

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

It provides usage context, such as using query_range for filtering/paging big tables and manage_table for advanced ops, but doesn't explicitly list when not to use this tool versus read_range or get_cells. However, the mention of alternatives gives clear context for distinct use cases.

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

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

Annotations already establish read-only behavior, and the description adds meaningful detail beyond that: it does not open the file for edit, works while Excel has the file open, reports the TRUE used range rather than possibly stale stored dimensions, and includes an openpyxl round-trip hazard summary. No contradiction with readOnlyHint or openWorldHint.

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

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

The description is dense but well-structured: the first sentence front-loads the action and lists the returned metadata, while the two short fragments add usage and behavioral context. Every clause earns its place; the parenthetical about TRUE used range is lengthy but 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?

Even without an output schema, the description enumerates the principal return fields, making the result set predictable. It also covers read-only behavior, concurrent use with Excel, and the hazard-summary caveat. Nothing critical is missing for this simple one-parameter tool.

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

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

The single 'path' parameter is reasonably self-evident from its name plus the tool description's 'workbook' context, so an agent can infer it refers to the workbook file. However, with 0% schema description coverage, the description itself adds no explicit path format, supported extension, or location guidance, so it only partially compensates for the schema 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 ('Read') and resource ('a workbook's structure'), then enumerates exactly what is returned: sheets, visibility, TRUE used range, dimensions, merged-cell count, defined names, tables, active sheet, and a round-trip hazard summary. It is clearly a read-only metadata/introspection tool, though it does not explicitly contrast with the sibling diagnose_workbook, so sibling differentiation is implicit rather than stated.

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

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

Provides clear usage context with 'The orient-before-editing call' and 'Read-only; works while the file is open in Excel', signaling that this is the pre-edit inspection step. It does not name alternative tools or state explicit when-not-to-use conditions, but the intended context is unambiguous.

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

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

Annotations already carry readOnlyHint=true and openWorldHint=false, and the description adds substantial context beyond them: 'reads nothing, changes nothing' reinforces the safety profile, and the disclosure that COM-tier unshipped tools are 'marked forthcoming rather than pretended present' is a genuinely valuable honesty guarantee — the agent learns it will not be handed fabricated tool names. The enable_tools/lite pack dependency is also disclosed.

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

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

Four dense sentences, each earning its place: output structure, invocation modes with concrete values, truthfulness policy, and safety note. The length is justified by the two-mode invocation and the honest-disclosure clause; it is front-loaded with the core purpose. Not a 5 only because it is somewhat long, 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 must convey return behavior — and it does: a task list or a step-by-step recipe with notes. It covers all invocation modes, all valid parameter values, the pack/enable_tools dependency, the no-mutation guarantee, and the forthcoming-tools policy. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden — and it fully compensates. It explains that the task parameter takes no value to list tasks or a named task for a recipe, and enumerates every valid value (merge-workbooks, report-build, data-cleanup, formatting-audit-and-fix, safe-edit-of-rich-workbook, migrate-from-incumbent), effectively supplying an enum the schema omits.

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

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

The description states a precise function: returning recommended tool sequences for multi-step spreadsheet tasks, each with the tool name, rationale, and pack. It clearly distinguishes itself from the ~40 operational siblings (read_range, write_range, set_cell, etc.) by being the only guidance/metadata tool, so an agent can separate it from the others without inspecting schemas.

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

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

The description gives explicit invocation patterns for both modes — call with no task to list available tasks, call with task='<name>' for a recipe — and enumerates all six valid task values. It provides clear context, but stops short of explicitly naming alternatives or stating when-not-to-use; the differentiation from operational siblings is implied through the tool's nature rather than 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?

The description goes well beyond the destructiveHint annotation by disclosing formula-injection protection, the 200,000-cell ceiling refusal, hazardous workbook handling, auto-backup, atomic verified save, and refusal while open in Excel.

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

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

The description is dense and front-loaded with the core action, followed by concise, purposeful sentences covering safety and refusal behavior. Every sentence earns its place with no repetition or filler.

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

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

For a tool with 13 parameters, destructive behavior, and no output schema, the description covers key safety and usage aspects well. It is incomplete, though, because it omits several parameter semantics and does not describe expected results or failure modes beyond refusal cases.

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

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

It adds meaning for source, source_file, fmt, location, formulas, allow_loss, and backup, which is valuable given 0% schema description coverage. But several parameters—header, delimiter, encoding, verify_com, path, and sheet—are not explained, leaving significant gaps.

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

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

The description clearly states it imports CSV, TSV, or JSON into a sheet at an anchor, giving a specific verb, resource, and formats. This distinguishes it from sibling tools like export_range or write_range.

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 a clear context for use—importing file contents into a sheet—and explains how to pass source or source_file. However, it never explicitly says when to prefer this tool over alternatives or notes exclusions.

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 only set destructiveHint=true; the description far exceeds that by disclosing exactly what each destructive path does: restore rotates current content into prev first (making it undoable), validates payloads before atomic replace, refuses files open in Excel, purge honors dry_run=TRUE default, and snapshots are never touched by rotation or purge. This is rich behavioral disclosure with zero contradiction against annotations.

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

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

The description is long (~250 words) but every sentence earns its place given 4 modes and 8 params. It is front-loaded with the storage model and organized action-by-action, with the LIMIT warning and cross-reference placed last. The only shortfall is a single dense paragraph rather than scannable structure, and minor repetition of the folder name.

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

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

For a destructive, multi-mode tool with no output schema, the description covers every parameter, every action's side effects, the fundamental limitation, and the recover-workflow alternative. The only omissions are explicit return-value formats for actions like list (it names fields — sizes, mtimes — but not the response shape), which is marginal against the overall exhaustiveness.

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%, so the description carries the full burden for all 8 parameters and discharges it completely: path (workbook vs directory), source (prev/anchor), scope (orphans/slots), dry_run (defaults TRUE, only reports), label/dest_dir (snapshot naming), and directory (folder listing). Every parameter's meaning and format is covered in prose.

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 resource (automatic backups in the hidden .ks4xl-backups folder with rotating prev/anchor slots) and fully enumerates the four actions (list, restore, purge, snapshot). No sibling tool handles backup management, so it is cleanly distinguished from every sibling merely by resource and verb.

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?

Goes beyond stating when to use it — it explains each action's mode with its governing parameters (list takes path or directory; restore takes source prev/anchor; purge takes scope orphans/slots and dry_run default; snapshot takes label/dest_dir). It also gives an explicit exclusion: the LIMIT paragraph warns what the tool cannot recover, and routes to the sibling get_workflows task='recover-workbook' for that case.

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

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

Annotations already mark destructiveHint=true, but the description goes further: it discloses that mutating actions refuse on hazardous workbooks unless allow_loss=true, auto-backup to prev/anchor slots, perform atomic verified saves, and refuse while the file is open in Excel. It also clarifies that 'remove' only strips the link, preserving text and style. This exceeds what annotations alone convey.

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

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

The description is densely packed but every sentence earns its place. It opens with purpose, then systematically covers each action's behavior, safety, backup, and locking constraints. No redundancy or filler; it is efficient and well-structured.

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

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

For a 10-parameter tool with no output schema, the description is remarkably complete. It specifies the exact semantics for each action, side effects, safety mechanisms, backup behavior, and even what the list action returns (both real and formula hyperlinks). An agent has enough to call it correctly without needing to inspect schemas further.

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 0%, so the description must carry the burden. It successfully explains core parameters: action (add/remove/list), location (cell reference), target (URL or 'Sheet!A1'), display (replaces cell value), tooltip, and allow_loss (hazardous refusal). However, it leaves path, sheet, backup, and verify_com unexplained. It covers the most important ones but misses several, so a 4 is appropriate.

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

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

The description opens with 'Manage cell hyperlinks' and immediately enumerates three concrete actions (add, remove, list) with precise semantics for each. It clearly distinguishes this tool from siblings like set_cell or write_range by focusing exclusively on hyperlink behavior. The phrasing is specific and action-oriented.

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?

While the description clearly conveys when to use the tool (to manage hyperlinks) and gives behavioral details for each action, it does not explicitly name alternative tools or state when NOT to use it (e.g., for simple cell value writes). The context is clear enough for an agent to infer usage, but it lacks explicit exclusions.

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

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

Even though destructiveHint is already true, the description adds substantial behavioral detail: delete and rename do not rewrite references and can produce #REF!, the last visible sheet is protected, hazardous workbooks require allow_loss, backups are rotated via .ks4xl-backups, saves are atomic and verified, and the tool refuses while the file is open in Excel. This goes well 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?

The description is dense but every sentence carries unique operational value. The action summary is front-loaded, and the caveats about references, backups, and Excel locking are efficiently grouped. It is long because the tool is complex, not because of waste.

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

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

The description covers actions, parameter constraints, side effects, safety refusals, backup behavior, and Excel-lock behavior comprehensively. Minor gaps remain: it does not state return values and leaves verify_com semantically unexplained, so it is not fully complete for an agent invoking every parameter 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?

With 0% schema description coverage, the description compensates well by defining action-to-parameter mappings, clarifying that index is 0-based, enumerating hide state values, and explaining backup=false and allow_loss. It does not explicitly explain verify_com or path, though path is self-evident.

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

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

The description names the resource (worksheet lifecycle) and then enumerates the exact actions available: add, delete, rename, copy, reorder, hide, unhide. This makes it clear what the tool does and distinguishes it from sibling workbook-level tools like create_workbook and copy_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 lifecycle framing and action list strongly imply when to use this tool, and the description adds practical conditions such as 'Audit references first when in doubt' and 'Refuses while open in Excel.' It does not explicitly name sibling alternatives or list exclusions, but the intended context is clear.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false. The description goes far beyond that: it details reference-rewrite scope, #REF! behavior, refusal on loss unless allow_loss, backup rotation, atomic verified save, and refusal while open in Excel. This is rich behavioral disclosure that fully covers the tool's side effects.

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

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

The description is long but every sentence adds substantive value given the tool's complexity. It front-loads the core purpose and then enumerates behaviors and parameters in a logical order. It is dense but not bloated; the length is justified by the intricate rewrite and safety mechanics.

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

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

For a tool with 8 parameters, no output schema, and destructive behavior, the description covers most critical aspects: reference rewriting, #REF! reporting, refusal conditions, backup/restore, and return counts. Missing details like the exact meaning of 'verify_com' and the full behavior of 'sheet' are minor gaps, but given the complexity, the description is largely complete.

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

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

Schema description coverage is only 13% (only 'at' has a description). The description adds meaning for 'action' (lists allowed values), 'at' (explains multiple formats), and 'count' (edits that many at once). It also touches on 'backup' and 'allow_loss' behavior. However, it leaves 'path', 'sheet', and 'verify_com' unexplained, and 'path'/'sheet' are essential for targeting the workbook. It compensates partially but not fully.

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

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

The description clearly states the tool inserts or deletes rows/columns and rewrites all references to keep the workbook coherent. It is specific about the resource (grid structure) and the verb (insert/delete), and the detail on reference rewriting distinguishes it from siblings like apply_edits.

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

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

The description provides clear context on when this tool is appropriate (structural edits with reference rewriting) and mentions refusal conditions (hazardous workbook, open in Excel). However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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

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

The annotations already mark this destructive, and the description adds substantial beyond-schema behavior: rewriting formulas, names, conditional formats, validation, table refs, and merges; overwriting destination cells; requiring allow_loss for hazardous workbooks; auto-backup; atomic verified save; and refusing while open in Excel. No contradiction with annotations.

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

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

Every clause carries a distinct, important fact: core semantics first, then restrictions, safety, backup/save behavior, and Excel lock refusal. No filler or repetition.

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

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

For a complex destructive move operation, the description is thorough: it covers preconditions (same sheet, not open in Excel), side effects (reference rewriting, overwriting), safety (allow_loss, backup, atomic save), and failure modes. A return-value contract is absent, but the behavioral and safety context is strong enough for an agent to invoke it correctly.

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

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

Schema coverage is only 29%, so the description must compensate. It does contextualize allow_loss and backup behavior and clarifies the same-sheet constraint and destination overwrite, but path, sheet, verify_com, and the backup parameter itself are left mostly to inference from their names. It partially compensates but not fully.

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 operation—moving a rectangle to a new anchor on the same sheet—and captures the core Excel-move semantics of rewriting references. It is clearly distinguishable from siblings like copy_range and clear_range, and even names the alternative approach for cross-sheet moves.

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

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

It explicitly says cross-sheet destinations are refused and routes to 'copy_range then clear_range instead'. It also gives refusal conditions for hazardous workbooks and while open in Excel, so an agent knows when this tool does and does not 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?

Annotations indicate readOnlyHint=true and openWorldHint=false, but the description goes far beyond those by disclosing cached-value semantics, blank-row behavior, regex timeout guarding, Excel-style aggregate rules, and hidden-row inclusion. These are non-obvious behaviors that would surprise an agent without this disclosure. A final 'Read-only.' confirms the annotation, adding no contradiction.

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

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

The description is long, but every sentence earns its place by adding operational detail an agent needs to call the tool correctly. The structure front-loads the core capability and then organizes semantics into clear paragraphs: parameter explanations, predicate behavior, and aggregate rules. Despite its length, there is no filler or repetition of schema fields without added value.

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

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

This is a complex 15-parameter tool with no output schema, so the description must carry significant explanatory weight. It covers defaults, filter operators, projection, sorting, pagination, aggregation, grouping, and subtle behavioral semantics such as cached reads and blank handling. There is no notable missing information that would prevent an agent from invoking 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 33%, but the description compensates richly by explaining the semantics of location (defaults to true used range), header (first row names columns), where (predicate list with ops and match), columns (projection), order_by (sort specs, unknown directions refuse), offset/limit, distinct, aggregate (function list and Excel semantics), group_by, and records. It maps directly onto the schema's parameters and adds meaning the schema lacks.

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

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

The description opens with a precise verb and resource: 'Filter, project, sort, paginate, and aggregate a range SERVER-SIDE,' immediately distinguishing it from plain range reads. The phrase 'instead of a whole sheet' further clarifies its role relative to sibling tools like read_range. This is a textbook clear purpose statement.

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

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

The description clearly implies when to use the tool: whenever an agent needs only a subset of rows/columns, sorting, pagination, or aggregation, rather than the full sheet. It does not explicitly name an alternative tool such as read_range or get_cells, but the 'instead of a whole sheet' contrast provides strong contextual routing. It lacks explicit 'when not to use' language, but the implied guidance is sufficient for an experienced agent.

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 this with 'Read-only'. It adds significant behavioral nuance by explaining the 'honest calc story' — that formula cells with no cached value are labelled 'absent' rather than blank — and mentions the performance hint about large ranges. This goes beyond the annotation without contradicting it.

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

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

The description is a single dense paragraph that front-loads the core purpose and then layers in parameter details. It is efficient with no fluff, though it is slightly long. The structure is logical: purpose, location options, values behavior, and a final note on read-only and pagination. It earns a high score for being information-dense without redundancy.

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

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

With four parameters, no output schema, and no parameter descriptions in the schema, the description covers most critical aspects: location types, sheet selection, values semantics, and the large-range pagination hint. It does not explicitly describe the return format or error behavior, but for a read operation with readOnlyHint, these are secondary. Overall it is adequately complete for an agent to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains the 'location' parameter by listing all accepted object types, explains the 'sheet' default behavior, and details the three 'values' modes ('cached', 'formula', 'both') with their exact meanings. The 'path' parameter is not explicitly explained, but its role is inferable as a workbook path. The description adds substantial semantic value beyond the bare schema.

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

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

The description states a specific verb ('Read') and resource ('cell or range'), and enumerates the accepted location object types (cell, range, r1c1, name, table, etc.), which clearly distinguishes it from sibling write tools and query_range. The phrase 'page large ranges with query_range' further differentiates it from 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?

The description gives explicit guidance on when to use query_range for large ranges, and implicitly indicates read_range for normal reads. However, it does not explicitly mention alternatives like get_cells or set_cell, or provide conditions for choosing read_range over them. It still gives clear context on when to use the tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's job is to add behavioral nuance. It does this richly: atomic batch application, auto-backup to .ks4xl-backups, refusal while open in Excel, hazardous workbook gating, formula-injection blocking, and number conversion of replaced values. These details go well beyond the annotations and materially inform an agent about side effects and safety. No contradiction with annotations.

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

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

The description is long but justifiably so for a tool with 13 parameters and significant safety implications. It front-loads the core purpose and then layers details logically. Every sentence adds value, though some clauses (e.g., the exact regex timeout mention) could be trimmed without loss. Overall, it is well-structured and dense without being 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?

For a complex mutation tool with no output schema and 0% schema coverage, the description covers the critical operational aspects: scope selection, match semantics, dry-run preview, batch application, return reporting (cells changed and occurrences replaced), safety guards (injection, hazardous workbook, Excel lockout), and backup/atomicity. It even explains output behavior, compensating for the lack of an output schema. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 0%, so the description must compensate. It explains key parameters: match (exact/contains/regex), look_in (values/formulas/both), dry_run, formulas (injection), allow_loss (hazardous workbook), and backup (auto-backup). However, it does not explain location, match_case, verify_com, or the precise interplay of sheet vs location. Given the 0% coverage, the description covers the most critical parameters but leaves some gaps, so a 4 is appropriate.

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

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

The description opens with a specific verb-resource pair: 'Find-and-replace across a workbook, sheet, or range.' This clearly distinguishes it from siblings like find_cells (read-only search) and set_cell (single cell write). The purpose is unambiguous and immediately actionable.

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

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

The description provides extensive context about how the tool behaves (match modes, dry-run, batch application, safety guards) but does not explicitly say when to choose this tool over alternatives like set_cell or find_cells. The usage is implied through the detailed behavior, but there is no explicit when-to-use/when-not-to-use guidance or mention of sibling tools.

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

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

The description adds substantial behavioral context beyond annotations: formula normalization with no literal escape, recalc-on-open flag, hazardous-workbook refusal tied to allow_loss, auto-backup rotation in .ks4xl-backups, atomic verified save with restore, and refusal while open in Excel. These explain real operational constraints and failure modes that the annotations do not capture.

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

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

The description is dense but well-organized: it front-loads the core action, then moves through formula handling, hazard gating, backup/save integrity, and Excel lock. Each sentence contributes distinct information, though the length is at the upper boundary of 'concise' for a tool of this 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 7-parameter mutation with no output schema and only 14% schema coverage, the description covers the critical invariants (formula behavior, hazard gate, backup, Excel lock) but omits the structure of the location object and the meaning of verify_com. These gaps matter because an agent cannot construct a correct call without understanding how to address a cell location.

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%, so the description must compensate for underdocumented parameters. It adds meaning for backup (prev/anchor rotation and backup=false skipping) and allow_loss (needed for hazardous workbooks), and clarifies value semantics. However, location is only called an object, and verify_com, sheet, and path receive no additional explanation, leaving key parameter behavior underspecified for such a low-coverage schema.

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

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

The description opens with 'Write a single cell addressed by a location object,' which names the specific verb, resource, and scope. The 'single cell' qualifier distinguishes it from range-oriented siblings like write_range, set_cells, and clear_range, so an agent can tell them apart without opening schemas.

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

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

The description implies usage through 'single cell' and explains formula vs literal behavior, but it never explicitly states when to choose set_cell over set_formula, write_range, or apply_edits. There are no exclusions or 'use this instead when...' notes, leaving the agent to infer the boundary from the scope wording.

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

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

The description goes far beyond the annotations. It reveals atomicity, resolution-before-write behavior, the 'one bad item refuses the whole batch untouched' failure mode, formula normalization, the hazardous-workbook gate via allow_loss, auto-backup, atomic verified save, and the refusal to run while the file is open in Excel. This gives an agent a rich, accurate behavioral model.

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

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

The description is dense and front-loaded, opening with the core purpose before diving into constraints and safeguards. Every sentence adds specific value, though the amount of detail makes it slightly long. It is well-organized and free of fluff.

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

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

For a complex mutation tool with no output schema and six parameters, the description covers the most critical operational aspects: atomicity, failure semantics, formula handling, hazard gating, backup, and Excel lock behavior. It does not explain sheet selection, the backup parameter's role, or verify_com, which leaves some gaps, but overall it is sufficiently complete for safe 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 very low (17%), so the description must compensate. It does add meaning for the cells parameter (structure, cell format, 1,000-cell ceiling) and for allow_loss (hazardous workbook gate). However, key parameters like path, sheet, backup, and verify_com are left unexplained, leaving noticeable gaps.

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

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

The description states the verb ('Write'), the resource ('many individually addressed cells'), and the key constraint ('ONE atomic batch'). It also explicitly frames the tool as the 'scatter complement to write_range', which immediately distinguishes it from the sibling range-writing tool and implies it is the batch version of set_cell.

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?

Mentioning 'scatter complement to write_range' gives contextual guidance for when to choose this over write_range, but it does not explicitly state when not to use it or name alternatives like set_cell for single-cell writes. The guidance is implied rather than explicit, so it falls short of a clear usage rule.

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

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

The description discloses important behavioral traits beyond annotations: a hazardous workbook refuses unless allow_loss is true, auto-backup to .ks4xl-backups, atomic verified save, refuses while open in Excel, and autofit is only an approximation. This complements the destructiveHint and idempotentHint annotations, with no contradiction.

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

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

The description is dense but purposeful. It front-loads the overall purpose, then organizes parameter semantics and behavioral caveats in separate sentences. For a 15-parameter tool, the length is justified and no sentence is filler.

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

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

The description covers all major operation groups, safety behavior, backup, and where to read outline state. A few optional parameters like verify_com and the exact effect of backup: false are left implicit, and path/sheet defaults are not stated, but the combination of schema and description is largely sufficient for a tool this complex.

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 47% schema description coverage, the description does the heavy lifting: it defines column_widths in Excel character units, row_heights in points, the group/ungroup span shape with levels 1-7, ungroup behavior, and outline_summary's {below, right} meaning. These are exactly the semantics missing from the schema.

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

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

The description states a specific verb and resource: 'Set column widths and row heights, hide rows or columns, group them into collapsible outline levels, and service an autofit request.' This enumerates the exact operations and distinguishes it from siblings like set_cell, format_cells, and modify_grid_structure.

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 useful context, such as grouping being 'the collapse bracket a budget or financial model is built around,' and points to get_workbook_metadata for reading back the current outline. It also notes true autofit requires the com pack, offering an alternative path. It does not explicitly compare against all sibling tools, but the guidance is clear enough.

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

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

Even though annotations already mark the tool as destructive and idempotent, the description adds substantial behavioral context: uncalculated formulas keep rows visible with a warning, hazardous workbooks require allow_loss, backup and atomic verified save happen automatically, and the tool refuses while the workbook is open in Excel. No contradiction with annotations.

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

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

The description is dense but information-rich, with the core action front-loaded. It is somewhat run-on, but virtually every clause carries distinct behavioral value, so the size is justified.

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

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

For a destructive write operation with no output schema, the description covers side effects, safety conditionalities, persistence behavior, and an important lock condition. It falls short only by omitting return-value behavior and leaving some parameter semantics undefined.

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 very low (14%), so the description must compensate. It does clarify criteria structure, AND combination, ops, and the meaning of allow_loss and backup, but path, sheet, location, and verify_com remain unexplained. This is partial compensation with notable gaps.

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

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

The first sentence names an exact action and resource: apply an autofilter over a range whose first row is the header. It also states the crucial behavior that non-matching rows are actually hidden, which distinguishes it from a criteria-only filter or from clear_filter.

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

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

The description gives clear context for what applying the filter does, but does not explicitly say when to choose this tool over alternatives like query_range, sort_range, or clear_filter. Refusal conditions and the auto-backup behavior help, but no when/when-not guidance is 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?

Annotations only declare readOnlyHint=false and destructiveHint=true; the description adds substantial behavioral detail: relative-reference shifting, absolute anchors, formula normalization, recalc-on-open, stale cached results, auto-backup, atomic verified save, and refusal while open in Excel. This goes well beyond the structured hints.

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

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

The core operation is front-loaded, followed by necessary caveats in compact, information-dense sentences. No filler; every sentence earns its place 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?

The description covers the most important behavioral caveats and safety measures, but it omits parameter-level semantics for ambiguous flags and says nothing about invalid-formula handling or return behavior. Since there is no output schema, those omissions make the tool not fully self-sufficient.

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

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

Schema description coverage is 0%, so the description must compensate for all 7 parameters. It clarifies formula and location behavior, but leaves allow_loss, verify_com, sheet, and the backup flag semantically unexplained. With multiple ambiguous flags, this is a meaningful 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 starts with a specific verb and resource: writing a formula to a single cell or filling a range, with Excel copy semantics. This clearly distinguishes the tool from value-writing siblings like write_range and set_cell by emphasizing formula-specific behavior.

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 formula-specific wording gives clear context for when to use this tool, and the explicit refusal while the workbook is open in Excel is a useful exclusion. It does not name sibling alternatives or state 'use X for values', but the purpose is clear enough 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 description richly discloses data-loss semantics ('only the top-left value survives'), refusal behavior, the confirm_data_loss reporting of discarded values, auto-backup to .ks4xl-backups, atomic verified save, and refusal while Excel is open. This far exceeds the annotations' destructiveHint:true and readOnlyHint:false. There is no contradiction.

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

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

Though dense, the description is a single paragraph where every clause adds necessary behavioral detail. The core purpose is front-loaded, and there is no filler or repetition. The length is justified by the tool's complexity.

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

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

For an 8-parameter mutation tool with no output schema and minimal annotations, the description covers actions, constraints, failure modes, safety flags, backup, atomic save, and concurrency. An agent has enough information to call the tool correctly in most scenarios, and the remaining parameter ambiguities are minor.

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 0% schema description coverage, the description must and does compensate: it explains action, location, allow_loss, confirm_data_loss, and backup behavior. However, verify_com is never explained, and path/sheet are only implied through context, leaving a few parameters to inference.

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

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

The description opens with 'Merge or unmerge cell ranges, or list every merge' — a specific verb, resource, and three distinct actions. It clearly differentiates this tool from siblings like set_cell or clear_range by focusing entirely on merge operations. No ambiguity remains about the tool's purpose.

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

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

The description gives explicit conditions for each action: unmerge requires the exact stored merged range, and list can target one sheet or the whole workbook. It also states refusal conditions (overlapping merge, hazardous workbook, Excel open) and which flags to set. It does not explicitly name alternative tools, but the unique merge purpose makes the usage context clear.

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

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

Adds valuable context beyond the annotations, which is notable for a destructiveHint=true tool: auto-backup to .ks4xl-backups, atomic verified save, refusal while open in Excel, unset-parameters-keep-values semantics, and exclusivity between freeze and split. Not a 5 because the verification-failure path and what allow_loss actually permits are left unstated.

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?

Dense and waste-free: every clause maps to a parameter or behavior, with the core purpose front-loaded. It is a single packed paragraph that would scan better as bullets, but there is no filler or redundancy to penalize.

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 destructive tool with no output schema, the description covers an unusual amount: formats, valid ranges, defaults, the safety net (backup + atomic save), and the Excel-lock constraint. The only notable omissions are the semantics of allow_loss and verify_com and the response/verification contract on failure, which an agent would need for advanced or error cases.

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

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

With 0% schema coverage the description carries the full burden and largely delivers: freeze='B2' semantics with 'clear', split={x,y} in points and exclusive with freeze, zoom range 10–400, selection as A1 cell or range, tab_color as 6-digit hex or 'clear', and unset-means-unchanged defaults. However, allow_loss and verify_com are completely unexplained, which is a real gap at zero 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?

Opens with a specific verb+resource ('Set sheet-view state in one call') and then enumerates the exact scope: freeze, split, gridlines, headings, zoom, selection, and tab color. This makes the tool's boundary clearly inferable against siblings like format_cells or set_dimensions, though it never names a sibling 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?

Usage context is implied through the enumeration of settable view aspects and the 'in one call' framing, and constraints are disclosed ('sheet defaults to the active sheet', 'Refuses while open in Excel'). However, there is no explicit when-to-use vs alternatives guidance or exclusions, so the agent must infer selection criteria from the parameter list.

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

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

The description adds substantial behavior beyond the annotations: no-parameter calls are read-only, manual calc mode causes stale caches, an auto-backup and atomic verified save occur, and the operation refuses while the file is open in Excel. It also discloses the conditional read-only nature despite the destructiveHint, clarifying rather than contradicting the annotations.

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

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

The description is compact and front-loaded: the first sentence establishes the primary purpose and parameter groups, while the remaining sentences add critical behavioral caveats. Every sentence earns its place, and there is no filler or repetition of schema/default information.

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

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

The description covers the core behavior, conditional read-only semantics, backup/save guarantees, and an important refusal condition, which is strong for a complex tool. Yet it still omits semantics for several parameters (allow_loss, verify_com, path) and does not describe the result/return shape, which matters because there is no output schema. An agent could call it correctly in most cases but may mis-handle the undocumented options.

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

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

With schema description coverage at 0%, the description carries the burden and does so well for most parameters: it names the document property fields, explains calc_mode values, and describes iterative_calc with max_iterations and max_change. However, allow_loss, verify_com, and path receive no semantic explanation, leaving meaningful gaps for a 15-parameter tool.

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 ('set') and a precise resource ('core document properties ... and calc settings'), enumerating the affected fields. The scope is clearly workbook-level metadata/calculation behavior, which distinguishes it from sibling tools like set_cell, manage_worksheet, or get_workbook_metadata. The added nuance about read-only reporting with no parameters further sharpens the purpose.

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

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

The context for use is implied: use this to change document properties or calculation settings, or to report current values when no parameters are given. It also gives a hard prerequisite ('Refuses while open in Excel'). However, it does not explicitly mention when to prefer an alternative sibling such as get_workbook_metadata or audit_formulas, and there are no when-not-to-use directives.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses critical behaviors: formula relative reference shifting, cached value comparison with warnings for uncalculated cells, pinned filter-hidden rows, auto-backup with undo capability, atomic verified save, and refusal when open in Excel. This rich detail greatly exceeds what annotations alone convey.

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

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

The description is dense yet well-organized, opening with the core purpose, then the key parameter semantics, followed by behavioral notes. Every sentence adds value, and there is no redundancy or filler. The length is justified by the tool's complexity and the need to convey safety-critical 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 tool with 8 parameters and low schema coverage, the description covers the main operational semantics, safety requirements, and error conditions. It addresses formula handling, hidden rows, and open-workbook refusal. Some parameters remain under-specified, but the essential information for correct invocation is present, making it reasonably complete.

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

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

The description explains the keys parameter thoroughly (list of {column, order}, column types, tie-breaking) and clarifies has_header ('keeps the first row put'). It also implies allow_loss and backup behavior. However, with schema coverage at only 13%, several parameters (path, sheet, location, verify_com) lack explicit elaboration in the description, so it only partially compensates 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 states a specific verb ('Sort') and resource ('a range or table body') with clear details about writing rows back reordered. It differentiates from sibling range operations (e.g., copy_range, clear_range, query_range) by focusing solely on sorting semantics, leaving no ambiguity about the tool's role.

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

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

The description provides strong contextual usage guidance, such as how filter-hidden rows are handled, the need for allow_loss on hazardous workbooks, and refusal while open in Excel. It does not explicitly name alternative tools, but since no sibling tool performs sorting, the intended usage is clear and unambiguous.

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

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

Even though readOnlyHint already covers safety, the description adds meaningful behavior: the default checks, the exact return shape {passed, results: {check: {passed, findings}}}, the fact that passed=false means findings rather than a failed call, and that findings retain underlying ops' shapes. It also discloses that the tool works while the file is open and that repairs are intentionally out of scope. There is no conflict with annotations.

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

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

The description is front-loaded with the core action and then uses a structured list for checks; every clause carries semantic content. It is longer than a minimal description because of the detailed check list, but the detail is justified for a tool with many options.

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, yet the description supplies the full return shape and the meaning of passed=false, and explains all available check options. It also addresses safety, repair routing, and open-file behavior, so an agent has what it needs to invoke validate correctly.

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

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

The input schema provides no descriptions for either parameter, but the description compensates by documenting the checks parameter in depth: the default list, every supported check name, and what each one validates. Path is not elaborated, but its meaning is self-evident from the tool's purpose. The only minor gap is that the schema's default null and the textual default list are not explicitly reconciled.

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

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

The description uses a specific verb and resource: 'Run read-only correctness checks and return one report' on the workbook, and enumerates supported checks. It clearly identifies the tool as a read-only validation pass, but it does not explicitly differentiate it from the sibling diagnose_workbook, which may occupy a similar diagnostic role.

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 says 'Read-only, always; repairs live in the editing tools,' which provides an exclusion and points to alternatives for fixing issues. It also notes that external_links are 'reported, not repaired' and that the tool works while the file is open, giving clear context. It does not explicitly name sibling alternatives or state when to prefer diagnose_workbook, so it stops short of a 5.

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

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

Annotations only supply readOnlyHint=false and destructiveHint=true; the description adds substantial beyond-annotation behavior: ragged rows are refused with null-padding semantics, content outside the block is untouched, formula normalization triggers recalculation, hazardous workbooks require allow_loss, auto-backup with atomic verified save, and refusal while open in Excel. No contradiction with the destructive hint.

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

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

Seven sentences, each earning its place: purpose is front-loaded, followed by data invariants, safety ceilings, loss handling, and workflow guards. Dense but not bloated, with zero filler or repetition of schema or annotation content.

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

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

For a 7-parameter destructive mutation with no output schema, the description covers behavior comprehensively: data shape, boundaries of effect, limits, hazard handling, backup, and concurrency refusal. It leaves minor gaps — no description of the confirmation/return payload, and sheet/verify_com semantics are unaddressed — but an agent can call this correctly with the information given.

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 14% schema description coverage, the description must compensate, and it does for the key parameters: data is explained in depth (list of row lists, must be rectangular, null clears, '=' prefix means formula), location is clarified as the top-left anchor, and allow_loss is mapped to the hazardous-workbook refusal. However, sheet, verify_com, and backup get no explicit parameter-level explanation beyond the general backup statement.

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 names a specific verb and resource ('Write a 2D block of values and formulas anchored at the location's top-left cell'), which clearly distinguishes it from single-cell writes (set_cell), clears (clear_range), and copies (copy_range). The anchoring detail adds precision beyond a generic 'write values' statement.

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

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

The description gives clear context for what the tool writes (rectangular blocks anchored top-left) and its constraints (200,000-cell ceiling, Excel lock refusal), so usage is implied. However, it never explicitly routes the agent away from near-siblings set_cells, apply_edits, or import_data, nor states when NOT to use it, which matters given ~40 sibling tools.

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