ai-toolkit

drive_sync_folder

Sync a local folder tree to a Google Drive folder by relative paths, creating new files and updating changed ones in place. Defaults to dry-run preview of creates, updates, and skips.

Instructions

Push a local folder tree into a Drive folder, creating or updating by name.

Matches local files to Drive files by their path relative to the sync root: a file that already exists is updated in place at its own id (no duplicate), one that doesn't is created, and one whose content already matches is left alone. Sub-folders are created as needed.

This defaults to a dry run. With dry_run=True (the default) nothing is written — you get the exact list of creates, updates, and skips that a real run would perform. Pass dry_run=False to apply it. Nothing is ever deleted from Drive: files present in Drive but absent locally are left untouched.

local_path is a directory on the machine running this server. drive_folder is a Drive folder id or path from My Drive root; create_destination makes a missing destination path (default False).

exclude is a list of glob patterns relative to the sync root — e.g. ["drafts/*", "*.tmp"]. A pattern ending in / excludes a directory and everything under it at any depth. These are added to a built-in list that always excludes private/, .git/, .env, key/certificate files, and credential JSON; that built-in list cannot be switched off by any argument. Malformed patterns abort the whole sync rather than silently matching nothing, and every excluded file is listed in skipped so an exclusion is never invisible.

The sync refuses to run at all — in dry run or for real — if any local file maps onto two same-named Drive files, or onto a Google-native Doc/ Sheet/Slide that a text upload would flatten. Those appear in collisions and native_conflicts for you to resolve by hand.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`dry_run`	No
`exclude`	No
`local_path`	Yes
`drive_folder`	Yes
`create_destination`	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

A4.8/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 burden and excels. It discloses the dry-run default, the no-deletion guarantee, the built-in exclusion list that cannot be disabled, the abort-on-malformed-pattern behavior, and the refusal conditions (collisions and native conflicts). Every behavioral nuance an agent needs is explicitly stated.

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?

Though lengthy, the description is meticulously organized: a summary sentence, then behavior details, then parameter explanations, then safety guarantees. It uses bolded emphasis for critical warnings (dry run, no deletion) and bullet-like formatting for exclusions. Every sentence adds essential information without redundancy.

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?

Given the tool's complexity (5 parameters, dry-run mode, exclusion patterns, collision handling), the description covers all operational aspects comprehensively. Since the context indicates an output schema exists, the description needn't document return values. The agent has everything needed to invoke it correctly and anticipate side effects.

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 coverage is 0%, so the description must fully explain each parameter, and it does. It clarifies local_path as a server-side directory, drive_folder as an id or path, create_destination's default, dry_run's boolean semantics, and exclude's glob syntax with directory-trailing-slash behavior. This goes well beyond the bare schema definitions.

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 precise verb-resource pair: 'Push a local folder tree into a Drive folder, creating or updating by name.' It is clearly distinct from sibling tools like drive_update_file (single file) or drive_ensure_folder_path (folder creation only). The scope is unambiguous.

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

Usage Guidelines4/5

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

The description explains when to use the tool (for syncing a directory tree) and provides important usage context like the dry-run default, but it does not explicitly name alternative tools or state when NOT to use it. The behavioral rules (collisions, native conflicts, exclusions) strongly imply the appropriate use cases. A dedicated 'use instead of X' statement would make it a 5.

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