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

Search Drive Files

search_drive_files

Read-onlyIdempotent

Find files and folders across Google Drive and shared drives using search queries, file type filters, and sorting options.

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 it defaults to 'allDrives' when `include_items_from_all_drives` is True. Pass 'user' to search only My Drive and files shared with the user.
`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.

Changed1 schema field changedv1.30.1Oct 3, 2026

changedInput schema / properties / corpora / description

Previous 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."New 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 it defaults to 'allDrives' when `include_items_from_all_drives` is True.\n                     Pass 'user' to search only My Drive and files shared with the user."

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

B3.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds only the shared-drive scope note; pagination behavior, corpora resolution, and query-operator quirks live entirely in the schema, so the description adds limited behavioral value.

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?

A single front-loaded sentence with no filler; every word earns its place. It is arguably under-specified for an 11-parameter tool, which keeps it just short of a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema, 100% parameter coverage, and complete annotations, the structured fields carry most of the burden, so the terse description is workable. Still, the lack of sibling differentiation and usage routing leaves a real gap for an agent choosing among the Drive tools.

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 all 11 parameters (including corpora defaults, order_by keys, and file_type mapping) are documented in the schema itself. The description contributes nothing about parameters, so the baseline 3 is appropriate.

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?

States a specific verb (Searches) and resource (files and folders within Google Drive), and adds the shared-drive scope. However, it never distinguishes itself from the sibling list_drive_items, which also enumerates Drive contents, so an agent cannot tell them apart from the description alone.

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?

No guidance on when to use this versus list_drive_items or get_drive_file_content. The description implies a search-oriented use case but provides no conditions, exclusions, or prerequisites to route the agent.

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

Deploy Server