Skip to main content
Glama

livediagram

by app.livediagram.mcp
OverviewDiscussionsAdmin

Change a form

change_form
Destructive

Change a form, in order, as one write: add_question, set_question, delete_question, move_question, add_section, set_section (a rule showIf shows it only on an earlier answer), delete_section, set_form (heading, description, cover), settings (closesAt, limit, confirmation, closedMessage) and responds_to. Questions by id or prompt, sections by id, title or place. A refusal names its change and writes nothing. While a form takes responses only settings change: close it with share_form first (the link stays). Everyone with the document open sees it at once.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
tabNoThe Form tab, by id or name. Absent: the document’s first Form tab.
changesYesUp to 50 changes, applied in order as one write; each an object with its "op".
documentIdYesThe document (from find_documents).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYesLink that opens the document in the livediagram editor.
linkYesThe form link anyone can fill it in at; null unpublished or for a non-Editor.
madeNoThe documents and tabs the call made.
coverNoThe cover band’s colours.
linesNoWhat the call did.
stateYesaccepting: the link takes responses. paused: published, but responses have nowhere to go.
tabIdYesThe Form tab.
unseenYesResponses the caller has not seen (opening the Form tab sees them).
headingYesThe form’s heading, which is its tab’s name.
problemsYesWhat stops it being published, in Share Form’s words; empty when ready.
sectionsYesThe pages of the form, in order.
settingsYesclosesAt (ISO), limit, and the confirmation and closed messages respondents see.
responsesYesResponses so far.
documentIdYesThe document.
respondsToYesWhere responses go: {to: "board", board, cardType, column}, {to: "sheet", sheet} or {to: "nowhere"}.
descriptionNoThe line under the heading.
closedReasonNoWhy a published form is closed: switched_off, closes_at (its time passed) or limit (it is full).
respondsToProblemNoWhy responses cannot land there now.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / changes / items / oneOf
      Previous value: -[
-  {
-    "properties": {
-      "after": {
-        "description": "Add right after this question.",
-        "type": "string"
-      },
-      "before": {
-        "description": "Add right before this question (before the first: first).",
-        "type": "string"
-      },
-      "op": {
-        "const": "add_question",
-        "type": "string"
-      },
-      "question": {
-        "description": "A question, with the settings its type has.",
-        "properties": {
-          "dropdown": {
-            "description": "single: a dropdown whatever its length (past 7 options it is one anyway).",
-            "type": "boolean"
-          },
-          "goesTo": {
-            "description": "Board forms: where the answer is kept on the response’s card: \"Title\" (one question at most; short, email, number, single or date), \"Description\" (the default: written under its prompt), or a card field’s name. A name the card type lacks makes that field, of the kind the question fits (a choice or rating shown on the card; a choice with \"other\" a text field, as an Other answer is no option). An existing currency field takes a number.",
-            "type": "string"
-          },
-          "help": {
-            "description": "A line under the prompt, up to 500 characters.",
-            "type": "string"
-          },
-          "highLabel": {
-            "description": "rating with numbers: the label under the last, up to 40.",
-            "type": "string"
-          },
-          "lowLabel": {
-            "description": "rating with numbers: the label under the first, up to 40.",
-            "type": "string"
-          },
-          "max": {
-            "description": "number: the highest answer. multi: the most picks.",
-            "type": "number"
-          },
-          "min": {
-            "description": "number: the lowest answer. multi: the fewest picks.",
-            "type": "number"
-          },
-          "options": {
-            "description": "single and multi: the options in order, 1 to 20, each up to 40 characters, unique.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "other": {
-            "description": "single and multi: an \"Other\" option with its own text box.",
-            "type": "boolean"
-          },
-          "placeholder": {
-            "description": "Grey text in the answer box until someone types (short, paragraph, number, email, link), up to 80.",
-            "type": "string"
-          },
-          "prompt": {
-            "description": "What the question asks, 1 to 200 characters.",
-            "type": "string"
-          },
-          "required": {
-            "description": "An answer is needed to submit (a Checkbox must be ticked).",
-            "type": "boolean"
-          },
-          "scale": {
-            "description": "rating: the top score, 3 to 10 (5 when left out).",
-            "maximum": 9007199254740991,
-            "minimum": -9007199254740991,
-            "type": "integer"
-          },
-          "style": {
-            "description": "rating: stars (the default) or numbered buttons.",
-            "enum": [
-              "stars",
-              "numbers"
-            ],
-            "type": "string"
-          },
-          "type": {
-            "description": "The question type: short (Short Answer), paragraph (Paragraph), number (Number), email (Email), link (Link), date (Date), single (Single Choice), multi (Multiple Choice), rating (Rating), checkbox (Checkbox).",
-            "enum": [
-              "short",
-              "paragraph",
-              "number",
-              "email",
-              "link",
-              "date",
-              "single",
-              "multi",
-              "rating",
-              "checkbox"
-            ],
-            "type": "string"
-          },
-          "whole": {
-            "description": "number: whole numbers only.",
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "type",
-          "prompt"
-        ],
-        "type": "object"
-      },
-      "section": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "maximum": 9007199254740991,
-            "minimum": 1,
-            "type": "integer"
-          }
-        ],
-        "description": "Add at the end of this section. Absent: the end of the form."
-      }
-    },
-    "required": [
-      "op",
-      "question"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "op": {
-        "const": "set_question",
-        "type": "string"
-      },
-      "question": {
-        "description": "A question: its id, or its prompt.",
-        "type": "string"
-      },
-      "set": {
-        "description": "The settings to change; a text setting given as \"\" is cleared, a switch given false is turned off.",
-        "properties": {
-          "dropdown": {
-            "description": "single: a dropdown whatever its length (past 7 options it is one anyway).",
-            "type": "boolean"
-          },
-          "goesTo": {
-            "description": "Board forms: where the answer is kept on the response’s card: \"Title\" (one question at most; short, email, number, single or date), \"Description\" (the default: written under its prompt), or a card field’s name. A name the card type lacks makes that field, of the kind the question fits (a choice or rating shown on the card; a choice with \"other\" a text field, as an Other answer is no option). An existing currency field takes a number.",
-            "type": "string"
-          },
-          "help": {
-            "description": "A line under the prompt, up to 500 characters.",
-            "type": "string"
-          },
-          "highLabel": {
-            "description": "rating with numbers: the label under the last, up to 40.",
-            "type": "string"
-          },
-          "lowLabel": {
-            "description": "rating with numbers: the label under the first, up to 40.",
-            "type": "string"
-          },
-          "max": {
-            "description": "number: the highest answer. multi: the most picks.",
-            "type": "number"
-          },
-          "min": {
-            "description": "number: the lowest answer. multi: the fewest picks.",
-            "type": "number"
-          },
-          "options": {
-            "description": "single and multi: the options in order, 1 to 20, each up to 40 characters, unique.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "other": {
-            "description": "single and multi: an \"Other\" option with its own text box.",
-            "type": "boolean"
-          },
-          "placeholder": {
-            "description": "Grey text in the answer box until someone types (short, paragraph, number, email, link), up to 80.",
-            "type": "string"
-          },
-          "prompt": {
-            "description": "What the question asks, 1 to 200 characters.",
-            "type": "string"
-          },
-          "required": {
-            "description": "An answer is needed to submit (a Checkbox must be ticked).",
-            "type": "boolean"
-          },
-          "scale": {
-            "description": "rating: the top score, 3 to 10 (5 when left out).",
-            "maximum": 9007199254740991,
-            "minimum": -9007199254740991,
-            "type": "integer"
-          },
-          "style": {
-            "description": "rating: stars (the default) or numbered buttons.",
-            "enum": [
-              "stars",
-              "numbers"
-            ],
-            "type": "string"
-          },
-          "type": {
-            "description": "The question type: short (Short Answer), paragraph (Paragraph), number (Number), email (Email), link (Link), date (Date), single (Single Choice), multi (Multiple Choice), rating (Rating), checkbox (Checkbox).",
-            "enum": [
-              "short",
-              "paragraph",
-              "number",
-              "email",
-              "link",
-              "date",
-              "single",
-              "multi",
-              "rating",
-              "checkbox"
-            ],
-            "type": "string"
-          },
-          "whole": {
-            "description": "number: whole numbers only.",
-            "type": "boolean"
-          }
-        },
-        "type": "object"
-      }
-    },
-    "required": [
-      "op",
-      "question",
-      "set"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "op": {
-        "const": "delete_question",
-        "type": "string"
-      },
-      "question": {
-        "description": "A question: its id, or its prompt.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "op",
-      "question"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "after": {
-        "description": "Move right after this question.",
-        "type": "string"
-      },
-      "before": {
-        "description": "Move right before this question (before the first: first).",
-        "type": "string"
-      },
-      "op": {
-        "const": "move_question",
-        "type": "string"
-      },
-      "question": {
-        "description": "A question: its id, or its prompt.",
-        "type": "string"
-      },
-      "section": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "maximum": 9007199254740991,
-            "minimum": 1,
-            "type": "integer"
-          }
-        ],
-        "description": "Move to the end of this section."
-      }
-    },
-    "required": [
-      "op",
-      "question"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "after": {
-        "description": "Split the form after this question. Absent: an empty section at the end.",
-        "type": "string"
-      },
-      "description": {
-        "type": "string"
-      },
-      "op": {
-        "const": "add_section",
-        "type": "string"
-      },
-      "showIf": {
-        "description": "Show the section only when an earlier answer is one of these.",
-        "properties": {
-          "anyOf": {
-            "description": "The answers that show the section: the question’s options, or \"Ticked\" / \"Not Ticked\".",
-            "items": {
-              "type": "string"
-            },
-            "minItems": 1,
-            "type": "array"
-          },
-          "question": {
-            "description": "An earlier Single Choice, Multiple Choice or Checkbox question.",
-            "type": "string"
-          }
-        },
-        "required": [
-          "question",
-          "anyOf"
-        ],
-        "type": "object"
-      },
-      "title": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "op"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "description": {
-        "type": "string"
-      },
-      "op": {
-        "const": "set_section",
-        "type": "string"
-      },
-      "section": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "maximum": 9007199254740991,
-            "minimum": 1,
-            "type": "integer"
-          }
-        ],
-        "description": "A section: its id, its title, or its place (1 is the first)."
-      },
-      "showIf": {
-        "anyOf": [
-          {
-            "description": "Show the section only when an earlier answer is one of these.",
-            "properties": {
-              "anyOf": {
-                "description": "The answers that show the section: the question’s options, or \"Ticked\" / \"Not Ticked\".",
-                "items": {
-                  "type": "string"
-                },
-                "minItems": 1,
-                "type": "array"
-              },
-              "question": {
-                "description": "An earlier Single Choice, Multiple Choice or Checkbox question.",
-                "type": "string"
-              }
-            },
-            "required": [
-              "question",
-              "anyOf"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "null: always shown."
-      },
-      "title": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "op",
-      "section"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "op": {
-        "const": "delete_section",
-        "type": "string"
-      },
-      "section": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "maximum": 9007199254740991,
-            "minimum": 1,
-            "type": "integer"
-          }
-        ],
-        "description": "Its questions join the section before."
-      }
-    },
-    "required": [
-      "op",
-      "section"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "cover": {
-        "anyOf": [
-          {
-            "description": "The band across the form’s top: a colour or gradient, and a pattern. No pictures.",
-            "properties": {
-              "angle": {
-                "description": "The gradient’s angle in degrees (default 160).",
-                "type": "number"
-              },
-              "color": {
-                "description": "A solid band.",
-                "type": "string"
-              },
-              "gradient": {
-                "additionalItems": false,
-                "description": "A two-stop gradient: the colours it runs from and to.",
-                "items": [
-                  {
-                    "description": "A hex colour such as #0f172a.",
-                    "type": "string"
-                  },
-                  {
-                    "description": "A hex colour such as #0f172a.",
-                    "type": "string"
-                  }
-                ],
-                "maxItems": 2,
-                "minItems": 2,
-                "type": "array"
-              },
-              "motion": {
-                "description": "A gradient that moves on screen (still in pictures and under reduced motion).",
-                "enum": [
-                  "flow",
-                  "drift",
-                  "aurora",
-                  "ripple",
-                  "ribbons",
-                  "mesh",
-                  "starfield",
-                  "retro-grid",
-                  "bokeh",
-                  "waves",
-                  "spotlight",
-                  "beams",
-                  "sunburst",
-                  "fireflies",
-                  "snowfall",
-                  "lava",
-                  "dot-wave",
-                  "clouds",
-                  "warp",
-                  "orbits",
-                  "radar",
-                  "equaliser",
-                  "confetti",
-                  "threads"
-                ],
-                "type": "string"
-              },
-              "pattern": {
-                "description": "A pattern over the colour.",
-                "enum": [
-                  "dots",
-                  "grid",
-                  "lines"
-                ],
-                "type": "string"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "The cover band; null removes it. The form’s own colour (bars, buttons) is its tab theme’s: set theme to match a cover."
-      },
-      "description": {
-        "type": "string"
-      },
-      "heading": {
-        "description": "The form’s heading and its tab’s name, up to 80.",
-        "type": "string"
-      },
-      "op": {
-        "const": "set_form",
-        "type": "string"
-      },
-      "theme": {
-        "description": "The Form tab’s theme (mocha, ocean, forest...): the form’s colour, font and finish follow it.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "op"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "closedMessage": {
-        "description": "Shown on the link once closed, up to 500 characters; null for the default.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "closesAt": {
-        "description": "When the form stops taking responses, an ISO date and time; one with no offset (no Z or +hh:mm) is UTC. Respondents are not shown it beforehand: say it in the description if they should know. null clears it.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "confirmation": {
-        "description": "Shown after submitting, up to 500 characters; null for the default.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "limit": {
-        "anyOf": [
-          {
-            "maximum": 9007199254740991,
-            "minimum": -9007199254740991,
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "The most responses it takes (each submission counts one, whatever it holds), 1 to 2000; null clears it."
-      },
-      "op": {
-        "const": "settings",
-        "type": "string"
-      }
-    },
-    "required": [
-      "op"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "board": {
-        "description": "An existing Board tab’s name (or its board’s title). Absent: a new Board tab \"<Form> Responses\" with New, In Progress and Done, taking the form’s card type alone.",
-        "type": "string"
-      },
-      "cardType": {
-        "description": "The card type each response becomes, by name. A name the document lacks brings in the ready-made type of that name (Bug, Idea, Candidate, Request...) or makes a new one. Absent: the form’s own, the board’s first, or a new type named after the form.",
-        "type": "string"
-      },
-      "column": {
-        "description": "An existing board’s column, by name. Absent: its first.",
-        "type": "string"
-      },
-      "op": {
-        "const": "responds_to",
-        "type": "string"
-      },
-      "sheet": {
-        "description": "An existing sheet, by its Sheet tab’s name. Absent: a new Sheet tab \"<Form> Responses\", its header row a column per question.",
-        "type": "string"
-      },
-      "to": {
-        "description": "Cards on a board (to work through) or rows in a sheet (to count).",
-        "enum": [
-          "board",
-          "sheet"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "to",
-      "op"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "after": {
+        "description": "Add right after this question.",
+        "type": "string"
+      },
+      "before": {
+        "description": "Add right before this question (before the first: first).",
+        "type": "string"
+      },
+      "op": {
+        "const": "add_question",
+        "type": "string"
+      },
+      "question": {
+        "description": "A question, with the settings its type has.",
+        "properties": {
+          "dropdown": {
+            "description": "single: a dropdown whatever its length (past 7 options it is one anyway).",
+            "type": "boolean"
+          },
+          "goesTo": {
+            "description": "Board forms: where the answer is kept on the response’s card: \"Title\" (one question at most; short, email, number, single or date), \"Description\" (the default: written under its prompt), or a card field’s name. A name the card type lacks makes that field, of the kind the question fits (a choice or rating shown on the card; a choice with \"other\" a text field, as an Other answer is no option). An existing currency field takes a number.",
+            "type": "string"
+          },
+          "help": {
+            "description": "A line under the prompt, up to 500 characters.",
+            "type": "string"
+          },
+          "highLabel": {
+            "description": "rating with numbers: the label under the last, up to 40.",
+            "type": "string"
+          },
+          "lowLabel": {
+            "description": "rating with numbers: the label under the first, up to 40.",
+            "type": "string"
+          },
+          "max": {
+            "description": "number: the highest answer. multi: the most picks.",
+            "type": "number"
+          },
+          "min": {
+            "description": "number: the lowest answer. multi: the fewest picks.",
+            "type": "number"
+          },
+          "options": {
+            "description": "single and multi: the options in order, 1 to 20, each up to 100 characters, unique.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "other": {
+            "description": "single and multi: an \"Other\" option with its own text box.",
+            "type": "boolean"
+          },
+          "placeholder": {
+            "description": "Grey text in the answer box until someone types (short, paragraph, number, email, link), up to 80.",
+            "type": "string"
+          },
+          "prompt": {
+            "description": "What the question asks, 1 to 200 characters.",
+            "type": "string"
+          },
+          "required": {
+            "description": "An answer is needed to submit (a Checkbox must be ticked).",
+            "type": "boolean"
+          },
+          "scale": {
+            "description": "rating: the top score, 3 to 10 (5 when left out).",
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "style": {
+            "description": "rating: stars (the default) or numbered buttons.",
+            "enum": [
+              "stars",
+              "numbers"
+            ],
+            "type": "string"
+          },
+          "type": {
+            "description": "The question type: short (Short Answer), paragraph (Paragraph), number (Number), email (Email), link (Link), date (Date), single (Single Choice), multi (Multiple Choice), rating (Rating), checkbox (Checkbox).",
+            "enum": [
+              "short",
+              "paragraph",
+              "number",
+              "email",
+              "link",
+              "date",
+              "single",
+              "multi",
+              "rating",
+              "checkbox"
+            ],
+            "type": "string"
+          },
+          "whole": {
+            "description": "number: whole numbers only.",
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "type",
+          "prompt"
+        ],
+        "type": "object"
+      },
+      "section": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "maximum": 9007199254740991,
+            "minimum": 1,
+            "type": "integer"
+          }
+        ],
+        "description": "Add at the end of this section. Absent: the end of the form."
+      }
+    },
+    "required": [
+      "op",
+      "question"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "op": {
+        "const": "set_question",
+        "type": "string"
+      },
+      "question": {
+        "description": "A question: its id, or its prompt.",
+        "type": "string"
+      },
+      "set": {
+        "description": "The settings to change; a text setting given as \"\" is cleared, a switch given false is turned off.",
+        "properties": {
+          "dropdown": {
+            "description": "single: a dropdown whatever its length (past 7 options it is one anyway).",
+            "type": "boolean"
+          },
+          "goesTo": {
+            "description": "Board forms: where the answer is kept on the response’s card: \"Title\" (one question at most; short, email, number, single or date), \"Description\" (the default: written under its prompt), or a card field’s name. A name the card type lacks makes that field, of the kind the question fits (a choice or rating shown on the card; a choice with \"other\" a text field, as an Other answer is no option). An existing currency field takes a number.",
+            "type": "string"
+          },
+          "help": {
+            "description": "A line under the prompt, up to 500 characters.",
+            "type": "string"
+          },
+          "highLabel": {
+            "description": "rating with numbers: the label under the last, up to 40.",
+            "type": "string"
+          },
+          "lowLabel": {
+            "description": "rating with numbers: the label under the first, up to 40.",
+            "type": "string"
+          },
+          "max": {
+            "description": "number: the highest answer. multi: the most picks.",
+            "type": "number"
+          },
+          "min": {
+            "description": "number: the lowest answer. multi: the fewest picks.",
+            "type": "number"
+          },
+          "options": {
+            "description": "single and multi: the options in order, 1 to 20, each up to 100 characters, unique.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "other": {
+            "description": "single and multi: an \"Other\" option with its own text box.",
+            "type": "boolean"
+          },
+          "placeholder": {
+            "description": "Grey text in the answer box until someone types (short, paragraph, number, email, link), up to 80.",
+            "type": "string"
+          },
+          "prompt": {
+            "description": "What the question asks, 1 to 200 characters.",
+            "type": "string"
+          },
+          "required": {
+            "description": "An answer is needed to submit (a Checkbox must be ticked).",
+            "type": "boolean"
+          },
+          "scale": {
+            "description": "rating: the top score, 3 to 10 (5 when left out).",
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "style": {
+            "description": "rating: stars (the default) or numbered buttons.",
+            "enum": [
+              "stars",
+              "numbers"
+            ],
+            "type": "string"
+          },
+          "type": {
+            "description": "The question type: short (Short Answer), paragraph (Paragraph), number (Number), email (Email), link (Link), date (Date), single (Single Choice), multi (Multiple Choice), rating (Rating), checkbox (Checkbox).",
+            "enum": [
+              "short",
+              "paragraph",
+              "number",
+              "email",
+              "link",
+              "date",
+              "single",
+              "multi",
+              "rating",
+              "checkbox"
+            ],
+            "type": "string"
+          },
+          "whole": {
+            "description": "number: whole numbers only.",
+            "type": "boolean"
+          }
+        },
+        "type": "object"
+      }
+    },
+    "required": [
+      "op",
+      "question",
+      "set"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "op": {
+        "const": "delete_question",
+        "type": "string"
+      },
+      "question": {
+        "description": "A question: its id, or its prompt.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "op",
+      "question"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "after": {
+        "description": "Move right after this question.",
+        "type": "string"
+      },
+      "before": {
+        "description": "Move right before this question (before the first: first).",
+        "type": "string"
+      },
+      "op": {
+        "const": "move_question",
+        "type": "string"
+      },
+      "question": {
+        "description": "A question: its id, or its prompt.",
+        "type": "string"
+      },
+      "section": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "maximum": 9007199254740991,
+            "minimum": 1,
+            "type": "integer"
+          }
+        ],
+        "description": "Move to the end of this section."
+      }
+    },
+    "required": [
+      "op",
+      "question"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "after": {
+        "description": "Split the form after this question. Absent: an empty section at the end.",
+        "type": "string"
+      },
+      "description": {
+        "type": "string"
+      },
+      "op": {
+        "const": "add_section",
+        "type": "string"
+      },
+      "showIf": {
+        "description": "Show the section only when an earlier answer is one of these.",
+        "properties": {
+          "anyOf": {
+            "description": "The answers that show the section: the question’s options, or \"Ticked\" / \"Not Ticked\".",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "type": "array"
+          },
+          "question": {
+            "description": "An earlier Single Choice, Multiple Choice or Checkbox question.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "question",
+          "anyOf"
+        ],
+        "type": "object"
+      },
+      "title": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "op"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "description": {
+        "type": "string"
+      },
+      "op": {
+        "const": "set_section",
+        "type": "string"
+      },
+      "section": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "maximum": 9007199254740991,
+            "minimum": 1,
+            "type": "integer"
+          }
+        ],
+        "description": "A section: its id, its title, or its place (1 is the first)."
+      },
+      "showIf": {
+        "anyOf": [
+          {
+            "description": "Show the section only when an earlier answer is one of these.",
+            "properties": {
+              "anyOf": {
+                "description": "The answers that show the section: the question’s options, or \"Ticked\" / \"Not Ticked\".",
+                "items": {
+                  "type": "string"
+                },
+                "minItems": 1,
+                "type": "array"
+              },
+              "question": {
+                "description": "An earlier Single Choice, Multiple Choice or Checkbox question.",
+                "type": "string"
+              }
+            },
+            "required": [
+              "question",
+              "anyOf"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "null: always shown."
+      },
+      "title": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "op",
+      "section"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "op": {
+        "const": "delete_section",
+        "type": "string"
+      },
+      "section": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "maximum": 9007199254740991,
+            "minimum": 1,
+            "type": "integer"
+          }
+        ],
+        "description": "Its questions join the section before."
+      }
+    },
+    "required": [
+      "op",
+      "section"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "cover": {
+        "anyOf": [
+          {
+            "description": "The band across the form’s top: a colour or gradient, and a pattern. No pictures.",
+            "properties": {
+              "angle": {
+                "description": "The gradient’s angle in degrees (default 160).",
+                "type": "number"
+              },
+              "color": {
+                "description": "A solid band.",
+                "type": "string"
+              },
+              "gradient": {
+                "additionalItems": false,
+                "description": "A two-stop gradient: the colours it runs from and to.",
+                "items": [
+                  {
+                    "description": "A hex colour such as #0f172a.",
+                    "type": "string"
+                  },
+                  {
+                    "description": "A hex colour such as #0f172a.",
+                    "type": "string"
+                  }
+                ],
+                "maxItems": 2,
+                "minItems": 2,
+                "type": "array"
+              },
+              "motion": {
+                "description": "A gradient that moves on screen (still in pictures and under reduced motion).",
+                "enum": [
+                  "flow",
+                  "drift",
+                  "aurora",
+                  "ripple",
+                  "ribbons",
+                  "mesh",
+                  "starfield",
+                  "retro-grid",
+                  "bokeh",
+                  "waves",
+                  "spotlight",
+                  "beams",
+                  "sunburst",
+                  "fireflies",
+                  "snowfall",
+                  "lava",
+                  "dot-wave",
+                  "clouds",
+                  "warp",
+                  "orbits",
+                  "radar",
+                  "equaliser",
+                  "confetti",
+                  "threads"
+                ],
+                "type": "string"
+              },
+              "pattern": {
+                "description": "A pattern over the colour.",
+                "enum": [
+                  "dots",
+                  "grid",
+                  "lines"
+                ],
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "The cover band; null removes it. The form’s own colour (bars, buttons) is its tab theme’s: set theme to match a cover."
+      },
+      "description": {
+        "type": "string"
+      },
+      "heading": {
+        "description": "The form’s heading and its tab’s name, up to 80.",
+        "type": "string"
+      },
+      "op": {
+        "const": "set_form",
+        "type": "string"
+      },
+      "theme": {
+        "description": "The Form tab’s theme (mocha, ocean, forest...): the form’s colour, font and finish follow it.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "op"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "closedMessage": {
+        "description": "Shown on the link once closed, up to 500 characters; null for the default.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "closesAt": {
+        "description": "When the form stops taking responses, an ISO date and time; one with no offset (no Z or +hh:mm) is UTC. Respondents are not shown it beforehand: say it in the description if they should know. null clears it.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "confirmation": {
+        "description": "Shown after submitting, up to 500 characters; null for the default.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "limit": {
+        "anyOf": [
+          {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "The most responses it takes (each submission counts one, whatever it holds), 1 to 2000; null clears it."
+      },
+      "op": {
+        "const": "settings",
+        "type": "string"
+      }
+    },
+    "required": [
+      "op"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "board": {
+        "description": "An existing Board tab’s name (or its board’s title). Absent: a new Board tab \"<Form> Responses\" with New, In Progress and Done, taking the form’s card type alone.",
+        "type": "string"
+      },
+      "cardType": {
+        "description": "The card type each response becomes, by name. A name the document lacks brings in the ready-made type of that name (Bug, Idea, Candidate, Request...) or makes a new one. Absent: the form’s own, the board’s first, or a new type named after the form.",
+        "type": "string"
+      },
+      "column": {
+        "description": "An existing board’s column, by name. Absent: its first.",
+        "type": "string"
+      },
+      "op": {
+        "const": "responds_to",
+        "type": "string"
+      },
+      "sheet": {
+        "description": "An existing sheet, by its Sheet tab’s name. Absent: a new Sheet tab \"<Form> Responses\", its header row a column per question.",
+        "type": "string"
+      },
+      "to": {
+        "description": "Cards on a board (to work through) or rows in a sheet (to count).",
+        "enum": [
+          "board",
+          "sheet"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "to",
+      "op"
+    ],
+    "type": "object"
+  }
+]
  2. Added

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds substantially more: changes apply in order as a single write, a refusal names its change and writes nothing (all-or-nothing), concurrent viewers 'see it at once', and the response-taking restriction forces share_form first. These are exactly the mutation semantics an agent needs and none are derivable from 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.

Conciseness4/5

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

The first clause front-loads verb, resource and the atomic-write trait before the op list, and each subsequent sentence carries a constraint (refusal behavior, response-taking restriction, live visibility). It is dense and somewhat run-on, but no sentence is filler.

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

Completeness5/5

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

Given a 3-parameter tool with a deeply nested changes array (10 ops), full schema coverage and an output schema, the description supplies what structured fields cannot: ordering/atomicity semantics, refusal behavior, the response-taking restriction, and live-collaboration effects. An agent can call this correctly without further guidance.

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 description coverage is 100%, so the baseline is 3. The description's addition ('Questions by id or prompt, sections by id, title or place') largely restates what the schema already documents for the question and section fields, and it does not explain the changes array structure or the maxItems=50 cap beyond what the schema states.

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 a specific verb and resource ('Change a form') and then enumerates all ten supported operations by name, which lets an agent distinguish it from read_form, add_form and share_form without opening any schema. It also states the atomic scope ('in order, as one write'), which is the key behavioral trait of this tool.

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?

It gives a concrete selection rule and names the alternative: while a form takes responses only settings can change and 'close it with share_form first (the link stays)'. That is real when-to-use guidance tied to a sibling. There is no explicit exclusion list for the read/creation siblings, so it stops short of a full 5.

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

All livediagram toolsInspect
Try in Browser
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources