Single tool with basic schema and description, but significant gaps in parameter documentation, error guidance, and composition patterns. The tool accepts credentials as parameters (security risk), has no output schema documentation, and provides minimal guidance for LLM invocation. Parameter descriptions are missing for critical fields (password, privateKey). Error handling returns raw text rather than actionable recovery guidance. No pagination, rate limiting, or idempotency patterns. Tool name is verb-based (positive), but the server overall demonstrates low maturity.
Credentials (password, privateKey) exposed as tool parameters. Secrets in parameters leak into agent logs and traces. Must use server-side secret injection via environment variables or vault.
Missing parameter descriptions for 'password' and 'privateKey'. LLMs cannot infer when to use password auth vs key auth. Both fields also lack format constraints (e.g., 'PEM-encoded private key').
No documented output schema. Tool returns stdout/stderr/exit code implicitly, but LLMs cannot plan downstream calls or extract structured data without a defined response format.
Error handling returns raw text (e.g., 'Command failed with code X') without recovery guidance. LLM has no next step when a command fails. Should indicate: is the error retryable? Should the user correct the command? Is it a connectivity issue?
Recommendations
Remove 'password' and 'privateKey' from input schema. Move credentials to server-side environment variables or a secure configuration file. Modify the tool to accept a 'connection_name' or 'profile' parameter instead, which the server resolves to real credentials internally.
Add descriptions to 'password' and 'privateKey' parameters explaining format and use cases, OR better yet: eliminate them and use environment variables. If you must accept keys: 'PEM-encoded private key (typically from ~/.ssh/id_rsa). Either password OR privateKey must be provided, not both.'
Document the output schema explicitly in the tool definition: 'Returns {stdout: string, stderr: string, exitCode: number}. stdout contains command output; exitCode 0 indicates success.'
Enhance error handling to provide recovery guidance. Wrap the SSH connection logic in a try-catch that returns structured errors: 'Connection failed: {reason: 'authentication failed' | 'host unreachable' | 'timeout', suggestion: '...'}'
Expand the tool description to ~100-150 characters covering WHEN to use it: 'Execute a shell command on a remote server via SSH. Use this to run scripts, queries, or administrative tasks. Note: commands must not be interactive (no expect/password prompts) and should complete within 60 seconds.'
Add a 'timeout' parameter (default 60 seconds, range 5-300) to prevent the agent from hanging on long-running commands. Document: 'Maximum seconds to wait for command completion. Longer timeouts may block the agent.'
Tool description is generic ('Execute command on remote server via SSH'). Missing WHEN to use it, prerequisites (e.g., 'SSH key must be installed on remote'), and what types of commands are safe (no mention of long-running processes, interactive commands).
No timeout or result-limit documentation. Long-running SSH commands could block the agent indefinitely. No pagination or result capping for large command outputs.
No confirmation or dry-run pattern for destructive operations. SSH commands can delete files or modify systems irreversibly. Agents should be able to preview or confirm before execution.
No input validation or actionable error messages. If 'host' is invalid or authentication fails, the error is a raw exception. Should return: 'SSH connection failed to 10.0.0.1:22 (username=user). Ensure host is reachable and credentials are correct.'
execute_ssh_command
Implement input validation: verify 'host' is a valid hostname/IP, 'port' is 1-65535, 'username' is non-empty, and either 'password' or 'privateKey' is provided (but not both unless explicitly needed). Return actionable errors: 'Invalid port: got 99999, must be 1-65535.'
Add an optional 'dry_run' or 'preview' parameter (boolean, default false). When true, return the command that WOULD be executed without actually running it. This lets agents confirm destructive operations: 'Would execute: rm -rf /data/* on host=prod.example.com'
Consider splitting execute_ssh_command into two tools for clarity: 'execute_ssh_command' (read-only) and 'execute_ssh_command_unsafe' (with confirmation prompt) for destructive operations. Alternatively, add a 'destructiveHint: true' annotation to the existing tool.
Document authentication order and fallback: 'If privateKey is provided, SSH will use key-based auth. If privateKey is absent or fails, password auth is attempted. Both must be present for the connection to succeed.' Consider making privateKey attempt first (more secure).