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

With no annotations, the description carries the full burden. It discloses auto-connect behavior, supported auth methods, and optional saving/command execution, but omits important traits: session persistence, return value or connection handle, failure behavior, and side effects of save_config writing to disk.

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?

Four sentences, front-loaded with the main action. Each sentence contributes information, and there is no filler. It could be slightly more structured or scannable, but it is efficient overall.

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 tool with 14 parameters, no annotations, and no output schema, the description covers the main behavior but leaves gaps. It does not explain what the tool returns, how the session lifecycle works, or how it interacts with siblings like ssh_disconnect and ssh_execute, which an agent would need for confident use.

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 coverage is 100%, so the schema already documents all 14 parameters. The description repeats the auto-read behavior for host/username and lists auth methods, but adds no syntax, format, or interaction details beyond what the schema provides. Baseline 3 is appropriate.

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?

States a specific verb and resource: 'Establish an SSH connection to a remote server.' The purpose is clear, but it does not explicitly distinguish itself from siblings such as ssh_execute or ssh_disconnect, leaving the agent to infer the boundary.

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?

Mentions auto-connection when no parameters are provided and optional command execution after connecting, which gives some usage context. However, it never explicitly says when to use this tool versus ssh_execute or ssh_disconnect, and offers no exclusions or alternative-routing guidance.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses both the destructive close action and the conditional list-all-sessions behavior, including that connection details are returned. It does not mention side effects or permission requirements, but covers the core observable behavior.

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 with no filler. The primary action is front-loaded, and the conditional behavior is stated efficiently in the second sentence.

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?

This is a low-complexity tool with a single optional parameter and no output schema. The description fully explains how to invoke both modes and what to expect when listing, so an agent has enough information to call it correctly.

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 coverage is 100% and the parameter description already states 'Session ID to disconnect. If omitted, lists all active sessions.' The tool description adds no new parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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 ('Close') and resource ('active SSH session'), and adds a conditional listing behavior when no session_id is given. This clearly distinguishes ssh_disconnect from sibling connection, execution, and file-transfer tools.

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 clear context: use this to close an active SSH session, and if no id is supplied it lists active sessions. It does not explicitly name alternatives or exclusion criteria, but the use case is unambiguous from the stated behavior.

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

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

With no annotations, the description carries the behavioral burden. It does disclose that build runs in the background and implies ps/images/logs are read-oriented actions, but it omits details like auth requirements, side effects of build, and failure behavior.

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 description is two focused sentences with no filler: the first states scope and the second lists the supported actions. It is front-loaded and every phrase 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?

For a multi-action tool with 12 parameters, the action list plus fully described schema is largely sufficient to invoke correctly. It lacks explicit usage guidance and output details, but no output schema is present and the schema supplies most invocation information.

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 100%, so every parameter is already documented. The tool description adds no extra parameter-level meaning, so it stays at the baseline of 3.

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 names a specific scope – Docker on a remote server – and enumerates the four supported actions (ps, images, build, logs). It is clear enough to distinguish this tool from the SSH sibling tools, though 'Manage' is somewhat broad.

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 makes it clear this is the Docker-specific remote tool, but it never explicitly says when to prefer it over alternatives like ssh_execute, or when not to use it. Usage context is implied rather than stated.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses auto-connection behavior, background auto-detection, and survival across SSH disconnect. It omits the most consequential traits — the command allowlist and hard blocks, sudo password delivery, and the mandatory backup decision for recursive deletion — all of which exist only in the schema, not the prose.

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?

Three tight sentences, front-loaded with the core action and followed by the two most agent-relevant behaviors. No filler, though for a tool this complex the brevity trades away needed coverage.

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 17-parameter remote-execution tool with no annotations and no output schema, the description covers connection resolution and background/persistence but says nothing about safety gating, sudo semantics, or what a call returns. Adequate to invoke a simple command, insufficient to invoke it safely or correctly in the risky cases the schema anticipates.

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 100%, so the baseline is 3. The description reinforces the session_id fallback chain and background auto-detection, but adds little syntax or semantics the schema doesn't already state for its 17 parameters.

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?

States a specific verb and resource: 'Execute a command on a remote server.' The connection-fallback and background/persistent-session clauses clarify its scope relative to ssh_connect and ssh_session, though it never explicitly contrasts with ssh_docker or ssh_process, whose command surfaces overlap.

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?

Gives clear conditional guidance for several modes: omit session_id to auto-connect via env vars, use session_type='screen'/'tmux' for persistence, use background for long tasks. However, it offers no exclusion rules or alternatives — an agent cannot tell from the description when to reach for ssh_docker or ssh_process instead, nor when this tool should not be used.

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

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

No annotations are provided, so the description carries the full burden, yet it says nothing about the destructive/irreversible nature of delete, whether upload overwrites existing files, whether mkdir creates parent directories, or what authentication constraints apply. Only the remote_copy relay behavior is disclosed, and that detail is already repeated in the schema.

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 core purpose is front-loaded in the first clause, and the long operation enumeration is dense but informative rather than filler. It is appropriately sized for a nine-direction tool, though the list partially duplicates the direction enum.

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?

With 16 parameters, no annotations, and no output schema, the description is complete on the 'what operations exist' axis but silent on results (what stat or list returns) and on safety semantics for delete/upload. The rich schema covers parameter-level details, so the gap is behavioral rather than structural.

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 100%, so the schema already documents every parameter including the remote_copy target_* set and the deprecated target_password. The description adds modest value by clarifying that write accepts content directly and that remote_path is the source path for remote_copy, but goes no further than the schema.

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 and resource ('Transfer and manage files ... via SFTP') and enumerates all nine supported operations, including the non-obvious remote_copy variant. It is clearly distinguishable from the ssh_execute/ssh_process siblings, which run commands rather than move files.

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?

It gives real selection guidance inside the tool: remote_copy is for server-to-server, 'avoiding local relay', which tells the agent not to chain upload+download. It does not say when to prefer this tool over ssh_execute or when a direction is inappropriate, so it stops short of explicit when-not guidance.

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

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

With no annotations, the description must carry behavioral disclosure. It mentions optional file saving, but fails to state whether keys are returned when no path is given, whether existing files are overwritten, or security-related behaviors like passphrases and file permissions.

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?

Single sentence with no filler, front-loading the action and resource, then compactly mentioning options. Every clause adds information.

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 tool with no output schema, no annotations, and 4 optional parameters, the description omits critical operational details: what the response contains, what happens if save_path is omitted, and whether the generated key is available immediately or only on disk.

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 already documents all 4 parameters (100% coverage), so the description adds little beyond naming RSA/Ed25519 and the optional save path. Baseline 3 applies.

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?

Description clearly states a specific verb ('Generate'), a specific resource ('new SSH key pair'), supported algorithms (RSA or Ed25519), and purpose (authentication). It is clearly distinct from sibling tools focused on sessions, connections, execution, and file transfer.

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 phrase 'for secure key-based authentication' implies use when creating SSH credentials, but there is no explicit guidance on when to use this tool over alternatives, prerequisites, or exclusions.

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

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

With no annotations provided, the description carries the transparency burden. It does disclose that removal deletes a server and that the tool manages the persistent hosts.json file. However, it does not describe side effects, permission requirements, return format, or clarify that this tool does not itself establish an SSH connection.

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 description is two concise sentences with no filler. The resource and the action pattern are front-loaded, making it easy for an agent to quickly understand the tool's core behavior.

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 full parameter documentation and explicit action examples make the invocation requirements mostly clear despite the absence of an output schema. The main gap is that the return/result shape is unspecified, but for a simple configuration-management tool this does not prevent correct selection or invocation.

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 100%, so parameter semantics are already fully documented by the input schema. The description only restates the action enum values, adding no new parameter-level meaning beyond what the schema already provides.

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?

Description anchors on a specific resource ('SSH server configurations in hosts.json') and enumerates concrete actions (list/add/remove). This clearly distinguishes it from operational siblings like ssh_connect, ssh_execute, and ssh_session.

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 action-level usage guidance ('use action=list', 'action=add', 'action=remove') but does not explicitly state when to select this tool over alternatives such as ssh_connect or ssh_session. The intended context is implied through 'hosts.json' and configuration management, not directly contrasted with sibling tools.

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

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

No annotations are present, so the description must carry the full burden. It discloses that start launches a detached background process and returns a PID, and that stop uses a PID, but omits details on error handling, idempotency, side effects, authentication requirements, or whether actions are destructive. The behavior is partially transparent.

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 description is a single paragraph with the purpose front-loaded, followed by a concise action list. It is efficiently structured, though the list of actions could be slightly more compact without losing clarity.

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?

Given 16 parameters and 7 actions, the description covers the actions but does not specify which parameters are required for each action, nor does it clarify connection options (session_id vs host/name vs environment variables). No output schema exists, so return formats for actions like list, status, or tunnel_list remain undefined, leaving gaps for an agent to fill.

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?

The schema covers 100% of parameters, but the description adds crucial meaning by mapping actions to their relevant parameters (e.g., start uses command, stop uses pid, tunnel_open uses local_port/remote_host/remote_port). This goes beyond the generic schema descriptions and aids correct invocation.

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 it manages background processes and SSH tunnels on a remote server, enumerating seven specific actions. This distinguishes it from siblings like ssh_execute (likely foreground execution) and ssh_session (session lifecycle management).

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 action list but there is no explicit guidance on when to use this tool versus alternatives like ssh_execute for foreground commands or ssh_session for session management. No when-not-to-use conditions are given.

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

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

No annotations are present, so the description must carry the behavioral burden. It discloses persistence and action meanings (create is detached, capture reads current screen), but does not mention the destructive irreversibility of kill, authentication needs, session/host precedence, or edge-case behavior on nonexistent sessions.

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 first front-loads purpose and context, the second compactly enumerates all actions. Every sentence earns its place with no filler or redundancy.

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 schema is rich and fully covers parameters, and the description covers the tool's overall behavior and all actions. However, with no output schema, it leaves gaps around return format for capture/list, which connection identity (session_id vs host_name vs host) takes precedence, and whether kill requires confirmation.

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 100%, with each parameter already documented in the input schema. The description's action list essentially restates the action enum values without adding new parameter-level meaning, so the baseline of 3 applies.

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?

States a specific purpose ('Manage persistent screen/tmux sessions... for long-running interactive tasks') and enumerates the five actions with concrete semantics. Differentiates from siblings by emphasizing persistence and surviving SSH disconnect, which clearly separates it from one-off ssh_execute.

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?

Provides clear context: use for long-running interactive tasks like deploy, build, test, and REPL, and notes sessions survive disconnect. Stops short of explicitly naming alternatives or stating when not to use this tool, so it misses the full when/when-not guidance.

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