Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Search Drive Files

search_drive_files

Read-onlyIdempotent

Search Google Drive for files and folders, including shared drives, using query operators, filters, and sort options to pinpoint the right items.

Instructions

Searches for files and folders within a user's Google Drive, including shared drives.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	Yes	The search query string. Supports Google Drive search operators. NOTE: Owner-based queries ('user@example.com' in owners) DO NOT WORK in Shared Drives because files are owned by the shared drive itself, not individual users. For recent files by a specific user in Shared Drives, search by modifiedTime and use order_by='modifiedTime desc' instead.
`corpora`	No	Bodies of items to query (e.g., 'user', 'domain', 'drive', 'allDrives'). If 'drive_id' is specified and 'corpora' is None, it defaults to 'drive'. Otherwise, Drive API default behavior applies. Prefer 'user' or 'drive' over 'allDrives' for efficiency.
`detailed`	No	Whether to include size, modified time, and link in results. Defaults to True.
`drive_id`	No	ID of the shared drive to search. If None, behavior depends on `corpora` and `include_items_from_all_drives`.
`order_by`	No	Sort order. Comma-separated list of sort keys with optional 'desc' modifier. Valid keys: 'createdTime', 'folder', 'modifiedByMeTime', 'modifiedTime', 'name', 'name_natural', 'quotaBytesUsed', 'recency', 'sharedWithMeTime', 'starred', 'viewedByMeTime'. Example: 'modifiedTime desc' or 'folder,modifiedTime desc,name'. Defaults to None (Drive API default ordering).
`file_type`	No	Restrict results to a specific file type. Accepts a friendly name ('folder', 'document'/'doc', 'spreadsheet'/'sheet', 'presentation'/'slides', 'form', 'drawing', 'pdf', 'shortcut', 'script', 'site', 'jam'/'jamboard') or any raw MIME type string (e.g. 'application/pdf'). Defaults to None (all types).
`page_size`	No	The maximum number of files to return. Defaults to 10.
`page_token`	No	Page token from a previous response's nextPageToken to retrieve the next page of results.
`include_trashed`	No	Whether to include files in the trash. Defaults to False, matching the Drive web UI and `list_drive_items`. Ignored when `query` already contains its own `trashed` clause (`=` or `!=`), which always wins.
`user_google_email`	Yes	The user's Google email address. Required.
`include_items_from_all_drives`	No	Whether shared drive items should be included in results. Defaults to True. This is effective when not specifying a `drive_id`.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv1.28.0Sep 24, 2026

removedInput schema / properties / corpora / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / corpora / type
```
Added value: +"string"
```

removedInput schema / properties / drive_id / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / drive_id / type
```
Added value: +"string"
```

removedInput schema / properties / file_type / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / file_type / type
```
Added value: +"string"
```

removedInput schema / properties / order_by / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / order_by / type
```
Added value: +"string"
```

removedInput schema / properties / page_token / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / page_token / type
```
Added value: +"string"
```

Changed22 schema fields changedv1.0.1Jul 31, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / corpora / description

Added value: +"Bodies of items to query (e.g., 'user', 'domain', 'drive', 'allDrives').\n                     If 'drive_id' is specified and 'corpora' is None, it defaults to 'drive'.\n                     Otherwise, Drive API default behavior applies. Prefer 'user' or 'drive' over 'allDrives' for efficiency."

removedInput schema / properties / corpora / title
```
Removed value: -"Corpora"
```

addedInput schema / properties / detailed

Added value: +{
+  "default": true,
+  "description": "Whether to include size, modified time, and link in results. Defaults to True.",
+  "type": "boolean"
+}

addedInput schema / properties / drive_id / description

Added value: +"ID of the shared drive to search. If None, behavior depends on `corpora` and `include_items_from_all_drives`."

removedInput schema / properties / drive_id / title
```
Removed value: -"Drive Id"
```

addedInput schema / properties / file_type

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Restrict results to a specific file type. Accepts a friendly\n                       name ('folder', 'document'/'doc', 'spreadsheet'/'sheet',\n                       'presentation'/'slides', 'form', 'drawing', 'pdf', 'shortcut',\n                       'script', 'site', 'jam'/'jamboard') or any raw MIME type\n                       string (e.g. 'application/pdf'). Defaults to None (all types)."
+}

addedInput schema / properties / include_items_from_all_drives / description

Added value: +"Whether shared drive items should be included in results. Defaults to True. This is effective when not specifying a `drive_id`."

removedInput schema / properties / include_items_from_all_drives / title
```
Removed value: -"Include Items From All Drives"
```

addedInput schema / properties / include_trashed

Added value: +{
+  "default": false,
+  "description": "Whether to include files in the trash. Defaults to False, matching\n                    the Drive web UI and `list_drive_items`. Ignored when `query` already\n                    contains its own `trashed` clause (`=` or `!=`), which always wins.",
+  "type": "boolean"
+}

addedInput schema / properties / order_by

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Sort order. Comma-separated list of sort keys with optional 'desc' modifier.\n                      Valid keys: 'createdTime', 'folder', 'modifiedByMeTime', 'modifiedTime',\n                      'name', 'name_natural', 'quotaBytesUsed', 'recency', 'sharedWithMeTime',\n                      'starred', 'viewedByMeTime'. Example: 'modifiedTime desc' or 'folder,modifiedTime desc,name'.\n                      Defaults to None (Drive API default ordering)."
+}

addedInput schema / properties / page_size / description

Added value: +"The maximum number of files to return. Defaults to 10."

removedInput schema / properties / page_size / title
```
Removed value: -"Page Size"
```

addedInput schema / properties / page_token

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Page token from a previous response's nextPageToken to retrieve the next page of results."
+}

addedInput schema / properties / query / description

Added value: +"The search query string. Supports Google Drive search operators.\n         NOTE: Owner-based queries ('user@example.com' in owners) DO NOT WORK in Shared Drives\n         because files are owned by the shared drive itself, not individual users.\n         For recent files by a specific user in Shared Drives, search by modifiedTime\n         and use order_by='modifiedTime desc' instead."

removedInput schema / properties / query / title
```
Removed value: -"Query"
```

removedInput schema / properties / service

Removed value: -{
-  "title": "service",
-  "type": "string"
-}

addedInput schema / properties / user_google_email / description
```
Added value: +"The user's Google email address. Required."
```
removedInput schema / properties / user_google_email / title
```
Removed value: -"User Google Email"
```

changedInput schema / required

Previous value: -[
-  "service",
-  "user_google_email",
-  "query"
-]New value: +[
+  "user_google_email",
+  "query"
+]

removedInput schema / title

Removed value: -"search_drive_filesArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object",
+  "x-fastmcp-wrap-result": true
+}

First observedv1.0.0Jun 10, 2025

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behaviorally relevant scope fact that shared drives are included, which is a meaningful trait beyond the annotations. It does not mention pagination or result truncation, but the schema covers those details, so the bar is lower.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the verb and resource, and contains no filler. It earns its place by conveying purpose and shared-drive scope concisely. This is an appropriate size given the rich schema and annotations.

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?

Given the complex 11-parameter schema (100% coverage), the presence of an output schema, and comprehensive annotations, the description does not need to explain return values or parameter details. It provides the essential purpose and the shared-drive nuance. A minor gap is the lack of guidance for choosing search over list operations, but the schema compensates for most missing context.

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 description coverage is 100%, so the baseline is 3. The description text adds no parameter-level semantics; all parameter meaning lives in the schema, which is thorough (query operators, order_by keys, file_type aliases, include_trashed precedence). No additional value is needed, but none is provided either.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('searches') and resource ('files and folders'), and qualifies scope with 'including shared drives.' It does not explicitly contrast with list_drive_items or search_docs, but the tool name and query parameter make the search intent clear. It is sufficiently distinct from siblings despite no explicit differentiation.

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

Usage Guidelines2/5

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

The description offers no guidance on when to use search_drive_files versus list_drive_items, list_docs_in_folder, or search_docs, and no exclusions or prerequisites. An agent must infer usage from the tool name and schema, which is insufficient for choosing between similar drive-list tools.

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

Deploy Server