grr

Overview Schema Source Related Servers Discussions Admin

drive.permissions.create

Creates a permission on a file or shared drive to grant users, groups, or domains access with a specified role. Use it to share Drive items via the API.

Instructions

Creates a permission for a file or shared drive. For more information, see Share files, folders, and drives. Warning: Concurrent permission modifications (such as update or delete) on the same file, folder, or shared drive aren't supported across any users or clients; only the last update is applied [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 Permission object accepting allowFileDiscovery, deleted, displayName, domain, emailAddress, expirationTime, id, inheritedPermissionsDisabled and 8 more fields; pass it via params or whole via body_file Siblings over the same resource: delete, get, list, update.

Input Schema

Name	Required	Description	Default
`query`	No	Extra KEY=VALUE query pairs for endpoints whose parameters Discovery does not describe.
`fileId`	Yes	[URL path segment] The ID of the file or shared drive.
`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 Permission object.
`emailMessage`	No	[query parameter] A plain text custom message to include in the notification email.
`request_body`	No	Request body of type Permission: pass it via `params` (merged into the built body) or whole via `body_file`.
`supportsAllDrives`	No	[query parameter] Whether the requesting application supports both My Drives and shared drives.	false
`transferOwnership`	No	[query parameter] Whether to transfer ownership to the specified user and downgrade the current owner to a writer. This parameter is required as an acknowledgement of the side ef	false
`supportsTeamDrives`	No	[query parameter] Deprecated: Use `supportsAllDrives` instead.	false
`enforceSingleParent`	No	[query parameter] Deprecated: See `moveToNewOwnersRoot` for details.	false
`moveToNewOwnersRoot`	No	[query parameter] This parameter only takes effect if the item isn't in a shared drive and the request is attempting to transfer the ownership of the item. If set to `true`, the	false
`useDomainAdminAccess`	No	[query parameter] Issue the request as a domain administrator. If set to `true`, and if the following additional conditions are met, the requester is granted access: 1. The file	false
`sendNotificationEmail`	No	[query parameter] Whether to send a notification email when sharing to users or groups. This defaults to `true` for users and groups, and is not allowed for other requests. It mu
`enforceExpansiveAccess`	No	[query parameter] Deprecated: All requests use the expansive access rules.	false

Output Schema

Name	Required	Description	Default
`id`	No
`kind`	No
`role`	No
`type`	No
`view`	No
`domain`	No
`deleted`	No
`photoLink`	No
`displayName`	No
`emailAddress`	No
`pendingOwner`	No
`expirationTime`	No
`permissionDetails`	No
`allowFileDiscovery`	No
`teamDrivePermissionDetails`	No
`inheritedPermissionsDisabled`	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 Permission object."

addedInput schema / properties / request_body

Added value: +{
+  "description": "Request body of type Permission: pass it via `params` (merged into the built body) or whole via `body_file`.",
+  "properties": {
+    "allowFileDiscovery": {
+      "type": "boolean"
+    },
+    "deleted": {
+      "type": "boolean"
+    },
+    "displayName": {
+      "type": "string"
+    },
+    "domain": {
+      "type": "string"
+    },
+    "emailAddress": {
+      "type": "string"
+    },
+    "expirationTime": {
+      "type": "string"
+    },
+    "id": {
+      "type": "string"
+    },
+    "inheritedPermissionsDisabled": {
+      "type": "boolean"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "pendingOwner": {
+      "type": "boolean"
+    },
+    "permissionDetails": {
+      "items": {
+        "properties": {
+          "inherited": {
+            "type": "boolean"
+          },
+          "inheritedFrom": {
+            "type": "string"
+          },
+          "permissionType": {
+            "type": "string"
+          },
+          "role": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "photoLink": {
+      "type": "string"
+    },
+    "role": {
+      "type": "string"
+    },
+    "teamDrivePermissionDetails": {
+      "items": {
+        "properties": {
+          "inherited": {
+            "type": "boolean"
+          },
+          "inheritedFrom": {
+            "type": "string"
+          },
+          "role": {
+            "type": "string"
+          },
+          "teamDrivePermissionType": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "type": {
+      "type": "string"
+    },
+    "view": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Changed18 schema fields changedOct 26, 2026

changedInput schema / properties / emailMessage / description

Previous value: -"A plain text custom message to include in the notification email."New value: +"[query parameter] A plain text custom message to include in the notification email."

addedInput schema / properties / enforceExpansiveAccess / default
```
Added value: +"false"
```

changedInput schema / properties / enforceExpansiveAccess / description

Previous value: -"Deprecated: All requests use the expansive access rules."New value: +"[query parameter] Deprecated: All requests use the expansive access rules."

addedInput schema / properties / enforceSingleParent / default
```
Added value: +"false"
```

changedInput schema / properties / enforceSingleParent / description

Previous value: -"Deprecated: See `moveToNewOwnersRoot` for details."New value: +"[query parameter] Deprecated: See `moveToNewOwnersRoot` for details."

changedInput schema / properties / fileId / description

Previous value: -"The ID of the file or shared drive."New value: +"[URL path segment] The ID of the file or shared drive."

addedInput schema / properties / moveToNewOwnersRoot / default
```
Added value: +"false"
```

changedInput schema / properties / moveToNewOwnersRoot / description

Previous value: -"This parameter only takes effect if the item isn't in a shared drive and the request is attempting to transfer the ownership of the item. If set to `true`, the "New value: +"[query parameter] This parameter only takes effect if the item isn't in a shared drive and the request is attempting to transfer the ownership of the item. If set to `true`, the "

changedInput schema / properties / sendNotificationEmail / description

Previous value: -"Whether to send a notification email when sharing to users or groups. This defaults to `true` for users and groups, and is not allowed for other requests. It mu"New value: +"[query parameter] Whether to send a notification email when sharing to users or groups. This defaults to `true` for users and groups, and is not allowed for other requests. It mu"

addedInput schema / properties / supportsAllDrives / default
```
Added value: +"false"
```

changedInput schema / properties / supportsAllDrives / description

Previous value: -"Whether the requesting application supports both My Drives and shared drives."New value: +"[query parameter] Whether the requesting application supports both My Drives and shared drives."

addedInput schema / properties / supportsTeamDrives / default
```
Added value: +"false"
```

changedInput schema / properties / supportsTeamDrives / description

Previous value: -"Deprecated: Use `supportsAllDrives` instead."New value: +"[query parameter] Deprecated: Use `supportsAllDrives` instead."

addedInput schema / properties / transferOwnership / default
```
Added value: +"false"
```

changedInput schema / properties / transferOwnership / description

Previous value: -"Whether to transfer ownership to the specified user and downgrade the current owner to a writer. This parameter is required as an acknowledgement of the side ef"New value: +"[query parameter] Whether to transfer ownership to the specified user and downgrade the current owner to a writer. This parameter is required as an acknowledgement of the side ef"

addedInput schema / properties / useDomainAdminAccess / default
```
Added value: +"false"
```

changedInput schema / properties / useDomainAdminAccess / description

Previous value: -"Issue the request as a domain administrator. If set to `true`, and if the following additional conditions are met, the requester is granted access: 1. The file "New value: +"[query parameter] Issue the request as a domain administrator. If set to `true`, and if the following additional conditions are met, the requester is granted access: 1. The file "

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "allowFileDiscovery": {
+      "type": "boolean"
+    },
+    "deleted": {
+      "type": "boolean"
+    },
+    "displayName": {
+      "type": "string"
+    },
+    "domain": {
+      "type": "string"
+    },
+    "emailAddress": {
+      "type": "string"
+    },
+    "expirationTime": {
+      "type": "string"
+    },
+    "id": {
+      "type": "string"
+    },
+    "inheritedPermissionsDisabled": {
+      "type": "boolean"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "pendingOwner": {
+      "type": "boolean"
+    },
+    "permissionDetails": {
+      "items": {
+        "properties": {
+          "inherited": {
+            "type": "boolean"
+          },
+          "inheritedFrom": {
+            "type": "string"
+          },
+          "permissionType": {
+            "type": "string"
+          },
+          "role": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "photoLink": {
+      "type": "string"
+    },
+    "role": {
+      "type": "string"
+    },
+    "teamDrivePermissionDetails": {
+      "items": {
+        "properties": {
+          "inherited": {
+            "type": "boolean"
+          },
+          "inheritedFrom": {
+            "type": "string"
+          },
+          "role": {
+            "type": "string"
+          },
+          "teamDrivePermissionType": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "type": {
+      "type": "string"
+    },
+    "view": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedOct 26, 2026

TDQS

A4/5.0

Behavior4/5

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

With no annotations present, the description carries the full burden and does substantial work: it discloses the concurrency caveat (last-write-wins across clients), that this is an HTTP POST mutation refused under readonly safety profiles, and that a JSON Permission resource is returned. It stops short of stating the authorization prerequisites (owner/sharing rights) needed to create a permission, which is a meaningful gap for a mutation.

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?

Purpose is front-loaded in the first sentence and the concurrency warning is prominent. The trailing field enumeration ("allowFileDiscovery, deleted, displayName...") and the bracket-tag HTTP POST boilerplate are partly redundant with the schema and dilute the prose slightly, but overall it is compact for the amount of content.

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?

For a 15-parameter mutation with 100% schema coverage and an output schema, the description supplies the missing behavioral layer (concurrency caveat, readonly refusal, response shape, body-passing mechanism). An agent has enough to call it correctly without additional docs.

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 every parameter is documented in the schema itself. The description adds only a partial field list for the Permission body plus the params/body_file mechanism, which is marginal value beyond the structured schema; baseline 3 applies.

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?

Opens with a specific verb and resource ("Creates a permission for a file or shared drive") and explicitly enumerates the sibling operations (delete, get, list, update) over the same resource, so an agent can place it precisely among the permissions family.

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

Usage Guidelines3/5

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

The sibling list implies this is the create-side operation versus read/update/delete, but no conditional routing guidance is given (e.g., when to grant a permission here vs. via update to an existing one, or when to use transferOwnership). Usage is implied rather than stated.

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

Deploy Server