Allows searching and reading Gmail messages and threads, including text extraction, attachment handling, and raw message downloads. Also supports creating plain-text drafts, optionally threaded as replies.
Allows creating, reading, exporting, and modifying Google Docs. Supports exporting to markdown, plain text, HTML, CSV, PDF, replacing document content, and appending text.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gcloud-workspace-mcp search my Gmail for the latest invoice from Acme"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for Google Docs, Drive and Gmail that
authenticates through your local gcloud CLI. It doesn't need an OAuth client of its own.
Some Google Workspace tenants block every third-party OAuth client. Other Workspace MCP servers
ask you to register or reuse an OAuth client ID, and on those tenants the sign-in stops at an
"access blocked by your admin" screen. Google's own Cloud SDK client usually stays allowed. So
this server borrows the access tokens that gcloud mints on your machine and calls the Google
REST APIs over HTTPS.
If your tenant lets you register an OAuth app, a full-featured server such as
google_workspace_mcp will cover more of
the API. Use this one when gcloud is the only client you can log in with.
The only dependency is the mcp SDK. The HTTP layer uses the Python standard library.
Related MCP server: mcp-google_docs
gcloud keeps two token stores, and you can't swap one for the other. A 403 usually means a
call used the wrong one.
Surface | Store | Token command | Quota header |
Docs & Drive | user |
| not needed |
Gmail | ADC |
| required |
Install the Google Cloud SDK so gcloud is on your
PATH. Then grant the scopes. The server never runs these commands for you.
Docs and Drive (user credentials):
# Grants the full drive scope. gcloud has no read-only variant.
gcloud auth login --enable-gdrive-accessGmail (Application Default Credentials):
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/gmail.readonly
gcloud auth application-default set-quota-project <your-quota-project>Keep cloud-platform in the list if other tools on your machine use ADC for Google Cloud. The
login rewrites ~/.config/gcloud/application_default_credentials.json in place, so back it up
first if you care about its current scopes.
You need uv. Register the server in Claude Code:
claude mcp add -s user gcloud-workspace \
-e GCLOUD_QUOTA_PROJECT=<your-quota-project> \
-- uvx --from git+https://github.com/thrix/gcloud-workspace-mcp gcloud-workspace-mcpFor another client, add this to its MCP config:
{
"mcpServers": {
"gcloud-workspace": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/thrix/gcloud-workspace-mcp",
"gcloud-workspace-mcp"
],
"env": { "GCLOUD_QUOTA_PROJECT": "<your-quota-project>" }
}
}
}Pin a release by appending @v0.1.0 to the git URL.
CI publishes a multi-arch image (amd64, arm64) to ghcr.io/thrix/gcloud-workspace-mcp. It
holds the server and the Google Cloud SDK on a distroless
Hummingbird Python image. You still do the
one-time gcloud logins on your host. The container reads and refreshes the tokens through a
mount of your gcloud config directory.
mkdir -p -m 700 "$HOME/.cache/gcloud-workspace-mcp/downloads"
claude mcp add -s user gcloud-workspace -- \
podman run -i --rm --userns=keep-id:uid=65532,gid=65532 \
-v "$HOME/.config/gcloud:/gcloud:z" \
-v "$HOME/.cache/gcloud-workspace-mcp/downloads:$HOME/.cache/gcloud-workspace-mcp/downloads:z" \
-e GCLOUD_WORKSPACE_DOWNLOAD_DIR="$HOME/.cache/gcloud-workspace-mcp/downloads" \
-e GCLOUD_QUOTA_PROJECT=<your-quota-project> \
ghcr.io/thrix/gcloud-workspace-mcp:latest--userns=keep-id maps your host user to the image's UID 65532, so gcloud can write refreshed
tokens back to your config. The downloads directory is mounted at the same path it has on your
host, so the paths the server returns work outside the container too. Pass -e GCLOUD_WORKSPACE_ENABLE_WRITES=1 to enable the write tools.
Tag | Points at |
| the newest release, and each release line |
| the tip of |
| one commit on |
Each published image carries a signed build provenance attestation. Check it with
gh attestation verify oci://ghcr.io/thrix/gcloud-workspace-mcp:latest --owner thrix.
To build the image yourself, run podman build -t gcloud-workspace-mcp . and use
gcloud-workspace-mcp as the image name. To pick a different SDK release, pass
--build-arg GCLOUD_VERSION=<version> together with that release's GCLOUD_SHA256_X86_64 and
GCLOUD_SHA256_ARM. The build checks the tarball against them.
Variable | Meaning |
| ADC quota project, sent as |
| Set to |
| Where binary downloads and |
Drive and Docs use the user credentials:
Tool | What it does |
| Search with a raw Drive |
| Metadata for one file: owners, size, link, parents. |
| Export a Google-native file as |
| Download an uploaded file (PDF, xlsx, txt, images), up to 10 MB. |
Text comes back 50,000 characters at a time. When there is more, the result ends with a note
that gives the offset for the next call.
PDF exports and binary downloads don't go into the tool result, since base64 would blow past
the client's output limit. The server saves them to the download directory as <file id>.<ext>
and returns {path, name, mimeType, bytes}. Claude Code can open the PDF or image at that path
with its Read tool. The directory is created with mode 0700 and each file with 0600. A
second download of the same file overwrites the first.
Gmail uses ADC plus the quota header:
Tool | What it does |
| Search with Gmail syntax. Returns |
|
|
| Every message in a thread, oldest first, decoded the same way. The bodies share a 100,000-character budget, filled from the newest message back. Older messages past it keep their headers, get |
The write tools stay unregistered until you set GCLOUD_WORKSPACE_ENABLE_WRITES=1, so your MCP
client can't see or call them by default.
Tool | What it does |
| Create a Google Doc. Drive converts the markdown to native formatting. |
| Replace a Doc's whole body with converted markdown. Drive keeps the old content in version history. Refuses any file that isn't a native Google Doc. |
| Append plain text to the end of a Doc through the Docs API. |
| Create a plain-text draft, threaded as a reply when you pass |
The server offers no tool that sends mail, deletes files or moves them to the trash.
Drafts need one more ADC scope:
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.composePrompt injection. The model reads your documents and mail, and anyone who can share a doc or send you an email can put instructions in it. With writes on, a poisoned doc could get the model to overwrite another doc or draft a message to someone. Turn writes on when you need them and review what the model changes.
The server gets tokens only by reading the stdout of the gcloud subprocess. It never puts a
token on a command line.
It never logs a token or returns one in a tool result or error message.
It attaches a token only to https URLs on a *.googleapis.com host. It checks this before it
mints the token, checks every redirect target the same way, and refuses every other URL.
See SECURITY.md to report a vulnerability.
You need a logged-in gcloud on the same machine. The server can't run an interactive login.
When gcloud asks for reauthentication, the tool error tells you, and you re-run the login.
The server gives gcloud no stdin, so a prompt fails instead of waiting, and it stops a
gcloud call after 60 seconds.
print-access-token doesn't report an expiry. The server assumes a 55-minute lifetime,
refreshes 5 minutes early, and retries once after a 401.
Gmail calls need GCLOUD_QUOTA_PROJECT, and they fail with 403 accessNotConfigured until
that project enables the Gmail API. Drive and Docs calls don't send that header. They bill the Cloud
SDK's own project, and GCLOUD_QUOTA_PROJECT can't enable an API for them.
Message bodies get cut at 50,000 characters, and a thread's bodies at 100,000 in total. Attachments come back as names and sizes only. HTML-only mail keeps table cells apart and shows each link target after its text.
Export a Google Doc (or other Google-native file) to text.
Uses user credentials. Allowed export types: text/markdown, text/plain,
text/html, text/csv, application/pdf. Docs export to all but text/csv.
Sheets export to text/csv (first sheet only) or PDF, and Slides to
text/plain or PDF. A PDF is saved to a local file, and the result gives
its path; open that file to read it. Text comes back 50,000 characters
at a time; a note at the end gives the offset of the next window. The
Drive API refuses exports larger than 10 MB.
For files that are not Google-native (uploaded PDFs, xlsx, txt, ...) use
drive_download instead.
Args: file_id: The Drive file id of a Google-native document. mime_type: Target export MIME type (see allowed list above). offset: Character offset to start the text from. Ignored for PDF.
Returns:
The exported document as text, or for PDF a JSON object
{path, name, mimeType, bytes} describing the saved file.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | ||
| file_id | Yes | ||
| mime_type | No | text/markdown |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, but the description adds substantial context beyond them: user credentials are used, the 10 MB Drive API export ceiling, the 50,000-character text window with an `offset` continuation note, and the fact that PDF exports land in a local file whose path must be opened. These are real behavioral traits an agent could not infer from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well front-loaded – purpose first, then constraints, then Args/Returns. Every clause earns its place except the Returns block, which restates structure already captured by the output schema, adding mild redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with 0% schema coverage, no enums, and no nested objects, the description covers selection criteria, per-type MIME legality, auth context, size limits, pagination continuation, and non-text return handling. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden and does: `file_id` is the Google-native document id, `mime_type` is constrained to the enumerated allowed list, and `offset` is the character start point that is explicitly ignored for PDF. Each parameter gains meaning not present in the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Export) and resource (a Google Doc or other Google-native file), with the output form (text) named up front. It also immediately distinguishes itself from the sibling drive_download by restricting scope to Google-native files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit routing rule: 'For files that are not Google-native (uploaded PDFs, xlsx, txt, ...) use `drive_download` instead.' It further specifies which export MIME types are legal per source type (Docs vs Sheets vs Slides), so the agent knows both when to use this tool and which arguments are valid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download the content of a non-Google-native Drive file.
Uses user credentials. Works for uploaded files such as PDF, xlsx, txt or
images, up to 10 MB. Text files come back 50,000 characters at a time; a
note at the end gives the offset of the next window. Anything else is
saved to a local file, and the result gives its path; open that file to
read it.
For Google Docs, Sheets and Slides use docs_export instead.
Args: file_id: The Drive file id. offset: Character offset to start the text from. Ignored for binary files.
Returns:
The file content as text, or for binary files a JSON object
{path, name, mimeType, bytes} describing the saved file.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No | ||
| file_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a safe read (readOnlyHint=true) and open-world reach, and the description adds genuinely new behavioral context: user credentials are used, large binaries are written to a local path rather than returned inline, and text is paginated in 50k-char windows. This tells the agent exactly what to expect from the call's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and sibling routing, then operational detail, then a compact Args/Returns block. Every sentence carries information an agent needs to call it correctly; nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still clarifies the practical shape of results (text vs. saved-file path). Together with the size limit, pagination behavior and credential note, an agent has everything needed to invoke and interpret this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden and does document both params: file_id as the Drive file id and offset as the character start position, explicitly noting it is ignored for binary files. It stops short of explaining offset's interaction with the 50k windowing beyond the implied pagination, but coverage is solid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb (Download) and resource (content of a non-Google-native Drive file), and the negative qualifier immediately separates it from the export flow. Combined with the explicit pointer to docs_export, an agent can distinguish it from siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use it (uploaded files such as PDF, xlsx, txt, images), when not to (Google Docs/Sheets/Slides), and names the exact alternative (docs_export). It also gives operational bounds: 10 MB cap and text returned in 50,000-character windows with an offset for the next page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return metadata for a single Drive file.
Uses user credentials.
Args: file_id: The Drive file id.
Returns: A JSON object with common metadata fields.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral detail beyond the annotations: it authenticates with *user* credentials, which matters for permission scoping on Drive files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded one-line purpose followed by a short auth note and the arg. The 'Returns:' block is redundant given an output schema exists, which is minor padding but not harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with annotations and an output schema, the description covers purpose and auth context adequately; return values need not be explained. Only the absence of guidance on behavior for missing/inaccessible file ids is a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden, but it only restates the schema title ('The Drive file id'). It confirms the identifier's domain but adds no format, examples, or constraints (e.g., accepts a bare id vs. a URL).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: 'Return metadata for a single Drive file.' The word 'single' implicitly separates it from the list-returning drive_search, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the agent infers it should call this when it already has a file_id and wants metadata rather than content (drive_download) or a search (drive_search). No when-to-use or when-not-to-use statement is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Google Drive files using a raw Drive q query string.
Uses user credentials (gcloud auth print-access-token). Searches My
Drive, files shared with you, and every shared drive you belong to.
Args:
query: A raw Drive v3 q expression, e.g.
"name contains 'design' and mimeType='application/vnd.google-apps.document'".
See https://developers.google.com/drive/api/guides/search-files
page_size: Maximum number of files to return (1-100).
page_token: The nextPageToken from a previous call, to fetch the next page.
Returns:
A JSON object {files: [{id, name, mimeType, modifiedTime}], nextPageToken, incompleteSearch}. nextPageToken is null on the last page.
incompleteSearch is true when Drive skipped some shared drives; narrow
the query and search again.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| page_size | No | ||
| page_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds valuable context beyond annotations: uses user credentials, searches across shared drives, and explains incompleteSearch behavior with remediation advice. Annotations already cover readOnlyHint and openWorldHint, so the extra operational details are a bonus.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Args, Returns) and front-loaded purpose. All sentences earn their place, including the incompleteSearch note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description explains the return shape including pagination and incompleteSearch semantics, which aids correct usage. It covers auth, scope, parameters, and error handling, making it complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully explain parameters. It does: query is a raw Drive q expression with an example and link, page_size range (1-100), and page_token usage from nextPageToken. This is comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) and resource (Google Drive files) and specifies the scope: My Drive, shared-with-me, and all shared drives. This distinguishes it from sibling tools like drive_get_metadata (fetch by ID) and drive_download (retrieve content).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly describes the search scope and auth mechanism (user credentials via gcloud), giving the agent context for when to use it. However, it does not explicitly state when not to use it or name alternatives like drive_get_metadata for known file IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single Gmail message.
Uses ADC credentials and sends the mandatory quota-project header.
Args:
message_id: The Gmail message id.
format: "text" (default) returns {id, threadId, labelIds, headers, body, attachments} with the body decoded to plain text (HTML-only mail is
stripped of tags). "metadata", "minimal" and "full" return the
Gmail message resource unchanged, up to 1 MB. "raw" saves the whole
RFC 822 message, attachments included, to <message id>.eml in the
download directory, and returns the resource with path,
mimeType and bytes in place of the base64 raw field.
Returns: The message as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | text | |
| message_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint/openWorldHint, and the description adds substantial behavior the annotations cannot: ADC credential usage, the mandatory quota-project header, the 1 MB cap on metadata/minimal/full, HTML tag-stripping on text format, and the side effect that 'raw' writes an .eml file to the download directory and swaps the base64 raw field for path/mimeType/bytes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the one-line purpose, then uses standard Args/Returns sections with no filler. Every clause (decoding, size cap, file write, field substitution) conveys information an agent needs to pick a format correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still explains the divergent return shapes per format, which is exactly the detail that matters given the format-dependent responses. Nothing needed to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden and does: message_id is identified as the Gmail message id, and all four format values are enumerated with their distinct return shapes and defaults. This is far beyond anything the bare schema conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a single Gmail message'), which cleanly separates it from gmail_search (bulk) and gmail_get_thread (thread-level). An agent can identify the tool from the first line alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The format modes are well explained, which effectively guides parameter selection, but the description never states when to prefer this tool over gmail_search or gmail_get_thread, nor any prerequisites for calling it. Usage is implied by the resource name rather than declared.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a whole Gmail thread, oldest message first.
Uses ADC credentials and sends the mandatory quota-project header.
Args:
thread_id: The Gmail thread id (the threadId of any of its messages).
format: "text" (default) decodes every message like gmail_get_message.
The bodies share a 100,000-character budget, newest message first;
older messages past it keep their headers, get body: null, and
their ids are listed in omittedBodies for gmail_get_message.
"metadata", "minimal" and "full" return the raw Gmail resources,
up to 1 MB for the whole thread.
Returns:
A JSON object {id, messages: [...]}, plus omittedBodies when the
"text" format dropped any body.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | text | |
| thread_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the readOnlyHint/openWorldHint annotations: ADC credential use, the mandatory quota-project header, the 100,000-character body budget shared newest-first, header-only retention with body:null past the budget, the omittedBodies escape hatch, and a 1 MB cap for raw formats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then organized into Args/Returns sections. Most detail earns its place, though the credential/header note is slightly incidental to selection and the format explanation is dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool this covers everything an agent needs: credential requirements, format semantics, truncation behavior and recovery path, plus the return shape (also backed by an output schema). Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden and does: thread_id is defined as the threadId of any member message, and every format value ('text' default, 'metadata', 'minimal', 'full') is explained with its decoding and size behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a whole Gmail thread') plus a scoping detail (oldest message first) that immediately distinguishes it from gmail_get_message, which the description names as the follow-up tool for omitted bodies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: fetching a whole thread versus a single message is inferable from the name and from the pointer to gmail_get_message, but there is no explicit when-to-use/when-not guidance or mention of gmail_search as an alternative entry point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Gmail messages using Gmail search syntax.
Uses ADC credentials and sends the mandatory quota-project header.
resultSizeEstimate is only an estimate and stops counting at 201. To
count matches, page through the results with page_token instead.
Args:
query: A Gmail search expression, e.g. "from:alice newer_than:7d".
max_results: Maximum number of message ids to return (1-500).
page_token: The nextPageToken from a previous call, to fetch the next page.
Returns:
A JSON object {messages: [{id, threadId}], nextPageToken, resultSizeEstimate}.
nextPageToken is null on the last page.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| page_token | No | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds notable behavioral details beyond annotations: the mandatory quota-project header, ADC credential usage, the caveat that resultSizeEstimate stops at 201, and the pagination pattern. That is meaningful non-obvious context, though auth failure modes and rate limits aren't fully addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It's structured with an opening purpose, behavior note, caveat, and clear Args/Returns sections; every sentence carries information. Front-loading the search purpose is good, though the ADC/header sentence could be considered lower-value for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters at 0% schema coverage, annotations covering safety, and an output schema present, the description provides the necessary parameter and return-field details. It explains resultSizeEstimate limitations and pagination, completing the picture for a search tool, though it could say a bit more about when to use it versus sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 3 parameters, so the description must compensate. It does document each parameter: query with an example, max_results with a 1–500 range, and page_token tied to nextPageToken from a previous call. This adds substantial meaning beyond the bare schema, though datetime/rank semantics aren't detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) and resource (Gmail messages) and mentions Gmail search syntax, clearly distinguishing it from siblings like gmail_get_message and drive_search. It stops short of comparing directly to sibling tools, which is why it's a 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by providing query examples and pagination hints, but it never states when to prefer gmail_search over gmail_get_message or gmail_get_thread. An agent can infer intent but must guess at alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0docs_exportdrive_downloaddrive_get_metadatadrive_searchgmail_get_messagegmail_get_threadgmail_searchScored across 7 tools
Each tool targets a clearly distinct service, resource, and action: Drive search, Drive metadata lookup, Google-native export, non-native download, Gmail search, message fetch, and thread fetch. The descriptions explicitly delineate Google-native files (docs_export) from uploaded files (drive_download) and single messages from threads, so misselection is unlikely.
The set follows a predictable service_action pattern (drive_search, drive_get_metadata, gmail_get_message, gmail_get_thread), with only a minor deviation in docs_export using the 'docs' prefix instead of 'drive'. The convention is still readable and nearly uniform throughout.
Seven tools is well-scoped for a read/search/export-focused Drive, Docs, and Gmail integration. Each tool has a distinct purpose, and there are no redundant or filler operations.
The surface covers the core read-only lifecycle: searching and fetching Drive metadata, exporting Google-native documents, downloading non-native files, and searching/fetching Gmail messages and threads. Minor gaps remain, such as direct Gmail attachment extraction or fuller Sheets multi-sheet export, but described workarounds (raw .eml, CSV first sheet) make these manageable.
Provides tools for searching Google Workspace documentation and much more.
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Find, read and reorganize files across Google Drive, OneDrive, SharePoint and Dropbox, with undo.
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.