GridCraft MCP Server

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent already knows this writes files without being flagged destructive. The description adds that inputs may be one file, a list, or a folder, but says nothing about overwrite semantics, whether output files are preserved by default, or side effects on the source workbook.

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

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

A single sentence that goes inputs → outputs → option semantics, with nothing wasted. The nested parentheticals make it dense but every clause carries information an agent needs.

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

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

For a 9-parameter, mostly-optional conversion tool with no output schema, the description covers the essentials an agent needs to invoke it: accepted inputs, target formats, and the one non-obvious output-shaping flag. Remaining gaps (suffix, output pathing, overwrite) are defaults the schema surfaces.

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

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

At 56% schema coverage, several parameters (suffix, output_path, output_dir, overwrite) are undocumented in both places. The description does add real meaning for the plurality of the input ('one, a list or a folder' maps to input_path/input_paths/input_dir) and for the all_sheets output naming, but only partially compensates for the coverage gap.

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

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

States a specific verb (convert) and resource (workbooks) and enumerates both the accepted input formats and the producible output formats, which no sibling (create/edit/read_workbook) does. An agent can pick this tool over its siblings without opening any schema.

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

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

The format matrix effectively delimits when this tool applies and the parenthetical explains the all_sheets decision point for csv/tsv/pdf. It stops short of explicit alternatives or when-not-to-use guidance (e.g. use read_workbook to merely inspect), so it is clear context rather than full routing.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, and the description is consistent with them by describing a write operation that produces files. It adds behavioral value beyond the annotations by disclosing that the tool returns the computed values of the first rows of every sheet and any formula errors as a verification mechanism, though it says nothing about overwrite semantics or size limits.

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

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

Front-loaded with the action and capped at three sentences, and the feature catalogue genuinely signals what can be accomplished in a single call rather than via follow-up edits. The middle sentence is a long comma-spliced list of capabilities, which is dense but still earns its place for a 12-parameter tool.

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

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

With no output schema and 12 parameters at 75% schema coverage, the description covers output formats, sample starting points and return values (computed first rows plus formula errors), which is enough to call the tool correctly. It omits guidance on how this differs from the edit/convert siblings, which is the main remaining gap.

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

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

Schema description coverage is 75%, so the schema already documents most parameters including formats, sample enums, output_dir and overwrite. The description paraphrases the format options and sample names but adds no syntax or format details beyond what the schema provides (e.g. how output_path must match the first format is only in the schema), so a baseline 3 is appropriate.

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

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

States a specific verb+resource ("Build an Excel workbook with GridCraft") and clarifies it is a creation tool that can also start from a sample. Sibling differentiation from edit_workbook/read_workbook is only implied by the word "build"; the description never names those alternatives.

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

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

There is no when-to-use or when-not-to-use guidance relative to edit_workbook, convert_workbook or open_in_gridcraft, which are all plausible alternatives for an agent holding an existing file. The only contextual hint is optional ("Or start from a sample"), leaving routing entirely to inference.

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

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

Annotations already declare destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: inputs may be one file, a list, or a folder, and results are written as new copies while originals are only read. It omits the default output suffix/overwrite semantics and any limit or failure behavior.

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

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

Two sentences, front-loaded with the verb and resource, and the long capability enumeration earns its length by covering a very broad feature surface. The chained list is dense but not padded or repetitive.

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

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

For a 22-parameter tool with no output schema and only modest annotations, the description covers formats, input multiplicity and the copy-not-mutate behavior, which are the essentials. It still leaves the agent guessing about output paths/naming defaults, how conflicting operations in one call are ordered, and coverage of the several parameters the schema leaves undocumented.

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

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

Schema description coverage is only 27%, so the schema cannot carry the burden for 22 parameters. The description partially compensates by naming operation categories that map onto the parameter set (write/replace/rows_columns/sort/remove_duplicates/add_sheets/tables/charts/pivots/formats/conditional_formats), but it gives no syntax or per-parameter semantics, and key parameters such as input_path vs input_paths vs input_dir vs output_dir are never disambiguated.

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

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

States a concrete verb pair (open and change) plus the resource (workbooks) and enumerates the exact mutation families supported (write, replace, rows/columns, sort, dedupe, sheets, formats, tables, charts, pivots). That enumeration makes it unmistakably distinct from its siblings create_workbook, read_workbook and convert_workbook without needing to name them.

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

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

Usage is only implied: the operation list tells an agent this is the tool for modifying spreadsheets, and 'saved as new copies' hints that in-place edits are not a concern. Nothing states when to prefer this over convert_workbook or run_gridcraft_commands, and no preconditions or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world scope, so the safety profile is fully covered without the description. The description adds modest context by revealing that it probes live state ('whether the app is running / listening for control'), but says nothing about cost, latency, or failure modes when no installation exists.

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

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

A single compact sentence, front-loaded with the verb and resource, followed by a colon-separated inventory of what is checked. The list is dense but every item earns its place given the absence of an output schema; nothing is padded.

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

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

With no output schema, the description usefully compensates by enumerating the categories of information returned (platform, version, executables, commands, functions, formats, running state). Zero parameters and full annotation coverage mean little else is required; only the shape/format of the returned data is left unstated.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No parameter text is needed or missing.

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

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

The description gives a specific verb ('Check') and resource ('the GridCraft installation') and enumerates the exact facets inspected: platform, executables, version, engine commands, worksheet functions, formats, running/listening state. This clearly separates it from siblings like get_workbook_info or list_gridcraft_catalog, though it never names those alternatives explicitly.

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

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

Use is only implied: the enumerated diagnostic output suggests 'run this to see whether GridCraft is installed and running before invoking open_in_gridcraft or run_gridcraft_commands,' but the description never states when to use it, when not to, or what alternative to pick instead.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful output-content context (used ranges, tables, charts, error formulas), but says nothing about cost, permissions, or failure modes on a bad path.

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

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

A single dense sentence with no filler; the most concrete inventory items are front-loaded. It is slightly list-heavy and would benefit from a leading verb, but nothing is wasted.

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

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

With no output schema, the description carries the return-value burden and does a reasonable job enumerating what comes back. However, it omits how the workbook is identified (input_path semantics), the preview row cap, and any error behavior, leaving gaps for a 2-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry both parameters. It partially compensates by implying preview rows ('the first rows of each sheet'), but never ties this to the preview_rows parameter, its default of 10, or its max of 100, and input_path is entirely unexplained.

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

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

The description is a noun-phrase inventory of returned contents rather than a verb+resource statement, so it never states plainly that this tool retrieves workbook metadata/contents. It conveys the resource scope well enough, but nothing distinguishes it from the sibling read_workbook, which an agent must guess between.

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

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

There is no when-to-use guidance, no prerequisite (e.g., the workbook must be open or on disk), and no mention of read_workbook or any other sibling as an alternative. The agent is left to infer the choice entirely.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so a 3 is the appropriate ceiling. The description usefully reveals what each entry carries (commands include parameters and ribbon place; functions include signature and description), which helps an agent know what it gets back, but says nothing about result size, filtering behavior, or empty-match handling.

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

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

A single front-loaded sentence that packs all five catalog categories without filler. The nested parentheticals make it dense, but nothing is wasted.

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

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

For a read-only, two-parameter catalog tool with no output schema, the description covers every kind an agent can request and what each contains, and the annotations carry the safety profile. Nothing essential for invoking it correctly is missing.

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

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

Schema description coverage is 50%: 'kind' has no description (only an enum) and 'filter' is documented in the schema. The description compensates partially by explaining what each 'kind' value yields, but it never clarifies the 'kind' selector itself or how 'filter' interacts with it, so it adds only modest meaning beyond the schema.

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

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

The description enumerates exactly what the catalog covers (commands, functions, charts, samples, formats) and ties 'commands' to the sibling run_gridcraft_commands, which cleanly separates it from the execution tool. It is a bit indirect — 'What GridCraft can do' never says 'list' or 'retrieve' — but the resource and scope are unambiguous.

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

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

Usage is only implied: pointing at run_gridcraft_commands for commands suggests this is the discovery step before execution, but there is no explicit when-to-use or when-not-to-use statement, and no guidance that 'kind' selects the subset returned. The relationship to the sibling is the only routing signal.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely non-obvious behavior: with control=true the app opens a loopback-only control channel, which is both a network-surface disclosure and a prerequisite for another tool. That is real context beyond the structured fields.

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

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

Two sentences, zero waste, front-loaded with the core action before the control-channel detail. Every clause earns its place.

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

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

For a zero-required-param launch tool with no output schema and no nested objects, the description covers the action, the interactive purpose, and the one undocumented flag's side effect. The sample parameter's behavior is left to the schema, which is acceptable but keeps this from a 5.

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

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

Schema coverage is 67%; paths and sample are documented in the schema, but the control boolean has no schema description. The description compensates by explaining exactly what control=true does and why it matters (enabling live command driving), which is the highest-value gap to fill.

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

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

States a specific verb and resource (open workbooks in the GridCraft desktop app) and clarifies the intent ('to keep working by hand'), which distinguishes it from the read/edit/convert siblings that operate without launching the app. It stops short of naming a sibling alternative for headless use, but the resource and mode are unambiguous.

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

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

Gives a clear use context (interactive work in the desktop app) and a concrete condition for the control flag that gates a downstream tool (run_gridcraft_commands live=true). It does not state when NOT to use this versus e.g. read_workbook, but the interactive-vs-programmatic split is implied well enough to route correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description reinforces this with 'without changing anything' and adds that formula evaluation happens against the workbook without persisting, plus the supported format set and evaluation examples, which is useful context 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.

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

A single dense sentence with the read action front-loaded and examples parenthesized at the end. The format list is long but earns its place by scoping the tool; no filler text.

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

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

With no output schema, the description should say something about the return shape (e.g. how a range or evaluated formula result comes back), and it does not. For a 6-parameter tool it also omits max_rows truncation semantics, so it is adequate but leaves real gaps.

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

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

Schema coverage is 67% and the description restates the three mode meanings, range/sheet targeting, and the evaluate expressions, matching the schema's own wording without adding format or syntax detail. max_rows and the truncation/limit behavior are not mentioned anywhere in the description.

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

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

States a specific verb (read) and resource (workbook), enumerates the supported file formats, and lists the three output modes and the formula-evaluation capability. Combined with the closing 'without changing anything', an agent can distinguish it from create_workbook, edit_workbook, and convert_workbook without opening any schema.

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

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

The description implies usage ('read', 'evaluate formulas ... without changing anything') and shows example evaluation expressions, but never states when to prefer this tool over get_workbook_info or open_in_gridcraft, nor any prerequisite or exclusion. Usage is inferable rather than spelled out.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotency, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the $steps[N].field cross-step reference syntax, that live=true drives the open app, and that commands run sequentially with a save at the end. It does not, however, explain failure handling or exactly what is destroyed/overwritten.

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

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

The action is front-loaded and nearly every clause carries information (command families, delegated tools, step-id convention, $steps reference, live mode). It is dense and runs long as essentially one sentence, which hurts scanability slightly, but there is little filler.

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

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

For an 11-parameter composite runner with no output schema, the description conveys the core execution model (ordered steps, engine tool steps, source workbook options, save step, live mode) so an agent can call it correctly. Gaps remain around error handling, overwrite behavior, and the output_dir/output_path pairing, keeping it short of a full 5.

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

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

Schema description coverage is only 36%, so the description must compensate. It does clarify live, sample, the steps/id model, and the $steps[N] reference syntax (which is not in the schema), but leaves name, overwrite, all_sheets, output_dir, output_path, and stop_on_error unaddressed. Partial compensation warrants the baseline 3.

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

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

States a specific verb and resource ('run any GridCraft engine commands in order') and makes the batch/composite nature explicit by enumerating the command families (cell.*, home.*, etc.) and the engine tools it can delegate to. An agent can immediately distinguish this general-purpose executor from single-operation siblings like create_workbook or edit_workbook.

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

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

The 'Advanced:' prefix and the description of operating on a new/sample/opened workbook imply context, and mentioning that it saves afterward gives a hint of when to reach for it. However, it never explicitly says when to prefer this batch tool over the plain sibling tools (create_workbook, edit_workbook, read_workbook), leaving the choice to inference.

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