Write SSH File

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

The description adds substantial context beyond the annotations: path-risk policy tiers, the confirmation gate, and the fact that the response deliberately omits file content. It does not spell out that overwrite mode destroys prior content while destructiveHint is false, nor whether writes are atomic or partially applied on failure — material for a 9-param mutation.

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 tight sentences: the operation first, then the policy and output contract. No filler, and the safety-critical gating is front-loaded before the return-shape note.

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?

Safety and policy coverage is good and an output schema exists, so return values need not be restated. However, for a 9-parameter mutation with zero schema descriptions, several parameters and the overwrite-vs-create blast radius remain unexplained, leaving the agent guessing at call correctness.

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 carry all parameter meaning, and it only partially does: it implies confirm/confirmation flow and modes, but never explains timeoutMs, workspaceId, or the duplicated confirmationText vs confirmation_text fields. The distinction between create and overwrite is also left to the bare enum.

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?

"Writes or appends a remote file through SSH" gives a specific verb and resource and is clearly distinct from read_file and list_dir. It does not explicitly distinguish itself from patch_file or exec-with-redirect, so sibling differentiation against the nearest alternative is left to inference.

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 environment tiering (dev allows project paths, test/high-risk requires confirmation, prod blocked by policy) is explicit when-to-use and when-blocked guidance that an agent can act on immediately. It stops short of naming alternatives such as patch_file for partial edits, so the routing half of the guidance is missing.

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