The Google Workspace MCP server enables structured reading, searching, and export of Google Docs, Sheets, and Chat content.
Google Sheets
read_sheet_values – Read raw cell values using A1 notation
read_sheet_grid – Read full grid data including formulas, notes, hyperlinks, and rich text styling (text_runs, annotated_text)
get_sheet_row – Fetch a single row mapped to its header columns
search_sheet – Search for text across one or all sheet tabs
sheet_to_json – Convert a sheet tab to JSON records using the header row as keys
inspect_sheet_images – Detect over-grid images (via XLSX export) and in-cell IMAGE() formulas
Google Docs
read_google_doc – Read a doc as structured JSON (paragraphs, tables, inline/positioned objects, image metadata)
download_google_doc_images – Download all images from a doc to a local folder
Google Chat
list_google_chat_spaces – List accessible Chat spaces
list_google_chat_memberships – List members of a Chat space
read_google_chat_messages – Read messages from a space (by resource name or URL)
read_google_chat_thread – Read a specific thread (by resource name or URL)
File Management & Export
resolve_google_file – Resolve metadata for any Google Docs, Sheets, or Drive file
export_google_file – Export files to PDF, XLSX, HTML zip, Markdown, or plain text
Authentication
diagnose_google_auth – Check and summarize the current authentication setup
Supports OAuth desktop client, service accounts, API keys, and bearer tokens
Utilizes Google Cloud for authentication via service accounts and OAuth to manage secure access to Google Workspace APIs.
Enables reading Google Docs as structured JSON, providing access to paragraphs, tables, inline objects, and image metadata.
Leverages Google Drive APIs for file resolution and exporting files to recover over-grid images and other metadata.
Provides comprehensive tools for reading sheet values, grid data, formulas, notes, and hyperlinks, along with capabilities for searching and converting sheets to JSON.
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., "@Google Workspace MCP read the values and formulas from my 'Project Budget' spreadsheet"
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.
Python MCP server for reading Google Docs, Google Sheets, and Google Chat with structured output and better image handling.
Reads Google Docs as structured JSON with paragraphs, tables, inline objects, positioned objects, and image metadata.
Reads Google Sheets values, grid data, formulas, notes, hyperlinks, and chip runs.
Lists Google Chat spaces, space members, and messages as structured JSON.
Preserves partial text styling in Sheets cells via text_runs and an annotated_text helper field for segments such as strikethrough and underline.
Extracts over-grid sheet images from Drive export -> XLSX.
Detects in-cell IMAGE("...") formulas separately from drawing exports.
Related MCP server: Google Docs & Drive MCP Server
google_workspace_mcp/
chat.py # Google Chat normalization helpers
cli.py # command-line entrypoint
client.py # Google API auth + HTTP client
common.py # shared constants and parsing helpers
docs.py # Google Docs normalization helpers
server.py # FastMCP server instance
sheets.py # Google Sheets normalization helpers
tools.py # MCP tool definitions
mcp_google_workspace.py # compatibility wrapper for local scripts/config
tests/pip install "git+https://github.com/NgoQuocViet2001/google-workspace-mcp.git"The most reliable way to run it across platforms is:
python -m google_workspace_mcpIf your Python Scripts directory is already on PATH, this shorter launcher works too:
google-workspace-mcpIn Google Cloud, create an OAuth client ID with application type Desktop app.
If the published package already includes a bundled OAuth desktop client, just run:
python -m google_workspace_mcp auth loginThat opens the browser OAuth flow directly.
If the package does not include a bundled OAuth client and no local OAuth client config exists yet, the CLI prompts once for:
Client ID
Client Secret
It then saves a reusable desktop-app client config at:
$HOME/.google-workspace-mcp/oauth-client-secret.jsonand opens the browser OAuth flow automatically. After the first successful login, the cached token is stored at:
$HOME/.google-workspace-mcp/oauth-token.jsonpython -m google_workspace_mcp auth status
python -m google_workspace_mcp auth logoutUse python -m google_workspace_mcp ... everywhere below. If google-workspace-mcp is already on PATH, the same commands also work with that shorter launcher.
python -m google_workspace_mcp
python -m google_workspace_mcp auth
python -m google_workspace_mcp auth login
python -m google_workspace_mcp auth login --client-secrets C:\path\to\oauth-client-secret.json
python -m google_workspace_mcp auth login --client-id <client-id> --client-secret <client-secret>
python -m google_workspace_mcp auth login --token-file C:\path\to\oauth-token.json
python -m google_workspace_mcp auth status
python -m google_workspace_mcp auth logout
Use a Google OAuth client ID for Desktop App if the files are private but shared to your personal Google account.
If you want end users to be able to run python -m google_workspace_mcp auth login and jump straight into the browser OAuth flow with no extra setup, publish the package with a bundled desktop-app client at:
google_workspace_mcp/oauth-default-client.jsonIf no bundled client is shipped, the CLI falls back to prompting once for Client ID and Client Secret, or it can read them from a local JSON file.
Enable:
Google Sheets API
Google Docs API
Google Drive API
Google Chat API
Create an OAuth client ID with application type Desktop app.
Choose one setup method:
Easiest: run python -m google_workspace_mcp auth login, paste the Client ID and Client Secret once, and let the CLI save them for future logins.
If you prefer files: download the client secret JSON. The downloaded filename is often something like client_secret_<id>.apps.googleusercontent.com.json.
Optional file-based setup:
$HOME/.google-workspace-mcp/oauth-client-secret.jsonOr set:
$env:GOOGLE_OAUTH_CLIENT_SECRETS_FILE="C:\path\to\oauth-client-secret.json"Run the one-time browser login flow:
python -m google_workspace_mcp authAfter the first successful login, the server automatically uses the cached OAuth token for private Docs, Sheets, Drive, and Google Chat calls. You do not need to provide a separate API key for that flow.
This stores a refreshable token by default at:
$HOME\.google-workspace-mcp\oauth-token.jsonUse this to inspect the cached token scopes and see which scopes are still missing:
python -m google_workspace_mcp auth statusIf auth status shows only drive.readonly, Sheets URLs that include gid and range can still be read through the server's Drive export fallback. That fallback returns values-oriented output and omits formulas, notes, hyperlinks, and rich text metadata until you re-run python -m google_workspace_mcp auth login with spreadsheets.readonly.
If you need to overwrite the cached token with a specific client secret file and token path, you can also run:
python -m google_workspace_mcp auth login --client-secrets C:\path\to\oauth-client-secret.json --token-file C:\path\to\oauth-token.jsonIf the desktop-app client JSON is already in $HOME/.google-workspace-mcp/, this shorter command also works:
python -m google_workspace_mcp auth loginWhen you log in with --client-secrets, or with --client-id plus --client-secret, the CLI also saves a reusable desktop-app client JSON into $HOME/.google-workspace-mcp/oauth-client-secret.json so future logins can omit the extra flags.
To delete the cached OAuth token later, run:
python -m google_workspace_mcp auth logoutIf you separately configured GOOGLE_OAUTH_ACCESS_TOKEN, remove that environment variable from your shell or MCP config as well.
Use a Google Cloud service account for the most reliable setup.
Enable:
Google Sheets API
Google Docs API
Google Drive API
Google Chat API if you plan to call the Chat tools with a user-scoped bearer token
Create a service account key.
Share the target Docs/Sheets files with the service account email.
Set:
$env:GOOGLE_SERVICE_ACCOUNT_FILE="C:\path\to\service-account.json"Suitable for public Google Sheets reads. Not recommended for Docs or Drive export.
$env:GOOGLE_API_KEY="your_api_key"$env:GOOGLE_OAUTH_ACCESS_TOKEN="ya29...."git clone https://github.com/NgoQuocViet2001/google-workspace-mcp.git
cd google-workspace-mcp
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txtgit clone https://github.com/NgoQuocViet2001/google-workspace-mcp.git
cd google-workspace-mcp
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txtpip install "git+https://github.com/NgoQuocViet2001/google-workspace-mcp.git"After installing from GitHub, the most reliable way to run it is:
python -m google_workspace_mcpThis avoids PATH issues when pip installs console scripts into a user-site Scripts directory.
If your Python Scripts directory is already on PATH, the standalone command also works:
google-workspace-mcpcd <path-to-repo>
.venv\Scripts\python.exe mcp_google_workspace.pyOr, if you installed it directly from GitHub:
python -m google_workspace_mcpTo bootstrap OAuth for a private user account:
python -m google_workspace_mcp authIf your google-workspace-mcp launcher is already available on PATH, the equivalent shorter command is:
google-workspace-mcp auth loginTo inspect the current auth setup:
python -m google_workspace_mcp auth statusTo remove the cached OAuth login:
python -m google_workspace_mcp auth logout{
"mcpServers": {
"google-workspace": {
"command": "<path-to-repo>/.venv/Scripts/python.exe",
"args": ["<path-to-repo>/mcp_google_workspace.py"],
"env": {
"GOOGLE_OAUTH_CLIENT_SECRETS_FILE": "C:/path/to/oauth-client-secret.json",
"GOOGLE_OAUTH_TOKEN_FILE": "C:/path/to/oauth-token.json"
}
}
}
}For public Sheets only, replace the env block with:
{
"GOOGLE_API_KEY": "your_api_key"
}If you installed the package directly from GitHub into an environment on your PATH, you can also use:
{
"mcpServers": {
"google-workspace": {
"command": "google-workspace-mcp",
"env": {
"GOOGLE_OAUTH_CLIENT_SECRETS_FILE": "C:/path/to/oauth-client-secret.json",
"GOOGLE_OAUTH_TOKEN_FILE": "C:/path/to/oauth-token.json"
}
}
}
}diagnose_google_auth
resolve_google_file
list_google_chat_spaces
get_google_chat_space
get_google_chat_message
read_google_chat_messages
read_google_chat_thread
list_google_chat_memberships
read_sheet_values
read_sheet_grid
get_sheet_row
search_sheet
sheet_to_json
inspect_sheet_images
read_google_doc
download_google_doc_images
export_google_file
Replace placeholders such as <spreadsheet-id>, <sheet-name>, and <output-dir> with your own values.
Google Sheets URLs with gid and range are resolved automatically. If the caller omits the sheet prefix, the server uses the tab identified by gid.
get_sheet_row(
"<spreadsheet-id>",
"<sheet-name>",
42,
1
)read_sheet_values also accepts row-style input such as <sheet-name>!42:42 and normalizes it to a valid full-row A1 range automatically.
gid and rangeread_sheet_values(
"https://docs.google.com/spreadsheets/d/<spreadsheet-id>/edit?gid=<gid>#gid=<gid>&range=38:38"
)When the cached OAuth token has drive.readonly but not spreadsheets.readonly, this still succeeds by exporting the addressed tab/range as CSV behind the scenes. The response includes source: "drive_export_csv_fallback" and an auth_warning so callers know richer grid metadata is unavailable.
read_sheet_grid(
"<spreadsheet-id>",
"<sheet-name>!A1:Z200"
)For cells with partial formatting, read_sheet_grid() now includes:
text_runs: structured offsets plus style flags from Google Sheets
annotated_text: a plain-text helper string such as [[STRIKE]]old[[/STRIKE]] new
search_sheet(
"<spreadsheet-id>",
"login"
)If you pass a Sheets URL with gid, search_sheet() searches only that tab by default instead of scanning the full workbook.
list_google_chat_spaces()read_google_chat_messages() accepts either a resource name like spaces/AAAA... or a Chat UI URL that contains the space id.
read_google_chat_messages(
"spaces/AAAA1234567",
50,
null,
null,
"DESC",
false
)read_google_chat_thread() accepts either a thread resource like spaces/<space>/threads/<thread> or a Chat UI URL like https://chat.google.com/room/<space>/<thread>/<message>.
read_google_chat_thread(
"https://chat.google.com/room/AAQAyxdRoZo/jVIpmenXnO0/WNSdv6IyQf0?cls=10"
)When the URL includes a message ID, the response includes both:
linked_message: the exact message referenced by the link
root_message: the first message in the thread
If Google Chat doesn't expose an API message resource that matches the URL token, the response sets linked_message to null and explains the limitation in linked_message_lookup_warning.
list_google_chat_memberships(
"spaces/AAAA1234567"
)sheet_to_json(
"<spreadsheet-id>",
"<sheet-name>",
1
)inspect_sheet_images(
"<spreadsheet-id>",
"<sheet-name>",
"C:/path/to/output/sheet-images"
)read_google_doc(
"https://docs.google.com/document/d/<doc-id>/edit",
null,
false,
null
)download_google_doc_images(
"https://docs.google.com/document/d/<doc-id>/edit",
"C:/path/to/output/doc-images",
null
)Google Docs image metadata is available directly through the Docs API, so document extraction is strong.
Google Sheets does not expose over-grid images as cleanly as cell data, so this server uses XLSX export to recover them.
Google Chat reads require OAuth scopes such as chat.spaces.readonly, chat.messages.readonly, and chat.memberships.readonly. If your cached token is older, rerun python -m google_workspace_mcp auth login.
Google Chat API requests also require a configured Chat app in the same Google Cloud project. In Google Chat API > Configuration, fill in at least App name, Avatar URL, and Description, then save.
Google Chat room URLs always expose the space ID, and often work for thread reads, but the final URL token isn't guaranteed to be a spaces/{space}/messages/{message} API resource name. In those cases the server can still return the thread and root message, but not reliably resolve the exact linked reply through the Chat API alone.
Google Chat private user conversations are most reliable with OAuth user credentials. A plain service account usually needs a properly configured Chat app flow to access Chat resources.
In-cell IMAGE("...") formulas are detected separately from exported drawing images.
Private files shared to your user account should use the OAuth desktop client flow.
Private files shared to a robot identity should use a service account.
An API key is only suitable for public Sheets and can't read Google Chat.
drive.readonly alone is enough for the Sheets URL fallback described above, but Google Docs still require documents.readonly.
Return a quick summary of the active Google authentication setup.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Return a quick summary' implies a read-only operation, it doesn't specify what information the summary contains, whether it checks authentication validity or just configuration, potential error conditions, or any rate limits. For an authentication diagnostic tool with zero annotation coverage, this leaves significant behavioral gaps.
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, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized for a zero-parameter tool and front-loads the essential information. Every word earns its place in this concise formulation.
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 that this tool has an output schema (which should document the return format), the description doesn't need to explain return values. However, for an authentication diagnostic tool with no annotations, the description should provide more context about what 'active Google authentication setup' means and what kind of summary to expect. The presence of an output schema helps, but the description remains somewhat minimal for this context.
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 tool has zero parameters, and schema description coverage is 100% (though empty). The description appropriately doesn't waste space discussing nonexistent parameters. Since there are no parameters to document, the baseline score of 4 is appropriate as the description doesn't need to compensate for any parameter documentation gaps.
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's purpose with a specific verb ('Return') and resource ('active Google authentication setup'), making it immediately understandable. However, it doesn't explicitly differentiate this authentication diagnostic tool from its sibling tools which are all focused on Google document/spreadsheet operations rather than authentication.
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 guidance about when to use this tool versus alternatives. It doesn't mention prerequisites (like needing authentication to be configured first), troubleshooting scenarios, or how this differs from other authentication-related tools that might exist. The agent receives no usage context beyond the basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download image objects from a Google Doc to a local folder.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id_or_url | Yes | ||
| output_dir | No | ||
| tab_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('download') but doesn't cover permissions needed, rate limits, file formats supported, error handling, or whether it overwrites existing files. For a tool that likely involves file system operations and API calls, this leaves significant gaps in understanding its behavior.
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, efficient sentence that front-loads the core action and resource. It wastes no words and is appropriately sized for the tool's complexity, making it 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 has an output schema (which likely covers return values), the description's job is reduced. However, with no annotations, 3 parameters (one undocumented due to 0% schema coverage), and operations involving downloads and file system changes, the description is incomplete. It should address more behavioral aspects like error cases or output specifics beyond what the output schema might provide.
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 must compensate for undocumented parameters. It mentions 'document_id_or_url' and 'output_dir' implicitly but doesn't explain what 'tab_id' does or provide details on parameter formats (e.g., URL patterns, directory paths). The description adds minimal value beyond the schema's property names, failing to fully address the coverage gap.
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 ('download') and resource ('image objects from a Google Doc'), specifying the destination ('to a local folder'). It distinguishes from siblings like 'read_google_doc' or 'inspect_sheet_images' by focusing on downloading images rather than reading content or inspecting images in sheets. However, it doesn't explicitly differentiate from all siblings, such as 'export_google_file', which might handle similar 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 provides no guidance on when to use this tool versus alternatives like 'export_google_file' or 'inspect_sheet_images'. It lacks context on prerequisites (e.g., authentication), exclusions (e.g., not for text extraction), or specific scenarios (e.g., batch image extraction). Usage is implied by the action but not explicitly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a Google Workspace file to PDF, XLSX, HTML zip, Markdown, or plain text.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id_or_url | Yes | ||
| mime_type | Yes | ||
| output_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a mutation (exporting changes format) but doesn't clarify if it modifies the original file, requires specific permissions, has rate limits, or what the output entails (e.g., file creation, download link). The description lacks details on error handling, performance, or side effects, leaving significant gaps for a tool with potential write operations.
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, efficient sentence that front-loads the core purpose without unnecessary words. It lists export formats clearly and avoids redundancy. Every part earns its place by specifying the action, resource, and target formats concisely.
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 3 parameters with 0% schema coverage, no annotations, and an output schema present, the description is moderately complete. It covers the basic purpose and formats but lacks details on usage, behavior, and parameter meanings. The output schema likely handles return values, reducing the need for output explanation, but the description doesn't fully address the tool's complexity and mutation aspects.
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 schema provides no parameter details. The description adds minimal semantics by implying 'mime_type' relates to export formats (PDF, XLSX, etc.) and 'file_id_or_url' identifies the source, but doesn't explain parameter roles, formats, or constraints (e.g., valid MIME types, URL patterns). It partially compensates for the coverage gap but leaves parameters largely undocumented.
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 ('Export') and resource ('Google Workspace file'), specifying the target formats (PDF, XLSX, HTML zip, Markdown, plain text). It distinguishes from siblings like 'read_google_doc' or 'download_google_doc_images' by focusing on format conversion rather than reading or downloading images. However, it doesn't explicitly differentiate from all siblings (e.g., 'sheet_to_json' also exports data).
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. It doesn't mention prerequisites (e.g., file accessibility, authentication), compare to siblings like 'read_google_doc' for viewing or 'sheet_to_json' for JSON export, or specify use cases (e.g., for archival, sharing in non-Google formats). The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one Google Sheets row and map it to the header row.
| Name | Required | Description | Default |
|---|---|---|---|
| spreadsheet_id_or_url | Yes | ||
| sheet_name | Yes | ||
| row_index | Yes | ||
| header_row | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions mapping to header row but doesn't disclose behavioral traits like error handling (e.g., invalid row index), permissions needed, rate limits, or output format details. For a tool with no annotation coverage, this is a significant gap.
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, zero waste, front-loaded with the core action. Every word earns its place by specifying the fetch operation and header mapping without unnecessary details.
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 no annotations and 0% schema description coverage, but with an output schema present, the description is incomplete. It covers the basic purpose but lacks crucial context like parameter semantics and behavioral transparency. The output schema mitigates some gaps, but overall it's minimally adequate with clear deficiencies.
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 must compensate. It mentions mapping to header row, which relates to the 'header_row' parameter, but doesn't explain the meaning or usage of other parameters like spreadsheet_id_or_url, sheet_name, or row_index. The description adds minimal value beyond 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?
The description clearly states the action ('fetch') and resource ('one Google Sheets row'), and specifies the mapping to header row. It distinguishes from siblings like read_sheet_grid or read_sheet_values by focusing on single-row retrieval with header mapping, though not explicitly naming alternatives.
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 read_sheet_values or search_sheet. The description implies it's for fetching a specific row with header mapping, but lacks explicit context or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect Google Sheets images via XLSX export and detect IMAGE() formulas.
| Name | Required | Description | Default |
|---|---|---|---|
| spreadsheet_id_or_url | Yes | ||
| sheet_name | No | ||
| output_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the method ('via XLSX export') and detection of 'IMAGE() formulas', but fails to describe critical behaviors: whether this is a read-only operation, if it modifies files, authentication requirements, rate limits, output format (though an output schema exists), or error handling. For a tool with no annotation coverage, this leaves significant gaps in understanding its operational traits.
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, efficient sentence that front-loads the core purpose without unnecessary details. Every word earns its place by specifying the action, target, and method concisely. There's no redundancy or fluff, making it 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 complexity (involving Google Sheets, XLSX export, and image/formula detection), no annotations, and an output schema (which mitigates the need to describe return values), the description is incomplete. It covers the 'what' but misses the 'how' and 'when'—lacking usage context, behavioral details, and parameter explanations. The presence of an output schema raises the baseline, but the gaps in other areas keep it at a minimal viable level.
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 adds no parameter-specific information beyond what the input schema provides. With 0% schema description coverage, the three parameters (spreadsheet_id_or_url, sheet_name, output_dir) are undocumented in both the schema and description. The description implies context about inspecting images and formulas but doesn't explain how parameters relate to this, such as what 'output_dir' controls or if 'sheet_name' limits the inspection scope. Baseline 3 is appropriate as the schema does minimal work, and the description doesn't compensate.
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's purpose: 'Inspect Google Sheets images via XLSX export and detect IMAGE() formulas.' It specifies the verb ('inspect'), resource ('Google Sheets images'), and method ('via XLSX export'), which is specific and actionable. However, it doesn't explicitly differentiate from sibling tools like 'download_google_doc_images' or 'export_google_file', which could have overlapping functionality.
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 guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., authentication, file access), use cases (e.g., analyzing embedded images vs. formulas), or exclusions (e.g., not for downloading images directly). With sibling tools like 'download_google_doc_images' and 'export_google_file', the lack of differentiation leaves the agent guessing about the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a Google Doc as structured JSON with text, tables, and image metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id_or_url | Yes | ||
| tab_id | No | ||
| download_images | No | ||
| output_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic operation. It doesn't disclose behavioral traits such as authentication needs, rate limits, error handling, or whether it's a read-only operation (implied but not explicit). The description doesn't add meaningful context beyond the basic function.
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, efficient sentence that front-loads the core purpose. Every word earns its place by specifying the action, target, and output format without 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's moderate complexity (4 parameters, no annotations) and the presence of an output schema, the description is minimally adequate. It covers the basic purpose but lacks crucial context like authentication, error cases, or parameter usage. The output schema likely handles return values, but the description doesn't address behavioral or usage gaps.
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 must compensate but provides no parameter information. It doesn't explain what 'document_id_or_url' format is expected, what 'tab_id' refers to, or how 'download_images' and 'output_dir' interact. However, with 4 parameters and an output schema present, the baseline is 3 as the schema provides structure but no semantic context.
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 specific action ('Read a Google Doc') and the output format ('as structured JSON with text, tables, and image metadata'). It distinguishes from siblings like 'export_google_file' or 'read_sheet_grid' by specifying it's for Google Docs with JSON output containing specific content types.
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 doesn't mention when to use 'read_google_doc' versus 'export_google_file' or 'download_google_doc_images', nor does it specify prerequisites like authentication or document access requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Google Sheets grid data including formatted values, formulas, notes, and links.
| Name | Required | Description | Default |
|---|---|---|---|
| spreadsheet_id_or_url | Yes | ||
| range_a1 | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states what data is read without behavioral details like permissions needed, rate limits, error handling, or output format. It mentions data types but lacks operational context.
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, efficient sentence with zero waste, front-loaded with the core action and key details. Every word earns its place 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 complexity (read operation with 2 params, no annotations) and an output schema (which covers return values), the description is minimally adequate but incomplete. It specifies data types read but misses parameter guidance and behavioral context, leaving gaps for effective tool use.
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 must compensate but adds no parameter information. It doesn't explain 'spreadsheet_id_or_url' format, 'range_a1' syntax, or default behavior when range is null, leaving parameters undocumented.
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 ('Read') and resource ('Google Sheets grid data') with specific data types included (formatted values, formulas, notes, and links). It distinguishes from sibling 'read_sheet_values' by specifying richer data content, though not explicitly naming alternatives.
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 'read_sheet_values' or 'sheet_to_json' is provided. The description implies usage for reading comprehensive sheet data but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read raw Google Sheets values for an A1 range.
| Name | Required | Description | Default |
|---|---|---|---|
| spreadsheet_id_or_url | Yes | ||
| range_a1 | No | ||
| major_dimension | No | ROWS | |
| value_render_option | No | FORMATTED_VALUE | |
| date_time_render_option | No | SERIAL_NUMBER |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a read operation ('Read raw Google Sheets values'), implying it's non-destructive, but doesn't mention authentication requirements, rate limits, error handling, or what 'raw values' entails. This leaves significant gaps for a tool with 5 parameters.
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, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a tool with this complexity and is front-loaded with the core functionality.
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 5 parameters with 0% schema coverage and no annotations, the description is incomplete—it doesn't address parameter meanings or behavioral details. However, the presence of an output schema means the description doesn't need to explain return values, preventing a lower score. This is the minimum viable for a read operation with structured output.
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 schema description coverage is 0%, meaning none of the 5 parameters have descriptions in the schema. The tool description adds no information about any parameters beyond implying 'range_a1' relates to 'A1 range'. It doesn't explain what 'spreadsheet_id_or_url', 'major_dimension', 'value_render_option', or 'date_time_render_option' mean or how to use them.
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 ('Read raw Google Sheets values') and the resource ('for an A1 range'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'read_sheet_grid' or 'search_sheet', which likely have overlapping functionality, so it doesn't reach the highest score.
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 guidance on when to use this tool versus alternatives like 'read_sheet_grid' or 'search_sheet'. It mentions 'raw values' and 'A1 range', but this is part of the purpose statement rather than explicit usage instructions. No context 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.
Resolve basic metadata for a Google Docs, Sheets, or Drive file.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id_or_url | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool resolves 'basic metadata' but doesn't specify what that includes (e.g., file name, type, size, permissions), whether it requires authentication, if it has rate limits, or what happens with invalid inputs. This leaves significant gaps in understanding the tool's behavior.
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, clear sentence that efficiently conveys the core purpose without unnecessary words. It's front-loaded and appropriately sized for the tool's apparent simplicity, making it 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 low complexity (1 parameter, no nested objects) and the presence of an output schema (which handles return values), the description is somewhat complete but lacks depth. It doesn't cover behavioral aspects like authentication needs or error handling, which are important for a tool interacting with external services like Google Drive, leaving room for improvement.
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 input schema has 0% description coverage, but the description doesn't add any meaningful details about the parameter 'file_id_or_url'. It doesn't explain what formats are accepted (e.g., file ID vs. full URL), examples, or constraints. Since the parameter count is low (1), the baseline is 4, but the lack of compensation for the schema gap reduces the score to 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?
The description clearly states the action ('resolve') and resource ('basic metadata for a Google Docs, Sheets, or Drive file'), making the purpose understandable. However, it doesn't distinguish this tool from potential sibling tools like 'inspect_sheet_images' or 'read_google_doc', which might also retrieve metadata, so it doesn't achieve full 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when it's appropriate (e.g., for quick metadata checks) or when not to use it (e.g., for detailed content access), nor does it refer to sibling tools like 'read_google_doc' or 'export_google_file' as alternatives for different needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search text across one sheet or all sheets and return matching cells.
| Name | Required | Description | Default |
|---|---|---|---|
| spreadsheet_id_or_url | Yes | ||
| needle | Yes | ||
| sheet_name | No | ||
| case_sensitive | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the search functionality but doesn't cover important aspects like whether this is a read-only operation, performance characteristics (e.g., speed on large sheets), authentication requirements, error handling, or what happens with multiple matches. The description is too minimal for a tool with 4 parameters.
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 extremely concise at just one sentence with zero wasted words. It's front-loaded with the core functionality and efficiently communicates the basic purpose. Every word earns its place, making it 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 that an output schema exists, the description doesn't need to explain return values. However, for a search tool with 4 parameters and no annotations, the description is too minimal. It covers the basic purpose but lacks crucial context about behavior, parameter usage, and relationship to sibling tools. The existence of an output schema raises the baseline slightly.
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 0% schema description coverage, the description must compensate but fails to do so. It mentions searching 'across one sheet or all sheets' which hints at the sheet_name parameter, but doesn't explain the spreadsheet_id_or_url format, what 'needle' represents, or the case_sensitive option. The description adds minimal value beyond what's implied by parameter names.
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 ('Search text'), target ('across one sheet or all sheets'), and outcome ('return matching cells'). It distinguishes from siblings like read_sheet_values or read_sheet_grid by focusing on text search rather than data retrieval. However, it doesn't explicitly differentiate from potential similar search tools that might exist.
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 guidance on when to use this tool versus alternatives. It doesn't mention when to choose search_sheet over other tools like read_sheet_values for data extraction or how it relates to siblings like sheet_to_json. There's no context about use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a Google Sheets tab into JSON records using the header row.
| Name | Required | Description | Default |
|---|---|---|---|
| spreadsheet_id_or_url | Yes | ||
| sheet_name | Yes | ||
| header_row | No | ||
| start_row | No | ||
| end_row | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the conversion action but lacks details on permissions required, rate limits, error handling, or output format specifics. This is inadequate for a tool with 5 parameters and no annotation coverage.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, making it easy for an agent 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 complexity (5 parameters, no annotations) and the presence of an output schema, the description is minimally adequate. It covers the core purpose but lacks details on parameter usage, behavioral traits, and differentiation from siblings, leaving gaps that the agent must infer from other sources.
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 must compensate. It mentions 'using the header row', which hints at the 'header_row' parameter, but does not explain other parameters like 'spreadsheet_id_or_url', 'sheet_name', 'start_row', or 'end_row'. The description adds minimal value beyond the schema, resulting in a baseline score.
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's purpose: converting a Google Sheets tab into JSON records using the header row. It specifies the verb 'convert' and resource 'Google Sheets tab', but does not explicitly differentiate from sibling tools like 'read_sheet_values' or 'read_sheet_grid', which might also read sheet data in different formats.
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 guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'read_sheet_values' or 'read_sheet_grid', nor does it specify use cases or exclusions, leaving the agent to infer usage from the purpose alone.
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.4.0diagnose_google_authdownload_google_doc_imagesexport_google_fileget_sheet_rowinspect_sheet_imagesread_google_docread_sheet_gridread_sheet_valuesresolve_google_filesearch_sheetsheet_to_jsonScored across 11 tools
Most tools have distinct purposes targeting specific Google Workspace components like Docs or Sheets, but some overlap exists between read_sheet_grid and read_sheet_values which both read sheet data with slightly different scopes. The descriptions help clarify the differences, but an agent might occasionally confuse these similar tools.
Tool names follow a consistent verb_noun pattern throughout, such as diagnose_google_auth and export_google_file, with clear and descriptive naming. There are minor deviations like sheet_to_json which uses 'to' instead of a verb, but overall the naming is highly predictable and readable.
With 11 tools, the count is well-scoped for a Google Workspace server, covering authentication, file operations, and detailed sheet/document interactions. Each tool earns its place by addressing specific needs without being excessive or insufficient for the domain.
The tool set covers reading and exporting files well, but there are notable gaps in CRUD operations for the domain, such as creating, updating, or deleting Google Docs or Sheets. While tools like export_google_file and read_google_doc handle retrieval, the lack of write or modify tools limits full lifecycle coverage.
Composable APIs for document extraction, image transformation, and document & sheet generation.
PDF and document extraction via Google Document AI. Free trial available.
Provides tools for searching Google Workspace documentation and much more.
Verified OCR with per-value coordinates, plus a workspace agents can file documents into and query.
