android_file_copy

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

Annotations already declare readOnlyHint=false and destructiveHint=true, covering the mutation and potential-destruction profile. The description adds useful context beyond annotations by limiting the operation to the same writable SAF root and conditioning it on provider support. It does not disclose overwrite behavior at the destination or partial-failure outcomes, which would be valuable given destructiveHint=true.

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?

A single 22-word sentence with the core action front-loaded ('Copy a file or directory to another directory') followed by the caveats. Every word earns its place; there is no repetition of schema fields or filler.

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?

The description covers the core copy scenario but omits operational details an agent would need: whether the source name is preserved in the destination, whether an existing destination file is overwritten, and what happens when targetDirectory is omitted. With no output schema, the agent also receives no indication of what the call returns.

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?

With 0% schema description coverage, the description carries the full burden of parameter meaning: it loosely maps path to the file/directory being copied, targetDirectory to the destination directory, and rootId via 'writable SAF root.' However, it does not explain targetDirectory's optionality or what the default empty string means, leaving a meaningful gap for a required-vs-optional parameter.

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 ('Copy') with an explicit resource ('a file or directory') and destination ('to another directory'), which clearly differentiates it from sibling tools like android_file_move, android_file_rename, and android_file_delete. The added scope constraints ('same writable SAF root', 'when the provider supports it') further disambiguate the operation.

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 provides clear context for when the tool applies: duplicating files or directories within the same writable SAF root, with the provider-support caveat acting as an applicability condition. However, it does not explicitly name alternatives such as android_file_move or android_file_write, nor state when-not-to-use conditions, so some routing is left to inference.

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