## Tool: `search_corpus`

> [!WARNING]
> **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview), which grants early access to certain features.

Performs a search across multiple Workspace corpora (Drive, Gmail, Calendar, and Chat) based on the provided query.

This tool is a cross-corpus search tool that by default fans out to all supported corpora (Drive, Gmail, Calendar, and Chat). If the user's query does not specify a particular corpus (e.g., "where am i planning to go for my photography walks in june?"), you MUST call this cross-corpus "search_corpus" tool first, rather than calling specific tools like "list_events", "search_threads", "list_threads", or "search_files". If this tool returns no results, you can then fallback to these per-product (single-corpus) search tools.

Note that if the user specifies a particular corpus in their query (e.g., "search for content in my email"), it is recommended to use a single-corpus tool, such as the GmailTool, for more focused results if available. However, this cross-corpus search tool will still function for those queries, and should be used if specific tools are not available.

This tool can filter results based on a query string. Pagination is not supported for cross-corpus search. Note that if a Gmail message contains attachments, they are not returned as a separate field; instead, attachment details will be included directly within the message's snippet.

The following code sample shows how to use `curl` to call the `search_corpus` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://workspacemcp.googleapis.com/mcp/v1' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "search_corpus", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request message for WorkspaceToolService.SearchCorpus.

### SearchCorpusRequest

| JSON representation |
|---|
| ``` { "query": string, "pageSize": integer, "pageToken": string } ``` |

| Fields ||
|---|---|
| `query` | `string` Required. The raw query string provided by the user. |
| `pageSize` | `integer` Optional. Currently ignored. The server returns up to a server-defined number of results. Pagination isn't supported. |
| `pageToken` | `string` Optional. Currently ignored. Pagination isn't supported. |

## Output Schema

Response message for WorkspaceToolService.SearchCorpus.

### SearchCorpusResponse

| JSON representation |
|---|
| ``` { "items": [ { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.SearchResultItem`) } ], "nextPageToken": string } ``` |

| Fields ||
|---|---|
| `items[]` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.SearchResultItem`)`` A list of universal search result items, each potentially from a different corpus. |
| `nextPageToken` | `string` Currently always empty. Pagination isn't supported. |

### SearchResultItem

| JSON representation |
|---|
| ``` { "driveResult": { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.DriveResult`) }, "gmailResult": { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.GmailResult`) }, "calendarResult": { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.CalendarResult`) }, "chatResult": { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatResult`) } } ``` |

| Fields ||
|---|---|
| Union field `item_result`. The specific search result from a workspace corpus. `item_result` can be only one of the following: ||
| `driveResult` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.DriveResult`)`` A search result from Google Drive. |
| `gmailResult` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.GmailResult`)`` A search result from Gmail. |
| `calendarResult` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.CalendarResult`)`` A search result from Google Calendar. |
| `chatResult` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatResult`)`` A search result from Google Chat. |
|   ||

### DriveResult

| JSON representation |
|---|
| ``` { "itemId": string, "title": string, "mimeType": string, "viewUrl": string, "contentSnippet": string } ``` |

| Fields ||
|---|---|
| `itemId` | `string` Unique identifier for the Drive item (e.g., document, sheet, presentation). |
| `title` | `string` The title of the Drive item. |
| `mimeType` | `string` The mime type of the Drive item. |
| `viewUrl` | `string` The URL to view the Drive item. |
| `contentSnippet` | `string` The content snippet of the Drive item. |

### GmailResult

| JSON representation |
|---|
| ``` { "thread": { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.GmailThread`) } } ``` |

| Fields ||
|---|---|
| `thread` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.GmailThread`)`` The thread that match the search query. |

### GmailThread

| JSON representation |
|---|
| ``` { "threadId": string, "messages": [ { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.GmailMessage`) } ] } ``` |

| Fields ||
|---|---|
| `threadId` | `string` Identifier for the Gmail thread. |
| `messages[]` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.GmailMessage`)`` A list of messages in the thread. |

### GmailMessage

| JSON representation |
|---|
| ``` { "messageId": string, "subject": string, "snippet": string, "sender": string, "recipients": [ string ], "ccRecipients": [ string ], "viewUrl": string } ``` |

| Fields ||
|---|---|
| `messageId` | `string` Identifier for the Gmail message. |
| `subject` | `string` The subject of the Gmail message. |
| `snippet` | `string` The content snippet of the Gmail message. |
| `sender` | `string` The sender's email address of the Gmail message. |
| `recipients[]` | `string` The recipients' email addresses of the Gmail message. |
| `ccRecipients[]` | `string` The cc recipients' email addresses of the Gmail message. |
| `viewUrl` | `string` The URL to view the Gmail message. |

### CalendarResult

| JSON representation |
|---|
| ``` { "eventId": string, "title": string, "description": string, "calendarId": string, "viewUrl": string, "location": string, "start": { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.DateOrDateTime`) }, "end": { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.DateOrDateTime`) } } ``` |

| Fields ||
|---|---|
| `eventId` | `string` Unique identifier for the Calendar event. |
| `title` | `string` The title of the Calendar event. |
| `description` | `string` The description of the Calendar event. |
| `calendarId` | `string` The calendar id of the Calendar event, which is the owner's email address. |
| `viewUrl` | `string` The URL to view the Calendar event. |
| `location` | `string` Represents the location of the Calendar event. |
| `start` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.DateOrDateTime`)`` The start time of the Calendar event (inclusive). |
| `end` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.DateOrDateTime`)`` The end time of the Calendar event (exclusive). |

### DateOrDateTime

| JSON representation |
|---|
| ``` { "date": string, "dateTime": string, "timeZone": string } ``` |

| Fields ||
|---|---|
| `date` | `string` ISO 8601 date in `yyyy-mm-dd` format (for example, `'2019-11-20'`). |
| `dateTime` | `string` ISO 8601 timestamp (for example, `'2019-11-20T08:19:06-07:00'`). |
| `timeZone` | `string` The original time zone in IANA Time Zone Database format (for example, `'America/Los_Angeles'`). The returned `'date_time'` might be in a different display time zone (for example the viewer's current time zone). |

### ChatResult

| JSON representation |
|---|
| ``` { "messages": [ { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatMessage`) } ] } ``` |

| Fields ||
|---|---|
| `messages[]` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatMessage`)`` A list of messages that could be grouped together as a conversation. |

### ChatMessage

| JSON representation |
|---|
| ``` { "id": { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatMessageId`) }, "plaintextBody": string, "sender": { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatUser`) }, "createTime": string, "threadedReply": boolean, "attachments": [ { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatAttachment`) } ], "reactionSummaries": [ { object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatReaction`) } ], "viewUrl": string } ``` |

| Fields ||
|---|---|
| `id` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatMessageId`)`` Unique identifier for the message and thread. |
| `plaintextBody` | `string` Plain text body of the message. |
| `sender` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatUser`)`` The sender of the message. |
| `createTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Timestamp when the message was created. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `threadedReply` | `boolean` Whether message is a thread reply. |
| `attachments[]` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatAttachment`)`` Attachments included in the message. |
| `reactionSummaries[]` | ``object (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatReaction`)`` The emoji reactions summary included in the message. |
| `viewUrl` | `string` The URL to view the Chat message. |

### ChatMessageId

| JSON representation |
|---|
| ``` { "messageId": string, "threadId": string } ``` |

| Fields ||
|---|---|
| `messageId` | `string` Resource name of the message. |
| `threadId` | `string` The thread this message belongs to. |

### ChatUser

| JSON representation |
|---|
| ``` { "userId": string, "displayName": string, "email": string, "chatUserType": enum (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatUserType`) } ``` |

| Fields ||
|---|---|
| `userId` | `string` Unique identifier for the user. |
| `displayName` | `string` The display name of the user. |
| `email` | `string` The email address of the user. |
| `chatUserType` | ``enum (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.ChatUserType`)`` The type of the user. |

### Timestamp

| JSON representation |
|---|
| ``` { "seconds": string, "nanos": integer } ``` |

| Fields ||
|---|---|
| `seconds` | `string (https://developers.google.com/discovery/v1/type-format format)` Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z). |
| `nanos` | `integer` Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive. |

### ChatAttachment

| JSON representation |
|---|
| ``` { "attachmentId": string, "filename": string, "mimeType": string, "source": enum (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.Source`) } ``` |

| Fields ||
|---|---|
| `attachmentId` | `string` Resource name of the attachment. |
| `filename` | `string` Name of the attachment. |
| `mimeType` | `string` Content type (MIME type). |
| `source` | ``enum (`https://developers.google.com/workspace/reference/mcp/tools_list/search_corpus#Output.Schema.Source`)`` The source of the attachment. |

### ChatReaction

| JSON representation |
|---|
| ``` { "emoji": string, "count": integer } ``` |

| Fields ||
|---|---|
| `emoji` | `string` The emoji unicode string or custom emoji name. |
| `count` | `integer` The total number of reactions using the associated emoji. |

### ChatUserType

Enum indicating the chat user type.

| Enums ||
|---|---|
| `CHAT_USER_TYPE_UNSPECIFIED` | Default value. Do not use. |
| `CHAT_USER_TYPE_HUMAN` | Human user. |
| `CHAT_USER_TYPE_BOT` | Bot user. |

### Source

The source of the attachment.

| Enums ||
|---|---|
| `SOURCE_UNSPECIFIED` | Reserved. |
| `DRIVE_FILE` | The file is a Google Drive file. |
| `UPLOADED_CONTENT` | The file is uploaded to Chat. |

### Tool Annotations


[Tool annotations](https://modelcontextprotocol.io/specification/latest/schema#toolannotations) are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.


Along with the title string, the following boolean hints are defined as follows:

- `readOnlyHint`: If true, the tool doesn't modify its environment. Default: false.
- `destructiveHint`: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
- `idempotentHint`: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
- `openWorldHint`: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ \| Idempotent Hint: ✅ \| Read Only Hint: ✅ \| Open World Hint: ❌

## Authorization Scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/drive`
- `https://www.googleapis.com/auth/drive.readonly`
- `https://mail.google.com/`
- `https://www.googleapis.com/auth/gmail.modify`
- `https://www.googleapis.com/auth/gmail.readonly`
- `https://www.googleapis.com/auth/calendar`
- `https://www.googleapis.com/auth/calendar.readonly`
- `https://www.googleapis.com/auth/chat.messages`
- `https://www.googleapis.com/auth/chat.messages.readonly`
- `https://www.googleapis.com/auth/chat.spaces.readonly`
- `https://www.googleapis.com/auth/chat.memberships.readonly`