remote_upload

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risky profile is known. The description adds nothing about the most important behavioral unknown for an upload: whether existing remote files are overwritten, whether parent directories are created, or what happens on partial transfer failure. For a destructive, non-idempotent write, that is a real gap beyond the annotations.

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?

Two short sentences, front-loaded with the core action and followed by the one non-obvious flag. Nothing is padded, though the extreme brevity contributes to the parameter and behavior gaps noted elsewhere.

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?

An output schema exists, so return values need not be explained, but this is a destructive open-world write with five parameters and no schema descriptions. Key facts an agent needs before calling — overwrite semantics, what profile/connection do, and directory prerequisites — are absent.

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%, so the description must compensate, and it only covers two of five parameters implicitly (local_path/remote_path) plus recursive explicitly. The profile and connection parameters, which likely control authentication and target host selection, are completely undocumented in both schema and description.

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 gives a specific verb and resource ("Copy a local file or directory to a remote host"), which cleanly distinguishes it from the sibling remote_download. It stops short of naming a sibling explicitly, but the directionality (local to remote) makes the distinction unambiguous.

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?

Usage is implied by the phrase "to a remote host" plus the operational hint "Set recursive=true for directories," which is genuinely actionable. However, there is no guidance on when to prefer this over remote_download, remote_run_script, or the session-based tools, and no prerequisites (profile/connection selection) are described.

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