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

With no annotations, the description carries the full burden of behavioral disclosure. It goes beyond a simple action statement by detailing the credential resolution order (explicit args, env vars, local agent) and a security rationale for avoiding inline secrets. It stops short of describing failure modes, timeouts, or session lifecycle, but the key behavioral context is well covered.

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 purpose is front-loaded in the first sentence, and the credential resolution order is presented as a compact numbered list. The security note earns its place by changing recommended behavior. Every sentence contributes meaning, and the format is easy to scan.

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 connection-establishing tool, the description provides the essential information: what it does, what it returns, and how authentication credentials are resolved. It does not mention session cleanup via ssh_disconnect or error/retry behavior, but given no output schema and no annotations, the description is reasonably complete for an agent to invoke 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?

The input schema has 0% description coverage, so the description must compensate. It adds real meaning to `password` and `key_path` by placing them in a resolution order and advising against their use, which is valuable. However, `key_passphrase` is not explained at all, and `host`, `username`, and `port` are only self-evident from their names, so the compensation is incomplete.

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 opens with a specific verb and resource: 'Open an SSH session to a remote host and return a session_id to use with the other ssh_* tools.' This clearly identifies the tool as the session-establishing entry point and distinguishes it from its siblings, which are all operations that consume that session_id.

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 explains the tool's role in the ssh_* workflow and gives explicit credential-handling guidance: it lists a resolution order and recommends leaving password/key_path unset in favor of env vars. It does not explicitly name alternative tools and the conditions for choosing them, but the phrase 'other ssh_* tools' makes the usage context clear.

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 burden. It discloses that the session is closed and resources are freed, which is the key side effect. However, it does not mention what happens if the session_id is invalid, whether repeated calls are safe, or whether running commands are terminated.

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, tight sentence with no filler. It front-loads the action ('Close an SSH session') and adds the resource-freeing effect without wasted words.

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 one-parameter tool with no output schema, the description conveys the core purpose and effect. But without annotations, some context is missing—such as error handling, idempotency, and the relationship to ssh_connect or ssh_list_sessions for obtaining the session_id.

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 has 0% description coverage, and the description never mentions session_id or how to obtain it. It does not compensate for the schema's lack of parameter documentation, leaving the agent to infer that session_id identifies the session to close.

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 uses a specific verb ('Close') and resource ('SSH session'), clearly distinguishing it from sibling tools like ssh_connect, ssh_exec, and ssh_list_sessions. There is no ambiguity about the action performed.

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 clear context: this tool closes an SSH session and frees resources. Although it does not explicitly state when-not-to-use or name alternatives, the action is straightforward and the intended usage is unmistakable given the sibling tool set.

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, and it does this well. It discloses return values, output truncation for large outputs, and the non-persistent shell behavior that significantly affects how an agent chains commands. These are exactly the behavioral traits an agent needs beyond the raw 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 description is concise, front-loaded with the core action and return values, then follows with the most important caveats. Each sentence adds substantive value with no fluff or repetition of schema fields.

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 annotations and no output schema, the description is quite complete: it covers what the command does, what it returns, truncation behavior, and statefulness. It could be slightly stronger by explicitly referencing the need to establish a session with ssh_connect and clarifying timeout units, but these are minor gaps.

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. It does meaningfully explain session_id as an existing session and command as a shell command, and the non-persistence note adds important semantics for command construction. However, the timeout parameter is not explained in terms of units or behavior, and the description does not fully cover all parameter nuances.

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 action—running a shell command on a remote host over an existing session—and specifies the outputs: stdout, stderr, and exit code. This differentiates it well from siblings like ssh_read_file, ssh_write_file, and ssh_connect. The scope is precise and immediately actionable.

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 useful usage context by warning that each call is a fresh exec_command and that cd/env changes do not persist, with a concrete recommendation to chain with && or use a wrapper script. It does not explicitly name alternatives or state when to prefer ssh_read_file or ssh_write_file, but the guidance is clear enough for typical invocation decisions.

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 transparency burden. It discloses the output fields (host/user/port) and grouping by session_id, which is useful. However, it does not state that the operation is read-only, what happens if there are no sessions, or what the exact return format looks like.

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, compact sentence that front-loads the core action and resource, then adds the relevant output details. Every word contributes value with no 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?

For a simple, parameterless listing tool, the description covers the key information an agent needs: what is listed, the fields included, and the identifier. Minor omissions such as return format or empty-list behavior are not critical given the tool's simplicity.

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 tool has zero parameters, so the baseline for this dimension is 4. The description appropriately focuses on output semantics rather than parameters, and there are no parameter ambiguities to clarify.

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 uses a specific verb 'List' with the resource 'currently open SSH sessions' and specifies the fields (host/user/port) and keying by session_id. It clearly differentiates from sibling tools like ssh_connect and ssh_exec, which perform different actions.

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 implies the usage context: when an agent needs an inventory of open SSH sessions. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions, leaving the guidance implicit rather than direct.

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 must carry the behavioral disclosure burden. It clearly indicates a read-only operation over SFTP and warns that the tool is for text files, but it does not explain behavior around max_bytes truncation or what happens with large or binary files.

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 concise, front-loaded sentence with no unnecessary words. It is appropriately short, though slightly too terse to cover important parameter 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?

For a simple read tool with three flat parameters and no output schema, the purpose is clear enough to attempt a call. However, the lack of parameter explanations, especially max_bytes behavior and session_id provenance, leaves meaningful gaps for correct invocation and interpretation of results.

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 for explaining the parameters. It does not describe session_id, path, or max_bytes at all; path is only indirectly implied by 'read a text file', and max_bytes remains completely unexplained.

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 uses a specific verb 'Read', identifies the resource as 'text file from the remote host', and specifies the mechanism 'via SFTP'. It is clearly distinct from sibling tools like ssh_write_file and ssh_exec.

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 implies when to use the tool: when you need to read a text file over SFTP. However, it does not explicitly mention alternatives or state when not to use it, such as for binary files, directory listings, or executing commands.

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 burden of behavioral disclosure. It does disclose the key destructive behavior—overwriting an existing file—which is critical for an agent to know. However, it omits other important behavioral traits such as the requirement for an existing session, the effect of create_dirs, and what happens on failure or success.

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 sentence that is tightly worded and front-loaded with the action. Every word contributes meaning: 'Write', 'text content', 'file', 'remote host', 'SFTP', and 'overwriting'. No unnecessary detail or repetition exists.

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?

Despite low complexity (4 flat scalar parameters), the description is missing important context that the schema doesn't provide: the create_dirs default behavior, the need for an active session, and any expected outcomes or response. The only extra context over the name is the SFTP mechanism and overwrite semantics. An agent could still misuse this tool without understanding session requirements or directory creation.

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 for the lack of parameter documentation. It does not mention any of the parameters by name or provide additional meaning for path, content, session_id, or create_dirs. The only indirect hints are 'text content' (mapping to content) and 'file' (mapping to path), which is insufficient for an agent to correctly populate all four 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?

The description uses a specific verb ('Write') and resource ('file on the remote host') and clearly distinguishes this from sibling tools like ssh_read_file and ssh_exec. It also adds a precise mechanism (SFTP) and the overwriting behavior. An agent can immediately understand what this tool does and how it differs from alternatives.

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 usage context is implied: use this tool when you need to write or overwrite a file on a remote host over SFTP. However, there is no explicit guidance on when not to use it, no mention of prerequisites like an active session, and no comparison to alternative siblings. The description does enough to suggest its purpose but leaves the reasoning to the agent.

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