CloudSee Drive MCP Server

Update file metadata

update_metadata

Destructive

Update a drive file's metadata (category, description, project) and tags by its storage ID. Use merge to keep omitted fields or replace to clear them; confirm=true applies the changes.

Instructions

Update a file's metadata (category / description / project) and tags in a drive, addressed by its storage id (the StorageId field from search_files / browse_folder / get_file_metadata — not from list_files or recent_files, whose ids are a different id space and will NOT work). Defaults to mode "merge": a metadata field you do not send is KEPT, a field sent as "" is CLEARED, and tags are merged by Key — a tag with the same Key is overwritten and tags with other Keys are kept. Destructive cases: sending tags: [] CLEARS every tag on the object, and mode "replace" clears every metadata field and every tag you do not send — that is also the only way to remove a single tag, by sending the complete set you want to keep. Requires the drive (bucketName) and confirm=true. Note: the update rewrites the object in place (S3 copy) — its ETag changes (and may change format) and LastModified is set to the update time; ETag-keyed caches and sync tools will see the object as new. Objects larger than 5 GiB are updated via multipart copy; objects larger than 8 GiB are rejected, because the rewrite cannot finish inside the API request timeout. (Write access is authorized server-side by the public API's RBAC — a denial means the API key lacks this tool's scope, not a tool failure.)

Input Schema

TableJSON Schema

Name	Required	Description
`mode`	No	merge (default): metadata keys you omit are KEPT, a key sent as "" is CLEARED, and tags are merged by Key — a tag with the same Key is overwritten, others are kept. replace: every metadata field and every tag you do not send is CLEARED. Use replace to remove a single tag (send the complete set you want to keep).
`tags`	No	Tags to apply. Under the default merge mode they are merged by Key — a tag with the same Key is overwritten and tags with other Keys are kept; under replace they become the COMPLETE tag set. Sending [] CLEARS every tag in both modes, and leaving this out keeps the existing tags under merge (clears them under replace).
`confirm`	No	Must be true to actually perform this mutating/irreversible action. If omitted or false, the tool returns a preview and makes no changes.
`metadata`	No	Metadata fields to set. Under the default merge mode a field you leave out is KEPT and a field sent as "" is CLEARED; under replace every field you leave out is CLEARED.
`storageId`	Yes	Storage/index id of the object — the StorageId field returned by search_files, browse_folder, or get_file_metadata. NOTE: the ids from list_files and recent_files belong to a different id space and will NOT work here.
`bucketName`	No	The CloudSee drive (S3 bucket) name to operate in, e.g. 'max-2778abc0' — find it in the CloudSee dashboard. Required unless CLOUDSEE_DEFAULT_BUCKET is configured on the server.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv3.1.1Sep 19, 2026

changedInput schema / properties / metadata / description

Previous value: -"Metadata to set. Full overwrite: a field left out here is CLEARED on the object."New value: +"Metadata fields to set. Under the default merge mode a field you leave out is KEPT and a field sent as \"\" is CLEARED; under replace every field you leave out is CLEARED."

addedInput schema / properties / mode

Added value: +{
+  "description": "merge (default): metadata keys you omit are KEPT, a key sent as \"\" is CLEARED, and tags are merged by Key — a tag with the same Key is overwritten, others are kept. replace: every metadata field and every tag you do not send is CLEARED. Use replace to remove a single tag (send the complete set you want to keep).",
+  "enum": [
+    "merge",
+    "replace"
+  ],
+  "type": "string"
+}

changedInput schema / properties / storageId / description

Previous value: -"Storage/index id of the object — the StorageId field returned by the INDEXED listing tools (search_files, browse_folder, recent_files). NOTE: list_files reads straight from storage and returns a different id that will NOT work here."New value: +"Storage/index id of the object — the StorageId field returned by search_files, browse_folder, or get_file_metadata. NOTE: the ids from list_files and recent_files belong to a different id space and will NOT work here."

changedInput schema / properties / tags / description

Previous value: -"The COMPLETE desired tag set for the object. Existing tags are replaced; omitting this clears all tags."New value: +"Tags to apply. Under the default merge mode they are merged by Key — a tag with the same Key is overwritten and tags with other Keys are kept; under replace they become the COMPLETE tag set. Sending [] CLEARS every tag in both modes, and leaving this out keeps the existing tags under merge (clears them under replace)."

First observedv1.0.0Aug 11, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already signal mutating/destructive behavior, and the description adds substantial context beyond that: merge vs replace destructive cases, ETag/LastModified side effects, the S3 copy rewrite, size limits, the confirm preview mechanism, and the RBAC denial meaning. This gives the agent a precise model of the tool's side effects.

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

Conciseness4/5

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

The description is long and dense, but nearly every sentence carries essential behavioral or safety information. The opening sentence front-loads the core purpose, and the later sentences earn their place by covering destructive cases, side effects, and constraints.

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?

For a complex mutation tool with nested objects, no output schema, and destructive annotations, the description is remarkably complete. It covers prerequisites, mode semantics, destructive edge cases, server-side authorization, size limits, and post-update side effects like ETag changes and multipart copy.

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

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic value beyond the schema: the storageId id-space warning, the tags: [] destructive case, the field-clearing semantics, and the S3 copy implication. It reinforces and expands on the schema descriptions rather than merely repeating them.

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?

States a specific verb ('Update'), an explicit resource ('a file's metadata (category / description / project) and tags in a drive'), and the addressing requirement (storageId). It also distinguishes itself from the read-oriented sibling tools by naming the correct id source and explicitly excluding list_files and recent_files ids.

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?

Provides clear context for correct invocation: requires bucketName and confirm=true, explains the default merge behavior, and identifies the only way to remove a single tag. It does not explicitly enumerate when to prefer this tool over alternatives, but no sibling tool performs metadata updates, so the guidance is sufficient.

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

Update file metadata

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools