Move or copy file

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

The description goes well beyond annotations by disclosing asynchronous queued behavior ('returns a RequestId... completes in the background'), the destructive nature of a move, the confirm=true guard, RBAC denial semantics, and the id-space incompatibility of list_files/recent_files ids. This is rich, actionable behavioral information not available from the structured annotations alone.

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?

The description is front-loaded with the core action, then adds necessary caveats in a logical order: addressing, queued behavior, destructive semantics, and authorization. Every sentence earns its place; despite the length, there is no filler or repetition of the schema.

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, destructive, async tool with no output schema, the description is complete: it explains the returned RequestId, the verification-by-listing pattern, the confirm requirement, the storage id constraint, the bucket prerequisite, and the meaning of RBAC denial. An agent has enough information to call the tool correctly.

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?

The input schema already has 100% parameter coverage, so the baseline is 3. The description adds critical semantic detail beyond the schema, especially the warning that storage ids from list_files and recent_files belong to a different id space and will not work, and the note that bucketName is required unless a default bucket is configured. This makes parameter misuse less likely.

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 states a specific verb and resource: 'Move (or copy, with asCopy=true) a file or folder to a new location.' It distinguishes between move and copy, and adds the precise addressing requirement (object key plus storage id), which separates it from related sibling tools like rename_file or duplicate_file.

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 clear operational context: it explains when the tool is appropriate (moving/copying to a new location), how to verify completion, and the confirmation requirement for destructive moves. It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough to guide selection.

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