Skip to main content
Glama
KitchenSink4AI

io.github.nometalalchemist/kitchensink4xl

by KitchenSink4AI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Diagnose Workbook

diagnose_workbook
Read-only

Check an Excel workbook for edit hazards before modifying it. Identifies fragile components, predicts data loss from file-based edits, and recommends routing to preserve content.

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

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

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

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

Conciseness4/5

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

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

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

Completeness4/5

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

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

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

Parameters3/5

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

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

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

Purpose5/5

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

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

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

Usage Guidelines5/5

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

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

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

Deploy Server

Other Tools