Sideshell exposes 10 terminal control tools with basic schemas and descriptions. Most tools have descriptions (8-50 chars), but many are terse and lack actionable guidance. Schemas are present but sparse: parameters lack detailed type constraints, enums are minimal, and output schemas are undocumented. No error handling guidance, no recovery hints, and no tool annotations (readOnlyHint/destructiveHint). Tool names are verb-based (execute, read, control-char, list, split, new-window, new-tab, focus, clear, paste) but some are hyphenated and non-standard (control-char, new-window, new-tab). Critical gap: no documentation of what each tool returns or how to chain them. Descriptions do not explain prerequisites, side effects, or when to call list() first. Parameters like session_id lack guidance on how to obtain them. This is a functional but under-documented toolkit typical of early-stage MCP servers.

• Add output schema documentation to every tool. Example for execute: 'Returns {success: bool, output: string, exit_code: int, session_id: string}'. This enables chaining and LLM planning.
• Expand descriptions to 100-150 chars with WHAT, WHEN, and PREREQUISITES. Example: 'Execute a shell command in a terminal session. Call list() first to find session_id. Returns command output and exit code. Supports timeout and multi-target broadcast.'
• Add tool annotations: mark read/list as readOnlyHint=true; mark execute/paste/clear/split/new-window/new-tab/focus as destructiveHint=true or idempotentHint=true as appropriate.
• Rename hyphenated tools to snake_case: control_char, new_window, new_tab. This aligns with verb_noun convention and improves LLM parsing.
• Document error cases and recovery paths. Example for execute: 'If timeout occurs, try increasing timeout parameter or breaking command into smaller steps. If session_id not found, call list() to verify session exists.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry