Agent Swarm MCP server has significant definition quality gaps. Tool names lack consistent verb-noun patterns (swarm_run, swarm_playbook, swarm_ontology are vague). Descriptions are present but generic, most under 100 chars, lacking WHEN/WHY guidance. Input schemas exist but are incomplete: many parameters lack type definitions (e.g., web_search.max_results is string not integer; http_fetch.max_length is string not integer). Output schemas are entirely undocumented. Error handling is minimal, no recovery guidance or categorization. Security-critical tools (shell_exec, file_write) lack permission gates or dry-run patterns. No tool annotations (readOnlyHint, destructiveHint). Composition is poor: shell_exec and file_write are high-risk with minimal safeguards.

• Convert all numeric parameters (max_results, max_length, timeout, max_lines) from string to integer type with min/max constraints in schema. E.g., max_results: {type: 'integer', minimum: 1, maximum: 10}.
• Document output schemas for all tools. Specify returned fields, types, and structure. E.g., web_search returns [{title, url, snippet, source}], swarm_run returns {status, results: [{task_id, output, error}]}.
• Rename vague tools: swarm_ontology → query_ontology, swarm_skills → list_skills, swarm_status → get_engine_status. Follow verb_noun pattern consistently.
• Add confirmation/dry-run support to shell_exec and file_write. Implement pattern:confirmation-request: return a confirmation_token, require explicit confirm_shell_exec(token) or confirm_file_write(token) call before execution.
• Enhance parameter descriptions with format constraints and dependency hints. E.g., file_read.path: 'File path to read (must be within base_dir if set; supports relative paths)'. Add examples of valid inputs without literal values.