grr

Overview Schema Source Related Servers Discussions Admin

forms.forms.create

Create an empty form with a title and optional document title, then add items via a separate update call.

Instructions

Create a new form using the title given in the provided form message in the request. Important: Only the form.info.title and form.info.document_title fields are copied to the new form. All other fields including the form description, items and settings are disallowed. To create a new form and add items, you must first call forms.create to create an empty form with a title and (optional) document title, and then call forms.update to add the items [HTTP POST] — creates or triggers a change; refused under --readonly safety profiles. Returns the API's response resource as JSON — request body is a JSON Form object accepting formId, info, items, linkedSheetId, publishSettings, responderUri, revisionId, settings; pass it via params or whole via body_file Siblings over the same resource: batchUpdate, get, setPublishSettings.

Input Schema

Name	Required	Description
`query`	No	Extra KEY=VALUE query pairs for endpoints whose parameters Discovery does not describe.
`params`	No	Parameter map merged into the request; typed parameters win.
`dry_run`	No	Return the request that would be sent, without sending it.
`body_file`	No	Read the request body from this file ('-' for stdin) instead of building one from the parameters. The body is a JSON Form object.
`unpublished`	No	[query parameter] Optional. Whether the form is unpublished. If set to `true`, the form doesn't accept responses. If set to `false` or unset, the form is published and accepts re
`request_body`	No	Request body of type Form: pass it via `params` (merged into the built body) or whole via `body_file`.

Output Schema

Name	Required	Description	Default
`info`	No
`items`	No
`formId`	No
`settings`	No
`revisionId`	No
`responderUri`	No
`linkedSheetId`	No
`publishSettings`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 26, 2026

changedInput schema / properties / body_file / description

Previous value: -"Read the request body from this file ('-' for stdin) instead of building one from the parameters."New value: +"Read the request body from this file ('-' for stdin) instead of building one from the parameters. The body is a JSON Form object."

addedInput schema / properties / request_body

Added value: +{
+  "description": "Request body of type Form: pass it via `params` (merged into the built body) or whole via `body_file`.",
+  "properties": {
+    "formId": {
+      "type": "string"
+    },
+    "info": {
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "documentTitle": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "items": {
+      "items": {
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "imageItem": {
+            "properties": {
+              "image": {
+                "properties": {
+                  "altText": {
+                    "type": "string"
+                  },
+                  "contentUri": {
+                    "type": "string"
+                  },
+                  "properties": {
+                    "type": "object"
+                  },
+                  "sourceUri": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "itemId": {
+            "type": "string"
+          },
+          "pageBreakItem": {
+            "type": "object"
+          },
+          "questionGroupItem": {
+            "properties": {
+              "grid": {
+                "properties": {
+                  "columns": {
+                    "type": "object"
+                  },
+                  "shuffleQuestions": {
+                    "type": "boolean"
+                  }
+                },
+                "type": "object"
+              },
+              "image": {
+                "properties": {
+                  "altText": {
+                    "type": "string"
+                  },
+                  "contentUri": {
+                    "type": "string"
+                  },
+                  "properties": {
+                    "type": "object"
+                  },
+                  "sourceUri": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "questions": {
+                "items": {
+                  "properties": {
+                    "choiceQuestion": {
+                      "type": "object"
+                    },
+                    "dateQuestion": {
+                      "type": "object"
+                    },
+                    "fileUploadQuestion": {
+                      "type": "object"
+                    },
+                    "grading": {
+                      "type": "object"
+                    },
+                    "questionId": {
+                      "type": "string"
+                    },
+                    "ratingQuestion": {
+                      "type": "object"
+                    },
+                    "required": {
+                      "type": "boolean"
+                    },
+                    "rowQuestion": {
+                      "type": "object"
+                    },
+                    "scaleQuestion": {
+                      "type": "object"
+                    },
+                    "textQuestion": {
+                      "type": "object"
+                    },
+                    "timeQuestion": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          "questionItem": {
+            "properties": {
+              "image": {
+                "properties": {
+                  "altText": {
+                    "type": "string"
+                  },
+                  "contentUri": {
+                    "type": "string"
+                  },
+                  "properties": {
+                    "type": "object"
+                  },
+                  "sourceUri": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "question": {
+                "properties": {
+                  "choiceQuestion": {
+                    "type": "object"
+                  },
+                  "dateQuestion": {
+                    "type": "object"
+                  },
+                  "fileUploadQuestion": {
+                    "type": "object"
+                  },
+                  "grading": {
+                    "type": "object"
+                  },
+                  "questionId": {
+                    "type": "string"
+                  },
+                  "ratingQuestion": {
+                    "type": "object"
+                  },
+                  "required": {
+                    "type": "boolean"
+                  },
+                  "rowQuestion": {
+                    "type": "object"
+                  },
+                  "scaleQuestion": {
+                    "type": "object"
+                  },
+                  "textQuestion": {
+                    "type": "object"
+                  },
+                  "timeQuestion": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "textItem": {
+            "type": "object"
+          },
+          "title": {
+            "type": "string"
+          },
+          "videoItem": {
+            "properties": {
+              "caption": {
+                "type": "string"
+              },
+              "video": {
+                "properties": {
+                  "properties": {
+                    "type": "object"
+                  },
+                  "youtubeUri": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "linkedSheetId": {
+      "type": "string"
+    },
+    "publishSettings": {
+      "properties": {
+        "publishState": {
+          "properties": {
+            "isAcceptingResponses": {
+              "type": "boolean"
+            },
+            "isPublished": {
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    "responderUri": {
+      "type": "string"
+    },
+    "revisionId": {
+      "type": "string"
+    },
+    "settings": {
+      "properties": {
+        "emailCollectionType": {
+          "enum": [
+            "EMAIL_COLLECTION_TYPE_UNSPECIFIED",
+            "DO_NOT_COLLECT",
+            "VERIFIED",
+            "RESPONDER_INPUT"
+          ],
+          "type": "string"
+        },
+        "quizSettings": {
+          "properties": {
+            "isQuiz": {
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

Changed2 schema fields changedOct 26, 2026

changedInput schema / properties / unpublished / description

Previous value: -"Optional. Whether the form is unpublished. If set to `true`, the form doesn't accept responses. If set to `false` or unset, the form is published and accepts re"New value: +"[query parameter] Optional. Whether the form is unpublished. If set to `true`, the form doesn't accept responses. If set to `false` or unset, the form is published and accepts re"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "formId": {
+      "type": "string"
+    },
+    "info": {
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "documentTitle": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "items": {
+      "items": {
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "imageItem": {
+            "properties": {
+              "image": {
+                "properties": {
+                  "altText": {
+                    "type": "string"
+                  },
+                  "contentUri": {
+                    "type": "string"
+                  },
+                  "properties": {
+                    "type": "object"
+                  },
+                  "sourceUri": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "itemId": {
+            "type": "string"
+          },
+          "pageBreakItem": {
+            "type": "object"
+          },
+          "questionGroupItem": {
+            "properties": {
+              "grid": {
+                "properties": {
+                  "columns": {
+                    "type": "object"
+                  },
+                  "shuffleQuestions": {
+                    "type": "boolean"
+                  }
+                },
+                "type": "object"
+              },
+              "image": {
+                "properties": {
+                  "altText": {
+                    "type": "string"
+                  },
+                  "contentUri": {
+                    "type": "string"
+                  },
+                  "properties": {
+                    "type": "object"
+                  },
+                  "sourceUri": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "questions": {
+                "items": {
+                  "properties": {
+                    "choiceQuestion": {
+                      "type": "object"
+                    },
+                    "dateQuestion": {
+                      "type": "object"
+                    },
+                    "fileUploadQuestion": {
+                      "type": "object"
+                    },
+                    "grading": {
+                      "type": "object"
+                    },
+                    "questionId": {
+                      "type": "string"
+                    },
+                    "ratingQuestion": {
+                      "type": "object"
+                    },
+                    "required": {
+                      "type": "boolean"
+                    },
+                    "rowQuestion": {
+                      "type": "object"
+                    },
+                    "scaleQuestion": {
+                      "type": "object"
+                    },
+                    "textQuestion": {
+                      "type": "object"
+                    },
+                    "timeQuestion": {
+                      "type": "object"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          "questionItem": {
+            "properties": {
+              "image": {
+                "properties": {
+                  "altText": {
+                    "type": "string"
+                  },
+                  "contentUri": {
+                    "type": "string"
+                  },
+                  "properties": {
+                    "type": "object"
+                  },
+                  "sourceUri": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "question": {
+                "properties": {
+                  "choiceQuestion": {
+                    "type": "object"
+                  },
+                  "dateQuestion": {
+                    "type": "object"
+                  },
+                  "fileUploadQuestion": {
+                    "type": "object"
+                  },
+                  "grading": {
+                    "type": "object"
+                  },
+                  "questionId": {
+                    "type": "string"
+                  },
+                  "ratingQuestion": {
+                    "type": "object"
+                  },
+                  "required": {
+                    "type": "boolean"
+                  },
+                  "rowQuestion": {
+                    "type": "object"
+                  },
+                  "scaleQuestion": {
+                    "type": "object"
+                  },
+                  "textQuestion": {
+                    "type": "object"
+                  },
+                  "timeQuestion": {
+                    "type": "object"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "textItem": {
+            "type": "object"
+          },
+          "title": {
+            "type": "string"
+          },
+          "videoItem": {
+            "properties": {
+              "caption": {
+                "type": "string"
+              },
+              "video": {
+                "properties": {
+                  "properties": {
+                    "type": "object"
+                  },
+                  "youtubeUri": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "linkedSheetId": {
+      "type": "string"
+    },
+    "publishSettings": {
+      "properties": {
+        "publishState": {
+          "properties": {
+            "isAcceptingResponses": {
+              "type": "boolean"
+            },
+            "isPublished": {
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    "responderUri": {
+      "type": "string"
+    },
+    "revisionId": {
+      "type": "string"
+    },
+    "settings": {
+      "properties": {
+        "emailCollectionType": {
+          "enum": [
+            "EMAIL_COLLECTION_TYPE_UNSPECIFIED",
+            "DO_NOT_COLLECT",
+            "VERIFIED",
+            "RESPONDER_INPUT"
+          ],
+          "type": "string"
+        },
+        "quizSettings": {
+          "properties": {
+            "isQuiz": {
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

First observedOct 26, 2026

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the burden and does well: it discloses the mutation verb, the read-only refusal condition, the surprising destructive-ish semantics that all other supplied fields (description, items, settings) are silently not applied, and that the API response resource is returned as JSON. It does not cover auth/scopes or error behavior, leaving a small gap.

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 critical restriction and the create-then-update workflow are front-loaded, which is good, but the text is a dense run-on mixing documentation, a bracketed '[HTTP POST]' transport note, a body-delivery explanation, and a sibling list. Several of those clauses are boilerplate that dilutes the two sentences an agent actually needs.

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?

For a 6-parameter, deeply nested body tool with an output schema, the description supplies the decisive context: fields that will be ignored, the two-step creation pattern, and how to pass the body. Only minor gaps remain (auth/permission requirements, and the camelCase mismatch between 'document_title' in prose and 'documentTitle' in the schema).

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 real meaning: it enumerates the body fields (formId, info, items, linkedSheetId, publishSettings, responderUri, revisionId, settings) and explains the two delivery paths (`params` vs whole `body_file`). Crucially it warns that items and settings in that body will not take effect — information the schema alone actively misleads on.

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 specific verb and resource ('Create a new form using the title given in the provided form message') and immediately scopes it: only form.info.title and document_title are used. It also names the sibling tools over the same resource (batchUpdate, get, setPublishSettings), so the agent can place it in the family without opening schemas.

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?

Gives an explicit workflow: create an empty form here, then call forms.update to add items, which is exactly the decision an agent is likely to get wrong. It also flags that the call is refused under --readonly profiles. It stops short of fully routing between the listed siblings (batchUpdate/get/setPublishSettings), which is why this is a 4 rather than a 5.

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

Deploy Server