ssh_create

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states the two key failure modes: fails if the path already exists and fails if the parent directory doesn't exist. This goes beyond minimal disclosure and addresses the most likely risks for a file-creation operation. However, it does not mention authentication/session preconditions or return behavior, leaving some gaps.

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 sentences: the first states the primary purpose and orientation, the second gives essential failure conditions and the alternative tool. No redundancy, clearly front-loaded, every sentence earns its place.

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 thoroughly covers the core create operation and its main failure conditions, and it differentiates from ssh_edit. However, for a tool with 9 parameters and no output schema or annotations, it leaves out several pieces of context: how it interacts with SSH sessions (sibling tools ssh_start_session, ssh_ensure_session exist), how it differs from file-transfer tools like ssh_scp or ssh_sync, and what the tool returns on success. This is not fully complete, but it is adequate for the primary use case.

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 67% (6 of 9 params described), which is moderate. The description adds meaningful context for the 'path' parameter by specifying it must not already exist and its parent directory must exist, and it clarifies 'content' as the full content to write. However, it does not explain the remaining parameters (port, identity_file, known_hosts_file, extra_ssh_args, timeout, strict_host_key_checking) beyond what the schema already provides. Baseline 3 is appropriate for this moderate coverage.

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 the verb ('Create'), the resource ('a new remote file'), and the method ('over SSH'). It explicitly distinguishes from ssh_edit, which is the primary sibling alternative, and also references the local file-creation tool as a counterpart. This satisfies the specific verb+resource+scope requirement.

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 explicit when-to-use context: use this for creating a new remote file, not for modifying an existing one (use ssh_edit instead). It also provides a critical precondition (parent directory must exist) and a failure condition (path already exists). This is direct, actionable guidance for an AI agent.

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