arc-mcp has well-structured tool definitions with consistent naming (verb_noun pattern) and descriptions present for all 9 tools. Input schemas use Zod with type declarations and descriptions. However, output schemas are not documented, responses are returned as unstructured JSON text without field-level documentation. Error handling is minimal (success/error flags only, no recovery guidance). Parameter descriptions lack detail on constraints, formats, and valid ranges. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk levels. Composition is sound, tools are single-responsibility and chainable via IDs.

• Document output schemas for all tools. Specify field names, types, and meanings. E.g., list_spaces should document: {spaces: [{id: string, name: string, icon: string}]}. This enables LLMs to extract and chain data reliably.
• Add tool annotations via MCP. Register destructive tools (delete_space, delete_tab) with destructiveHint=true; read-only tools (list_spaces, list_tabs) with readOnlyHint=true. This exposes safety properties in the tool definition.
• Enhance error messages with recovery guidance. Instead of 'Failed to delete space: {error}', return 'Space not found. Available spaces: [list]. Did you mean one of these?' This enables self-correction without extra calls.
• Add parameter validation rules to descriptions. E.g., 'icon: emoji (single character) or SF Symbol name (e.g., star.fill, heart.fill). See https://developer.apple.com/sf-symbols/ for valid names.' This prevents invalid input from LLMs.
• Implement a confirm_delete pattern for destructive tools. Add an optional 'confirm' boolean parameter (default false). When false, return a preview of what will be deleted. When true, execute. This prevents accidental data loss.