Skip to main content
Glama
Sign In
SheetForge MCP

SheetForge MCP

by iHeldan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

inspect_workbook_contract

Read-only

Validate a workbook’s native table against a declared contract before recipe preview or commit, checking headers, field types, grain, keys, and filters without inferring business meaning.

Instructions

Read-only full bounded native-table contract check; never infer business meaning.

Contract v1 requires version=1, name, source={table_name, optional sheet_name},
row_grain (a declaration), key_fields (logical names), and fields=[{name,
headers: [approved exact alternatives], type: string|number|integer|boolean,
nullable?: false, meaning?, allowed_values?, min?, max?}]. Optional min_rows
defaults to 1; filters use logical field names and Recipe predicates. Missing
or multiple matching headers are unresolved, never automatically selected.
Checks all source rows BEFORE filtering, excluding native totals. Declared
meanings are not verified facts. No coercion, formulas, dates, joins or code.
Limits: 32KB JSON, 32 fields, 8 aliases/field, 8 key fields, 20 filters,
50000 table cells/64 columns; sample_limit 1-5 affects row examples only.
Pass the same contract as workbook_contract to run_workbook_recipe to enforce
it in preview/commit; this inspection alone does not guard other tools.
Recovery: omit sample_limit for default 3 (never use Recipe's 10 here).
recipe_input_fields lists the exact logical names to use in Recipe inputs;
bindings values are physical headers for inspection, not Recipe field names.
For {name: "net", headers: ["NetSales"]}, use metrics.field="net", not
"NetSales". For {name: "currency", headers: ["Currency"]}, use
group_by=["currency"]. Metric as="Revenue" is an output label, not remapped.
Follow next_action: unresolved/violated requires an owner decision, not a
changed contract or filtered-out violation. Reuse the supplied filepath;
do not construct an absolute path by prefixing the client working directory.

Input Schema

NameRequiredDescriptionDefault
contractYes
filepathYesReuse supplied server path; NEVER prepend client cwd. Rooted: relative OK; unrooted stdio: absolute, ask if missing.
sample_limitNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.14.0

TDQS

A4.3/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true; the description adds substantial behavior beyond that: checks all source rows BEFORE filtering, excludes native totals, no coercion/formulas/dates/joins/code, missing or multiple header matches are left unresolved rather than auto-selected, declared meanings are not verified, and sample_limit affects only row examples. It also spells out hard limits (32KB JSON, 32 fields, 8 aliases/field, 8 key fields, 20 filters, 50000 cells/64 columns) and the recovery behavior for sample_limit.

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

Conciseness3/5

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

Nearly every sentence carries non-redundant information, but the whole thing is delivered as one unbroken run-on block that mixes contract schema, limits, naming rules, and recovery advice with no headings or front-loaded structure. An agent must parse ~250 words linearly to find the contract spec it needs first.

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?

With no output schema and a nested free-form contract object, the description does the heavy lifting: limits, resolution semantics, next_action handling, and filepath rules are all present. The main residual gap is the return payload itself — next_action, recipe_input_fields, and bindings are referenced but their structure and values are never described, so the agent learns how to call it far better than how to read the result.

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

Parameters5/5

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

Schema coverage is only 33% and the contract parameter is an undescribed free-form object, so the description has to carry the load — and it does, enumerating the contract v1 shape: version=1, name, source.table_name/sheet_name, row_grain, key_fields, fields with headers/type/nullable/meaning/allowed_values/min/max, plus min_rows defaulting to 1 and logical-name filter syntax. It also disambiguates sample_limit (default 3 here vs Recipe's 10) and clarifies the logical-vs-physical naming distinction with concrete examples (metrics.field="net" not "NetSales").

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

Purpose4/5

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

States a specific verb+resource+scope: a read-only, bounded contract check over a native Excel table, with an explicit constraint ('never infer business meaning'). It distinguishes itself from the enforcement path by naming run_workbook_recipe and clarifying that inspection alone does not guard other tools. It does not, however, differentiate itself from adjacent read/diagnostic siblings such as describe_dataset, profile_workbook, or read_excel_as_table.

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

Usage Guidelines4/5

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

Gives real routing guidance: pass this contract as workbook_contract to run_workbook_recipe to enforce it in preview/commit, and follow next_action on unresolved/violated rather than silently changing the contract or filtering violations out. It also tells the agent to reuse the supplied filepath instead of prefixing cwd. No explicit exclusion against other inspection siblings, so not a 5.

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