ssh_interactive_exec

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

No annotations are provided, so the description carries the full burden. It does disclose key behaviors: waits until output goes quiet or process exits, returns output plus session_id, auto-closes session if no prompt, idle sessions expire after 10 minutes. However, it doesn't specify auth requirements (uses local SSH config/keys is mentioned in schema), what the return format looks like, or how errors/timeouts are surfaced. The waiting threshold (quiet_ms) is documented in schema, not description.

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 three well-structured sentences that front-load the core purpose with concrete use cases, then proceed to lifecycle behavior and follow-up tool routing. It's appropriately sized and every sentence carries information. Minor waste: could be seen as slightly dense but nothing is redundant.

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 stateful, multi-tool interactive workflow with no output schema and no annotations, the description does a strong job covering the key semantics: PTY allocation, quiet-wait behavior, session lifecycle (auto-close, follow-up tools), and expiry. It integrates well with the sibling tool ecosystem. Slight gap is not explaining the return structure/output format for the initial call, but this is partly compensated by listing what it returns (output + 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?

Schema coverage is 67%. The description explains the 'command' parameter conceptually (programs that prompt for input) and mentions quiet_ms behavior indirectly ('waits until output goes quiet'). However, the description doesn't add depth to 'target' beyond what schema already states (user@host[:port], local config/keys) or explain the quiet_ms tuning semantics (what the tradeoffs of shorter/longer wait are). Baseline 3 is appropriate with moderate schema 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+resource (start a command on remote host with PTY) and the purpose (for programs that prompt for input). It lists specific use cases (sudo, y/N confirmations, setup wizards, REPLs) which sharply distinguishes it from siblings like ssh_exec (non-interactive execution) and ssh_interactive_input (a separate follow-up tool).

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?

Excellent guidance on when to use this vs alternatives. It explicitly names the sibling tools to use (ssh_interactive_input to reply/poll, ssh_interactive_close to finish), describes the behavior when the command finishes without prompting (session auto-closes, nothing further to do), and provides the auto-expiry timeout (10 min). This is explicit when/how guidance with named alternatives.

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