Run command in persistent SSH session

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

Beyond annotations (readOnlyHint=false, destructiveHint=true), the description adds rich behavioral detail: wait_sec behavior with status=running, no automatic timeout, timeout_sec sending Ctrl-C, one foreground command per id, and persistence of cwd/environment changes.

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 front-loaded with the core operation and then provides precise behavioral and usage clauses. Every sentence adds value, and the length is justified by the tool's complexity.

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 lifecycle, timeout, concurrency, and restrictions are thoroughly covered. However, with no output schema, the description does not specify the return payload for completed commands—only mentioning status=running for still-active commands. This is a minor but non-negligible gap.

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 zero property descriptions, but the description fully compensates: id identifies the persistent shell, command is non-interactive, wait_sec is the call wait limit with a default, and timeout_sec triggers Ctrl-C at the deadline. All four parameters are semantically grounded.

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 starts a non-interactive command in the same persistent shell identified by id, with persistent cwd and environment changes. This distinguishes it from sibling tools like ssh_open (new session) and ssh_peek/ssh_interrupt.

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?

Explicit guidance is given: poll with ssh_peek(wait_sec=...), call ssh_interrupt to stop, open another session for concurrency, and never retry a running command. It also explicitly forbids interactive TUI/input flows such as vim or top.

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