This bash/Python MCP server has 16 tools with explicit schemas and descriptions visible in libexec/mcp_tools_cli.py. However, critical gaps undermine quality: (1) Most tool descriptions are under 100 chars and lack WHEN/WHY context required for LLM selection. E.g., 'refresh' says 'Refresh MCP tools metadata cache' but doesn't explain when an agent should call it vs 'index'. (2) Parameter descriptions are minimal or absent, 'apply' and 'all' flags appear across tools but lack guidance on their interaction or side effects. (3) No output schemas documented; tools return JSON but LLMs cannot predict field structure. (4) Error handling is implicit (Python exceptions); no recovery guidance. (5) Destructive tools (remove, apply, render) lack confirmation patterns or dry-run support. (6) Tool names are inconsistent in verb clarity: 'refresh' and 'index' are vague; 'enable' and 'disable' are clear. (7) No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels assigned in metadata.

• Add output schemas to every tool. Document the JSON structure returned, including field names, types, and what each field means. E.g., 'list returns {agents: [{name, enabled, status, target, description}], total_count}.'
• Expand tool descriptions to 80 - 150 chars. Include WHEN to use it and how it differs from similar tools. E.g., 'refresh: Re-fetch tool metadata from STDIO servers and update cache. Call this after adding a new MCP. Use index to rebuild the searchable index from cached data.'
• Add parameter descriptions for all flags. Explain 'apply' (execute vs preview), 'all' (scope), and 'force' (override behavior). E.g., 'apply: boolean. If true, execute the operation and write state. If false, preview changes without modifying files.'
• Implement dry-run or confirmation for destructive tools (remove, apply, render, sync). Return a preview of changes and require explicit confirmation before executing irreversible operations.
• Add error handling with recovery hints. Catch exceptions and return structured errors like '{error: "registry.json not found", recovery: "Run: mcp-agent-manager bootstrap"}' so LLMs know what to do next.