merge_cellsCombine a specified cell range into one cell, keeping the top-left value, or unmerge it to split back into individual cells in an Excel sheet.
Merge a range into one cell (keeping the top-left value), or unmerge it.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| range | Yes | ||
| sheet | Yes | ||
| action | No | Unmerge splits it again. | merge |
Changes observed during successful MCP inspections.
v2.0.0Input schema / properties / action / descriptionPrevious value: -"Merge the range or split it again."New value: +"Unmerge splits it again."Input schema / properties / action / titleRemoved value: -"Action"Input schema / properties / path / descriptionRemoved value: -"Path to an .xlsx, .xlsm, .xltx or .xltm file. Relative paths are resolved in the server's workbook directory when one is configured; otherwise use an absolute path."Input schema / properties / path / titleRemoved value: -"Path"Input schema / properties / range / descriptionRemoved value: -"A cell or rectangular range in A1 notation, e.g. 'A1:D20'."Input schema / properties / range / titleRemoved value: -"Range"Input schema / properties / sheet / descriptionRemoved value: -"Worksheet name, e.g. 'Sheet1'."Input schema / properties / sheet / titleRemoved value: -"Sheet"Input schema / titleRemoved value: -"merge_cellsArguments"Output schema / (root)Previous value: -{
- "properties": {
- "result": {
- "title": "Result",
- "type": "string"
- }
- },
- "required": [
- "result"
- ],
- "title": "merge_cellsOutput",
- "type": "object"
-}New value: +nullv1.1.1Input schema / properties / actionAdded value: +{
+ "default": "merge",
+ "description": "Merge the range or split it again.",
+ "enum": [
+ "merge",
+ "unmerge"
+ ],
+ "title": "Action",
+ "type": "string"
+}Input schema / properties / end_cellRemoved value: -{
- "title": "End Cell",
- "type": "string"
-}Input schema / properties / filepathRemoved value: -{
- "title": "Filepath",
- "type": "string"
-}Input schema / properties / pathAdded value: +{
+ "description": "Path to an .xlsx, .xlsm, .xltx or .xltm file. Relative paths are resolved in the server's workbook directory when one is configured; otherwise use an absolute path.",
+ "title": "Path",
+ "type": "string"
+}Input schema / properties / rangeAdded value: +{
+ "description": "A cell or rectangular range in A1 notation, e.g. 'A1:D20'.",
+ "title": "Range",
+ "type": "string"
+}Input schema / properties / sheetAdded value: +{
+ "description": "Worksheet name, e.g. 'Sheet1'.",
+ "title": "Sheet",
+ "type": "string"
+}Input schema / properties / sheet_nameRemoved value: -{
- "title": "Sheet Name",
- "type": "string"
-}Input schema / properties / start_cellRemoved value: -{
- "title": "Start Cell",
- "type": "string"
-}Input schema / requiredPrevious value: -[
- "filepath",
- "sheet_name",
- "start_cell",
- "end_cell"
-]New value: +[
+ "path",
+ "sheet",
+ "range"
+]v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates data. The description does add real value by disclosing what is destroyed — non-top-left values are discarded — which the annotation only flags generically. However, it says nothing about idempotency, failure on already-merged/never-merged ranges, or how unmerge restores content.
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 covering both operations with zero filler. Every clause earns its place by adding the merge/unmerge distinction and the retained-value rule.
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 needn't cover returns, and annotations carry the safety profile. Still, for a 4-parameter mutation tool with 25% schema coverage, the description leaves the three required parameters and error/edge-case behavior unexplained.
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 25%: of four parameters, only 'action' carries a schema description, and the description text merely echoes it. 'path', 'sheet', and 'range' are undocumented in both places, and the description does not compensate (e.g., no range syntax, no sheet-name format).
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 states a specific verb pair (merge/unmerge) and resource (a cell range), and the parenthetical clarifies the merge semantics. It is distinguishable from siblings like format_range or copy_range, though it never names or contrasts with any of 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?
There is no guidance on when to choose merge versus unmerge beyond the trivial restatement of the enum, and no prerequisites (e.g., range must be multi-cell, action defaults to merge). The agent must infer usage entirely from the single sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.