Update file metadata

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

The description goes well beyond the annotations by disclosing full-state overwrite semantics (omitted fields are cleared), the in-place S3 copy rewriting the object, ETag and LastModified changes, multipart copy for >5 GiB objects, and RBAC denial meaning scope rather than failure. This is exceptional behavioral transparency.

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?

Every sentence conveys a distinct, operational fact: the resource and id source, destructive overwrite behavior, required confirm/bucket, ETag/LastModified side effects, large-object multipart handling, and RBAC error interpretation. No filler or repetition; the most important destructive warning is front-loaded.

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?

For a complex mutating tool with 5 parameters and nested objects, the description covers all key caller needs: correct id, required bucket, confirm guardrail, full-overwrite semantics, side effects relevant to caches and sync, large-object limitation, and auth error interpretation. No output schema exists, but return values are not critical for correctness here because the preview/commit behavior is already documented in the schema.

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 100%, so description-level parameter help is less critical. The description still adds value by explicitly stating that omitted metadata fields and omitted tags are cleared and that bucketName plus confirm=true are required. It reinforces the destructive full-overwrite semantics and the storageId source, complementing the schema definitions.

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 operation: updating a file's metadata (category / description / project) and tags. It also specifies the exact identifier to use (storageId from indexed listing tools) and distinguishes this from list_files, which returns an incompatible id. This makes the tool easy to select and differentiate from siblings.

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 gives important context about which id source to use and requires confirm=true and bucketName. It does not explicitly name alternative tools for reading metadata or for other file operations, but the id-source note effectively prevents misuse with list_files and provides enough situational guidance.

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