Server has 12 tools with basic descriptions and input schemas using Zod. However, descriptions are minimal (10-50 chars), lack context on WHEN to use each tool, and omit error recovery guidance. Parameters are typed but descriptions are sparse. No output schemas documented. Tools lack idempotency hints and error classification. Naming is verb-prefixed (good), but descriptions do not explain prerequisites, side effects, or dependencies between tools. No tool annotations (readOnlyHint/destructiveHint). Error handling returns raw AppleScript errors without actionable recovery steps.

• Add tool annotations: mark affinity_status, affinity_get_menus, affinity_get_submenu as readOnlyHint=true; mark affinity_save, affinity_export, affinity_launch as destructiveHint=true. This enables LLMs to reason about side effects without parsing descriptions.
• Expand descriptions to 50-150 chars with WHEN/WHY context. E.g., affinity_keystroke: 'Send a single keystroke (e.g., Cmd+S) to Affinity. Use for keyboard shortcuts. For text input, use affinity_type_text instead.'
• Document output schemas. E.g., affinity_get_menus returns {type: 'text', text: 'Menu name:\n - item1\n - item2'}. Declare this in the tool definition so LLMs know the structure.
• Wrap error handling with recovery guidance. E.g., catch AppleScript errors and return: {content: [{type: 'text', text: 'Failed to click menu: menu not found. Verify menu name with affinity_get_menus(). Retryable: true.'}]}
• Add parameter constraints and examples in descriptions. E.g., menuPath: 'Array of menu names, 2-4 levels deep. Example: ["File", "Export", "Export…"]. Call affinity_get_menus() to discover valid top-level menus.'