Orbit MCP presents a functional but unpolished tool suite with moderate definition quality. All 6 tools have names, descriptions, and input schemas visible in the source code (orbit-mcp/src/index.ts). Naming follows verb-prefix conventions (orbit_status, orbit_switch_env, orbit_sidecars). However, descriptions lack depth, most are 80-150 chars, below the production baseline of 194 chars. Parameter descriptions are present but minimal (10-30 chars typically). Input schemas use proper JSON Schema with type declarations and enums, but output schemas are nowhere documented. Error handling exists but is generic (catch-all 'JSON.stringify({ error: message })'). No parameter validation constraints are documented (e.g., limits for 'limit' field). The tools bundle related concerns (e.g., orbit_sidecars handles list/start/stop with optional conditional params), which risks confusion. No indication of idempotency, confirmation steps for destructive operations, or rich error guidance.

• Document output schemas for all tools. Use JSDoc comments or separate .md files to specify what fields are returned (e.g., orbit_status returns { project_name, current_env, sidecars: [{ name, status }], recent_activity: [...] }). Include field types and constraints.
• Expand tool descriptions to 100-250 chars. Add WHEN guidance: 'Use orbit_status to check the current environment before switching. Use orbit_switch_env to change environments. orbit_status is lighter-weight and read-only.'
• Add parameter constraints to descriptions. E.g., 'limit: Audit query result limit (1-1000, default 20)'. 'confirm: Boolean confirmation required to stop all containers (default true; if false, acts as dry-run check).'
• Split orbit_sidecars into separate tools or document conditional param logic explicitly. Option A: create orbit_list_sidecars, orbit_start_sidecar, orbit_stop_sidecar. Option B: add a description note: 'If action=list, sidecar param is ignored. If action=start or stop, sidecar is required.'
• Implement confirmation_request pattern for orbit_stop_all. Return { content: 'About to stop all containers. Pass confirm=true to proceed.' } without confirming the first time, then require confirm=true on retry.
• Enhance error messages with recovery guidance. In the CallToolRequestSchema handler, catch specific errors and return: { error: 'Project not found at path /home/user/project. Available projects: [list]. Check orbit_status for details.' }
• Add tool annotations to the ListToolsRequestSchema response. Mark tools as readOnlyHint, destructiveHint, etc. Example for orbit_stop_all: { name: 'orbit_stop_all', description: '...', inputSchema: {...}, destructiveHint: true }.