Skip to main content
Glama

Add a sheet

add_sheet

Put a new Sheet (a spreadsheet) on a tab in Plan (any other tab is refused), beside what the tab holds, titled uniquely on the tab: blank, filled from A1 with rows of values or CSV text read as typed, or laid out from a design as a template is (change_sheet’s design), the Sheet sized to show it. Then read and change it with read_sheet and change_sheet. A document of its own sheet is create_document with the blank-spreadsheet template, its sheet "Sheet 1".

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
csvNoIts first cells as CSV text instead (a tab in the first line reads as TSV), from A1.
rowsNoIts first cells, from A1: rows of values, read as typed.
tabIdNoThe tab to put it on, which must be in Plan; defaults to the first tab with a sheet, else the first tab.
titleNoThe sheet’s title (made unique on the tab); "Sheet 1", "Sheet 2"... when left out.
designNoOr the sheet laid out as a template is (the same design change_sheet takes); the Sheet is made large enough to show it.
documentIdYesThe document (from find_documents).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
revYesThe tab revision after it.
urlYesLink that opens the document in the livediagram editor.
tabIdYesThe tab it was put on.
titleYesIts title, unique on the tab: what read_sheet and change_sheet take.
filledYesThe cells filled, in A1 form; null for a blank sheet.
laidOutNoWhat a design laid out: each block’s ranges in A1, and its charts.
sheetIdYesThe new sheet’s id.
elementIdYesThe Sheet element that frames it.
truncatedYesWhether the first cells were cut at the sheet’s 10,000 rows or 200 columns.
changesetIdYesThe changeset that placed the element (revertible).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / tabId / description
      Previous value: -"The tab to put it on; defaults to the first tab with a sheet, else the first tab."New value: +"The tab to put it on, which must be in Plan; defaults to the first tab with a sheet, else the first tab."
  2. Changed2 schema fields changed
    • addedInput schema / properties / design
      Added value: +{
      +  "description": "Or the sheet laid out as a template is (the same design change_sheet takes); the Sheet is made large enough to show it.",
      +  "properties": {
      +    "accent": {
      +      "description": "The colour family of the header rows, title, totals and charts (default blue).",
      +      "enum": [
      +        "emerald",
      +        "violet",
      +        "sky",
      +        "indigo",
      +        "blue",
      +        "amber",
      +        "teal",
      +        "orange",
      +        "rose",
      +        "purple",
      +        "cyan",
      +        "fuchsia"
      +      ],
      +      "type": "string"
      +    },
      +    "blocks": {
      +      "description": "In order. Rows 1 to 3 are the heading, subtitle and a gap. A block without at starts on row 4 (the first) or after one blank row under the block before it, in column A; a table is its header row, then its rows, then its total; fields are their heading (if any), then one row per item. So formulas can name the cells their blocks land on. The answer names each block’s ranges.",
      +      "items": {
      +        "oneOf": [
      +          {
      +            "properties": {
      +              "at": {
      +                "description": "Its header row’s first cell (\"A4\"); stacked when left out.",
      +                "type": "string"
      +              },
      +              "chart": {
      +                "description": "A chart of the table’s header and body rows (never its total), live from its cells.",
      +                "properties": {
      +                  "at": {
      +                    "description": "The cell its top-left sits on; right of the table by default.",
      +                    "type": "string"
      +                  },
      +                  "columns": {
      +                    "description": "The columns charted by name, the first the labels; every column when left out.",
      +                    "items": {
      +                      "type": "string"
      +                    },
      +                    "type": "array"
      +                  },
      +                  "height": {
      +                    "description": "px, default 280.",
      +                    "type": "number"
      +                  },
      +                  "palette": {
      +                    "description": "Its colours. Left out: the family of its table’s header (a design’s accent: emerald and teal forest; sky, blue, indigo and cyan ocean; amber and orange sunset; rose, violet, purple and fuchsia berry), else vivid; a line, area or scatter chart of several series vivid, so its lines tell apart.",
      +                    "enum": [
      +                      "vivid",
      +                      "ocean",
      +                      "forest",
      +                      "sunset",
      +                      "berry",
      +                      "earth",
      +                      "grey",
      +                      "contrast"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "type": {
      +                    "description": "column, bar, pie and doughnut draw one series (the first value column); line, area and scatter draw every value column.",
      +                    "enum": [
      +                      "column",
      +                      "bar",
      +                      "line",
      +                      "area",
      +                      "scatter",
      +                      "pie",
      +                      "doughnut"
      +                    ],
      +                    "type": "string"
      +                  },
      +                  "width": {
      +                    "description": "px, default 420.",
      +                    "type": "number"
      +                  }
      +                },
      +                "required": [
      +                  "type"
      +                ],
      +                "type": "object"
      +              },
      +              "checkboxes": {
      +                "description": "Checkbox columns by name (TRUE or FALSE values).",
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "dropdowns": {
      +                "additionalProperties": {
      +                  "properties": {
      +                    "colors": {
      +                      "description": "#rrggbb per option, or null.",
      +                      "items": {
      +                        "type": [
      +                          "string",
      +                          "null"
      +                        ]
      +                      },
      +                      "type": "array"
      +                    },
      +                    "options": {
      +                      "items": {
      +                        "type": "string"
      +                      },
      +                      "maxItems": 500,
      +                      "minItems": 1,
      +                      "type": "array"
      +                    }
      +                  },
      +                  "required": [
      +                    "options"
      +                  ],
      +                  "type": "object"
      +                },
      +                "description": "Dropdown columns by name, over the body rows: each value a chip in its option’s colour.",
      +                "propertyNames": {
      +                  "type": "string"
      +                },
      +                "type": "object"
      +              },
      +              "formats": {
      +                "additionalProperties": {
      +                  "anyOf": [
      +                    {
      +                      "type": "string"
      +                    },
      +                    {
      +                      "description": "The parts of the format to set; parts left out are kept.",
      +                      "properties": {
      +                        "align": {
      +                          "anyOf": [
      +                            {
      +                              "enum": [
      +                                "left",
      +                                "center",
      +                                "right"
      +                              ],
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Horizontal alignment; null for automatic (numbers right, text left)."
      +                        },
      +                        "background": {
      +                          "description": "Fill colour, #rrggbb; null for none.",
      +                          "type": [
      +                            "string",
      +                            "null"
      +                          ]
      +                        },
      +                        "bold": {
      +                          "description": "Bold on (true) or off (false).",
      +                          "type": "boolean"
      +                        },
      +                        "color": {
      +                          "description": "Text colour, #rrggbb; null for the default.",
      +                          "type": [
      +                            "string",
      +                            "null"
      +                          ]
      +                        },
      +                        "currency": {
      +                          "description": "The currency symbol: R$ CHF zł kr £ $ € ¥ ₹ ₩ ₽ ₺ ₪ ₫; null for the default.",
      +                          "type": [
      +                            "string",
      +                            "null"
      +                          ]
      +                        },
      +                        "decimals": {
      +                          "anyOf": [
      +                            {
      +                              "maximum": 10,
      +                              "minimum": 0,
      +                              "type": "integer"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Decimal places, 0 to 10; null for the format’s own."
      +                        },
      +                        "fontSize": {
      +                          "description": "Font size in points, a whole number from 6 to 96; null for the default.",
      +                          "type": [
      +                            "number",
      +                            "null"
      +                          ]
      +                        },
      +                        "italic": {
      +                          "description": "Italic on or off.",
      +                          "type": "boolean"
      +                        },
      +                        "numberFormat": {
      +                          "description": "How numbers show: auto, number, percent, currency, accounting, scientific, date, time, datetime, duration, text, custom; null for auto.",
      +                          "type": [
      +                            "string",
      +                            "null"
      +                          ]
      +                        },
      +                        "strikethrough": {
      +                          "description": "Strikethrough on or off.",
      +                          "type": "boolean"
      +                        },
      +                        "underline": {
      +                          "description": "Underline on or off.",
      +                          "type": "boolean"
      +                        },
      +                        "verticalAlign": {
      +                          "anyOf": [
      +                            {
      +                              "enum": [
      +                                "top",
      +                                "middle",
      +                                "bottom"
      +                              ],
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Vertical alignment; null for the default (bottom)."
      +                        },
      +                        "wrap": {
      +                          "anyOf": [
      +                            {
      +                              "enum": [
      +                                "overflow",
      +                                "wrap",
      +                                "clip"
      +                              ],
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Long text runs over empty neighbours, wraps, or is clipped; null for overflow."
      +                        }
      +                      },
      +                      "type": "object"
      +                    }
      +                  ],
      +                  "description": "A number format by name (auto, number, percent, currency, accounting, scientific, date, time, datetime, duration, text, custom; number, currency and percent show 2 decimals), or a format in words ({\"numberFormat\": \"number\", \"decimals\": 0} for whole numbers)."
      +                },
      +                "description": "Formats by column name over the body and total: {\"Amount\": \"currency\", \"Share\": \"percent\"}.",
      +                "propertyNames": {
      +                  "type": "string"
      +                },
      +                "type": "object"
      +              },
      +              "head": {
      +                "description": "The header row: each column’s name.",
      +                "items": {
      +                  "type": "string"
      +                },
      +                "minItems": 1,
      +                "type": "array"
      +              },
      +              "inputs": {
      +                "description": "Columns meant to be typed over, by name: tinted soft yellow.",
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "kind": {
      +                "const": "table",
      +                "description": "A block is a table, fields or a note.",
      +                "type": "string"
      +              },
      +              "rows": {
      +                "description": "The body rows, values read as typed (a leading = a formula).",
      +                "items": {
      +                  "description": "One row, left to right.",
      +                  "items": {
      +                    "description": "A value: text is read as typed in en-GB (a leading = is a formula, \"12%\" a percent, \"03/04/2026\" the 3rd of April), a JSON number or boolean is kept as it is, null clears the cell.",
      +                    "type": [
      +                      "string",
      +                      "number",
      +                      "boolean",
      +                      "null"
      +                    ]
      +                  },
      +                  "maxItems": 200,
      +                  "type": "array"
      +                },
      +                "maxItems": 10000,
      +                "type": "array"
      +              },
      +              "total": {
      +                "description": "A total row under the body, bold and ruled above (\"Total\", null, \"=SUM(C5:C12)\").",
      +                "items": {
      +                  "description": "A value: text is read as typed in en-GB (a leading = is a formula, \"12%\" a percent, \"03/04/2026\" the 3rd of April), a JSON number or boolean is kept as it is, null clears the cell.",
      +                  "type": [
      +                    "string",
      +                    "number",
      +                    "boolean",
      +                    "null"
      +                  ]
      +                },
      +                "type": "array"
      +              }
      +            },
      +            "required": [
      +              "kind",
      +              "head",
      +              "rows"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "properties": {
      +              "at": {
      +                "description": "Its first cell; stacked when left out.",
      +                "type": "string"
      +              },
      +              "heading": {
      +                "description": "A ruled heading over them.",
      +                "type": "string"
      +              },
      +              "items": {
      +                "items": {
      +                  "properties": {
      +                    "format": {
      +                      "anyOf": [
      +                        {
      +                          "type": "string"
      +                        },
      +                        {
      +                          "description": "The parts of the format to set; parts left out are kept.",
      +                          "properties": {
      +                            "align": {
      +                              "anyOf": [
      +                                {
      +                                  "enum": [
      +                                    "left",
      +                                    "center",
      +                                    "right"
      +                                  ],
      +                                  "type": "string"
      +                                },
      +                                {
      +                                  "type": "null"
      +                                }
      +                              ],
      +                              "description": "Horizontal alignment; null for automatic (numbers right, text left)."
      +                            },
      +                            "background": {
      +                              "description": "Fill colour, #rrggbb; null for none.",
      +                              "type": [
      +                                "string",
      +                                "null"
      +                              ]
      +                            },
      +                            "bold": {
      +                              "description": "Bold on (true) or off (false).",
      +                              "type": "boolean"
      +                            },
      +                            "color": {
      +                              "description": "Text colour, #rrggbb; null for the default.",
      +                              "type": [
      +                                "string",
      +                                "null"
      +                              ]
      +                            },
      +                            "currency": {
      +                              "description": "The currency symbol: R$ CHF zł kr £ $ € ¥ ₹ ₩ ₽ ₺ ₪ ₫; null for the default.",
      +                              "type": [
      +                                "string",
      +                                "null"
      +                              ]
      +                            },
      +                            "decimals": {
      +                              "anyOf": [
      +                                {
      +                                  "maximum": 10,
      +                                  "minimum": 0,
      +                                  "type": "integer"
      +                                },
      +                                {
      +                                  "type": "null"
      +                                }
      +                              ],
      +                              "description": "Decimal places, 0 to 10; null for the format’s own."
      +                            },
      +                            "fontSize": {
      +                              "description": "Font size in points, a whole number from 6 to 96; null for the default.",
      +                              "type": [
      +                                "number",
      +                                "null"
      +                              ]
      +                            },
      +                            "italic": {
      +                              "description": "Italic on or off.",
      +                              "type": "boolean"
      +                            },
      +                            "numberFormat": {
      +                              "description": "How numbers show: auto, number, percent, currency, accounting, scientific, date, time, datetime, duration, text, custom; null for auto.",
      +                              "type": [
      +                                "string",
      +                                "null"
      +                              ]
      +                            },
      +                            "strikethrough": {
      +                              "description": "Strikethrough on or off.",
      +                              "type": "boolean"
      +                            },
      +                            "underline": {
      +                              "description": "Underline on or off.",
      +                              "type": "boolean"
      +                            },
      +                            "verticalAlign": {
      +                              "anyOf": [
      +                                {
      +                                  "enum": [
      +                                    "top",
      +                                    "middle",
      +                                    "bottom"
      +                                  ],
      +                                  "type": "string"
      +                                },
      +                                {
      +                                  "type": "null"
      +                                }
      +                              ],
      +                              "description": "Vertical alignment; null for the default (bottom)."
      +                            },
      +                            "wrap": {
      +                              "anyOf": [
      +                                {
      +                                  "enum": [
      +                                    "overflow",
      +                                    "wrap",
      +                                    "clip"
      +                                  ],
      +                                  "type": "string"
      +                                },
      +                                {
      +                                  "type": "null"
      +                                }
      +                              ],
      +                              "description": "Long text runs over empty neighbours, wraps, or is clipped; null for overflow."
      +                            }
      +                          },
      +                          "type": "object"
      +                        }
      +                      ],
      +                      "description": "A number format by name (auto, number, percent, currency, accounting, scientific, date, time, datetime, duration, text, custom; number, currency and percent show 2 decimals), or a format in words ({\"numberFormat\": \"number\", \"decimals\": 0} for whole numbers)."
      +                    },
      +                    "kind": {
      +                      "description": "input: tinted to type over; result: larger, bold, in the accent; value (default).",
      +                      "enum": [
      +                        "input",
      +                        "value",
      +                        "result"
      +                      ],
      +                      "type": "string"
      +                    },
      +                    "label": {
      +                      "description": "In the first column, quiet.",
      +                      "type": "string"
      +                    },
      +                    "value": {
      +                      "description": "In the column right of it.",
      +                      "type": [
      +                        "string",
      +                        "number",
      +                        "boolean",
      +                        "null"
      +                      ]
      +                    }
      +                  },
      +                  "required": [
      +                    "label",
      +                    "value"
      +                  ],
      +                  "type": "object"
      +                },
      +                "minItems": 1,
      +                "type": "array"
      +              },
      +              "kind": {
      +                "const": "fields",
      +                "description": "Labels and values, two columns.",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "kind",
      +              "items"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "properties": {
      +              "at": {
      +                "type": "string"
      +              },
      +              "kind": {
      +                "const": "note",
      +                "description": "One quiet line.",
      +                "type": "string"
      +              },
      +              "text": {
      +                "description": "A quiet italic line.",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "kind",
      +              "text"
      +            ],
      +            "type": "object"
      +          }
      +        ]
      +      },
      +      "minItems": 1,
      +      "type": "array"
      +    },
      +    "freeze": {
      +      "description": "Rows frozen at the top; by default through the header of the table with the most rows, when it starts by row 12.",
      +      "maximum": 100,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "heading": {
      +      "description": "The title in A1, large and in the accent, across the sheet.",
      +      "type": "string"
      +    },
      +    "look": {
      +      "description": "banded (default: filled header, every other row tinted, ruled total), header, boxed (every cell lined), minimal (ruled, no gridlines) or plain.",
      +      "enum": [
      +        "plain",
      +        "header",
      +        "banded",
      +        "boxed",
      +        "minimal"
      +      ],
      +      "type": "string"
      +    },
      +    "subtitle": {
      +      "description": "A quiet line under it, in A2: what the sheet is for, what to type over.",
      +      "type": "string"
      +    },
      +    "widths": {
      +      "description": "Column widths in px from A; each column fitted to its cells when left out.",
      +      "items": {
      +        "type": "number"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "heading",
      +    "blocks"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / laidOut
      Added value: +{
      +  "description": "What a design laid out: each block’s ranges in A1, and its charts.",
      +  "type": "string"
      +}
  3. Added

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare this a non-readonly, non-destructive, non-open-world write, so the bar is lower; the description still adds real behavior: the sheet lands beside existing tab content, the title is silently made unique, and the tab must be in Plan or the call is refused. It also states the sheet is sized to show the design content. Auth and rate-limit behavior are unstated.

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?

The action is front-loaded, but the core is one long run-on sentence with stacked parentheticals and comma clauses ("...as a template is (change_sheet's design), the Sheet sized to show it") that is hard to parse on first read. Most content earns its place, but the structure does not help scanning.

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?

An output schema exists, so return values need not be explained, and the deeply nested design object is fully specified in the schema. The description covers placement, naming, mode selection, and sibling routing. It stops short of permission requirements or what happens on title collision beyond "made unique", but nothing critical for a correct call is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds a useful taxonomy the schema does not: the three mutually exclusive creation modes (blank, filled from A1 via rows/CSV read as typed, or laid out from a design "as a template is"), plus the tie to change_sheet's design shape. That framing genuinely helps the agent pick between the csv, rows and design parameters.

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?

States a concrete verb and resource ("Put a new Sheet (a spreadsheet) on a tab in Plan") with its scope constraint ("any other tab is refused"). It explicitly separates itself from siblings by naming read_sheet and change_sheet for subsequent use and create_document for a standalone sheet document, so an agent can route without opening another schema.

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?

Names the alternatives directly: use read_sheet/change_sheet to work with the sheet afterwards, and create_document with the blank-spreadsheet template when you want a document of its own. It also gives a hard exclusion ("any other tab is refused"). What is missing is an explicit decision rule in "use X when / use Y when" form, so routing still requires a small inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources