1Shell exposes 9 tools with basic schemas and descriptions, but critical gaps undermine production readiness. All tools have descriptions (10-60 chars, mostly too brief), and input schemas are present with typed parameters. However, descriptions lack actionable context for LLM selection, they state WHAT but not WHEN or WHY. Error handling is absent: no recovery guidance, no categorization of retryable vs fatal errors. Security concerns: host_exec and file upload tools accept hostId as a string parameter with no validation hints, inviting injection attacks. Composition is weak: upload_file, write_remote_file, start_file_upload, append_file_upload, and finish_file_upload represent a fragmented multi-step workflow that should be abstracted into a single high-level tool. Output schemas are undocumented, LLMs cannot predict response structure. No pagination, no result limits, no chaining IDs. ask_1shell_ai and get_1shell_ai_run form an incomplete async pattern with no timeout or status enum guidance.

• Expand all tool descriptions to 100-200 characters. Include WHEN to use the tool, what it returns, and any prerequisites. Example: 'Execute a shell command on a remote host. Use this to run diagnostics, deploy code, or manage services. Returns stdout, stderr, and exit code. Timeout defaults to 30s; set higher for long-running tasks.'
• Consolidate file upload into a single high-level tool: upload_file_chunked(hostId, dirPath, filename, fileContent|localPath, chunkSize=1MB). Handle chunking internally. Return uploadId, status, and progress percentage. This matches the chat data model and reduces agent reasoning overhead.
• Add output schema documentation for every tool. Example for host_exec: 'Returns {stdout: string, stderr: string, exitCode: number, duration_ms: number}'. This enables LLMs to plan downstream tool calls.
• Add parameter validation hints. For hostId, document format (e.g., 'alphanumeric, 1-64 chars'). For command, state: 'Shell command string. Sanitized against injection; special chars like $, `, | are escaped unless quoted.' This guides LLM input and signals security measures.
• Implement error categorization. Return structured errors: {error: string, code: 'RETRYABLE'|'USER_FIXABLE'|'FATAL', suggestion: string}. Example: 'Host not found. Try list_hosts() to see available targets.' This enables agents to self-correct.