This server is a Google Drive MCP interface that provides Claude.ai-compatible tools for managing files and folders across personal and shared drives. Its capabilities include:
Search & Discovery
Search files using Google Drive query operators with filtering and pagination
List recently modified files and browse folder/shared drive contents
Retrieve detailed file metadata
Reading & Downloading
Extract text from Google Docs, Sheets, Slides, Office files (.docx/.xlsx/.pptx), PDFs, and images
Download raw file bytes as base64 (up to 25 MB), with export format selection for native Google types (e.g., Docs→PDF, Sheets→CSV)
Creation & Import
Create new files with text or base64 binary content (or fetch from a URL), with optional auto-conversion to Google native formats
Create new folders
Import Markdown, DOCX, HTML, RTF, or ODT files as native Google Docs
Initiate resumable upload sessions for large files (bypassing MCP transport limits)
File Management
Update file metadata: rename, move, trash, star, add descriptions, or custom properties
Copy files to new locations
Permissions & Sharing
View detailed permissions and check public access status
Generate shareable links
Grant, update, revoke, or batch-grant permissions, and transfer ownership
Set high-level link-sharing settings (anyone-with-link, copy restrictions, writer-can-share)
Authentication
Manually trigger Google OAuth 2.0 if needed (OAuth 2.1 mode handles auth automatically)
Provides tools for searching, reading, creating, and managing files and folders on Google Drive, including metadata retrieval, content reading/downloading, file creation with MIME-type handling, and permission management.
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., "@Custom Google Drive MCP find documents about Q4 planning"
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.
A slimmed-down fork of taylorwilsdon/google_workspace_mcp that exposes only the Drive tool surface, with the four overlapping tools renamed and reshaped to match the Claude.ai Google Drive connector contract. Drop-in compatible with skills/scripts written against Claude.ai's built-in Drive tools.
The upstream server is a great general-purpose Workspace MCP, but three things made it unsuitable for drop-in use as a Claude.ai Drive connector replacement:
Tool surface doesn't match Claude.ai's Drive connector. Skills written against Claude.ai's built-in search_files, read_file_content, download_file_content, create_file break against upstream's search_drive_files, get_drive_file_content, get_drive_file_download_url, create_drive_file. Param names and response shapes also differ.
create_drive_file corrupts binary uploads. Upstream does content.encode("utf-8") regardless of mime type, so passing a base64-encoded xlsx or pptx results in a Drive file whose bytes are the literal base64 ASCII string — not the decoded binary.
It bundles 11 other Google services (Gmail, Calendar, Docs, Sheets, Slides, Forms, Chat, Tasks, Contacts, Search, Apps Script) that inflate the OAuth consent surface, deploy size, and auth blast radius if you only need Drive.
Related MCP server: MCP Google Drive Server
Change | Effect |
Drive-only | No Gmail/Calendar/Docs/Sheets/Slides/Forms/Chat/Tasks/Contacts/Search/AppsScript modules in the repo. CLI no longer exposes |
Claude.ai-compatible tool surface | Four overlapping tools renamed and reshaped (see table below). Two new tools ( |
|
|
| Base64 bytes inline, not a temporary URL. Capped at 25 MB by default (env var |
|
|
Mime-aware | If |
Dead-code pruning | Removed unused tier loader, comments helpers, granular-permissions module, dev CLI, and all non-Drive scope/service constants. See |
The OAuth machinery (Google provider, scopes, session store, callback handling, middleware), core/ server scaffold, attachment storage, http_utils, tool registry, and gdrive/drive_helpers.py are functionally identical to upstream — just trimmed of references to services this fork doesn't ship.
Tool | Purpose | Key params |
| Query-based search across all accessible drives |
|
| Most recently modified files (excludes trashed) |
|
| Single-file metadata by ID |
|
| Extract text from Docs/Sheets/PDF/Office natively |
|
| Raw bytes as base64 |
|
| Create file or folder; auto-converts to Google native unless |
|
list_drive_items — list children of a folder
create_drive_folder — dedicated folder creation
update_drive_file — metadata only (rename/move/trash), not content
import_to_google_doc — import MD/DOCX/TXT/HTML/RTF/ODT and convert to a native Google Doc
copy_drive_file
get_drive_file_permissions, check_drive_file_public_access
get_drive_shareable_link, manage_drive_access, set_drive_file_permissions
Upstream | This fork |
|
|
|
|
|
|
|
|
Python 3.10+ (.python-version pins the exact minor version uv will fetch)
uv package manager — install via curl -LsSf https://astral.sh/uv/install.sh | sh
A Google account you'll authorize the server with
A Google Cloud project (free tier is fine)
In console.cloud.google.com, select or create a project, then:
a. Enable the Drive API APIs & Services → Library → search "Google Drive API" → Enable.
b. Configure the OAuth consent screen APIs & Services → OAuth consent screen.
User type: External (or Internal if you have a Workspace org).
Add yourself under Test users so you can authorize while the consent screen is in testing mode.
Add scopes:
openid
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive.file
c. Create an OAuth 2.0 Client ID APIs & Services → Credentials → Create credentials → OAuth client ID.
Application type: Web application (not "Desktop app").
Authorized redirect URIs: http://localhost:8000/oauth2callback
Save the Client ID and Client Secret — you'll paste them into .env next.
.envcp env.example .envFor the recommended local setup (HTTP transport + OAuth 2.1 + in-memory session storage, matches the Railway production config):
# Google OAuth client (from step 2c)
GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
GOOGLE_OAUTH_REDIRECT_URI=http://localhost:8000/oauth2callback
# Transport
WORKSPACE_MCP_TRANSPORT=streamable-http
WORKSPACE_MCP_PORT=8000
WORKSPACE_MCP_HOST=0.0.0.0
# Externally-reachable URL — used to build the OAuth callback redirect.
# For plain localhost dev, point this at the same host:port the server binds to.
# Tunnel/Railway setups override this with their public HTTPS URL.
WORKSPACE_EXTERNAL_URL=http://localhost:8000
# Auth mode
MCP_ENABLE_OAUTH21=true
WORKSPACE_MCP_STATELESS_MODE=trueIf
WORKSPACE_EXTERNAL_URLis unset the OAuth callback URL is derived from request headers and can drift from what's registered in GCP, causingredirect_uri_mismatch. Always set it explicitly to the URL where this MCP is reachable.
For stdio mode (e.g. Claude Desktop), see the alternative recipe under Run locally below.
uv syncuv run main.py --transport streamable-httpExpected output:
Custom Google Drive MCP Server
Transport: streamable-http
URL: http://localhost:8000
OAuth Callback: http://localhost:8000/oauth2callback
...
Ready for MCP connectionsThe server listens on http://localhost:8000/mcp.
Matches the Railway production setup. Use this for Claude.ai, MCP Inspector, or any client that speaks streamable-http.
uv run main.py --transport streamable-httpConnect a client to http://localhost:8000/mcp. The client triggers the OAuth flow on the first tool call — your browser opens, you authorize, the access token lives in server memory for the session.
Smoke test with MCP Inspector:
npx @modelcontextprotocol/inspector
# Transport: streamable-http
# URL: http://localhost:8000/mcp
# Click Connect → do the OAuth handshake → List toolsStdio mode talks the MCP protocol over stdin/stdout instead of HTTP, so the OAuth callback uses a tiny standalone server on port 8000 that auto-starts when needed.
Override .env with:
# Drop or comment these out for stdio mode:
# WORKSPACE_MCP_TRANSPORT=streamable-http
# MCP_ENABLE_OAUTH21=true
# WORKSPACE_MCP_STATELESS_MODE=true
# Required: pin to one Google account
USER_GOOGLE_EMAIL=you@example.com
MCP_SINGLE_USER_MODE=1
# Where credentials persist between runs
WORKSPACE_MCP_CREDENTIALS_DIR=./store_credsRun:
uv run main.py --single-userWire into a Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"custom-gdrive": {
"command": "uv",
"args": ["run", "/absolute/path/to/this/repo/main.py", "--single-user"]
}
}
}Claude.ai's custom connector requires a public HTTPS URL — http://localhost won't work because Anthropic's edge servers, not your browser, fetch the MCP endpoint. Two paths:
Deploy to Railway (see below) — set WORKSPACE_EXTERNAL_URL=https://<service>.up.railway.app.
Tunnel localhost over ngrok / Cloudflare Tunnel for testing:
ngrok http 8000
# copy the https://<id>.ngrok-free.app URL it printsThen in .env:
WORKSPACE_EXTERNAL_URL=https://<id>.ngrok-free.app
GOOGLE_OAUTH_REDIRECT_URI=https://<id>.ngrok-free.app/oauth2callbackAnd add https://<id>.ngrok-free.app/oauth2callback to the GCP OAuth client's authorized redirect URIs. Restart the MCP server after editing .env.
In claude.ai → Settings → Connectors → Add custom connector:
Name: anything
Remote MCP server URL: https://<your-external-url>/mcp (don't omit the /mcp path — POST to / returns 405)
Click Connect. The OAuth flow opens in a new tab; authorize with the Google account you added under GCP Console → OAuth consent screen → Test users.
Whitelist googleapis.com in Claude.ai's network egress allowlist. Claude's analysis sandbox can't reach arbitrary hosts by default, so any tool call that streams file bytes from the sandbox to Google Drive (e.g. uploading a generated xlsx via create_file) silently fails until you allow it. In claude.ai → Settings → Capabilities → enable Allow network egress, leave the dropdown on Package managers only, and add these under Additional allowed domains:
*.googleapis.com
googleapis.com
Without this, the connector itself works (Claude → MCP → Drive is fine), but any code execution step that pushes bytes outbound to Google will be blocked by the sandbox firewall, not by the MCP.
Free ngrok URLs change on each restart. Each new URL means re-editing .env and re-adding the redirect URI in GCP. Use a static domain (paid plan) or Cloudflare Tunnel for a stable setup.
docker compose up --buildEquivalent to the HTTP transport recipe; reads .env from this directory.
The Dockerfile is set up for Railway as-is:
# From the repo root
railway up --service custom-gdrive-mcpSet these in Railway service variables (see env.example):
GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET
WORKSPACE_EXTERNAL_URL=https://<service>.up.railway.app
MCP_ENABLE_OAUTH21=true
WORKSPACE_MCP_STATELESS_MODE=true
WORKSPACE_MCP_TRANSPORT=streamable-http
Add https://<service>.up.railway.app/oauth2callback to the GCP OAuth client's authorized redirect URIs.
# 1. Round-trip a small pptx
PPTX=/path/to/test.pptx
B64=$(base64 -i "$PPTX")
# 2. Call create_file via MCP inspector or your client with:
# title="test_binary.pptx"
# content=$B64
# mimeType="application/vnd.openxmlformats-officedocument.presentationml.presentation"
# disableConversionToGoogleType=true # keep as pptx, don't convert to Slides
# 3. Download the resulting file from Drive
curl -L -o roundtrip.pptx "<webContentLink>"
# 4. Verify
file roundtrip.pptx # Should report "Microsoft PowerPoint", not "ASCII text"
md5 "$PPTX" roundtrip.pptx # Should matchFor a text round-trip (markdown, no base64), pass mimeType="text/markdown" and content=<raw string> — the UTF-8 path kicks in automatically. Add disableConversionToGoogleType=true to keep it as a plain .md file (otherwise the auto-convert path turns it into a Google Doc).
Symptom | Fix |
| The URI in |
| OAuth consent screen isn't published or your Google account isn't in the test-users list. |
| Step 2a was skipped. The server prints a direct enable link in the error message. |
| Change |
| You set both |
| Claude's sandbox egress is blocking the outbound call to |
OAuth callback redirects to the wrong host (e.g. |
|
Forked from taylorwilsdon/google_workspace_mcp at commit 5495c83cd3ac503d00cd8015de944c9949cd6443. Upstream LICENSE (MIT) preserved in this directory.
Searches for a file by name and checks if it has public link sharing enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| file_name | Yes | The name of the file to check. | |
| drive_id | No | ID of the shared drive to scope the search to. When set, the underlying files.list call uses corpora='drive' and the given driveId, which is required to reliably find files that live only in that shared drive. When None, behaviour is unchanged (default API corpora applies). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds context that it first searches by name then checks public access, but it does not address edge cases like multiple matching files or exactly what 'public link sharing' entails. This adds some but limited behavioral insight beyond 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?
A single, front-loaded sentence with no waste. Every word contributes to the purpose.
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?
Given the tool's simplicity, high schema coverage, and existence of an output schema, the description is mostly complete. It lacks clarification on how to handle multiple matches or what the return value represents, but the output schema likely covers return structure.
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 100%, so baseline is 3. The description minimally adds semantics by linking the search action to the file_name parameter, but it does not explain how parameters like user_google_email or drive_id affect the operation. No additional detail beyond the 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?
The description clearly states the tool searches for a file by name and checks for public link sharing. It uses specific verbs ('searches','checks') and identifies the resource ('file'), distinguishing it from siblings like get_drive_file_permissions or get_drive_shareable_link.
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 provides no explicit guidance on when to use this tool versus alternatives. With 17 sibling tools, such as get_drive_file_permissions or get_drive_shareable_link, the lack of usage context is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a copy of an existing Google Drive file.
This tool copies the template document to a new location with an optional new name. The copy maintains all formatting and content from the original file.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| file_id | Yes | The ID of the file to copy. Required. | |
| new_name | No | New name for the copied file. If not provided, uses "Copy of [original name]". | |
| parent_folder_id | No | The ID of the folder where the copy should be created. Defaults to 'root' (My Drive). | root |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds that formatting is maintained, which is useful. However, it does not disclose side effects, authorization needs beyond the email param, or what happens if parent_folder_id is invalid.
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?
The description is brief, front-loaded, and efficient. Three sentences provide all necessary information without 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?
Given the tool's straightforward purpose, complete input schema, and annotations, the description is mostly complete. The presence of an output schema likely covers return values. Minor gap: no explicit comparison to sibling tools like create_file.
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?
With 100% schema description coverage, the description adds no new parameter semantics. The schema already fully explains each parameter, including defaults and nullability.
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 description clearly states the action (creates a copy), resource (Google Drive file), and key behaviors (new location, optional new name, maintains formatting). It implicitly distinguishes from sibling tools like create_file (creating from scratch) or get_file_metadata (reading).
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 for copying template documents but does not explicitly state when to use this tool versus alternatives like create_file or download_file_content. No prerequisites, when-not-to-use, or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new folder in Google Drive, supporting creation within shared drives.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| folder_name | Yes | The name for the new folder. | |
| parent_folder_id | No | The ID of the parent folder. Defaults to 'root'. For shared drives, use a folder ID within that shared drive. | root |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations present (readOnlyHint=false, destructiveHint=false, openWorldHint=true), description aligns but adds no extra behavioral details like permission requirements or side effects beyond creation. Meets baseline but does not enhance transparency.
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?
Single sentence, 13 words, front-loaded with purpose. No extraneous information.
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?
Description covers the basic purpose but does not address prerequisites like authentication, error handling, or behavior when parent folder is missing. Output schema exists, so return values are covered, but overall completeness is adequate rather than comprehensive.
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 100%, so parameters are well-documented. Description adds minor context about shared drives for parent_folder_id, but otherwise repeats schema info. Baseline score is appropriate.
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?
Description clearly states verb 'Creates', resource 'new folder in Google Drive', and distinguishes by noting support for shared drives. This differentiates it from sibling tools like 'create_file' which create 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?
Description implies usage for folder creation, especially in shared drives, but does not explicitly state when to use versus alternatives or when not to use. Lacks exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new file in Google Drive, supporting creation within shared drives. Accepts either direct content or a fileUrl to fetch the content from.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | user@gmail.com | |
| title | Yes | The name for the new file. | |
| content | No | If provided, the content to write to the file. Encoding is chosen by mimeType: text/* and application/{json,xml,javascript,yaml,x-yaml} are UTF-8 encoded; everything else is treated as base64 and decoded to raw bytes (use this for xlsx, pptx, pdf, images, and any other binary payload). | |
| parentId | No | The ID of the parent folder. Defaults to 'root'. | root |
| mimeType | No | The MIME type of the source content. Defaults to 'text/plain'. | text/plain |
| fileUrl | No | If provided, fetches the file content from this URL. Supports file://, http://, and https:// protocols. | |
| disableConversionToGoogleType | No | When False (default), source MIME types with a Google-native equivalent are auto-converted (e.g. text/csv → Sheet, text/plain → Doc, docx → Doc). Set to True to store the file as-is. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool can fetch content from a URL (fileUrl), which aligns with openWorldHint=true annotation. It also mentions shared drive support. No contradictions with annotations. Could mention that file creation may fail if insufficient permissions.
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?
The description is two sentences, concise and front-loaded with the core purpose. Every sentence adds value without 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 tool with 7 parameters and an output schema, the description covers the essential behavior and key options. It does not explain the return value, but the output schema likely does. Slightly more context on authentication or file size limits could improve completeness.
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 86%, so parameters are well-documented in the schema. The description adds value by grouping input methods (content vs fileUrl) but does not provide additional semantics beyond the 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?
The description clearly states the tool creates files in Google Drive, supporting shared drives. It distinguishes from siblings like create_drive_folder or import_to_google_doc by specifying it accepts direct content or a fileUrl.
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 does not explicitly state when to use this tool versus alternatives like import_to_google_doc or update_drive_file. It implies usage for creating files with content or URL, but lacks conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a Google Drive resumable upload session and returns the upload URL.
The caller (e.g. a skill running in claude.ai's sandbox) uses the returned
upload_url to PUT raw file bytes directly to Google — bypassing MCP
transport limits on large content arguments. Only the short URL travels
through MCP; the bytes go straight from the sandbox to Google.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | user@gmail.com | |
| title | Yes | The name for the new file. | |
| mimeType | Yes | The source MIME type of the content (e.g. "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" for xlsx, "text/plain" for markdown). This is what the bytes on the wire actually are. | |
| parentId | No | The ID of the parent folder. Defaults to 'root'. | root |
| disableConversionToGoogleType | No | When False (default), source MIME types with a Google-native equivalent are auto-converted (e.g. text/csv → Sheet, xlsx → Sheet). Set to True to store the file as-is — REQUIRED for binary uploads that must not be converted (xlsx, pptx, pdf, images) and for keeping markdown as .md rather than Google Doc. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds key behavioral context not covered by annotations: it explains that the caller will PUT bytes directly to Google, bypassing MCP transport limits, and that only the URL travels through MCP. This goes beyond the readOnlyHint and openWorldHint 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?
The description is very concise, with five sentences that are front-loaded with the main purpose. Every sentence adds value, and there is no unnecessary elaboration.
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?
Given the tool complexity, the presence of an output schema, and 80% schema coverage, the description provides sufficient context for an agent to understand the tool's role. It explains why the session is resumable and how it bypasses limits. However, it could mention session expiry or that the URL is temporary for full completeness.
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 80%, so the schema already documents most parameters well. The description adds no extra parameter-specific meaning beyond what is in the schema, just mentions the return of upload_url. Baseline score of 3 is appropriate.
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 description clearly states it creates a Google Drive resumable upload session and returns the upload URL, specifying the verb and resource. However, it does not explicitly distinguish itself from the sibling 'create_file' tool, so while clear, it misses some differentiation.
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?
No explicit guidance on when to use this tool versus alternatives like 'create_file'. The description implies it is for large files bypassing MCP limits, but this is not stated as a usage rule or contrasted with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Downloads a Google Drive file and returns its raw bytes as a base64-encoded blob.
For Google native files (Docs, Sheets, Slides), exports to a useful format:
Google Docs -> PDF (default) or DOCX if export_format='docx'
Google Sheets -> XLSX (default), PDF if export_format='pdf', or CSV if export_format='csv'
Google Slides -> PDF (default) or PPTX if export_format='pptx'
For other files, downloads the original file format.
Size limit: DOWNLOAD_FILE_CONTENT_MAX_MB env var (default 25 MB). Files larger than the limit return an error pointing to read_file_content for text extraction, or a Drive shareable link as a fallback.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | user@gmail.com | |
| fileId | Yes | The Google Drive file ID to download. | |
| export_format | No | Optional export format for Google native files. Options: 'pdf', 'docx', 'xlsx', 'csv', 'pptx'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by detailing export behavior, size limit with env var, and fallback errors. No contradiction with 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?
Two concise paragraphs, front-loaded with core purpose. Every sentence provides necessary detail without verbosity. Well-structured for quick scanning.
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?
Covers core functionality, export rules, size limits, and fallback. No output schema, but return format is described as base64-encoded blob. Could mention response structure (e.g., JSON) but minor.
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 67% with descriptions for fileId and export_format. The description adds context for export_format by listing options, but user_google_email param is not explained beyond default. Baseline 3 is appropriate as description partially compensates.
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 description clearly states the tool downloads a Google Drive file and returns base64-encoded bytes. It specifies export formats for Google native files and distinguishes from siblings like read_file_content and get_drive_shareable_link.
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?
Provides explicit guidance on when to use alternatives: if file exceeds size limit, points to read_file_content or shareable link. Also explains export format options for different file types. Does not explicitly state when not to use, but covers main scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets detailed metadata about a Google Drive file including sharing permissions.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| file_id | Yes | The ID of the file to check permissions for. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no additional behavioral context such as authentication requirements, rate limits, or potential side effects. It merely restates the read-only nature implied by the name and 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?
The description is a single sentence that is front-loaded with the action word 'Gets' and clearly identifies the resource and scope. It wastes no words and is easy to parse quickly.
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?
Given the tool's simplicity (2 parameters, both well-documented in schema), the presence of an output schema, and comprehensive annotations covering read-only and idempotent properties, the description is adequate. It could mention that the file must be accessible by the authenticated user, but the score remains high due to the richness of other structured fields.
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 100%, and both parameters have adequate descriptions in the schema. The tool description does not add any further semantics or clarifications about parameter usage, format, or dependencies beyond what the schema provides, so a baseline score of 3 is appropriate.
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 description explicitly states it retrieves detailed metadata including sharing permissions from a Google Drive file. The verb 'gets' combined with the resource 'drive file permissions' clearly distinguishes it from siblings like 'check_drive_file_public_access' (which checks public access status) and 'set_drive_file_permissions' (which modifies permissions).
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?
No guidance is provided on when to use this tool versus alternatives. For example, it does not contrast with 'check_drive_file_public_access' or 'get_file_metadata'. The agent receives no context about scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns metadata for a single Google Drive file by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | user@gmail.com | |
| fileId | Yes | The Drive file ID. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and idempotent. The description adds no additional behavioral context beyond the annotations, such as what metadata fields are returned or any rate limits.
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?
The description is a single, front-loaded sentence without unnecessary words, achieving conciseness. However, it is slightly too terse and could provide more context without sacrificing brevity.
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?
The presence of an output schema reduces the need to explain return values. However, given the tool has multiple parameters and many siblings, the description lacks contextual guidance on parameter usage (e.g., when to specify 'user_google_email') and fails to differentiate from similar 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?
The description only mentions the 'ID' parameter implicitly, ignoring the 'user_google_email' parameter entirely. With only 50% schema description coverage, the description fails to clarify the purpose or usage of the missing parameter.
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 description clearly specifies the action ('Returns metadata') and the resource ('single Google Drive file by ID'), distinguishing it from sibling tools like copy, create, or list operations.
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 for retrieving metadata but provides no explicit guidance on when to use versus alternatives like 'list_drive_items' or 'read_file_content'. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Imports a file (Markdown, DOCX, TXT, HTML, RTF, ODT) into Google Docs format with automatic conversion.
Google Drive automatically converts the source file to native Google Docs format, preserving formatting like headings, lists, bold, italic, etc. For batch operations, prefer file_path for files on disk so callers do not need to load full file contents into their context.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| file_name | Yes | The name for the new Google Doc (extension will be ignored). | |
| content | No | Text content for text-based formats. Use only for short snippets or content already in memory. | |
| file_path | No | Local file path or file:// URL for any supported format (MD, TXT, HTML, DOCX, ODT, RTF). Appropriate for larger files than content, but file_path may still load the file into memory or perform non-streaming reads. Avoid very large files that could exceed memory or time limits; use streaming/chunked uploads or an alternative API for huge files. | |
| file_url | No | Remote URL to fetch the file from (http/https). | |
| source_format | No | Source format hint ('md', 'markdown', 'docx', 'txt', 'html', 'rtf', 'odt'). Auto-detected from file_name extension if not provided. | |
| folder_id | No | The ID of the parent folder. Defaults to 'root'. | root |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses automatic conversion and formatting preservation. It warns about file_path loading into memory and advises against very large files. Annotations (readOnlyHint=false, destructiveHint=false) are consistent, and the description adds memory and size considerations beyond 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?
Three sentences, each serving a purpose: main action, conversion behavior, and usage advice. No wasted words, well-structured with key information upfront.
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-purpose import tool with an output schema (presumably documenting return values), the description covers input sources, formats, conversion behavior, and practical constraints. It is complete for an AI agent to invoke 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 coverage is 100%, but the description adds meaningful advice: prefer file_path for batch operations, use content only for short snippets, and avoid huge files. This enhances understanding beyond the schema's basic descriptions.
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 description clearly states the verb 'imports' and the resource 'file into Google Docs format' with automatic conversion. It lists supported formats, making the purpose unambiguous. The tool is distinct from siblings like create_file or update_drive_file, which do not involve conversion to Google Docs.
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 provides guidance on parameter selection (prefer file_path for batch operations, content for short snippets) but does not explicitly compare to sibling tools. It lacks when-to-use versus alternatives like create_file or update_drive_file, so usage context is partial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists files/folders or shared drive containers, supporting shared drives.
If drive_id is specified, lists items within that shared drive. folder_id is then relative to that drive (or use drive_id as folder_id for root).
If drive_id is not specified, lists items from user's "My Drive" and accessible shared drives (if include_items_from_all_drives is True).
Set resource_type to "shared_drives" to list shared drive containers instead of folder contents.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| folder_id | No | The ID of the Google Drive folder. Defaults to 'root'. For a shared drive, this can be the shared drive's ID to list its root, or a folder ID within that shared drive. | root |
| page_size | No | The maximum number of items to return. Defaults to 100. | |
| page_token | No | Page token from a previous response's nextPageToken to retrieve the next page of results. | |
| drive_id | No | ID of the shared drive. If provided, the listing is scoped to this drive. | |
| include_items_from_all_drives | No | Whether items from all accessible shared drives should be included if `drive_id` is not set. Defaults to True. | |
| corpora | No | Corpus to query ('user', 'drive', 'allDrives'). If `drive_id` is set and `corpora` is None, 'drive' is used. If None and no `drive_id`, API defaults apply. | |
| 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). | |
| detailed | No | Whether to include size, modified time, and link in results. Defaults to True. | |
| 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). | |
| resource_type | No | What to list. Use "items" for folder contents or "shared_drives" for shared drive containers. Defaults to "items". | items |
| query | No | Shared drive query used only when resource_type="shared_drives", e.g. "name contains 'Engineering'". | |
| include_organizers | No | When resource_type="shared_drives", include principals with the organizer role. This costs one extra permissions.list API call per shared drive returned. Defaults to False. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnly, non-destructive, and idempotent. The description adds valuable behavioral details: behavior with/without drive_id, folder_id relativity, and the effect of resource_type. No contradictions with 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?
Four sentences, each with a distinct purpose: main function, drive_id behavior, without drive_id behavior, and resource_type. Front-loaded with the most important info. No unnecessary words.
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?
Given 13 parameters, full schema coverage, and output schema presence, the description covers key behavioral aspects (scope, resource type). Could mention pagination or sorting, but those are in schema. Overall adequate for a list tool.
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?
While schema coverage is 100% with good descriptions, the description adds meaningful semantics by explaining parameter interactions (e.g., drive_id scoping, folder_id relative to drive, resource_type switching). This goes beyond the schema's standalone descriptions.
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 description clearly states the verb 'lists' and resource 'files/folders or shared drive containers', with specific mention of supporting shared drives. It effectively distinguishes this tool from siblings like search_files or check_drive_file_public_access by focusing on listing contents versus searching or checking access.
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 provides explicit guidance on when to use drive_id and how resource_type='shared_drives' changes behavior. It implies usage context (listing items vs containers) but does not explicitly state when not to use this tool or list alternatives, though siblings provide context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the user's most recently modified files in Google Drive (across all drives the user has access to). Excludes trashed items.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | user@gmail.com | |
| page_size | No | Maximum number of files to return. Defaults to 10. | |
| page_token | No | Page token from a prior nextPageToken. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe read operation (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds value by specifying that results span all accessible drives and exclude trashed items, enhancing behavioral understanding beyond 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?
The description is a single, well-structured sentence of 20 words. It is front-loaded with the core action and resource, making it highly concise and easy to parse.
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?
Given the simple tool with 3 parameters, existing output schema, and detailed annotations, the description is sufficiently complete. It covers key aspects (scope, exclusion), though it does not explicitly mention pagination or sorting order, which are implicit.
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 67% (two of three parameters have descriptions). The description does not elaborate on parameters, but the schema already provides adequate meaning for 'page_size' and 'page_token'. The undocmented 'user_google_email' parameter could benefit from clarification, but the baseline of 3 is appropriate given the schema's coverage.
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 description clearly states the tool lists the user's most recently modified files across all drives and excludes trashed items. The verb 'Lists' and resource specification make the purpose unambiguous, distinguishing it from sibling tools like 'list_drive_items' and 'search_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?
The description implies usage for retrieving recently modified files but lacks explicit guidance on when to use this tool versus alternatives like 'list_drive_items' or 'search_files'. No when-not-to-use or alternative names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Consolidated tool for managing Google Drive file and folder access permissions.
Supports granting, batch-granting, updating, revoking permissions, and transferring file ownership -- all through a single entry point.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| file_id | Yes | The ID of the file or folder. Required. | |
| action | Yes | The access management action to perform. Required. One of: - "grant": Share with a single user, group, domain, or anyone. - "grant_batch": Share with multiple recipients in one call. - "update": Modify an existing permission (role or expiration). - "revoke": Remove an existing permission. - "transfer_owner": Transfer file ownership to another user. | |
| share_with | No | Email address (user/group), domain name (domain), or omit for 'anyone'. Used by "grant". | |
| role | No | Permission role -- 'reader', 'commenter', or 'writer'. Used by "grant" (defaults to 'reader') and "update". | |
| share_type | No | Type of sharing -- 'user', 'group', 'domain', or 'anyone'. Used by "grant". Defaults to 'user'. | user |
| permission_id | No | The permission ID to modify or remove. Required for "update" and "revoke" actions. | |
| recipients | No | List of recipient objects for "grant_batch". Each should have: email (str), role (str, optional), share_type (str, optional), expiration_time (str, optional). For domain shares use 'domain' field instead of 'email'. | |
| send_notification | No | Whether to send notification emails. Defaults to True. Used by "grant" and "grant_batch". | |
| email_message | No | Custom notification email message. Used by "grant" and "grant_batch". | |
| expiration_time | No | Expiration in RFC 3339 format (e.g., "2025-01-15T00:00:00Z"). Used by "grant" and "update". | |
| allow_file_discovery | No | For 'domain'/'anyone' shares, whether the file appears in search. Used by "grant". | |
| new_owner_email | No | Email of the new owner. Required for "transfer_owner". | |
| move_to_new_owners_root | No | Move file to the new owner's My Drive root. Defaults to False. Used by "transfer_owner". |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, which the description aligns with by mentioning revoke and transfer. However, the description adds no additional behavioral context beyond what annotations provide, such as side effects of ownership transfer or notification sending. The description is consistent but not additive.
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?
The description is two sentences, front-loading the core purpose ('Consolidated tool for managing...') and then listing actions succinctly. Every sentence contributes value without redundancy. Ideal length for a complex tool.
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?
Given the high complexity (14 parameters, multiple actions) and the presence of an output schema, the description covers the tool's scope but lacks examples or guidance on action selection. It is minimally complete but could be more helpful with usage patterns.
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 100%, so the input schema fully documents all 14 parameters. The tool description adds no extra parameter-level meaning or usage context beyond the schema, so it meets the baseline but does not elevate understanding.
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 description clearly states it is a consolidated tool for managing Google Drive access permissions and explicitly lists all supported actions (grant, batch-grant, update, revoke, transfer ownership). This distinguishes it from sibling tools like set_drive_file_permissions and get_drive_file_permissions by positioning itself as a unified entry point.
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 does not explicitly guide when to use this tool versus its siblings. It implies it is for any permission management need but lacks concrete scenarios, alternatives, or exclusions. The guidance is implied but not actionable for an AI agent deciding between this and set_drive_file_permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the content of a specific Google Drive file by ID, supporting files in shared drives.
• Native Google Docs, Sheets, Slides → exported as text / CSV. • Office files (.docx, .xlsx, .pptx) → unzipped & parsed with std-lib to extract readable text. • PDFs → text extracted with pypdf when possible; scanned/image-only PDFs fall back to a download hint. • Images → returned as base64 with MIME metadata for multimodal clients. • Any other file → downloaded; tries UTF-8 decode, else notes binary.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | user@gmail.com | |
| fileId | Yes | Drive file ID. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, etc. The description adds significant detail on per-type behavior (export, parsing, base64 for images, fallbacks), going well beyond the annotations. No contradiction.
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?
The description is concise, well-organized with bullet points, and every sentence provides valuable behavioral information. No wasted words.
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?
Given the complexity of handling multiple file types, the description covers input, behavior, edge cases (e.g., scanned PDFs), and fallbacks. Output schema exists, so return values are covered.
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 50% (only fileId has a brief description). The description does not add any parameter semantics or clarify user_google_email. It fails to compensate for the missing schema descriptions.
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 description clearly states the tool retrieves file content by ID, supporting shared drives. It lists specific handling for different file types (Google Docs, Office files, PDFs, images, others), distinguishing it from siblings like download_file_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?
The description implies use for getting textual content, but does not explicitly state when to use this tool vs alternatives like download_file_content. No guidance on when not to use (e.g., for binary files that cannot be parsed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches for files and folders within a user's Google Drive, including shared drives.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| 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. | |
| 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. | |
| drive_id | No | ID of the shared drive to search. If None, behavior depends on `corpora` and `include_items_from_all_drives`. | |
| 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`. | |
| 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. | |
| 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). | |
| detailed | No | Whether to include size, modified time, and link in results. Defaults to True. | |
| 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). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds no additional behavioral context such as permission requirements, rate limits, or pagination behavior. For a search tool with zero annotation coverage on behaviors, it underdelivers.
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?
A single, efficient sentence that immediately conveys the core function. No redundant or unnecessary words. Perfectly concise.
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?
Given the tool has 10 parameters and an output schema, the description omits high-level information about return format (e.g., list of file metadata) and pagination. Adequate for basic understanding but misses completeness for complex usage.
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 100% and includes detailed parameter explanations. The tool description itself contributes no parameter information, which is acceptable per scoring rules, earning the baseline of 3.
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?
Description clearly states verb (searches) and resource (files and folders) within Google Drive including shared drives. However, it does not explicitly differentiate from sibling tools like list_drive_items or list_recent_files, though the search function is implicitly distinct.
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?
No guidance on when to use this tool versus alternatives. No mention of prerequisites, contexts, or exclusions. Agent must infer usage from tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets file-level sharing settings and controls link sharing for a Google Drive file or folder.
This is a high-level tool for the most common permission changes. Use this to toggle "anyone with the link" access or configure file-level sharing behavior. For managing individual user/group permissions, use share_drive_file or update_drive_permission instead.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| file_id | Yes | The ID of the file or folder. Required. | |
| link_sharing | No | Control "anyone with the link" access for the file. - "off": Disable "anyone with the link" access for this file. - "reader": Anyone with the link can view. - "commenter": Anyone with the link can comment. - "writer": Anyone with the link can edit. | |
| writers_can_share | No | Whether editors can change permissions and share. If False, only the owner can share. Defaults to None (no change). | |
| copy_requires_writer_permission | No | Whether viewers and commenters are prevented from copying, printing, or downloading. Defaults to None (no change). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true and readOnlyHint: false, indicating mutation. Description adds that it is a 'high-level tool' but does not elaborate on behavioral nuances like immediacy of changes or permission requirements. No contradiction with 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?
Two short paragraphs with the main purpose front-loaded. Every sentence adds value; no redundant or vague phrases.
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?
Given annotations, output schema, and complete parameter descriptions, the description adequately explains scope and alternatives. Could mention required permissions (e.g., write access) but overall sufficient.
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 100%, so schema already documents parameters well. Description does not add extra meaning beyond listing high-level purpose. Baseline score of 3 is appropriate.
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?
Description clearly states it sets file-level sharing settings and controls link sharing for a Google Drive file or folder. It explicitly distinguishes from sibling tools share_drive_file and update_drive_permission.
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?
Provides explicit when-to-use guidance: 'Use this to toggle 'anyone with the link' access or configure file-level sharing behavior.' Directs to alternatives: 'For managing individual user/group permissions, use share_drive_file or update_drive_permission instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manually initiate Google OAuth authentication flow.
NOTE: This is a legacy OAuth 2.0 tool and is disabled when OAuth 2.1 is enabled. The authentication system automatically handles credential checks and prompts for authentication when needed. Only use this tool if:
You need to re-authenticate with different credentials
You want to proactively authenticate before using other tools
The automatic authentication flow failed and you need to retry
In most cases, simply try calling the Google Workspace tool you need - it will automatically handle authentication if required.
| Name | Required | Description | Default |
|---|---|---|---|
| service_name | Yes | ||
| user_google_email | No | user@gmail.com |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the legacy nature and OAuth 2.1 disabling, adding context beyond the minimal annotations. However, it does not describe side effects or what happens on failure.
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?
The description is front-loaded with the main purpose and well-structured with bullet points, though it could be slightly more concise.
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?
Covers legacy and usage guidance well, but lacks parameter explanations and output details. The output schema exists but is not referenced.
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% and the description does not explain 'service_name' or 'user_google_email' parameters, leaving the agent without guidance on their values or purpose.
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 description clearly states 'Manually initiate Google OAuth authentication flow' and differentiates from sibling tools focused on Drive operations, with specific use cases listed.
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?
Explicitly states when to use the tool (re-authentication, proactive login, retry) and when not to (automatic flow is preferred), with a clear recommendation to attempt other tools first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates metadata and properties of a Google Drive file.
| Name | Required | Description | Default |
|---|---|---|---|
| user_google_email | No | The user's Google email address. Required. | user@gmail.com |
| file_id | Yes | The ID of the file to update. Required. | |
| name | No | New name for the file. | |
| description | No | New description for the file. | |
| mime_type | No | New MIME type (note: changing type may require content upload). | |
| add_parents | No | Comma-separated folder IDs to add as parents. | |
| remove_parents | No | Comma-separated folder IDs to remove from parents. | |
| starred | No | Whether to star/unstar the file. | |
| trashed | No | Whether to move file to/from trash. | |
| writers_can_share | No | Whether editors can share the file. | |
| copy_requires_writer_permission | No | Whether copying requires writer permission. | |
| properties | No | Custom key-value properties for the file. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, which is consistent with 'updates'. But description adds no extra behavioral context (e.g., risk of data loss, permission requirements, rollback).
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?
Single sentence, no fluff, front-loaded with key action. Could benefit from brief examples or structural hints.
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 destructive tool with 12 parameters and many siblings, the description is too minimal. It omits return value hints, prerequisites, and does not help the agent decide when to invoke it.
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 has 100% description coverage for all 12 parameters, so description adds no value beyond what the schema already provides.
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?
Clearly states it updates metadata and properties of a Google Drive file. However, it does not distinguish from sibling tools like copy_drive_file or manage_drive_access, which also modify file state.
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?
No guidance on when to use this tool versus alternatives like copy_drive_file or set_drive_file_permissions. No when-not or context provided.
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.0check_drive_file_public_accesscopy_drive_filecreate_drive_foldercreate_filecreate_resumable_upload_sessiondownload_file_contentget_drive_file_permissionsget_drive_shareable_linkget_file_metadataimport_to_google_doclist_drive_itemslist_recent_filesmanage_drive_accessread_file_contentsearch_filesset_drive_file_permissionsstart_google_authupdate_drive_fileScored across 18 tools
Most tools have distinct purposes, with clear descriptions differentiating overlapping functions like multiple permission tools and content retrieval methods. However, some pairs (e.g., create_file vs import_to_google_doc, download_file_content vs read_file_content) could cause confusion despite descriptive names.
Naming follows a general verb_noun pattern but mixes styles: some use 'get', some 'list', some 'read', and 'manage_drive_access' is generic. Inconsistencies like 'create_file' vs 'create_drive_folder' and 'start_google_auth' break the pattern, making the set somewhat predictable but not fully uniform.
With 18 tools, the server covers a broad range of Google Drive operations without being overwhelming. Each tool addresses a distinct need (CRUD, permissions, search, auth, upload), and the count feels well-scoped for the domain.
The tool set lacks a basic delete/trash operation, which is a critical gap for file management. While it covers creation, copying, updating, permissions, and reading, the absence of deletion means agents cannot complete lifecycle workflows, leading to potential failures.
Give Claude only the Google Drive files you choose. Every action logged.
Personal CRM for Claude. Contacts live as plain-text files in your own Google Drive.
Multiple Google accounts (Gmail, Calendar, Drive, Contacts, Tasks) in one Claude connector.
Provides tools for searching Google Workspace documentation and much more.
