The gdrive-mcp server provides a read/write interface for Google Drive, Docs, and Sheets, with safety guardrails like bounded reads, confirm-gated destructive operations, and a local file sandbox. Core capabilities include:
Discovery & Navigation: Resolve Drive/Docs/Sheets URLs or IDs; search files by name, content, MIME type, or parent folder; list folder contents; and retrieve file metadata (owner, timestamps, size, parents, sharing).
Google Docs:
Read documents in markdown/text with paginated bounded chunks, outline, revision ID, and optional colored text.
Extract embedded images in document order.
Create documents with optional initial markdown content.
Append or insert text (supports markdown and colored text) at specific locations using indices or locators.
Insert tables from row grids.
Delete or replace text/sections (with explicit confirmation and dry-run option).
List and add comments.
Google Sheets:
Preview sheets with a bounded 5×5 grid or a specified A1 range.
Read full tabs to local CSV files, returning path and dimensions.
Write rows starting at a cell (confirm-gated when overwriting, dry-run, supports RAW or USER_ENTERED input).
Append rows non-destructively (dry-run supported).
Format cells (bold/italic/underline) within an A1 range (dry-run).
Create spreadsheets with optional named tabs; add tabs to existing ones.
Clear ranges or delete rows (confirm-gated, dry-run).
File Management:
Read any file as text in bounded chunks (including Google-native exports and PDF text).
Download binary files (inline base64 or to sandbox).
Upload new files or replace existing content (confirm-gated for replacement).
Move and rename files (both confirm-gated).
Export Google-native files to PDF, DOCX, XLSX, PPTX, CSV, TXT, MD, HTML.
Safety & Security:
Destructive operations require explicit confirm=true; many support a dry-run to preview changes.
Local file I/O is sandboxed to a configurable directory, rejecting path traversal.
Verification gate can require per-call approval for certain models or universally.
All tool calls are audit-logged (user, tool, target, outcome, without content).
Reads are bounded to prevent context flooding.
Markdown formatting and color support for rich text creation/editing in Docs.
Provides tools for interacting with Google Drive, including reading and writing Google Docs and Google Sheets, searching files, managing folders, and more.
Click on "Install 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., "@gdrive-mcp show me files named 'report' in my Drive"
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 read/write MCP for Google Drive, Docs & Sheets that fixes what trips agents on naive Drive servers — whole-document context floods, unguarded destructive writes, and inconsistent argument names — with bounded/paged reads, spill-to-disk for full data, confirm-gated mutations, and one consistent item argument.
Conventions: every tool takes its target as
item(a URL or ID); unknown args are rejected; destructive tools (ᶜ) return an impact preview unless called withconfirm=true.Dry-run (edit-only): the edit tools for existing files —
append_text,insert_text,insert_table,delete_text,replace_text,write_sheet,append_rows,format_cells,clear_range,delete_rows— acceptdry_run=true, returning a predicted before/after without writing (client-side;write_sheetshows formula cells literally, so Google's recalculation isn't simulated, and Docsinsert_textreports the insertion point rather than a merged string). Dry-runs are still subject to the verification gate.Editing a Doc by content, not by offset:
delete_text/replace_text(andinsert_text/insert_table'safter/before) locate their target with a locator —match(a literal, case-sensitive substring lying within one paragraph) orsection(a heading's exact text, covering that heading and everything under it up to the next heading of the same or higher level). Character offsets intoread_document's content are not valid Docs indexes: that content is rendered markdown (heading prefixes, synthesized table delimiter rows, escaped pipes) and does not align with the document's UTF-16 index space. The server resolves locators against the API's own element offsets instead, so anchors are always valid — and for block content they land on a paragraph boundary by construction. Eachread_documentoutlineentry also carries realstart/endoffsets, plus arevision_id; locator writes pin that revision, so a concurrent edit makes the write fail rather than land on shifted text.Colored text (opt-in):
append_text/insert_texttake an optionalcolor(hex, e.g.#3366CC) applied only when explicitly passed — unset = plain text.read_document(include_colors=true)returnscolored_runs(spans with an explicit foreground color).Formatted writes (opt-in):
append_text/insert_text/create_documentacceptmarkdown=true, rendering a small dialect —#…######headings,-/*bullets,1.numbered lists (nest with two spaces or a tab per level),**bold**,*italic*,<u>underline</u>, and GFM pipe tables (a header row immediately followed by a| --- | --- |delimiter row — a lone| a | b |line with no delimiter stays literal text). The only escape is\|for a literal pipe inside a table cell; otherwise text that looks like markup gets styled (leavemarkdownunset to store text verbatim). Table round-trip preserves structure and plain cell text — cell emphasis and multi-paragraph cells are not preserved on read. In Sheets,format_cellssets bold/italic/underline on a cell range without touching values.Local-file sandbox: all local file I/O is confined to
GDRIVE_MCP_FILES_DIR(default a private0700dir under the config dir) —download_file/export_file/read_full_sheetwrite there (relativedest_path; absolute paths and..rejected, files0600), andupload_file(source_path)reads only from there. This stops a prompt-injected agent from writing to~/.sshor exfiltrating arbitrary local files to Drive. Fetched Doc images are pulled only from Google hosts (the OAuth token is never sent elsewhere).Spilled-file retention + audit: files spilled to the sandbox are swept on server start once older than
GDRIVE_MCP_FILES_TTL_HOURS(default 24;0disables) — for a long-lived server, restart to dispose, or lower the TTL. The sweep is ownership-gated: it only runs in a sandbox gdrive-mcp itself created (tracked by a.gdrive-mcp-sandboxmarker file), so pointingGDRIVE_MCP_FILES_DIRat a pre-existing directory never deletes the files already there — a startup warning notes the skipped sweep, and creating the marker file yourself opts the directory in. Every tool call is appended to an audit log (GDRIVE_MCP_AUDIT_LOG, defaultaudit.login the config dir) recording user, tool, target id, and outcome — never the content read or written.Verification gate: set
GDRIVE_MCP_VERIFICATION_MODEL_PATTERNSto comma-separated, case-insensitive model-name substrings when selected model families should require per-call user approval via MCP elicitation. A match from either the operator pinGDRIVE_MCP_CALLING_MODELor the request's self-reported_meta.modelturns the gate on; a nonmatching request model cannot turn off an operator-pin match. SetGDRIVE_MCP_REQUIRE_VERIFICATION=alwaysto gate every call regardless of model. Gated calls fail closed on decline or when the client cannot prompt. Because request metadata is advisory, enforce mandatory policy with deployment-controlled environment variables and credential boundaries.
Discovery
resolve_link — resolve any Drive/Docs/Sheets URL or ID into its id, kind, name, and link.
search_files — find files by name, full-text content, MIME type, and/or parent folder.
list_folder — list a folder's direct children.
get_metadata — full metadata for a file: owner, timestamps, size, parents, sharing.
Docs
read_document — read a Doc as markdown/text in bounded ~8k-char chunks (paginated, with an outline carrying each heading's start/end offsets, plus revision_id); reads all tabs by default or a specific tab.
extract_images — pull embedded images (inline and positioned/floating) out as viewable images, in document order (tab-aware).
create_document — create a new Doc, optionally with initial content (markdown=true for formatted).
append_text — append text to the end of a Doc, targeting a chosen tab (markdown=true for headings/lists/bold/italic/underline).
insert_text — insert text after/before a matched substring (or at a raw index), targeting a chosen tab (markdown=true as above).
insert_table — insert a table filled from a rows grid (append, or after/before a match, or at an index; header=true bolds the first row).
**delete_text**ᶜ — delete a matched substring or a whole heading section.
**replace_text**ᶜ — replace a matched substring or a whole section (markdown=true for formatted replacements; use insert_table for tables).
read_comments — list a doc/file's comments and replies.
add_comment — add an (unanchored) comment.
Sheets
read_sheet — a bounded 5×5 preview of each tab (configurable max_rows/max_cols; pass a1_range for an exact range; values=FORMULA for formulas).
read_full_sheet — read a whole tab, save it to a local CSV, and return the path + exact total_rows/total_cols + the 5×5 preview.
**write_sheet**ᶜ — write rows starting at a cell; gated when it would overwrite non-empty cells.
append_rows — append rows after the last row (non-destructive).
format_cells — set bold/italic/underline on a bounded A1 range (tri-state flags; values untouched).
create_spreadsheet — create a new spreadsheet with optional named tabs.
add_tab — add a tab to an existing spreadsheet.
**clear_range**ᶜ — clear the values in an A1 range.
**delete_rows**ᶜ — delete N rows from a tab.
Files
read_file_as_text — a file's content as text in bounded chunks (Google-native exported; PDFs text-extracted).
download_file — download a binary file (base64 if small, else written to disk).
**upload_file**ᶜ — create a new file, or replace an existing file's content (replace is gated).
**move_file**ᶜ — move a file into a parent folder.
**rename_file**ᶜ — rename a file.
export_file — export a Google-native file to pdf / docx / xlsx / pptx / csv / txt / md / html.
Related MCP server: google-mcp
Requires uv, the Claude Code CLI (claude), and your own Google OAuth client (see Setup). Then:
git clone https://github.com/shivankj11/gdrive-mcp.git && cd gdrive-mcp && bash setup.shsetup.sh is idempotent — re-run it any time. It installs uv (if missing), runs the one-time Google browser consent, and registers the server with Claude Code. It looks for the Desktop-app OAuth client JSON in this order: an existing ~/.config/gdrive-mcp/oauth_client.json; a GDRIVE_MCP_OAUTH_CLIENT_CMD that prints the JSON; or a plaintext oauth_client.json at the repo root. If none is found it tells you how to create one.
In a Google Cloud project you control, create an OAuth client (Application type Desktop app) and configure its consent screen. The drive scope is restricted, so follow Google's verification requirements (for personal use, add yourself as a test user).
Enable the Drive, Docs, and Sheets APIs (all three are authorized by the single drive scope, but each must be enabled once).
Save the client JSON to ~/.config/gdrive-mcp/oauth_client.json (or set GDRIVE_MCP_OAUTH_CLIENT), then:
uv run gdrive-mcp auth # one-time loopback-OAuth browser consent; caches a token
uv run gdrive-mcp whoami # verifyYou authenticate as yourself, so the server can only reach what your own Google account already can.
claude mcp add gdrive -- uv run --directory /path/to/gdrive-mcp gdrive-mcp serverust/)rust/ holds a second, self-contained implementation of the same server — same 29 tools, same
argument names, same result shapes, same confirm/dry-run/locator/gate semantics — as a single
static binary with no Python runtime. The two are interchangeable: they read the same
~/.config/gdrive-mcp/oauth_client.json and write the same token.json (byte-compatible with
google-auth's format), so authenticating with one authenticates the other, and every
GDRIVE_MCP_* variable in Configuration means the same thing to both.
cargo install --path rust # or: cargo build --release --manifest-path rust/Cargo.toml
gdrive-mcp auth # one-time browser consent (skip if the Python side already ran it)
gdrive-mcp whoami # verify
claude mcp add gdrive -- gdrive-mcp serveNotable differences, all internal:
Google APIs are called directly over REST (reqwest) instead of through a discovery
document, behind a GoogleApi trait so the tool tests run against a recording fake.
MCP is served by rmcp, the official Rust SDK; the verification gate prompts through its
elicitation support, and tests/server_integration.rs drives the registered path with a real
in-memory MCP client (annotations, strict schemas, and every accept/decline/no-prompt branch).
Argument handling reproduces both of FastMCP's layers, not just the strict one: unknown
arguments are rejected (extra="forbid"), and a list sent as a JSON string or a boolean sent
as "true" is coerced the way pydantic's lax mode did, because MCP clients really send those.
PDF text extraction uses pdf-extract rather than pypdf, so extracted text may differ in
whitespace for unusual PDFs.
The markdown dialect's inline rules need lookaround, which Rust's default regex engine
does not support, so md.rs uses fancy-regex for exactly those two patterns — with \w and
\s spelled out, since the two engines define them differently.
Known behavioural divergences, both confined to how a spilled filename is spelled: A1 cells accept
only ASCII digits (Python's \d also matched other Unicode digits), and localfs's filename
sanitiser keeps Unicode combining marks where Python replaced them with _. Neither affects
containment or content.
cargo test --manifest-path rust/Cargo.toml # unit + integration tests, no credentials needed
python3 scripts/diff_tool_surface.py # both servers advertise an identical tool surfaceSee VERIFICATION.md for what each implementation's tests actually pin, and for
the live credentialed runs.
Env var | Default | Purpose |
|
| Desktop-app OAuth client JSON |
|
| Cached per-user token |
|
| Sandbox for local file I/O — download/export/CSV writes and upload sources are confined here (absolute/ |
|
| Age (hours) after which spilled sandbox files are swept on server start; |
|
| Base config dir |
| (unset) | Operator-controlled caller-model pin; used when the client does not send |
| (unset) | Comma-separated model-name substrings that require per-call verification |
| (unset) | Set to |
Credential files are git-ignored and must never be committed.
uv sync # install deps (incl. dev group)
uv run pytest # run the test suiteMIT — see LICENSE.
Append rows after the last row of a tab of a spreadsheet (item). Non-destructive.
value_input RAW (default) stores cell text literally; 'USER_ENTERED' interprets formulas/typed
values. dry_run=true returns where the rows would land (predicted) without appending.
| Name | Required | Description | Default |
|---|---|---|---|
| tab | Yes | ||
| item | Yes | ||
| rows | Yes | ||
| dry_run | No | ||
| value_input | No | RAW |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses non-destructive nature, and explains the behavior of 'value_input' (RAW vs USER_ENTERED) and 'dry_run' (predicted location without appending). Annotations already indicate non-destructive, so description adds value 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, no wasted words. Purpose is front-loaded, parameter explanations are concise. Every sentence adds value.
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 purpose, non-destructive behavior, and key parameters. However, lacks details about return value (no output schema), error handling, or constraints like row array structure. Adequate but not complete for a tool with 5 parameters.
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 description compensates partially by explaining 'value_input' and 'dry_run' parameters. However, required parameters ('tab', 'item', 'rows') lack additional meaning beyond the schema. The added details for two optional parameters raise it above baseline 1, but not enough to be a 4.
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 the tool appends rows after the last row of a spreadsheet tab. It specifies the resource (spreadsheet tab) and action (append rows), and distinguishes itself from siblings like 'write_sheet' by being non-destructive.
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 mentions non-destructive but provides no guidance on when to use this tool versus alternatives like 'write_sheet' or 'clear_range'. No explicit when-to-use or when-not-to-use context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear all values in an A1 range of a spreadsheet (item), e.g. 'Data!A2:C10'. Requires confirm=true.
dry_run=true returns the values that would be cleared (before) without clearing.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | ||
| confirm | No | ||
| dry_run | No | ||
| a1_range | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by explaining the confirm requirement and dry_run functionality. It does not contradict annotations (readOnlyHint=false, destructiveHint=true). Minor lack of detail on side effects like formatting, but acceptable.
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-loaded with the main action, and no unnecessary words. It efficiently conveys the core behavior and key parameters.
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 description covers the main functionality and critical parameters. It lacks explicit mention of behavior when confirm=false or potential errors, but the overall completeness is high given the tool's simplicity.
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 compensates by explaining all four parameters: item (as spreadsheet), a1_range (via example), confirm (required), and dry_run (returns values before clearing). This adds significant meaning 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 action (clear all values), the resource (A1 range of a spreadsheet), and provides an example range. This distinguishes it from sibling tools like write_sheet or append_rows.
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 the tool is for destructive clearing and requires confirm=true, giving clear context for when to use it. It does not explicitly mention alternatives, but the purpose is self-evident and distinct from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Google Doc (in My Drive root), optionally with initial text content.
markdown=true renders `text` with the same dialect as append_text: headings, bullets,
numbered lists, **bold**, *italic*, <u>underline</u>. (For spreadsheets use
create_spreadsheet.)
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | ||
| title | Yes | ||
| markdown | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is not read-only (readOnlyHint=false), not destructive (destructiveHint=false), and open-world (openWorldHint=true). The description adds specific behavioral details: it creates in My Drive root, and explains the markdown rendering dialect. No contradictions.
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-loaded with the main purpose and key constraints. Every sentence adds value, and there is no unnecessary 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?
Given the tool's complexity (3 parameters, no output schema), the description covers the essential aspects: what it does, where it creates, optional text, markdown behavior, and a pointer to an alternative tool. It is largely complete for a creation 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?
With 0% schema description coverage, the description adds value for the markdown parameter by explaining its rendering behavior, but does not explicitly describe the 'text' and 'title' parameters beyond what the schema already provides (type, default). More detail on these parameters would improve clarity.
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 the tool creates a new Google Doc in My Drive root, optionally with initial text content. It uses a specific verb-resource combination and distinguishes itself from the sibling create_spreadsheet.
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 clear context ('Create a new Google Doc') and suggests an alternative tool for spreadsheets. However, it does not explicitly state when not to use this tool or mention prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new spreadsheet with optional named tabs.
| Name | Required | Description | Default |
|---|---|---|---|
| tabs | No | ||
| title | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds minimal behavioral context beyond annotations. It confirms mutation but does not disclose side effects (e.g., storage location, permissions) despite openWorldHint=true.
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, front-loaded, no extraneous information. Efficient and clear.
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?
Adequate for a simple two-parameter tool with no output schema. Covers core functionality, though could hint at return value or default behavior.
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 coverage, the description explains that 'tabs' is optional and contains array of strings (names), but does not elaborate on 'title' or constraints. Adds some value but not fully comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create', the resource 'spreadsheet', and specifies optional named tabs. It distinguishes from sibling tools like create_document.
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 vs alternatives (e.g., create_document). No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set text formatting (bold/italic/underline) on a bounded A1 range of a spreadsheet (item).
a1_range like 'Data!A1:C10' or a single cell 'Data!B2' (no tab prefix targets the first
tab; open-ended ranges like 'A:C' are rejected). Each flag is tri-state: true applies it,
false removes it, unset leaves that property as-is. Formatting only — cell values are
untouched. dry_run=true returns the resolved target without writing. (Headings, bullets,
and rich text are Docs concepts: see append_text/create_document with markdown=true.)
| Name | Required | Description | Default |
|---|---|---|---|
| bold | No | ||
| item | Yes | ||
| italic | No | ||
| dry_run | No | ||
| a1_range | Yes | ||
| underline | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: formatting only affects appearance, not cell values; flags are tri-state (true/false/unset); open-ended ranges are rejected; dry_run returns resolved target without writing. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true). Minor gap: no mention of authorization or rate limits, but not critical.
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 paragraph but well-structured: first sentence defines purpose, then a1_range guidelines, flag behavior, dry_run, and alternative tools. Every sentence serves a purpose without redundancy. It is concise yet informative.
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 parameter count (6), required fields (2), and no output schema, the description covers essential behavior: formatting only, parameter semantics, range constraints, dry_run, and boundaries with other tools. It does not mention error handling or return value shape (no output schema), but these are minor omissions. Overall, it equips an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining the a1_range format, the tri-state nature of bold/italic/underline, and the dry_run parameter. The 'item' parameter is not elaborated beyond being a spreadsheet identifier, but overall the description adds significant meaning 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 (set text formatting), the resource (spreadsheet cells in a bounded A1 range), and the specific properties (bold/italic/underline). It uses a specific verb+resource structure and distinguishes from sibling tools like append_rows or clear_range by focusing on formatting.
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 the tool: for setting text formatting on a spreadsheet range. It explains the a1_range format, the tri-state flag behavior, and the dry_run parameter. It also directs users to alternative tools for heading/bullets/rich text (append_text/create_document with markdown=true), helping agents choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the direct children of a folder (item = folder URL or ID).
Returns one page; when `has_more` is true, pass the returned `next_page_token` to continue.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | ||
| page_size | No | ||
| page_token | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds pagination behavior (has_more, next_page_token) and the 'direct children' constraint, enhancing transparency 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?
Two sentences with no wasted words. Purpose is front-loaded, and all information is directly relevant. Ideal conciseness.
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?
No output schema exists, so description should detail return format. It mentions pagination fields (has_more, next_page_token) but does not describe the structure of child items returned, leaving ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains that 'item' is a folder URL or ID and implies how page_token works via pagination notes. However, page_size and default value are not explained, leaving room for confusion.
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 'List the direct children of a folder' with specific verb and resource. It clarifies that 'item' is a folder URL or ID, distinguishing it from tools like search_files that may have broader scope.
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 pagination guidance ('Returns one page; when has_more is true, pass the next_page_token'). However, it lacks explicit instructions on when to use this tool versus siblings like search_files or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List comments on a Doc or file (item = URL or ID).
Returns one page; when `has_more` is true, pass the returned `next_page_token` to continue.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | ||
| page_size | No | ||
| page_token | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds pagination details and parameter clarification beyond annotations. Annotations correctly indicate read-only and open-world. No contradictions.
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 sentences. Front-loaded with purpose, immediately followed by pagination guidance. 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?
Covers pagination and item format. Lacks full return structure but annotations and simplicity of a paginated list make it 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?
Description adds meaning for item (URL or ID) and page_token (pagination usage). With 0% schema coverage, compensates partially; page_size remains undocumented but is self-explanatory.
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 the verb 'List' and resource 'comments on a Doc or file'. Specifies that item can be URL or ID. No ambiguity; distinguishes from sibling tools that read document 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?
Explains pagination behavior (one page, use next_page_token when has_more is true). Does not explicitly state when to use this tool vs alternatives, but the unique purpose is clear.
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 (item = URL or ID) as 'markdown' (default) or 'text', one bounded chunk at a time.
Multi-tab docs: by default every tab is read (each prefixed with its title as a heading);
pass a `tab` id, or an `item` URL containing `tab=t.xxxx`, to read only that tab. Returns the
requested chunk (0-based) plus title, the doc's `tabs`, the outline, and paging metadata
(total_chunks, total_chars, has_more). Set max_chars<=0 to get the whole document. Set
include_colors=true to also return `colored_runs` (text spans with an explicit foreground color).
| Name | Required | Description | Default |
|---|---|---|---|
| tab | No | ||
| item | Yes | ||
| chunk | No | ||
| max_chars | No | ||
| output_format | No | markdown | |
| include_colors | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and openWorldHint=true, and the description adds behavioral details beyond these: chunked reading, paging metadata, return fields (title, tabs, outline), and special behaviors like reading all tabs by default. No contradictions.
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-organized paragraph that front-loads the core action and parameter types. Every sentence adds value, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description details return values (title, tabs, outline, paging metadata). Parameters are all explained, and the tool's behavior (chunked, bounded) is fully described. Annotations cover safety and openness, making this complete for the complexity 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?
Input schema has 0% description coverage (no descriptions for properties), but the tool description provides clear semantics for all parameters: tab usage, chunk as 0-based, max_chars<=0 for whole doc, include_colors for colored_runs, output_format default. This significantly compensates for 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 specifies the verb 'Read', the resource 'Google Doc', and critical details like input format (URL or ID) and output formats (markdown or text). It is unique among siblings: other tools read comments or files, not 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 explains when to use the tab parameter, how multi-tab works, and options like max_chars or include_colors. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., read_comments for reading comments only).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file's content as text, one bounded chunk at a time.
Google-native files are exported; PDFs are text-extracted. Returns the requested chunk
(0-based) in `content` plus name, mime_type, and paging metadata (total_chunks,
total_chars, has_more) — page through by incrementing chunk. Set max_chars<=0 for the
whole document.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | ||
| chunk | No | ||
| max_chars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and openWorld. Description adds value beyond annotations by explaining chunking behavior, return paging metadata, and special handling for file types.
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 sentences, front-loaded with primary action. 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 complexity (chunked reading, export/extraction) and no output schema, description covers return fields (content, name, mime_type, paging metadata) and paging mechanism. Completeness is high but could mention output structure more explicitly.
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 0% description coverage. Description explains all three parameters: item (required), chunk (0-based, default 0), max_chars (default 8000, set <=0 for whole document). Adds meaning beyond 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?
Description clearly states verb (Read), resource (file's content as text), and operation (one bounded chunk at a time). It distinguishes from siblings like read_document by focusing on arbitrary files with chunking and export/extraction.
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 explains when to use (for text content of any file) and gives context about file types (Google-native exported, PDFs text-extracted). However, no explicit guidance on when not to use or alternatives, though context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an entire sheet tab, save it to a local CSV, and return the path + a 5x5 preview.
Reads the full tab (item = URL or ID; default first tab) via the Sheets API, writes it to
dest_path (resolved inside the sandbox files dir; a sanitized default name otherwise), and
returns total_rows/total_cols plus the same first-5-rows/cols preview as read_sheet. Use this
instead of read_sheet when you need the complete data without flooding the context.
| Name | Required | Description | Default |
|---|---|---|---|
| tab | No | ||
| item | Yes | ||
| values | No | UNFORMATTED | |
| dest_path | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses reading entire tab, writing to local CSV, and returning path/preview. Annotations indicate non-read-only and non-destructive, which aligns. Missing details on error conditions or file overwrite behavior, but overall transparent.
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 with no fluff. First sentence summarizes action, details follow. Every sentence provides value.
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?
Handles all key aspects: input (item, tab, dest_path), output (rows/cols and preview), and side effect (file write). No output schema, so description suffices. Lacks error handling details, but complete for typical 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?
Explanation covers item (URL/ID), tab (default first), and dest_path (resolved in sandbox), but does not mention the 'values' parameter (default UNFORMATTED) or its options. Schema description coverage is 0%, so 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 reads an entire sheet tab, saves to CSV, and returns path + preview. It distinguishes from siblings by comparing with read_sheet and noting it provides complete data without flooding context.
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 recommends using this tool over read_sheet when full data is needed, providing clear when-to-use guidance. No alternative is mentioned for other scenarios, but the comparison is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a file. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes | ||
| confirm | No | ||
| new_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not add behavioral context beyond what the annotations provide (destructiveHint=true, readOnlyHint=false). The only additional behavior mentioned is the confirm requirement, which is a parameter constraint rather than a behavioral trait like side effects or 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 extremely short (two sentences), but at the cost of missing essential information. For a tool with three parameters and no output schema, it is under-specified. Conciseness is not beneficial when it leads to ambiguity.
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 three parameters, no output schema, and no parameter descriptions, the description fails to provide a complete picture. The agent lacks information about what 'item' is, how to format 'new_name', and what happens after renaming.
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 explain the parameters. It only mentions that 'confirm' should be true, but does not clarify what 'item' or 'new_name' represent (e.g., file path, name format). This is insufficient for correct invocation.
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 ('Rename a file') and the resource ('a file'), which is a specific verb+resource combination. There are no sibling rename tools, so it is distinct. However, it could be more precise about whether folders are included.
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 explicitly states 'Requires confirm=true', which gives a necessary precondition for using the tool. However, it does not provide guidance on when to use rename versus other file operations (e.g., copy, move) available among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a Google Drive/Docs/Sheets URL or bare ID (item) to its id, kind, name and link.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint. The description adds context that the tool accepts URLs or bare IDs and returns id, kind, name, and link, going beyond the annotations. No contradictions.
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, concise sentence that front-loads the purpose and output. Every word earns its place with no redundancy or unnecessary detail.
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 simplicity (one parameter, no output schema), the description adequately covers the tool's purpose and output fields. However, it could be improved by specifying the return format (e.g., JSON object) to reduce ambiguity.
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 with a single 'item' parameter. The description compensates by clarifying that 'item' can be a Google Drive URL or bare ID, adding critical meaning that the schema alone lacks.
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 that the tool resolves a Google Drive URL or ID to metadata (id, kind, name, link). It uses a specific verb and resource, distinguishing it from sibling tools like read_document or list_folder.
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 context (resolving identifiers) but provides no explicit guidance on when to use it versus alternatives, nor when not to use it. The sibling tools list suggests a search for files but lacks direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Drive by name, full-text content, mime type, and/or parent folder.
Returns one page; when `has_more` is true, pass the returned `next_page_token` to continue.
`incomplete_search` true means Drive couldn't search every corpus (results may be partial).
| Name | Required | Description | Default |
|---|---|---|---|
| full_text | No | ||
| in_folder | No | ||
| mime_type | No | ||
| page_size | No | ||
| page_token | No | ||
| name_contains | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds valuable behavioral details: pagination behavior and the meaning of incomplete_search. 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?
The description is very concise: two sentences and a phrase. It is front-loaded with the purpose, and 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?
Given the 6 parameters, no output schema, and no nested objects, the description adequately covers search criteria and pagination. The incomplete_search explanation adds completeness for a search 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?
Schema description coverage is 0%, so the description must compensate. It maps the search types to parameters (name_contains, full_text, mime_type, in_folder) but does not individually describe page_size or page_token beyond the pagination note. This adds some meaning but is not exhaustive.
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 Drive by multiple criteria (name, content, mime type, folder), which is a specific verb+resource. It distinguishes from siblings like list_folder or read_document by focusing on search with filters.
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 explains pagination (returned page, has_more, next_page_token) and the incomplete_search flag, providing clear context for usage. However, it does not explicitly compare to alternative tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write rows to a tab of a spreadsheet (item), starting at start_cell (default A1).
value_input RAW (default) stores cell text literally; pass 'USER_ENTERED' to interpret typed
values/formulas (a leading '=' becomes a live formula). Overwriting existing non-empty cells
requires confirm=true. dry_run=true returns a predicted before/after (client-side) without
writing; formula cells are shown literally (Google's recalculation is not simulated).
| Name | Required | Description | Default |
|---|---|---|---|
| tab | Yes | ||
| item | Yes | ||
| rows | Yes | ||
| confirm | No | ||
| dry_run | No | ||
| start_cell | No | A1 | |
| value_input | No | RAW |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveness; description adds detail on confirm requirement for overwriting, dry_run preview behavior, and value_input formula handling. Contradiction not present.
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 with front-loaded purpose. Efficient but could be slightly tighter; no 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?
Covers key behaviors and parameters but omits output/return value and potential constraints like row limits. Adequate for basic 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 coverage 0% so description carries burden. Explains start_cell default, value_input options, confirm, dry_run, but leaves item, tab, rows structure unexplained. Adds partial value.
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 writes rows to a spreadsheet tab, with specific verb and resource. It distinguishes from siblings like append_rows by implying overwriting behavior and referencing start_cell.
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 context for confirm, dry_run, and value_input parameters, guiding when to use each. Lacks explicit when-not-to-use or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct action on a specific resource (e.g., append_rows vs write_sheet, read_document vs read_file_as_text) with clear scoping, eliminating ambiguity.
All tools follow a consistent verb_noun snake_case pattern (e.g., create_document, search_files, rename_file) with no deviations.
14 tools cover the essential operations for Google Drive, Docs, and Sheets without being overwhelming or sparse.
Solid for Sheets (CRUD + format/append/clear) but missing create_folder, delete/organize files, and update document content beyond creation, leaving notable gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted Google Ads MCP with OAuth, bounded reads, and prepare/confirm writes.
Streamable HTTP MCP server for Google Calendar and Sheets with OAuth login.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Google Ads MCP server — manage campaigns, keywords, and metrics.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shivankj11/gdrive-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
