Orbit MCP exposes 45 tools with critical definition gaps across naming, descriptions, and schemas. Tool names are generally well-formed (verb_noun pattern: get_*, install_*, uninstall_*, etc.), but descriptions are uniformly minimal (10-40 chars) and lack actionable context for LLM tool selection. Input schemas are partially visible in the TypeScript client code but lack comprehensive JSON Schema documentation with type constraints, enums, min/max bounds, and format specifications. Output schemas are not documented at all. Error handling guidance is absent. The Rust MCP implementation (src/mcp.rs) is not provided, so the actual server-side schemas and validation logic cannot be verified, this caps per-tool scores at 50 when relying on inferred definitions.
Tool descriptions are uniformly minimal (10-30 characters), providing no context for LLM tool selection. Examples: 'Get Claude Code status', 'Install mkcert', 'Add host entry to system hosts file'. These violate the 50-200 character ideal and lack WHEN/WHY guidance.
Expand all tool descriptions to 50-200 characters with explicit WHAT/WHEN/RETURN structure. Example: 'Get Claude Code status' → 'Check if Claude Code is installed and return version, installation path, and source (native/orbit/system). Call this first to determine if installation is needed.'
Document all input parameters with type, description, constraints, and format. Add enums for constrained values: 'serviceType' should document 'Allowed values: php, nginx, mariadb, postgres, redis' (or actual valid types). Add format guidance: 'domain must be a valid hostname (e.g., example.com).'
Add output schemas to all tools. Example for get_claude_code_status: '{"type": "object", "properties": {"installed": {"type": "boolean"}, "path": {"type": "string", "nullable": true}, "version": {"type": "string", "nullable": true}, "source": {"enum": ["native", "orbit", "system"], "nullable": true}, "latest_version": {"type": "string", "nullable": true}}}'
Add error handling guidance to descriptions. Example: 'If domain resolution fails, return error: "Domain not found in /etc/hosts. Use add_host_elevated to add it first." Retryable: yes.'
Add confirmation/dry-run patterns to destructive tools. Example: clear_all_logs should accept optional 'confirm=true' parameter. Without confirmation, return '{"status": "input_required", "message": "Clear all log files? This cannot be undone.", "action": "confirm"}'.
Document tool sequences and dependencies. Example: install_redis description should note 'Call get_cache_status first to check current state. After installation, call update_redis_config to customize. Before uninstall, consider backup via get_redis_exe_path.'
Score history
Overall score trend
↑ 47 points across a rubric change (v1 → v2)
47/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
47
2026-07-28+
v2
2026-03-09
F
0
-
v1
Run composer install in a project
composer_removewritesource verified55/100
Remove a package from a project using composer
composer_requirewritesource verified57/100
Add a package to a project using composer
composer_updatewritesource verified52/100
Run composer update in a project
delete_ssl_certdestructivesource verified50/100
Delete SSL certificate for domain
generate_ai_context_cmdwritesource verified53/100
Generate and write AI context files for a site project
No input parameter validation schemas documented. Parameters like 'serviceType' (add_service_to_path, remove_service_to_path, check_service_path_status) lack enum constraints. 'domain' parameter (used in 7+ tools) has no format specification or allowed-values documentation. LLMs cannot infer valid enum values without explicit constraints.
No output schemas documented for any tool. LLMs cannot plan downstream calls or extract return values. Example: 'get_claude_code_status' returns AiToolStatus interface (installed, path, version, source, latest_version) visible in TypeScript but not in MCP schema. Agents must guess what fields are returned.
No error handling guidance in any tool description. Destructive tools (uninstall_claude_code, delete_ssl_cert, clear_all_logs, uninstall_redis, uninstall_composer) marked DESTRUCTIVE but lack confirmation steps or recovery guidance. Agents cannot determine which errors are retryable vs fatal.
Rust MCP implementation (src/mcp.rs) not provided in source listing. Tool definitions are inferred from TypeScript client wrappers only. Cannot verify actual server-side schema registration, validation logic, or error messages.
Parameter descriptions lack format/constraint guidance. Example: 'projectPath' (used in composer_install, composer_update, composer_require, composer_remove, get_composer_project, open_in_terminal) has no documentation of expected format (absolute vs relative path, symlink handling, existence validation). LLMs cannot predict valid inputs.
Multiple tools perform related operations but lack cross-references. Example: install_redis, get_cache_status, update_redis_config, uninstall_redis form a logical group but descriptions do not indicate dependency order or when to call each. Agents cannot infer workflow sequence.
Tool names occasionally ambiguous or non-standard. 'open_in_terminal' (verb_noun correct) but description unclear: does it open the project editor, a shell, or both? 'generate_ai_context_cmd' uses underscore + 'cmd' suffix; prefer 'generate_ai_context'. 'setup_mcp_config' uses 'setup' (non-standard); prefer 'update_' or 'configure_'.
No parameter mutual-exclusivity or dependency documentation. Example: open_in_terminal accepts 'tool' (claude-code or gemini-cli) but no description states which tools are installed or which is required first. 'domain' is optional but no guidance on when it's needed or what happens if omitted.
open_in_terminal
Add parameter constraints for numeric/string inputs. Examples: 'lines' in read_log_file should document 'min: 1, max: 10000, default: 100'. 'port' in update_redis_config should document 'valid range: 1024 - 65535'.
Provide the Rust MCP server implementation (src/mcp.rs) to enable verification of actual tool registration, schema compliance, and validation logic.
Standardize parameter naming: replace domain-specific suffixes with clear type hints. Example: 'cmd' in generate_ai_context_cmd is redundant, use generate_ai_context. 'setup' in setup_mcp_config should be 'update_mcp_config' or 'configure_mcp'.
Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to guide LLM planning. Mark all 'get_*' tools with readOnlyHint=true. Mark all 'delete_*', 'uninstall_*', 'clear_*' with destructiveHint=true. Mark all 'install_*' with idempotentHint=true (if true).