ai-toolkit

drive_update_file

Replace an existing Google Drive file's content without changing its link, location, or sharing. Overwrites in place, keeping a recoverable revision.

Instructions

Replace the contents of an existing Drive file, in place.

This is the operation the Drive connector is missing: it writes to the file's existing id, so the file keeps its link, its location, and its sharing, and no duplicate is created. Drive retains the previous content as a revision, so an overwrite is recoverable through the file's version history in the Drive UI.

file is either a Drive file id (the token in the file's URL) or a slash-separated path from your My Drive root, e.g. Career/consulting/rates.md. A path that matches more than one file is an error rather than a guess. content is the complete new text — this replaces the file, it does not append, so send the full document. mime_type overrides the upload type; by default it is guessed from the file's name and Drive keeps the target file's own type.

Refuses to write to Google-native files (Docs, Sheets, Slides), where a plain-text upload would replace a formatted document with its text. Returns the file's id, name, path, and new modified_time.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`file`	Yes
`content`	Yes
`mime_type`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 24, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It discloses that the file keeps its link, location, sharing, that no duplicate is created, that previous content is retained as a revision (recoverable), that content replaces (not appends), and that it returns id, name, path, and modified_time. This is thorough and goes well beyond a basic statement of mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured, front-loading the core purpose and then logically expanding on behavior, parameters, and limitations. Every sentence adds value, with no redundant or filler content. The use of backticks and bold for emphasis aids readability without bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description still summarizes the return fields, which is helpful. It covers all necessary aspects: the operation, file identification, content semantics, MIME handling, edge cases (Google-native files, ambiguous paths), and revision safety. An agent has everything needed to invoke this tool correctly and understand its consequences.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

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, and it does excellently. It explains 'file' as either an id or a path with an example, warns that ambiguous paths error, clarifies 'content' is the full replacement text, and details 'mime_type' override behavior. This fully demystifies all three parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Replace the contents of an existing Drive file, in place') and immediately distinguishes itself from siblings like drive_move_file and drive_rename_file by emphasizing the in-place, no-duplicate behavior. It clearly states what the tool does and what it is not.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly frames this as the missing Drive operation, indicating when to use it (to overwrite an existing file's contents) and provides a clear exclusion: it refuses Google-native files (Docs, Sheets, Slides). This gives an agent both a strong signal to use it for content replacement and a concrete when-not, though it does not name alternative tools by name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.