This server exposes 17 tools with significant quality gaps. Only 2 tools (shell, code) have complete input schemas visible in src/tools.ts; the remaining 15 are inferred from examples or lack visible schema definitions. Descriptions range from extremely terse (6-12 chars: 'Capture a screenshot of the screen', 'Control mouse movement and clicks') to moderately detailed. No tool provides structured output documentation. Most parameter descriptions are missing or non-existent. Error handling is minimal, no recovery guidance or categorization. Tool composition violates single-responsibility principle (e.g., input_sequence bundles multiple actions). Security concerns: shell tool accepts arbitrary commands with only path-based sandboxing; no permission gates; no audit trail declarations. Schema completeness is particularly poor: 15 of 17 tools lack visible input schemas.
Descriptions are critically sparse. 12 tools have descriptions under 50 characters ('Capture a screenshot of the screen', 'Control mouse movement and clicks') with no explanation of WHEN to use them, WHAT they return, or dependencies.
Add complete JSON Schema input definitions to all 15 tools missing schemas. Include type, description, and constraints (min/max, enums, patterns) for every parameter. Reference src/tools.ts 'tool<S extends ZodSchema>()' helper as the schema source.
For each tool, explain: (1) WHAT it does, (2) WHEN to call it (vs similar tools), (3) Key constraints or side effects. E.g., 'Capture a screenshot of the current display, respecting screen lock state and max resolution constraints. Use before sending mouse/keyboard input to verify UI state.'
Document output schemas for all tools. Create a table in README or schema comments showing: field name, type, description, and chaining implications. E.g., screenshot returns {image_base64: string, width: int, height: int, timestamp: ISO8601}. This enables agents to plan downstream calls.
Add parameter descriptions to every input. For shell, document timeoutMs range (1000 - 86400000), cwd sandbox rules, and env var passthrough. For harness_* tools, document session_id format, expected return fields, and dependencies between tools.
Implement tool annotations: mark shell, code, harness_stop, harness_start as 'destructiveHint: true'; mark screenshot, harness_list, harness_status as 'readOnlyHint: true'. Add 'idempotentHint: true' where applicable (e.g., screenshot).
Add error handling and recovery guidance. E.g., for accessibility_query, return structured errors: {error: 'accessibility_not_available', recovery: 'Try screenshot() to capture UI state instead'}. Categorize errors as retryable (timeout), user-fixable (invalid session_id), or fatal (unsupported OS).
Run a shell command as the local user. This is terminal-equivalent capability. The command runs inside MACHINECTL_ALLOWED_PATHS, with a scrubbed environment.
input_sequence violates single-responsibility principle, it 'Execute[s] a sequence of input actions', bundling mouse, keyboard, and timing logic. Should be split into separate composition-ready tools per pattern:tool.
shell tool accepts arbitrary shell commands with only path-based sandboxing (MACHINECTL_ALLOWED_PATHS). No permission-gate checks, no audit trail declarations, no user/agent authentication. Per pattern:permission-gate and pattern:scope-declaration, destructive tools must verify authority before execution.
No output schemas documented for any tool. LLMs cannot predict what fields they'll receive, preventing downstream tool chaining and forcing discovery. Per pattern:tool, every tool must document its return structure.
Error handling is absent. No recovery guidance (e.g., 'If accessibility query fails, try screenshot'), no error categorization (retryable vs user-fixable vs fatal), no actionable error messages. Per pattern:recovery-guide and pattern:error-classification.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) present. shell is DESTRUCTIVE; screenshot is READ_ONLY; harness_* tools are WRITE, but no formal declarations in schemas. Per current spec (2026-07-28), tool annotations enable safety-aware agent planning.
No confirmation/dry-run support for destructive operations (shell, harness_stop, code execution). Per pattern:confirmation-request, irreversible operations should support a confirmation step to prevent agent mistakes.
Split input_sequence into composable tools: input_mouse_click(x, y, button), input_keyboard_type(text), input_wait_ms(duration). This lets agents build complex sequences via composition rather than one opaque tool.
Add permission gates to shell and code execution. Require an explicit allow-list of commands or code patterns. Log who invoked what (agent ID, timestamp, command/code hash). Per pattern:permission-gate and pattern:audit-trail.
Add confirmation/dry-run steps for destructive tools. E.g., shell with dry_run: bool parameter; return would-be output without executing. code with 'sandbox_only: bool' to execute in isolation. Per pattern:confirmation-request.
For harness_* tools, document the session lifecycle: harness_start() returns {session_id, ...}; harness_prompt(session_id, ...) expects that session_id; harness_stop(session_id) closes it. Verify all tool outputs include chaining IDs. Per pattern:tool-chain.
Add parameter constraints and validation. E.g., code max 64 KB (visible); shell timeoutMs must be 1000 - 86400000 (visible in code); add enum constraints for harness operations (start|stop vs prompt|steer).
Reduce parameter overload on shell and code. Consider adding higher-level wrappers: run_python_script, run_shell_script_safe (dry-run only), execute_js_snippet (sandbox). Per pattern:chat-data-model, abstract API complexity so agents operate at intent level.
Add response limiting and pagination. If harness_list or harness_catalog return large result sets, cap to 20 - 50 items and provide a 'next_cursor' or limit parameter. Per pattern:paginated-result.
Document security boundaries. In README, explain: MACHINECTL_ALLOWED_PATHS isolation, environment variable passthrough rules, what agent permissions are required to call each tool. Per pattern:scope-declaration and pattern:secret-injection.