Skip to main content
Glama
KitchenSink4AI

io.github.nometalalchemist/kitchensink4xl

by KitchenSink4AI
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

diagnose_workbook

Read-only

Detect hazards in an Excel workbook before editing: reveals fragile elements that file-based edits would drop and recommends whether to edit via Excel or accept the loss.

Instructions

The round-trip hazard scan surfaced as a health readout: which fragile parts the workbook holds (slicers, shapes, embedded objects, Power Query, VBA, and the rest), whether a file-based openpyxl edit would drop any of them, the routing recommendation for a surgical versus a structural edit, and a light integrity summary (sheet counts, formula-cell count, keep_vba). This is how you check a workbook is safe to edit before mutating it.

What to do with the verdict: hazards never block reads; a would-lose verdict means every mutating tool will refuse unless you route through Excel (com pack) or pass allow_loss:true (an explicit, backed-up acceptance of the loss). A clean verdict means file-based edits are round-trip safe. Content with no part of its own is covered too: the scan reads each worksheet's extLst, so x14 conditional formats (data bars, icon sets), sparkline groups and slicer lists come back as a would-lose verdict like any other drop-risk hazard. Limit: the extLst walk looks at the worksheet's top level, and an extension openpyxl drops from anywhere else is caught at save time by openpyxl's own load warning rather than here. Read-only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.0
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "type": "object"
-}New value: +null
  2. First observedv1.0.0

TDQS

A4.4/5.0
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/5

Is 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/5

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

There is no output schema, so the description 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/5

Does 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/5

Does 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/5

Does 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.

Install Server

Other Tools