---
name: "google_forms"
description: "Read, create, and update the user's Google Forms, and read responses."
metadata: { "includeInPrompt": false }
---
# Google Forms
## Purpose
Manage Google Forms through `hatch_gws_cli`; the vendored Google Workspace CLI is the only implementation path.
## Tooling
Use `exec` to run:
```sh
hatch_gws_cli forms <resource> <method> [flags]
```
### Connection management
```sh
hatch_gws_cli forms status
hatch_gws_cli forms disconnect
```
### Forms operations
Core patterns:
- `hatch_gws_cli forms status`
- `hatch_gws_cli forms disconnect`
- `hatch_gws_cli schema forms.forms.get`
- `hatch_gws_cli schema forms.forms.create`
- `hatch_gws_cli schema forms.forms.batchUpdate`
- `hatch_gws_cli schema forms.forms.responses.list`
- `hatch_gws_cli schema forms.forms.responses.get`
Common raw API calls:
- `hatch_gws_cli forms forms get --params '{"formId":"<form_id>"}'`
- `hatch_gws_cli forms forms create --json '{"info":{"title":"Feedback Survey","documentTitle":"Feedback Survey"}}'`
- `hatch_gws_cli forms forms batchUpdate --params '{"formId":"<form_id>"}' --json '{"requests":[{"updateFormInfo":{"info":{"description":"Quarterly survey"},"updateMask":"description"}}]}'`
- `hatch_gws_cli forms forms responses list --params '{"formId":"<form_id>","pageSize":20}'`
- `hatch_gws_cli forms forms responses get --params '{"formId":"<form_id>","responseId":"<response_id>"}'`
JSON output contract:
- `status`: parse `status`, `connect_url`, and `disconnect_url`
- `disconnect`: parse `ok`, `action`, `status`, and `disconnect_url`
## Auth
Authentication is handled by the wrapper's `status` and `disconnect` subcommands. Do not hand-write credential files or run raw `gws auth ...`.
## First-use setup flow
1. Run `hatch_gws_cli forms status`.
2. If `status` is `unavailable`, tell the user that Google Forms is not available on this device. Do not offer alternative integration approaches or ask the user for credentials.
3. If `status` is `not_connected` and `connect_url` is present, replace `<connect_url>` with the returned URL and share exactly this Markdown link: `[Connect Google Forms](<connect_url>)`; do not paste the raw URL separately. Wait for the user to reconnect.
4. Once `status` is `connected`, proceed with Forms operations.
## Operating Rules
1. Use `schema` before unfamiliar Forms methods so `--params` and `--json` match the current vendored CLI contract.
2. Creating a form and editing an unpublished form owned only by the user may proceed from a clear request. Confirm before editing a shared or published form, or publishing one, because its contents can reach other people.
3. Run `forms.get` before presenting response data so you can map question IDs to human-readable form structure.
4. Treat form IDs and response IDs as opaque strings and only use IDs returned by prior commands or explicit user input.
5. Run `hatch_gws_cli forms disconnect`. After running it, when `disconnect_url` is present, replace `<disconnect_url>` with the returned URL and share exactly this Markdown link: `[Disconnect Google Forms](<disconnect_url>)`; do not paste the raw URL separately.
6. Paginate through responses when the user asks for all responses; stop when `nextPageToken` is absent.
7. After a read or write action, confirm the user-visible result only. Do not surface raw API identifiers (form, response, and question IDs) or other internal response fields (page tokens/cursors, raw JSON) in text shown to the user unless the user asks for them or you need them to troubleshoot a failure; keep using them internally to chain follow-up commands.
8. Response reads retain Google's raw timestamps and add semantic UTC and
user-local forms for response creation/submission times.