mcp-google-workspace

Overview Schema Source Related Servers Discussions Admin

Prepare Workspace Action

prepare_workspace_action

Read-onlyIdempotent

Previews consequential Google Workspace actions and binds them to a one-time commit token so clients that cannot prompt users can obtain consent before committing.

Instructions

Preview a consequential call (sending mail, sharing, permanent deletion, forwarding, a bulk change) and bind it to a one-time commit token, for clients that cannot ask the user directly: a direct call of such a tool fails with confirmation_required and names this tool as the next step. Nothing runs here. Returns status 'prepared', action, preview (the exact text to show the user before committing), commit_token, expires_at (epoch seconds, 10 minutes ahead by default) and next_action; a call that needs no consent fails with invalid_input naming the direct call.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "arguments": "<arguments>",
      "tool_name": "<tool_name>"
    },
    "name": "prepare_workspace_action"
  }
}

Input Schema

Name	Required	Description	Default
`arguments`	Yes	The arguments for tool_name exactly as in a direct call, as in that required_action. They are validated now and bound to the token; they cannot be edited afterwards.
`tool_name`	Yes	Published name of the tool to run, as in the required_action of its confirmation_required error, e.g. 'gmail_send_email'.

Output Schema

Name	Required	Description
`action`	No
`status`	No	Machine-readable operation status.
`preview`	No
`expires_at`	No
`next_action`	No
`commit_token`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed18 schema fields changedv2.1.0Nov 6, 2026

removedInput schema / maxProperties
```
Removed value: -10000
```

changedInput schema / properties / arguments / description

Previous value: -"Exact keyword arguments to bind and later execute unchanged for tool_name."New value: +"The arguments for tool_name exactly as in a direct call, as in that required_action. They are validated now and bound to the token; they cannot be edited afterwards."

removedInput schema / properties / arguments / maxProperties
```
Removed value: -10000
```

changedInput schema / properties / tool_name / description

Previous value: -"Full name of the consequential tool to prepare; must be one of ['calendar_update_event', 'drive_create_permission', 'gmail_batch_modify', 'gmail_send_email', 'sheets_batch_update_spreadsheet']. Other tools do not use the prepare/commit protocol."New value: +"Published name of the tool to run, as in the required_action of its confirmation_required error, e.g. 'gmail_send_email'."

removedInput schema / properties / tool_name / maxLength
```
Removed value: -1000000
```
changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```

removedOutput schema / description

Removed value: -"Documented structured response returned by this MCP tool."

addedOutput schema / properties / action

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / commit_token / description
```
Removed value: -"Response field: commit token."
```

removedOutput schema / properties / context

Removed value: -{
-  "description": "Identifying request arguments echoed back with an error.",
-  "type": "object"
-}

removedOutput schema / properties / error

Removed value: -{
-  "description": "Error message or structured error details when the call failed.",
-  "type": [
-    "object",
-    "string"
-  ]
-}

removedOutput schema / properties / expires_at / description
```
Removed value: -"Response field: expires at."
```

removedOutput schema / properties / impact

Removed value: -{
-  "description": "Response field: impact.",
-  "type": "object"
-}

removedOutput schema / properties / next_action / description
```
Removed value: -"Response field: next action."
```
addedOutput schema / properties / preview
```
Added value: +{}
```

removedOutput schema / properties / provider_status

Removed value: -{
-  "description": "HTTP status code returned by the Google API for a failed call.",
-  "type": "integer"
-}

removedOutput schema / properties / resource

Removed value: -{
-  "additionalProperties": false,
-  "description": "Stable cross-tool Workspace resource handle when applicable.",
-  "properties": {
-    "etag": {
-      "description": "Provider entity tag.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "id": {
-      "description": "Provider resource identifier.",
-      "type": "string"
-    },
-    "kind": {
-      "description": "Workspace resource kind.",
-      "type": "string"
-    },
-    "mime_type": {
-      "description": "MIME type when applicable.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "modified_at": {
-      "description": "Last modification time.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "name": {
-      "description": "Human-readable name.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "uri": {
-      "description": "Stable Workspace resource URI.",
-      "type": "string"
-    },
-    "web_url": {
-      "description": "Provider web URL.",
-      "type": [
-        "string",
-        "null"
-      ]
-    }
-  },
-  "required": [
-    "kind",
-    "id",
-    "uri"
-  ],
-  "type": "object"
-}

removedOutput schema / title

Removed value: -"Prepare Workspace Action response"

Changed3 schema fields changedv0.3.10Aug 8, 2026

addedOutput schema / properties / context

Added value: +{
+  "description": "Identifying request arguments echoed back with an error.",
+  "type": "object"
+}

addedOutput schema / properties / error

Added value: +{
+  "description": "Error message or structured error details when the call failed.",
+  "type": [
+    "object",
+    "string"
+  ]
+}

addedOutput schema / properties / provider_status

Added value: +{
+  "description": "HTTP status code returned by the Google API for a failed call.",
+  "type": "integer"
+}

First observedv0.3.7Jul 29, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false), it discloses that nothing executes, that the token is one-time and expires (epoch seconds, 10 minutes by default), that arguments are validated now and immutable afterwards, and which error codes signal which recovery path. This is fully consistent with the read-only, non-destructive annotation profile.

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 description is front-loaded with the purpose then the failure/recovery flow, and every sentence carries information. It is dense but somewhat run-on, packing return fields and error behavior into long clauses that could be split for faster scanning.

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?

The description covers trigger, non-trigger, immutability constraint, token lifetime, and the recovery path, which is everything an agent needs for a two-parameter confirmation broker. Listing the return fields is mildly redundant given the output schema, but it usefully frames the next_action handoff rather than just restating types.

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 coverage is 100%, so both parameters are already documented in the schema, including that arguments must match the direct call and cannot be edited after binding. The description reinforces the recovery flow but adds no new syntax or format detail beyond what the schema and the required_action error already provide.

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 states a specific verb and resource ('Preview a consequential call ... and bind it to a one-time commit token') and enumerates the covered cases (sending mail, sharing, permanent deletion, forwarding, bulk change). It is clearly distinguishable from the sibling commit_workspace_action, since this tool explicitly says 'Nothing runs here.'

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 the exact trigger condition: a direct call of such a tool fails with confirmation_required and names this tool as the next step, and it targets clients that cannot ask the user directly. It also states the negative case – a call needing no consent fails with invalid_input naming the direct call – so the agent knows when to skip this tool.

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

Deploy Server