Copy a file or directory

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

Annotations already cover readOnly=false, destructive=false, and idempotent=false, so the description does not contradict them. But it adds almost no behavioral detail: it does not explain overwrite behavior, recursive copying, directory creation, path handling, or what side effects may occur on the remote host. The phrase 'on the remote host' is the only added context, and even that is largely implied by the tool family.

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 entire description is only two sentences, but the second sentence restates the first with just 'on the remote host' added. The repetition does not earn its place; a single sentence such as 'Copy a file or directory on the remote host' would be equally informative and more concise.

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 5-parameter tool with no required parameters and no output schema, the description is materially incomplete. An agent does not learn which parameters identify the remote host, whether both source and target paths must be supplied, what file types are supported, or what the operation returns. The schema names are self-descriptive, but the description leaves too much operational ambiguity.

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 description coverage is 0%, and the description does not compensate. It never explains sourcePath versus targetDir, which of hostId/userId/sessionId are needed, why all parameters are optional, or how paths are interpreted. At most, the word 'copy' hints that sourcePath is the origin and targetDir is the destination, but that mapping is not explicit.

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 a specific action ('Copy') and resource ('a file or directory') and adds the scope 'on the remote host.' It is not a tautology because it communicates the core operation, though it repeats the title almost verbatim and does not explicitly contrast with sibling operations like move_file_directory or rename_file_directory.

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 intended use is implied: use this tool when you want to duplicate a file or directory on a remote host. However, it provides no explicit guidance about when not to use it, no mention of alternatives like move_file_directory, and no prerequisites such as active sessions or host requirements.

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