Skip to main content
Glama
Sign In

Atwork

by so.atwork
OverviewDiscussionsAdmin

Update Form

form.update
DestructiveIdempotent

Change a form (a peek of kind form: it collects new rows): name, description, addFields (names or codes, or { field, required, label, help, placeholder, width }, added at the end), removeFields, editFields (a question's label, required, help, placeholder or width: 25, 50, 75 or 100 percent of the row in the classic layout), order (every question in the new order), layout (classic, or steps: one question at a time), submitLabel (the Submit button's text), visibleWhen (per question: show it only when a sheet.read-style filter on the answers holds; when: null always shows it) successMessage, aiReply (the thank-you screen shows Dana's reply written from each person's answers: a plain-text prompt where {Field name} stands for an answer, and a fallback shown when it is slow; null goes back to the message) and redirect (send people to a web page after they submit; put answers in the link as {Field name}; null goes back to the message). onResponse turns the response emails on or off: notify emails the people you name (members; default you) one email per response with the answers, copy emails the respondent their answers at an Email field on the form (a form anyone with the link can fill needs Block spam first). Pass aiReply or redirect, not both. Only what you pass changes; the other questions and settings stay. Without formId it changes the form open in Form Studio. A record layout (how a row opens) is refused: change it with the peek.* tools. Theme, accent and header: peek.update_options. Publishing, and blocks (a heading, text, image, divider or section), stay in the form builder.

Input Schema

NameRequiredDescriptionDefault
nameNo
orderNoEvery question on the form (field names or codes) in the new order, after addFields and removeFields; headings and other blocks keep their place.
formIdNoThe form's id (sheet.schema lists a sheet's peeks with their kind). Default: the form open in Form Studio.
layoutNoclassic places the questions side by side by width (100% takes the row), steps asks one at a time.
aiReplyNoShow each person an AI reply written from their answers on the thank-you screen; null shows the thank-you message again.
sheetIdNoThe form's sheet. Default: the form's own sheet.
redirectNoSend people to a web page after they submit; null goes back to the thank-you message.
addFieldsNoQuestions to add at the end of the form.
editFieldsNoChange a question's label, required flag, help, placeholder or width; the other questions stay.
onResponseNoThe emails a response sends; only the switch you pass changes.
descriptionNoText shown above the questions.
submitLabelNoThe Submit button's text, in the form's language. Default: Submit in the visitor's language.
visibleWhenNo
removeFieldsNoField names or codes to take off the form.
successMessageNoThank-you message shown after the form is sent (plain text; answer tokens, answers, button and Submit another are set in Form Studio).

Output Schema

NameRequiredDescriptionDefault
fieldsYesThe field names the form asks for now, in order
formIdYes
changedYesWhat was saved
sheetIdYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / onResponse
      Added value: +{
+  "description": "The emails a response sends; only the switch you pass changes.",
+  "properties": {
+    "copy": {
+      "description": "Email the person who filled the form a copy of their answers",
+      "properties": {
+        "field": {
+          "description": "The Email field on the form holding the address; default: the first one",
+          "minLength": 1,
+          "type": "string"
+        },
+        "on": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "on"
+      ],
+      "type": "object"
+    },
+    "notify": {
+      "description": "Email these members one email per response, with the answers",
+      "properties": {
+        "on": {
+          "type": "boolean"
+        },
+        "people": {
+          "description": "Members to email, by name or employee id; default: you",
+          "items": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "maxItems": 20,
+          "type": "array"
+        }
+      },
+      "required": [
+        "on"
+      ],
+      "type": "object"
+    }
+  },
+  "type": "object"
+}
  2. Changed11 schema fields changed
    • changedInput schema / properties / addFields / items / anyOf
      Previous value: -[
-  {
-    "description": "A field name or code",
-    "minLength": 1,
-    "type": "string"
-  },
-  {
-    "properties": {
-      "field": {
-        "description": "A field name or code",
-        "minLength": 1,
-        "type": "string"
-      },
-      "label": {
-        "description": "The question shown on the form. Default: the field name.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "required": {
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "field"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "description": "A field name or code",
+    "minLength": 1,
+    "type": "string"
+  },
+  {
+    "properties": {
+      "field": {
+        "description": "A field name or code",
+        "minLength": 1,
+        "type": "string"
+      },
+      "help": {
+        "description": "Help text shown under the question.",
+        "maxLength": 300,
+        "minLength": 1,
+        "type": "string"
+      },
+      "label": {
+        "description": "The question shown on the form. Default: the field name.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "placeholder": {
+        "description": "Hint shown inside the empty answer box.",
+        "maxLength": 120,
+        "minLength": 1,
+        "type": "string"
+      },
+      "required": {
+        "type": "boolean"
+      },
+      "width": {
+        "anyOf": [
+          {
+            "const": 25,
+            "type": "number"
+          },
+          {
+            "const": 50,
+            "type": "number"
+          },
+          {
+            "const": 75,
+            "type": "number"
+          },
+          {
+            "const": 100,
+            "type": "number"
+          }
+        ],
+        "description": "Share of the row in the classic layout, in percent; steps ignores it. Default 100."
+      }
+    },
+    "required": [
+      "field"
+    ],
+    "type": "object"
+  }
+]
    • addedInput schema / properties / aiReply
      Added value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "fallback": {
+          "description": "Plain text shown instead when the reply can't be written within 15 seconds.",
+          "maxLength": 500,
+          "type": "string"
+        },
+        "prompt": {
+          "description": "What Dana's reply to each person should say, plain text; {Field name} stands for their answer to a question on the form.",
+          "maxLength": 4000,
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "prompt"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Show each person an AI reply written from their answers on the thank-you screen; null shows the thank-you message again."
+}
    • addedInput schema / properties / editFields
      Added value: +{
+  "description": "Change a question's label, required flag, help, placeholder or width; the other questions stay.",
+  "items": {
+    "properties": {
+      "field": {
+        "description": "A field on the form, by name or code",
+        "minLength": 1,
+        "type": "string"
+      },
+      "help": {
+        "description": "Help text shown under the question.",
+        "maxLength": 300,
+        "minLength": 1,
+        "type": "string"
+      },
+      "label": {
+        "description": "The question shown on the form",
+        "minLength": 1,
+        "type": "string"
+      },
+      "placeholder": {
+        "description": "Hint shown inside the empty answer box.",
+        "maxLength": 120,
+        "minLength": 1,
+        "type": "string"
+      },
+      "required": {
+        "type": "boolean"
+      },
+      "width": {
+        "anyOf": [
+          {
+            "const": 25,
+            "type": "number"
+          },
+          {
+            "const": 50,
+            "type": "number"
+          },
+          {
+            "const": 75,
+            "type": "number"
+          },
+          {
+            "const": 100,
+            "type": "number"
+          }
+        ],
+        "description": "Share of the row in the classic layout, in percent; steps ignores it. Default 100."
+      }
+    },
+    "required": [
+      "field"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • changedInput schema / properties / formId / description
      Previous value: -"The form's id (sheet.schema lists a sheet's forms)."New value: +"The form's id (sheet.schema lists a sheet's peeks with their kind). Default: the form open in Form Studio."
    • addedInput schema / properties / layout
      Added value: +{
+  "description": "classic places the questions side by side by width (100% takes the row), steps asks one at a time.",
+  "enum": [
+    "classic",
+    "steps"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / order
      Added value: +{
+  "description": "Every question on the form (field names or codes) in the new order, after addFields and removeFields; headings and other blocks keep their place.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / redirect
      Added value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "notice": {
+          "description": "Show \"Thanks, taking you to <site>…\" for 3 seconds first. Default true.",
+          "type": "boolean"
+        },
+        "url": {
+          "description": "An http or https address; put answers in the link as {Field name}, after the site name (https://example.com/thanks?name={Full name}).",
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "url"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Send people to a web page after they submit; null goes back to the thank-you message."
+}
    • addedInput schema / properties / sheetId / description
      Added value: +"The form's sheet. Default: the form's own sheet."
    • addedInput schema / properties / submitLabel
      Added value: +{
+  "description": "The Submit button's text, in the form's language. Default: Submit in the visitor's language.",
+  "maxLength": 40,
+  "minLength": 1,
+  "type": "string"
+}
    • changedInput schema / properties / successMessage / description
      Previous value: -"Shown after the form is sent."New value: +"Thank-you message shown after the form is sent (plain text; answer tokens, answers, button and Submit another are set in Form Studio)."
    • removedInput schema / required
      Removed value: -[
-  "sheetId",
-  "formId"
-]
  3. Added

TDQS

A4.5/5.0
Behavior4/5

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: only supplied settings change, other questions stay, record layouts are refused, and aiReply/redirect cannot be combined.

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 purpose is front-loaded, but the description is a dense single paragraph that is hard to scan despite covering many parameters. The length is justified by the 15-parameter surface, but the structure could be clearer.

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 the rich annotations, high schema coverage, and existing output schema, the description is complete enough for an agent to call the tool correctly. It covers defaults, exclusions, cross-field constraints, and alternative tools without needing to explain return values.

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 description coverage is high at 87%, so the schema already documents most parameters. The description still adds cross-parameter meaning, such as addFields being appended at the end, order covering every question after add/remove, and the aiReply/redirect exclusivity.

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." It also distinguishes this tool from siblings by naming peek.* for record layouts, peek.update_options for theme/accent/header, and the form builder for publishing and blocks.

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

Usage Guidelines5/5

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

It gives explicit when-to-use context, including the default behavior without formId, the rule that only passed fields change, and the mutual exclusion of aiReply and redirect. It also clearly routes excluded work to the correct alternative tools.

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

All Atwork toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources