Google Drive tools for agents
Fifteen tools let an agent work directly against Google Drive: find and read files, organize them, manage who has access, and work a file's comment threads. They are separate from the Google Drive pipeline source, which ingests Drive content into a corpus — these tools act in Drive at conversation time.
Unlike the Box tools, Google Drive tool names carry no version suffix. The name you configure is the bare name: google_drive_search, not google_drive_search_20260723.
For a Google Doc whose text you want to read or edit, prefer the Google Docs tools over downloading the file with google_drive_get_file.
Authentication
Every Google-backed tool — Drive, Docs, Sheets, and Chat — authenticates as a Google service account, and they all share one credential resolver. A single service-account key backs every Google API; only the OAuth scopes differ per tool.
Credentials resolve in this order:
- An explicit
service_account_keyargument — the full service-account JSON key. This is the connector-less path; no connector is required. - An explicit
connector_idargument that resolves to a Google connector. - The connector that triggered the current loop, when it carries Google credentials.
- The first connector with Google credentials attached to the agent, ordered by connector ID so the choice is deterministic.
If none of these produce credentials, the tool call fails.
The shipped defaults
All fifteen tools ship the same default argument_override:
| Argument | Default reference |
|---|---|
connector_id | session.metadata.connector_id, defaulting to "" |
subject_email | "" |
Both references carry a default, so neither blocks a session from starting when the value is absent.
The Drive tools do not wire service_account_key to an agent secret by default. The gchat_post_message tool does — it fills that argument from agent.secrets.gchat_service_account_key. To authenticate a Drive tool with an explicit key rather than a connector, you have to set argument_override yourself.
Store the key as an agent secret and reference it:
{
"service_account_key": { "$ref": "agent.secrets.google_service_account_key" }
}
A user-supplied argument_override replaces the shipped defaults wholesale rather than key by key. If you set one to add service_account_key, the connector_id and subject_email defaults are dropped rather than merged over — restate them if you still want them.
Impersonation
subject_email impersonates a Google Workspace user. It requires domain-wide delegation and applies to both explicit service-account credentials and connector credentials. Without it, the acting identity is the service account itself, which matters in two visible ways: comments are authored by the service account, and share-notification emails are sent from its address.
Two failure modes worth knowing
A connector_id that resolves to a non-Google connector is ignored, not rejected. Resolution falls through to the next step. This is deliberate: the shipped default injects session.metadata.connector_id, which is whichever connector triggered the session — often Slack or Zoom when a Drive tool is used cross-platform. Failing there would break every legitimate cross-post. A connector_id that resolves to nothing, however, is still an error, because that is a genuinely dangling reference.
A bare service account owns no Drive storage. Creating a new file fails with Service Accounts do not have storage quota unless the destination is on a Shared Drive the service account can write to, or subject_email is set to impersonate a Workspace user through domain-wide delegation. This affects google_drive_put_file and google_drive_copy_file. google_drive_create_folder is exempt — folders consume no quota.
Finding and reading content
google_drive_search
Searches Drive, matching query (required) against file names and full-text contents, most recently modified first.
Narrow with mime_type — application/vnd.google-apps.document for Docs, application/vnd.google-apps.spreadsheet for Sheets, application/pdf for PDFs. limit defaults to 10 (1–100).
Each result carries id, name, mime_type, and where available modified_time, web_view_link, and owner. When nothing matches, files is empty; when error is set, surface it rather than retrying.
Without subject_email, the service account only finds files shared with its client_email. With subject_email and correctly configured domain-wide delegation, searches run as that Workspace user.
google_drive_list_folder
Lists the direct contents of a folder — files and subfolders, folders first then alphabetically. folder_id is required; pass "root" for the top level of My Drive. limit defaults to 10 (1–100), and paging is by page_key: pass metadata.page_key from the previous response.
Each entry carries file_id, name, mime_type, and where available modified_at, web_view_link, and owner. Only direct children are returned — list a subfolder by calling again with its id.
Use google_drive_search to find files across all of Drive; use this to browse a known tree.
google_drive_get_file
Downloads a file's content into a session artifact and returns its artifact_id. Requires file_id. The bytes are streamed through the file cache and never buffered whole in memory.
Ordinary files (PDFs, images, Office documents, text) download as-is. Google-native files are exported: Docs and Slides to text/plain, Sheets to text/csv, Drawings to image/png. Override with export_mime_type. When exporting a Sheet to a single-tab format, sheet_id picks the tab; omit it for the first.
Returns artifact_id, filename, mime_type, source_mime_type, conversion_note, and size_bytes. Pass the artifact to image_read for images, to the artifact tools for text, or to the document-conversion tools for other formats.
google_drive_revisions
Lists a file's revision history — who saved each version and when, oldest first. Requires file_id. limit defaults to 20 (1–1000), paged with page_key. Each revision carries id, modified_at, modified_by, and modified_by_email.
This is revision-level history only. Google exposes no per-cell or per-paragraph edit history through any API, so this cannot tell you what changed inside a file or what a cell's previous value was — only that someone saved a new version at a given time. For files with long histories Google may omit the oldest revisions, and lastModifyingUser occasionally reflects the file owner rather than the actual editor. Live collaborator presence and cursor position are Sheets web-UI features with no REST equivalent.
The service account's Google Cloud project must have the Drive API enabled, or the call fails with PERMISSION_DENIED / SERVICE_DISABLED.
Organizing files
google_drive_create_folder
Creates a folder. name is required; folder_id optionally names a parent, and when omitted the folder lands at the top level of My Drive. Returns folder_id, name, and web_view_link.
Folders consume no storage quota, so a bare service account can create them even in its own quota-less My Drive.
google_drive_put_file
Uploads a session artifact's bytes to Drive. artifact_id is required. By default a new file is created taking the artifact's name and MIME type, overridable with name and mime_type; folder_id places it.
Passing file_id replaces an existing file's content instead. That path is safe-by-default: it also requires replace_content set to true, and otherwise the tool refuses and names the file that would be overwritten. On the replace path the file keeps its existing name unless you explicitly set name.
Returns file_id, name, mime_type, and web_view_link.
Because a bare service account cannot own storage, replacing an existing file it has edit access to is often the only path that works — replacement consumes no service-account quota.
google_drive_copy_file
Copies a file, leaving the original untouched. file_id is required; name names the copy (Drive defaults to Copy of <original name>) and folder_id places it, defaulting to next to the original. Returns the copy's file_id, name, mime_type, and web_view_link.
Folders cannot be copied. The copy is owned by the copying identity, so the storage-quota constraint applies.
google_drive_move_file
Moves a file or folder into a different folder. Both file_id and folder_id are required; pass "root" for the top level of My Drive. The file's id and sharing are unchanged — only its location moves.
The move is applied in a single call that adds the destination and removes every current parent, so a file with multiple parents ends up only in the destination. Returns file_id, name, folder_id, and web_view_link.
Moving into a Shared Drive requires the identity to be a member of it, and Google refuses some cross-drive moves outright — those come back in error. To place a copy elsewhere instead, use google_drive_copy_file.
google_drive_rename_file
Changes a file's or folder's name, its description (the text in Drive's details pane), or both. file_id is required and at least one of name and description must be set. Metadata only — content, id, location, and sharing are untouched. Returns file_id, name, and web_view_link.
google_drive_trash_file
Moves a file or folder to the trash, or restores it with restore set to true. file_id is required. Returns file_id, name, and trashed.
Trashing is reversible — the file stays recoverable in the owner's trash, which Google purges after 30 days — and this tool cannot permanently delete anything or empty the trash. Trashing a folder trashes everything inside it. Trashed files stop appearing in google_drive_search and google_drive_list_folder results.
On a Shared Drive, trashing requires at least fileOrganizer-level rights.
Managing access
google_drive_list_permissions
Lists every sharing grant on a file or folder. file_id is required; limit defaults to 10 (1–100), paged with page_key. Each permission carries permission_id, role, type, and where applicable email, domain, and display_name.
Call this before sharing to see who already has access, or to find the permission_id to revoke. On Shared Drives, listing may additionally require the identity to be a member.
google_drive_share_file
Grants access. file_id is required. role is reader (default), commenter, or writer. type is user (default), group, domain, or anyone — set email for user and group grants, domain for a domain grant.
send_notification defaults to true and applies only to user and group grants; message adds a personal note to that email. Returns file_id, permission_id, role, and granted_to.
Sharing with a whole domain or with anyone-with-link requires confirm_public set to true. Without it the tool refuses, so a file cannot be opened up beyond individually named people by accident.
Ownership cannot be transferred. Drive also refuses when the file's writersCanShare is false or a Workspace admin policy blocks external sharing — those surface in error.
google_drive_unshare_file
Revokes access. file_id is required, plus exactly one of email or permission_id. With email, the tool pages through the file's permissions and deletes the grant whose address matches case-insensitively. Use permission_id for grants with no email — a domain grant or anyone-with-link. Returns file_id, permission_id, and revoked_from.
Owner access cannot be revoked; Google refuses and the refusal surfaces in error.
Comments
google_drive_list_comments
Lists a file's comment threads. file_id is required; limit defaults to 10 (1–100), paged with page_key. Each thread carries comment_id, content, author, author_email, created_at, resolved, quoted_text (the file text the comment is anchored to), and its replies. Deleted comments are excluded.
Use this to catch up on reviewer feedback before editing, or to find the comment_id to reply to.
google_drive_add_comment
Posts a comment. file_id and content (plain text) are required. Passing reply_to_comment_id posts the text as a reply inside that existing thread instead of starting a new one. Returns file_id, comment_id, reply_id, author, and created_at.
New threads are always unanchored — they appear at the document level rather than attached to a specific range of text. Anchored comments are not supported.
Both tools work on Docs, Sheets, Slides, and any other commentable Drive file, and both need at least comment access.