io.github.nometalalchemist/kitchensink4xl
Server Quality Checklist
Latest release: v1.2.0
- Disambiguation4/5
Most tools follow a clear action+resource pattern and the detailed descriptions separate rectangular reads from scatter reads, grid views from queries, and single-cell writes from batch edits. A few close pairs (set_cell/set_cells/set_formula, get_table/read_range/query_range) still rely heavily on descriptions to avoid misselection.
Naming Consistency5/5All tools use a consistent snake_case verb_noun convention (get_*, set_*, clear_*, manage_*, create_*), with clear resource terms like range, cell, table, worksheet, and workbook. The bare 'validate' is the only slight outlier and does not break the overall pattern.
Tool Count2/540 tools is well above the 25+ threshold and makes the surface heavy, even though the optional pack mechanism and detailed descriptions mitigate the cognitive load. Several tools are near-variants (set_cell/set_cells/write_range/apply_edits) that could arguably be consolidated.
Completeness4/5The core spreadsheet lifecycle is well covered: workbook create/copy/metadata, worksheet lifecycle, range read/write/clear/copy/move, query/find/replace, formatting, filters, merges, hyperlinks, and backup management. Minor gaps remain—no delete_workbook, no table deletion/resize in the static list, and advanced features (charts, protection, recalc) are only reachable through pack descriptions via enable_tools.
Average 4.5/5 across 40 of 40 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 124 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under AGPL 3.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set readOnlyHint to false, but the description ends with 'Read-only.' This is a direct contradiction. Additionally, the description itself notes 'out_file writes a file,' so even internally the read-only claim is misleading. The guard and backup details are useful, but the contradiction forces a score of 1.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: purpose first, then defaults, mode options, output behavior, file-safety guards, hidden-row handling, and the multi-sheet caveat. Every sentence carries information, though the packed style reduces skimmability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers defaults, mode reporting, file overwrite/backup behavior, target guard restrictions, and hidden-row behavior, which is strong for a tool with no output schema. However, the unclear meaning of the required 'path' parameter and the unaddressed header/records semantics leave it below complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It covers location, values, out_file, overwrite, and fmt implicitly, but leaves path, sheet, header, and records unexplained. Path is required, making this a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening clause states a specific verb ('Export'), resource ('a range, table, or sheet'), and target formats ('CSV, TSV, or JSON'), making the tool's function immediately distinct from read, copy, or import siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives some context by noting that multi-sheet exports are handled elsewhere ('Multi-sheet is export_file, io pack') and that out_file vs inline text changes the result, but it never explicitly states when to prefer export_range over read_range or get_cells, nor lists alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false provided, the description carries the full burden of behavioral disclosure and does so richly. It explains cached/literal evaluation, formula rows staying visible with a warning, refusal of hazardous workbooks unless allow_loss=true, auto-backup with atomic verified save, and refusal while the workbook is 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but tightly structured: the core behavior is front-loaded, followed by caveats and safety details. Each clause contributes non-obvious context, and nothing feels redundant or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter destructive write with no output schema, the description covers many non-obvious behaviors, from formula warnings to backup and Excel locking. However, it leaves the meaning of the required location parameter and the optional verify_com parameter unexplained, and it does not state what the tool returns, so some gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 14%, and the required location parameter is essentially unexplained beyond its type union. The description adds useful meaning for criteria and allow_loss, but it does not clarify location, sheet, or verify_com, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb, resource, and outcome: 'Apply an autofilter over a range whose first row is the header, and actually hide the non-matching rows.' It clearly distinguishes the tool's behavior from related operations by emphasizing actual row-hiding, and it even references query_range for operator semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the main use case: applying filter criteria and hiding rows because .xlsx stores criteria, not hidden state. However, it never explicitly says when to prefer set_filter over clear_filter or query_range, and it gives no 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=false annotation, the description discloses refusal conditions (overlap, name conflicts, hazardous workbooks, file open in Excel), the behavior of allow_loss, auto-backup to .ks4xl-backups, and atomic verified saving. This is substantial behavioral context that meaningfully goes 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by dense but relevant behavioral details. Every sentence adds information about how the tool behaves or what the agent must account for. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides rich safety and behavior context, but given no output schema, only a single annotation, and 0% schema coverage over 13 parameters, it is not fully complete. An agent still lacks clear semantics for locating the target range/file and for return/verification outcomes. It is above average but not exhaustive enough for a high score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries a heavy burden. It explains header deduplication, style, row/col stripes, totals mapping, backup, and allow_loss. However, it leaves several important parameters undocumented: path, sheet, location, totals_row, and verify_com. The compensation is good but incomplete for a 13-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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.' It clearly distinguishes this from siblings by focusing on table creation rather than generic write/format operations. The scope is unambiguous and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a range should become a structured Excel table with styling, totals, and safety guarantees. However, it does not explicitly contrast it with alternatives like write_range or format_cells, nor does it state when not to use it. The usage context is discernible but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false in annotations, the description carries the full burden and does so richly: formula normalization, #NAME? avoidance, workbook recalculation flagging, stale cached results, auto-backup, atomic verified save, and refusal 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but information-packed, with the core purpose front-loaded and each clause adding behavioral context. It is slightly long and run-on in the middle, but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter tool with no schema descriptions and no output schema, this is reasonably complete for the required parameters and safety behavior. However, the semantics of allow_loss and verify_com remain unexplained, leaving real invocation gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, so the description must compensate. It explains formula semantics and location (cell or range) well, and backup behavior is mentioned, but optional parameters such as allow_loss and verify_com are never given meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: writing a formula to a single cell or filling a range. It also defines the distinctive Excel copy semantics (relative references shift, absolute anchors stay), which clearly separates it from generic value-writing siblings like set_cell and write_range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly identifies the intended use case: any operation that writes formulas to cells/ranges. It adds contextual constraints (refuses while open in Excel, recalculate behavior via a companion tool), though it does not explicitly name sibling alternatives or state 'use set_cell for static values'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description aligns with and enriches that by adding substantial behavioral context: it works while the file is open, lists are capped with counts and a truncated flag, missing cached values read as blank to non-Excel consumers until recalculation, and it enumerates exactly what each of the five reports catches. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but dense and well-organized, front-loading the scope and core deliverable before enumerating the five reports and usage guidance. Every section adds value, though 'Read-only' appears at both the start and the end, a small redundancy that could be trimmed for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema, the description covers the main behaviors, report semantics, truncation behavior, scope selection, and safe usage context. It stops short of describing the exact response envelope or how the counts/truncated flag are structured per report, which would be useful for parsing results, but it is sufficient for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 partially does by describing the three scopes: a range, one sheet (sheet alone), or the whole workbook (no scope), which maps conceptually to location, sheet, and omitting both. However, it does not explicitly explain the path parameter or describe the expected format/shape of location (e.g., A1 notation or object form), leaving notable ambiguity for parameter construction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a read-only formula intelligence audit that produces a formula list plus five named safety reports, across three explicit scopes (range, sheet, workbook). It distinguishes itself from siblings like read_range, set_formula, and diagnose_workbook by focusing specifically on formula auditing and safety analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Use it before and after structural edits, and to judge whether cached values can be trusted.' It also notes it works while the file is open in Excel. However, it does not name alternatives or state when not to use this tool versus diagnose_workbook or read_range, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false in annotations, the description carries the full behavioral burden and does so excellently. It discloses that the destination is overwritten, the source is buffered for safe overlap, formula references shift like Excel, allow_loss gates hazardous workbooks, backups are auto-created, saving is atomic/verified, and the operation refuses while the workbook is open in Excel. This all aligns with readOnlyHint=false; 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and dense with high-value behavioral details; there is no filler. The minor grammatical break after the first sentence and the slightly crowded list of safety caveats keep it from being perfectly polished, but it remains appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating 9-parameter tool with no output schema, the description covers the most consequential behaviors comprehensively. However, it still leaves `sheet`, `verify_com`, and the backup-disable path under-specified, and it does not describe the return shape, so the definition is not fully complete on its own.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 22%, so the description compensates meaningfully by explaining the `what` values, `adjust_formulas` behavior, `allow_loss` gating, backup/atomic-save behavior, and source/dest as location objects that may name different sheets. It leaves some parameters like `sheet`, `verify_com`, and the exact semantics of `backup` only partially explained, so it is not fully compensating.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation ('Copy a source rectangle to a destination anchor') and explicitly lists the optional content values ('all', 'values', 'formulas', 'formats'). This makes it clearly distinct from sibling operations like move_range or write_range, even without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides strong situational context: overlapping paste is safe, formulas adjust unless disabled, hazardous workbooks require allow_loss, and the tool refuses while Excel has the file open. However, it never explicitly directs the agent to prefer this over siblings like move_range or clear_range, so the when-to-use guidance remains mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint annotation by explaining what the scan reads (worksheet extLst), what it does not catch (openpyxl drops from elsewhere caught later by its own warning), and what the side effects are. It explicitly states 'Read-only' and clarifies that hazards never block reads, making the tool's non-destructive behavior unambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured into what the scan produces, how to act on the verdict, and known limitations. Almost every sentence carries useful information, though the opening metaphor 'surfaced as a health readout' and the final 'Read-only' are somewhat redundant with the rest of the text. It is appropriate for the complexity, but slightly less concise than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of explaining return values and does so effectively: it lists the hazard categories, the would-lose verdict, the routing recommendation, and the integrity summary. It also covers exception cases (content without its own part) and limitations, giving an agent enough context to call the tool and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no additional meaning for the single required 'path' parameter. While 'path' is somewhat self-explanatory given the tool name and workbook focus, the description does not compensate for the low schema coverage as required, leaving format, location, or supported file type unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a round-trip hazard scan for workbooks, listing the specific types of fragile parts it checks (slicers, shapes, Power Query, VBA, etc.) and the verdicts it produces. It distinguishes itself from siblings like get_workbook_metadata or validate by centering on 'is this workbook safe to edit before mutating it.' The verb 'diagnose' plus the concrete hazard-scan scope makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it: 'before mutating' a workbook. It then gives actionable interpretation of the verdict: hazards never block reads, a would-lose verdict blocks mutating tools unless routed through Excel or allow_loss:true, and a clean verdict means file-based edits are safe. This is strong when-to-use and how-to-respond guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses formula-injection blocking, the 200,000-cell write ceiling refusal, hazardous-workbook refusal, auto-backup, atomic verified save, and refusal while open in Excel. This is far beyond the minimal readOnlyHint=false annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but each sentence carries operational value, from source selection to safety limits and concurrent open refusal. It is appropriately sized for a 13-parameter import tool and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers the main workflow and most edge cases comprehensively, which matters given the sparse annotations and absent output schema. It is not fully complete because the required path parameter is unexplained and success/error return behavior is not stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
It usefully explains source vs source_file, fmt, location, formulas, and allow_loss. However, the required 'path' parameter is never described, and header, delimiter, encoding, backup, sheet, and verify_com are left to inference despite 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Import CSV, TSV, or JSON into a sheet at an anchor.' This clearly differentiates the tool from write_range or export_range by identifying the input formats and the anchor concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear invocation guidance: use source for inline text or source_file for a path, fmt auto-detects from extension, and location defaults to A1. It doesn't explicitly name alternatives or exclusion conditions, 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the sparse readOnlyHint=false annotation. It discloses formula normalization, the lack of literal escapes for strings beginning with '=', recalculation flags, hazardous workbook refusal, backup rotation behavior, atomic verified saves with rollback, and refusal while the workbook is open in Excel. This is rich, non-obvious 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds necessary operational detail. The core purpose is front-loaded, followed by formula behavior, safety caveats, backup semantics, and the Excel lock refusal. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 7 parameters and no output schema, the description covers most critical behavior: formulas, backups, allow_loss, and workbook lock. It does not explain verify_com or return/verification outcomes, but the atomic-verified-save mention partially covers the verification concept. Overall it is strong but not fully exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14%, so the description carries heavy weight. It does add meaning for value ('=' means formula, otherwise literal), location, backup=false skip behavior, and allow_loss. However, it leaves verify_com unexplained and does not clarify path or sheet semantics, 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.
Purpose5/5Does 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 exact action, target resource, and scope. It clearly distinguishes this tool from range-oriented siblings like write_range or set_cells by emphasizing a single cell.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: writing a single cell, including formula/literal handling and safety conditions like allow_loss and Excel lock refusal. It does not explicitly name sibling alternatives or state 'use X instead for ranges,' but the single-cell framing is a solid implicit guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=false annotation, the description discloses many behavioral traits: rows are written back, formulas shift with Excel semantics, hidden rows stay pinned, uncalculated values produce warnings, hazardous workbooks require allow_loss, auto-backup is the undo mechanism, saving is atomic and verified, and the tool refuses while open in Excel. This is rich, non-obvious behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph with the core purpose front-loaded. Every sentence adds a distinct fact about operation, parameter semantics, safety, or edge-case behavior. There is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema and low schema coverage, this description is unusually complete: it covers key syntax, in-place mutation, formula behavior, filtered rows, safety flags, backup/undo, and file-lock refusal. The main gaps are the exact form of the required location parameter and the meaning/use of verify_com, plus the absence of any return/result contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, so the description must compensate for weak schema documentation. It does explain the central keys parameter well: list of {column, order}, header name/letter/1-based index, asc/desc, and tie-breaking. It also clarifies has_header and allow_loss. However, the required location parameter is only vaguely tied to 'range or table body' without stating accepted string/object forms, and sheet, path, and verify_com are not meaningfully explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Sort a range or table body by one or more keys, writing the rows back reordered.' This clearly distinguishes it from read, fetch, and other mutation tools. It also specifies the kind of target (range or table body) and the in-place reordering behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys when to use this tool: when rows need to be reordered in place by one or more keys. It also gives practical context such as hidden-row behavior and safety requirements. It does not explicitly name alternatives or state when not to use it, which prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, so the description carries the behavioral burden and exceeds it. It discloses error behavior (NOT_FOUND on no autofilter), return value (rows unhidden), loss protection semantics, auto-backup specifics (prev/anchor slots, atomic verified save), and a concurrency restriction (refuses while open in Excel). This is rich, non-obvious behavior an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries distinct information: core action, sheet selection, error policy, return value, safety guard, backup mechanism, and lock-out condition. The main purpose is front-loaded, followed by supporting details without fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema and six parameters, the description covers the critical operational aspects: error modes, safety gates, backup behavior, row-count return, and Excel lock. An agent can predict outcomes and avoid dangerous invocations from the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 location/sheet selection, allow_loss, and implies backup behavior with the auto-backup note, but it does not clarify the exact semantics of the backup boolean or verify_com parameter at all. Since two of six parameters remain ambiguous, the compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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') plus the concrete side effect ('unhide the rows it hid'). It explicitly frames itself as the reverse of set_filter, which distinguishes it from sibling filtering tools. No ambiguity remains about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: how the sheet is selected, what happens when no autofilter exists, and preconditions like hazardous workbook handling and Excel-open refusal. It names set_filter as the counterpart, implying when this tool is the appropriate choice, though it does not enumerate alternatives or contrast with sibling tools explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and the description reinforces this while adding substantial behavioral detail: it computes TRUE used range rather than stored dimensions, reports a round-trip hazard summary for openpyxl edits, and works while the file is open in Excel. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then provides a dense but well-organized list of returned metadata, and ends with concise usage context. Every sentence contributes meaningful information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating all major return categories and operational caveats (read-only, works while open, hazard summary). An agent has sufficient information to invoke the tool correctly and interpret its results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required 'path' parameter with 0% description coverage, so the description must compensate. It indirectly implies the parameter is the workbook path by describing the operation, and adds the important note that it works on files open in Excel. However, it never explicitly defines the path format or expected input, offering only partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Read a workbook's structure without opening it for edit' and enumerates the exact metadata returned (sheets, visibility, used range, dimensions, merged count, defined names, tables, active sheet, hazard summary). This clearly distinguishes it from cell-level tools 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description positions the tool as 'The orient-before-editing call' and notes it works read-only while the file is open in Excel, giving clear when-to-use context. It does not explicitly name sibling alternatives or when-not conditions, 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false in annotations, the description carries the burden and exceeds it. It discloses that delete and rename do not rewrite references (leading to #REF!), describes the auto-backup rotation and atomic verified save, the one-visible-sheet invariant, the allow_loss hazardous-workbook gate, and the refusal 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded with the action-to-parameter mapping, then adds high-value safety and backup caveats. Every sentence carries information, though the single-paragraph format and length could have been slightly improved with clearer separation of the action list and behavioral cautions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, multi-action mutation tool with no output schema and almost no annotation support, the description is impressively complete: it covers allowed actions, per-action parameters, refusal conditions, reference-breaking consequences, backup behavior, and loss protection. The only noticeable gap is the undefined verify_com parameter, and return values are not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description maps actions to their relevant parameters (e.g., add uses new_name and optional index; delete uses sheet; reorder uses sheet and a 0-based index). It also explains backup=false skips rotation and allow_loss gates hazardous workbooks. However, verify_com is not explained, and path is only implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear resource and function ('Manage the worksheet lifecycle') and immediately enumerates the specific actions: add, delete, rename, copy, reorder, hide, unhide. This makes it distinctly about worksheets rather than workbook-level tools like create_workbook or copy_workbook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: deleting/hiding the last visible sheet refuses, hazardous workbooks require allow_loss=true, and the tool refuses while the workbook is open in Excel. It also advises auditing references first. It does not explicitly name alternative sibling tools or state when-not-to-use, so it misses a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false, so the description carries the full burden. It discloses extensive behavior: reference rewriting across sheets, defined names, validations, conditional formats, tables, and merges; axis-specific handling of whole-column/row spans; #REF! results and their reporting; refusal conditions; per-kind rewrite counts; auto-backup rotation; atomic verified save with restoration; and undo semantics via the prev slot. This is exceptional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every sentence adds meaningful behavioral or parameter information. It is front-loaded with the core purpose and reference-rewriting guarantee, followed by parameter and safety details. It could be organized into bullet points for readability, but there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, minimal schema descriptions, no output schema, and only readOnlyHint=false, the description covers most of what an agent needs: exact actions, positional inputs, refusal conditions, return type, backup, and save verification. Gaps remain for the sheet and verify_com parameters, which are not mentioned at all, and the exact output structure is only summarized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, and the description compensates well: it explains action values, the various forms of at (row number, column letter, A1 cell, location object), count semantics, backup skipping, and allow_loss behavior. It does not explain sheet, verify_com, or path, but the key parameters are substantially enriched beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Insert or delete rows or columns at a position' and immediately adds the defining behavior 'REWRITE EVERY REFERENCE so the workbook stays coherent.' This clearly distinguishes it from sibling tools like apply_edits or set_dimensions by emphasizing the global reference-rewriting effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when the tool applies: inserting/deleting rows or columns with actions enumerated, and it explicitly states when the tool refuses (hazardous workbook without allow_loss, workbook open in Excel, insert pushing cells off grid). It does not explicitly name alternative tools or when-not conditions relative to siblings, but the operation-specific context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description explains how the values parameter shapes results (cached/formula/both), what labels are returned, and that formula cells without cached values are labelled 'absent' rather than blank. This is meaningful behavioral disclosure that the schema and annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded; the main verb and resource are first, followed by the most behaviorally significant parameter. The prose is compact given the number of location modes and values modes, though the phrase 'honest calc story' is a mild flourish.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-output-schema read tool with a complex location input, it covers the main invocation semantics: addressing modes, sheet default, values modes, and the large-range alternative. It does not spell out the exact return shape for 'both' or the path parameter, but it is sufficient for calling the tool correctly in common cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining values in detail, enumerating location object kinds, and describing sheet resolution. The path parameter is left unexplained, and exact location object shapes are not specified, so it is not a full substitute for schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a precise operation ('Read a cell or range') and scopes it via the location-object addressing modes. It also distinguishes itself by telling the agent to use query_range for large ranges, so it does not read as a generic read tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use the tool (for any addressed cell/range read) and explicitly routes large ranges to query_range. It also clarifies sheet fallback behavior. It could be stronger by stating exclusions against get_cells or export_range, but the core selection context is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the single readOnlyHint=false annotation, the description discloses substantial behavior: destructive scope per 'what' mode, non-removal of merges/conditional formats/validations/comments/hyperlinks, refusal for hazardous workbooks unless allow_loss is true, auto-backup rotation behavior, atomic verified save with restore-on-failure, and refusal while open in Excel. This is far above typical annotation coverage and contains 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense yet efficient: five sentences, each earning its place by covering a distinct facet—core operation, exclusions, location, safety/allow_loss, backup/verification, and Excel lock. It is front-loaded with the primary action and most important parameter, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with seven parameters and no output schema, the description covers the critical operational semantics well: what is cleared, what is not, destructive safeguards, backup, and lock behavior. Still, verify_com and sheet semantics are left to inference, and there is no mention of return behavior, leaving a minor completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It adds meaningful semantics for what ('contents', 'formats', 'all'), backup (skips rotation when false), allow_loss (hazardous workbook refusal), and location (addressed by a location object). However, path, sheet, and verify_com are not explained, so compensation is strong but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Clear a cell or range,' then defines the exact variants via the 'what' parameter. It also distinguishes the tool from sibling operations by explicitly stating what it does not remove (merges, conditional formats, validations, comments, hyperlinks), which prevents confusion with dedicated management tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool is appropriate and explicitly says that certain artifacts are not handled because 'those have their own manage tools.' It does not name specific sibling tools or contrast with write_range/set_cell, but the scope and exclusions are concrete enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint annotation by explaining exact side effects: existing files are untouched unless overwrite is true, overwrite first rotates the file into a .ks4xl-backups prev slot, and restore source='prev' recovers it. It also discloses validation constraints around sheet names and parent directory existence, giving the agent full awareness of consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: first the core creation action, then the sheet-name constraints and directory prerequisite, then overwrite/backup behavior and return value. There is no filler or repetition of schema defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, no output schema, and only readOnlyHint false as annotation, the description provides a complete picture: input semantics, defaults, validations, side effects, backup rotation, and return value. An agent has enough information to invoke it safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility for explaining parameters. It covers path, sheets (default to a single 'Sheet1', uniqueness, 31-character limit, apostrophe restriction), and overwrite (false leaves existing file untouched, true triggers backup rotation), providing meaning far beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a new .xlsx workbook at path with the given sheet names.' It also adds concrete details about defaults, overwrite behavior, and return values, which make the tool's purpose unmistakable and distinguish it from siblings like copy_workbook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for creating new workbooks, but it does not explicitly name alternatives or state when not to use it. There is no 'use X instead' guidance relative to sibling tools, so the usage context is inferable rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses several meaningful behaviors: exact/contains/regex matching with a timeout guard, look_in semantics, use of a formula cell's last cached value, paging via limit/offset, total match count reporting, and that it works while the file is open in Excel. No annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place, starting with the core purpose and then layering parameter behavior, paging, and read-only status. It uses a compact structure with no filler or repeated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 the operational essentials: scope, match modes, look_in behavior, formula-cache caveat, paging, total count, and safety. It leaves some gaps, such as the exact response shape beyond 'unambiguous address' and match_case/path details, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must carry parameter meaning, and it does for match, look_in, limit/offset, and scope. It also clarifies the query and workbook/sheet/range context. However, match_case is not described, and path is only implied by 'across a workbook', leaving a couple of parameters under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: searching cell values and/or formulas across a workbook, sheet, or range and returning every match with an unambiguous address. It also positions itself as the plural sibling of a single-target search selector, which helps distinguish it from more targeted lookup tools. This is a clear, actionable purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when multiple matches are needed and when searching across a workbook, sheet, or range. It references a single-target sibling, implying the alternative for one-match lookups, though it does not name that sibling or provide explicit when-not-to-use conditions. This is strong context but not a fully explicit routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=false annotation, the description discloses material behavioral traits: it is hazard-gated with allow_loss as an override, performs auto-backup, uses an atomic verified save, and refuses to run while the file is open in Excel. This substantially informs risk assessment during invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but highly efficient. Every sentence conveys needed information: the merge behavior, the format code representations, hazard handling, backup behavior, and operational constraints. It front-loads the core purpose and keeps supporting detail compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 11-parameter tool with no output schema and no per-parameter schema descriptions, this is a thorough definition. It covers formatting object structures, safety overrides, persistence behavior, and a concurrency constraint. The main gaps are the undocumented verify_com parameter and the absence of any guidance on return values or verification steps after the atomic save.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description takes on the documentation burden and does so well for most formatting parameters: it explains number_format, font, fill, border, alignment, and hex colors. It does not fully explain every parameter such as verify_com or the exact accepted shape of location, so the compensation is strong but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Apply formatting to a range'. It further distinguishes this tool from simple cell writes by explicitly stating it merges onto the existing style and preserves unspecified attributes, which makes its role among the large sibling set clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is the tool for range formatting with style merging, not for raw cell values or structural operations. It does not explicitly name alternatives or state when-not-to-use, so it falls short of a 5, but the scope is clear enough for an agent to avoid the most obvious mis-routings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint: false, so the description carries the behavioral burden. It discloses important side effects: display replaces the cell's value, removal preserves text and style, list surfaces formula links, hazardous workbooks require allow_loss, auto-backup occurs, and the tool refuses while open in Excel. These are significant behavioral details that go far beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause adds operational value. It front-loads the core action semantics and then covers side effects and safety behavior without repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no output schema, and minimal annotations, the description covers the main behaviors, side effects, and failure conditions well. It does not describe return values or output shape for list, nor resolve verify_com semantics, but the primary invocation paths are adequately specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 action values, location, target as URL or 'Sheet!A1', display, tooltip, allow_loss, and backup behavior. However, verify_com is not explained, and the location parameter's object form is not detailed, so some gaps remain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 the three actions: add, remove, and list. It specifies what each action does and adds distinguishing details like listing both real hyperlinks and HYPERLINK() formula links, so the tool is clearly differentiated from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use each action and explains the read-only nature of list. It also gives operational conditions for mutating actions, such as hazardous workbooks requiring allow_loss and refusal while the file is open in Excel. It does not explicitly name alternatives or exclusions, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals extensive behavioral details beyond the minimal readOnlyHint: false annotation: rewriting all reference types, overwriting destination cells, refusing hazardous workbooks without allow_loss, auto-backup, atomic verified save, and Excel lock refusal. There is no contradiction with the annotation; the mutation implied by 'move' aligns with readOnlyHint false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose first, then reference-rewriting behavior, then constraints and fallback, then safety and persistence details. No filler or redundant restatement of the name or input schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 minimal annotations, the description is impressively complete: it covers same-sheet scope, overwrite semantics, cross-sheet alternative, hazard handling, backup, save verification, and Excel lock refusal. The only notable omission is what the tool returns after a successful move, plus a couple of parameters (verify_com) remain ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29%, so the description must compensate for the missing parameter documentation. It does add context for allow_loss ('hazardous workbook refuses unless allow_loss is true') and backup ('Auto-backup'), and implies the sheet parameter via 'same sheet', but path, sheet, and verify_com remain largely unexplained. The description partially compensates but does not fully resolve the parameter semantics gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Move a rectangle to a new anchor on the same sheet' with Excel move semantics. It clearly distinguishes this from copy_range and clear_range by naming them as alternatives. The purpose is unambiguous and immediately scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says cross-sheet destinations are refused and instructs to use copy_range then clear_range instead. It also states hazard conditions, allow_loss behavior, and refusal while open in Excel, giving an agent concrete conditions for when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses cached-value reads, formula handling, comparison coercion rules, regex timeout guarding, Excel-compatible aggregate semantics, and treatment of hidden rows. This is substantial behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but organized into purpose, parameter tour, and semantics sections, with the core value proposition front-loaded. Some enum lists duplicate the schema, but they are presented compactly and are useful in prose; the density justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter query tool with no output schema, the description covers operations, edge cases, and behavioral semantics thoroughly. The main gap is the default return shape—it only states records=true emits objects—so an agent must infer the non-records response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, but the description compensates by explaining the where predicate shape and ops, column references, columns projection, order_by behavior, offset/limit, distinct, aggregate functions, group_by, records, and location/header defaults. It maps nearly every parameter to semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific verb set—filter, project, sort, paginate, and aggregate—attached to a range, and frames it as server-side subsetting so an agent avoids reading a whole sheet. This clearly distinguishes it from siblings like read_range and get_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the use case: when an agent needs only the rows and columns it needs rather than the whole sheet. It does not name alternative tools or explicit when-not-to-use conditions, so it misses the top tier, but the context is clear enough for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false provided, the description carries the full behavioral burden and does so thoroughly. It discloses dry-run semantics, one-batch atomic application, formula injection prevention, number coercion, hazardous-workbook refusal, auto-backup, and refusal while open in Excel. This far exceeds what annotations alone provide, 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded with the core purpose, and every clause adds relevant behavioral or safety detail. There is no filler or repetition of schema fields, making the length appropriate for a tool with 13 parameters and no schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutating tool with no output schema, sparse annotations, and zero parameter descriptions, this definition is nearly complete: it covers calling modes, safety constraints, return reporting, and failure conditions. The main gaps are the undocumented match_case and verify_com behaviors and the precise format accepted by the location parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates strongly by explaining match modes, look_in behavior, dry_run, formulas, allow_loss, backup, and replacement-value safety rules. However, match_case and verify_com are not explained, and the exact syntax of the 'location' range object is left unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb phrase, 'Find-and-replace across a workbook, sheet, or range,' which clearly identifies the operation and scope. This distinguishes it from siblings like find_cells (search-only) and set_cells (single-cell writes), so the agent can select the right tool 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool applies: bulk find-and-replace over a workbook, sheet, or range, with modes for matching, lookup targets, and dry runs. It does not explicitly name alternatives or state 'use X instead,' but the scope and behavior are specific enough to make the intended usage obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false in annotations, the description carries the full behavioral burden and does so excellently. It discloses atomicity, pre-resolution of all addresses, whole-batch refusal on any bad item, formula normalization, hazardous-workbook refusal unless allow_loss is true, auto-backup, atomic verified save, and refusal while open in Excel. This goes far 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose, then packs essential operational details into tight, information-dense sentences. Every sentence earns its place: atomicity, cell addressing rules, formula handling, hazard protection, backup 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex write operation with a single weak annotation and no output schema, the description covers the critical context: atomic semantics, failure behavior, formula handling, hazard gating, backup, and operating constraints. It does not describe the return value or success signal, and a few parameters remain unexplained, but the core behaviors needed for correct invocation are well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, so the description must compensate. It adds meaningful semantics for the cells parameter: lists of {cell, value}, A1 string or location object, 1,000-cell ceiling, and pre-resolution behavior. It also explains formula behavior for value strings and ties allow_loss to hazardous workbooks. However, path, sheet, and verify_com receive no explanatory treatment, so compensation is strong but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Write many individually addressed cells as ONE atomic batch.' It also explicitly names write_range as the contrast ('scatter complement'), and the emphasis on 'many' and 'atomic batch' distinguishes it from the sibling set_cell. An agent can identify this tool correctly without inspecting the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames when this tool is appropriate: writing many individually addressed cells in a single atomic scatter operation, and it names write_range as the alternative concept. It does not explicitly state when not to use it versus set_cell, but the context makes the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the minimal readOnlyHint=false annotation, the description fully discloses dangerous behaviors: only the top-left value survives, data-loss refusals require confirm_data_loss=true, overlapping merges refuse, hazardous workbooks require allow_loss, auto-backup occurs, saves are atomic, and the tool refuses 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds actionable operational detail: action modes, merge value semantics, safety flags, backup behavior, and lockout condition. It is front-loaded with the core purpose and contains no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, 8-parameter mutation tool with no output schema, the description covers the essential invocation decisions and failure modes, so an agent can call it reasonably safely. Minor gaps remain around verify_com and the exact return value of the list mode, but the critical behavioral context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters itself. It compensates well by explaining the action values, location semantics, confirm_data_loss, allow_loss, and backup behavior. However, verify_com and the exact output format for the list action are left to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 and resource with three distinct modes. It further differentiates this tool from sibling cell-manipulation tools by naming exact merge semantics and behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains when to use each action: merge, unmerge, or list, including the precise location requirements for unmerge. It also lists refusal conditions such as overlapping merges and Excel locking, but it does not explicitly contrast this tool with alternatives like write_range or set_cells.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint:false in annotations, the description carries the full burden and succeeds. It discloses auto-backup behavior, atomic verified save, refusal while the workbook is open in Excel, defaulting logic, and precise semantics for freeze, split, zoom, and tab color. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: purpose is front-loaded, and each clause adds necessary detail about parameter behavior, defaults, and side effects. No filler or redundant restating of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter mutating tool with no output schema, the description is remarkably complete: it covers the view-state semantics, default behavior, backup safety, atomic save, and the Excel-lock refusal. The only meaningful gaps are the undocumented allow_loss and verify_com parameters and the lack of explicit return/result information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 most parameters: freeze, split, gridlines, headings, zoom, selection, tab_color, and sheet defaults. However, path, allow_loss, and verify_com are not semantically explained, so it does not fully cover all 12 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair, 'Set sheet-view state in one call', and enumerates the exact aspects it controls: freeze, split, gridlines, headings, zoom, selection, and tab color. This clearly distinguishes it from siblings like get_grid_view or format_cells even without naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: a one-call batch for multiple view settings, with unset parameters keeping current values and sheet defaulting to the active sheet. It also notes the split/freeze exclusivity. It does not explicitly name alternative tools, but the context is sufficient for correct routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only provide readOnlyHint=false, so the description carries the burden of disclosing behavior. It details partial read-only behavior with no parameters, the staleness consequence of manual calc mode, auto-backup, atomic verified save, and refusal while the workbook is open in Excel. This goes well beyond the formal annotations and gives an agent concrete expectations of side effects and safeguards.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient; every clause adds operational knowledge. It is front-loaded with the main purpose, then gives mode behavior, a warning, safety guarantees, and an error condition, all in a compact form. There is no filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and minimal annotations, the description covers the essential operation semantics, read-only reporting mode, side effects, persistence guarantees, and the open-in-Excel refusal. Missing details are limited to advanced parameter meanings (allow_loss, verify_com) and any explicit return-value description, but the overall context is sufficiently rich for an agent to select and invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates substantially by naming the property parameters, listing calc_mode enum values, and explaining the meaning of iterative_calc, max_iter iterations, and max_change. It also ties backup to auto-backup behavior. However, some parameters like allow_loss and verify_com are not explained, and path is only implicit, so the coverage is strong but incomplete for a 15-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and clearly identifies the resource: core document properties (title, author, subject, keywords, category, comments) and calc settings. It lists exact property families and calc settings, and distinguishes this workbook-level tool from siblings like set_cell or set_formula by focusing on metadata and calculation configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when needing to change workbook properties or calc settings, and notes the read-only reporting mode when no parameters are passed. However, it does not explicitly name alternative tools or state when not to use it, relying on the purpose statement rather than direct exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=false annotation, the description discloses substantial behavioral details: ragged rows are refused, null clears cells, formulas are normalized and trigger recalculation, grid limits and a 200,000-cell ceiling apply, hazardous workbooks require allow_loss, auto-backup and atomic verified save occur, and the tool refuses while open in Excel. This is far beyond the annotation and gives agents accurate expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet dense, front-loading the core purpose before detailing data constraints, limits, safety, and refusal conditions. Each sentence adds a distinct piece of behavioral information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is comprehensive for a mutating tool with no output schema: it covers the write semantics, data shape, safety, backup, and refusal cases. Minor gaps remain around the exact form of location and the sheet/verify_com parameters, but the core invocation requirements are clearly sufficient for an agent to proceed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 14%, the description compensates for the most complex parameters: data must be rectangular and ragged rows refuse, null clears, location anchors the block at its top-left cell, and allow_loss gates hazardous workbooks. It does not add semantics for path, sheet, or verify_com, but the critical failure-prone parameters are well covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Write a 2D block of values and formulas anchored at the location's top-left cell.' It specifies the block write scope and differentiates itself from single-cell siblings like set_cell by emphasizing the 2D block and 'content outside the block is never touched.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes when this tool is appropriate: for writing rectangular blocks of values/formulas anchored at a cell, with explicit constraints such as refusing ragged rows and refusing in hazardous workbooks unless allow_loss is true. It does not explicitly name sibling alternatives (e.g., set_cell for single cells), so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false in annotations, the description carries the behavioral burden and does so thoroughly. It discloses pre-validation before any write, single-backup and single-save semantics, verify-after-write with restore, formula recalculation, the 200,000-cell ceiling, hazardous-workbook refusal via allow_loss, Excel-lock refusal, and the returned counts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place. It front-loads the purpose and op list, then layers atomicity, safety, limits, and return values in a logical order. There is no filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, sparse annotations, and no output schema, the description is remarkably complete. It tells the agent what happens on partial failure, how backups and verification work, what constraints apply, and what the return value reports, leaving no critical calling decision unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, and the description compensates substantially by explaining the nested edits structure, each op's payload, location semantics (including stale-checked get_grid_view anchors), and allow_loss behavior. It does not explicitly describe the path, backup, or verify_com parameters, but the core complex parameter is well covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb ('apply'), a specific resource ('edits'), and a defining characteristic ('ONE atomic batch'). It also enumerates the four op types, making the tool's scope unmistakable and clearly distinct from single-edit siblings like set_cell, write_range, and clear_range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'many addressed edits as ONE atomic batch' clearly indicates when to use this tool: when multiple edits must commit together. It does not explicitly name alternatives such as set_cells or write_range or state when not to use it, so it stops short of a full when/when-not routing guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false in annotations, the description carries the behavioral burden and excels: it explains the byte-for-byte guarantee, the overwrite flow with backup rotation into .ks4xl-backups, the restore path via source='prev', and the return value. This gives the agent a precise model of side effects and safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense yet efficient. Each sentence earns its place: the preservation guarantee, the overwrite/backup behavior, the return value, and the recommended use case. It is front-loaded with the core purpose and avoids filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description states the return value ('Returns the destination path'). It also covers the key edge case (overwrite) and the typical use scenario. For a 3-parameter copy tool, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does: 'from src to dst' clarifies both parameters as source and destination paths, and overwrite semantics are fully described including backup rotation and restore behavior. The only minor gap is not explicitly stating that src/dst are file paths, though 'destination path' appears in the return value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 workbook file byte-for-byte from src to dst.' It further distinguishes itself from sibling tools by emphasizing whole-file preservation and the branch-before-edits use case, which clearly separates it from copy_range or create_workbook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool 'to branch a working copy before a risky batch of edits,' providing clear context. It does not explicitly name alternatives or state when not to use it, but the 'byte-for-byte whole workbook' framing strongly implies the boundary against range-level or create operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses pagination caps (200 and 100), truncated flags, the U+0192 marker for formulas with no cached value, anchor-token behavior with STALE_ANCHOR, and compatibility with files open in Excel. These are meaningful behavioral details not present in 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded: the first sentence states the purpose and output shape, and subsequent sentences expand only on behaviors an agent must know. There is no filler and no repetition of structured schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only view tool with no output schema, the description explains the output shape, pagination, value modes, markers, anchor semantics, and a natural follow-up tool. An agent has enough information to invoke it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the burden and explains location defaulting to the used range, values='cached' versus 'formula' behavior, and max_rows/max_cols caps. However, path and sheet parameters are left implicit, so it does not fully compensate for the absence of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation—a compact grid-view projection of a sheet or range—and enumerates exactly what is returned: used range, markdown table with A1 addressing, formula and merged-cell markers, dimensions, and hazard summary. It also contrasts itself with a per-cell JSON dump, making its niche clear among read-oriented siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It is clearly positioned as the way to 'see the grid without a per-cell JSON dump,' and it explicitly warns that it is read-only, which rules out edit use cases. The pairing instruction with apply_edits gives a concrete alternative workflow, though it does not explicitly name other read tools to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true is independently reinforced by 'Read-only; nothing is written,' and the description adds substantial behavior beyond the annotation: case-insensitive matching, the cached/formula/both semantics ('the honest calc story'), and the disclosure that returned rows exclude the header and totals row. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
One dense paragraph that front-loads the core purpose and packs each clause with distinct information: parameter semantics, return shape, sibling routing, and safety. Every sentence earns its place; the quirky parenthetical 'the honest calc story' and the trailing 'Read-only' reaffirmation are minor stylistic noise rather than waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and meets it (table ref, column names, rows, header/totals exclusions), and the low schema coverage is compensated in prose. Remaining gaps are error behavior for missing tables and the precise shape of the table ref/location identifier.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 20% (only columns has a schema description), but the description decodes values ('cached | formula | both'), columns ('projects a subset'), records ('row objects keyed by column name'), and name (case-insensitive). Only the required path parameter is left implicit, inferable from the '{table} location' routing remark.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Read a table's data by its name') and adds a distinguishing qualifier (case-insensitive). The return-shape sentence — 'table ref, column names, data rows without the header or totals row' — makes it unambiguous that this reads whole table data, separating it from location-based siblings like read_range, get_grid_view, and get_cells.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes big-table filtering/paging to query_range with a {table} location, and advanced table ops (columns, totals, resize, banding) to manage_table. The by-name scoping implicitly distinguishes it from location-based reads, giving an agent clear routing conditions without opening sibling schemas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses idempotency, the result content (disabled packs, tokens removed, remaining surface), the non-dead-end behavior when calling a disabled tool, and the refusal under KS4XL_PACK_POLICY=locked. This goes well beyond the sparse readOnlyHint=false annotation and fully describes what will happen.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense sentences with no wasted words. The primary action and effect are front-loaded, and the cross-reference to enable_tools keeps the description lean while preserving necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the minimal input schema, no output schema, and sparse annotations, the description covers the action, parameter vocabulary, return value, failure modes, and idempotency. The full pack menu is intentionally delegated to enable_tools, which is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 0% and no enum values, the description must compensate for the 'packs' parameter. It does so by saying packs takes the same names as enable_tools or ['everything'], giving the agent concrete value guidance. This exceeds the baseline for undocumented params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Disable previously enabled tool packs for this session and reclaim their context.' It clearly distinguishes this from enable_tools and other siblings by focusing on disabling and context reclamation rather than any other operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to specify packs via enable_tools' naming convention and the 'everything' special value, and it notes the locked-policy refusal condition. It doesn't explicitly contrast with alternatives because it is the only disabling tool, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description explicitly states 'Pure guidance: reads nothing, changes nothing', which fully communicates the tool's side-effect profile. It also discloses that COM-tier tools that have not shipped are marked as forthcoming rather than pretended present, adding honesty about content reliability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, invocation modes, task values, pack behavior, status honesty, and safety. The structure front-loads the core purpose and then clearly separates list mode from recipe mode, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only guidance tool with one optional parameter and no output schema, the description fully covers what the agent receives in each mode, which task names are valid, and that the tool has no side effects. Nothing essential is missing for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions, but the description fully compensates by explaining the null/default behavior, listing valid task names, and specifying what happens with each invocation. An agent can correctly pass the task parameter without needing extra schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool returns recommended tool sequences for common multi-step spreadsheet tasks, and it distinguishes between listing available tasks and retrieving a step-by-step recipe. It also separates this tool from sibling spreadsheet operations by labeling it 'Pure guidance', so an agent can understand exactly what it is without inspecting other definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit invocation patterns: call with no task to list available tasks, or call with task='<name>' for a recipe. It also enumerates valid task names, which strongly guides an agent on when and how to use the tool. It does not explicitly state when not to use it, but the call patterns and purpose make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=false annotation, the description discloses significant behavioral traits: autofit_columns is a best-effort approximation and true autofit requires Excel via the COM pack, hazardous workbooks refuse unless allow_loss is true, auto-backup to .ks4xl-backups occurs, saves are atomic and verified, and the tool refuses while the workbook is open in Excel. This is exactly the kind of value that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well organized: the main operation is front-loaded, then parameter units and grouping semantics are explained, and finally safety/backup behavior is stated. Every sentence adds operational detail; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 15-parameter mutation tool with no output schema, the description covers the essential operational context: parameter semantics, grouping behavior, autofit limitations, safety safeguards, backup behavior, and Excel lock refusal. It also names get_workbook_metadata as the companion for reading outline state, which closes the main contextual loop an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 47% schema description coverage, the description compensates well: column_widths are in Excel character units, row_heights are in points, grouping spans are {start, end, level 1-7, collapsed}, outline_summary determines which side the total sits on, and ungroup clears a span's level and unhides it. These details map directly to the schema parameters and add meaning that the bare schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource scope: 'Set column widths and row heights, hide rows or columns, group them into collapsible outline levels, and service an autofit request.' It clearly identifies the tool's domain as workbook layout/dimensions, which distinguishes it from sibling tools focused on cell values or content formatting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when this tool applies, including sizing, hiding, grouping, outline summary, and autofit. It explicitly points to get_workbook_metadata for reading the current outline, which helps an agent know where to fetch related state. It does not enumerate negative cases or direct the agent to alternative tools for content formatting, but the usage context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true is reinforced and expanded: 'Read-only, always' plus 'passed=false means findings, not a failed call.' It also discloses important behavior like working while the file is open and external links being reported but not repaired, which 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries necessary information: the main purpose is front-loaded, the check list is compactly parenthesized, and the return semantics and read-only behavior are stated without filler. The length is justified by the absence of enums in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and minimal input schema, the description provides everything needed: parameter values, default behavior, return shape, the meaning of passed=false, and operating constraints. There are no significant gaps for an agent selecting or invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates. It explains the required path parameter implicitly, lists every valid check name with a one-line meaning, and states the default check set. Without this, an agent would have no idea what values 'checks' accepts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Run read-only correctness checks and return one report.' It then enumerates exactly which checks are included, which distinguishes it from sibling editing/diagnostic tools and makes 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly frames when to use the tool: for read-only correctness validation, and it explicitly says 'repairs live in the editing tools,' so an agent knows not to use this for fixes. It does not name a specific sibling alternative, but the context is clear enough that this is the validation entry point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint, but the description adds substantial behavioral detail: the 1,000-cell ceiling, the values options (cached, formula, both), the honest result labels (cached, absent, formula, value), and the guarantee that formulas without cached values are not misrepresented as blank. This is far beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but well organized: the core purpose is front-loaded, and every clause contributes either scope, limits, return semantics, or runtime context. There is no filler or repetition of annotation data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only scatter read with no output schema, the description covers the operation's scope, limits, alternative, return labeling behavior, and runtime conditions. An agent has enough context to select and invoke the tool correctly without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds real semantic value for the main parameters: cells must resolve to exactly one cell and has a 1,000-cell ceiling, while values accepts cached, formula, or both. However, the path and sheet parameters are not described, leaving a minor gap given the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific operation: reading many individually addressed cells in one call. It names the resource type (cells), the addressing mechanism (A1 strings or location objects), and explicitly positions itself as the scatter complement to read_range, distinguishing it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly contrasts with read_range ('scatter complement to the rectangular read_range'), giving the agent a clear rule for when to choose this tool over a sibling. It also adds context that the tool is read-only and works while the file is open in Excel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: it is a read-only orientation call, touches no file, requires no workbook, reports a count of sandbox roots rather than the paths themselves, and gives an approximate token bill. This is rich transparency that helps the agent set expectations and avoid safety missteps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-organized sentences front-load the purpose and enumerate details without redundancy. The explanatory clause about config 'carrying install settings a user otherwise cannot confirm arrived' earns its place by clarifying why those fields matter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-input, read-only server-info tool, the description is complete: it covers safety, operational use, and the full set of reported information. No output schema exists, so the explicit list of return fields is essential and present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter semantics are not applicable; the schema coverage is trivially 100%. The description appropriately focuses on the output payload instead, which is exactly what an agent needs to know for an inputless call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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.' It enumerates exactly what is reported (version, tool surface, packs, platform, Python, config), and the server-level scope clearly distinguishes it from all workbook- and range-focused siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this tool 'to confirm the server is up and see which packs are loaded,' and it provides a when-not condition: it 'needs no workbook and touches no file,' so an agent knows not to route workbook-scoped calls here. This is actionable selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=false annotation, the description discloses idempotency, token reporting, policy-based refusal, and that the 'com' pack operates on a private hidden Excel instance and never touches the user's open session. These are valuable behavioral traits not inferable from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: the opening sentence states purpose, the middle covers behavior and alternatives, and the task map plus pack definitions are essential for parameter selection. The structure is front-loaded and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only a minimally typed schema, no enums, no output schema, and one required parameter, the description carries the full burden and meets it: it defines all valid inputs, explains behavior, lists prerequisites, and provides enough detail for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only says 'packs' is an array of strings with 0% documentation coverage. The description fully compensates by listing the exact accepted pack names ('design', 'io', 'com'), the special value 'everything', and detailed contents for each pack, making it clear what values to pass.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Enable optional tool packs mid-session.' It clearly distinguishes itself from its inverse sibling disable_tools and explains the pack model, so an agent can immediately understand what the tool accomplishes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use it ('sessions start lite' and mid-session enablement), names the reversing alternative (disable_tools), provides a task-to-pack mapping for choosing the right pack, and notes the locked-policy refusal condition. This gives the agent clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false, but the description discloses critical behavioral details beyond that: restore rotates current content into prev first so it is undoable, payloads are validated before atomic replace, Excel-open files refuse, dry_run defaults to TRUE and only reports, and snapshots are exempt from rotation and purge. It also candidly states the 'LIMIT' of prev coverage. This is excellent transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Although the description is dense, every sentence carries meaningful information: storage location, rotation slots, action semantics, safety behavior, default dry_run, limits, and routing to recovery. It is front-loaded with the core concept before diving into actions, and the 'LIMIT, stated loudly' section is a deliberate and effective structure for emphasizing the tool's coverage gap.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, no output schema, no enums, and 0% schema coverage, this description is remarkably complete. It explains all actions, parameters, defaults, safety mechanisms, edge cases (orphans, Excel-open files), the rotation limit, and the correct sibling for recovery. Nothing essential for an agent to select and invoke this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters, and it does. It maps path/directory for list, source for restore, scope for purge, dry_run, label, and dest_dir for snapshot. Each parameter's role is described in context, compensating fully for the empty schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Manage the automatic backups in the hidden .ks4xl-backups folder next to each mutated workbook.' It enumerates the four actions (list, restore, purge, snapshot) with concrete effects, and distinguishes itself from the recovery sibling by pointing to get_workflows task='recover-workbook' for lost/corrupt files. This is far more than a vague or tautological statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context for each action, including scope, source, dry_run behavior, and snapshot permanence. It also names the alternative tool and the exact condition for using it: 'Lost or corrupt file? get_workflows task=\"recover-workbook\" is the walkthrough.' This directly guides an agent on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md: