PortaMCP provides 27 tools with basic naming and descriptions, but critical gaps undermine production readiness. Tool names follow verb_noun convention (good), but descriptions are minimal (10-30 chars, well below the 50-200 char baseline for LLM optimization). Input schemas are present but sparse: most parameters lack detailed descriptions, constraints, or format guidance. No output schemas documented. Error handling is absent, tools provide no recovery guidance. Security-critical tools (run_shell_command, delete_file, kill_process) lack permission gates, confirmation patterns, or audit trail integration. Composition is poor: browser_* and chrome_tab_* tools duplicate functionality without clear differentiation. No pagination, rate limiting, or result capping for list operations.

• Expand all tool descriptions to 50-200 characters. Include WHAT the tool does, WHEN to use it, and what it returns. E.g., 'system_info' → 'Returns CPU, memory, disk, and OS info. Use to assess system capacity before running resource-intensive tasks.'
• Document output schemas for all tools. Specify field names, types, and whether results are paginated. E.g., list_files should return {files: [{name, size, modified_time}], total_count, has_more}.
• Add confirmation patterns to destructive tools (delete_file, kill_process, run_shell_command). Implement a dry-run parameter or require explicit confirmation before execution.
• Consolidate browser_* and chrome_tab_* tools. Choose one canonical set (prefer chrome_tab_* for clarity) and remove duplicates. Document when to use each remaining tool.
• Enhance parameter descriptions with format constraints. E.g., 'path' → 'Absolute or relative file path (e.g., /home/user/file.txt or ./data/file.txt)'. 'selector' → 'CSS selector (e.g., #button-id, .class-name, div > p) or XPath expression.'
• Add error handling with recovery guidance. E.g., run_shell_command should return {success, stdout, stderr, exit_code} and guide LLM on retryable vs fatal errors.
• Implement pagination for list_* tools. Add limit and offset/cursor parameters, return total_count, and cap results at 50 items by default.
• Add permission gates and audit logging. Log who called what tool, with which parameters, at what time, and what happened. Gate destructive operations behind permission checks.

Inferred effective spec: 2026-07-28+.

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