ops-mcp provides 8 read-only Linux operations tools with consistent naming (verb_noun pattern: system_info, disk_usage, service_status, etc.) and clear descriptions (avg ~80 chars). All tools declare readOnlyHint and destructiveHint annotations. However, parameter descriptions are sparse or missing entirely in several tools (e.g., docker_ps 'all' param lacks detail on behavior), and output schemas are completely undocumented, LLMs cannot predict response structure. Error handling is basic (wrapped in audit.Log but no recovery guidance). Audit logging is a security strength. No pagination, no structured output documentation.

• Document output schemas for all tools. E.g., system_info returns {kernel: string, hostname: string, load_average: string}. Use JSON Schema in tool definitions so LLMs can plan downstream parsing.
• Add min/max bounds and default values to all numeric parameters. E.g., service_journal lines: 'Number of log lines to return (default 50, min 1, max 500)'.
• Enhance error messages with recovery guidance. Instead of 'docker_ps failed: exit status 1', return 'Docker daemon not running. Verify with: systemctl status docker. Or try service_status("docker.service") to check service state.'
• Document the unit allowlist feature in service_status and service_journal descriptions. E.g., 'Note: If OPS_MCP_UNIT_ALLOWLIST is set, only listed units are accessible.'
• Add structured output parsing. Convert raw command output (df, free, systemctl) into JSON objects with typed fields (filesystem, size_gb, used_gb, available_gb) so LLMs can reliably extract values.