GoalOS MCP server has well-structured tool definitions with consistent naming (verb_noun pattern: goalos_*), complete input schemas with proper types and enums, and reasonable descriptions. However, descriptions are often generic and lack LLM-optimized guidance on WHEN to use each tool vs. alternatives. Parameter descriptions are present but minimal (10-30 chars typical). Output schemas are not documented, critical for agents planning downstream calls. Error handling and recovery guidance are absent. No tool annotations (readOnlyHint/destructiveHint) despite clear risk stratification (READ_ONLY, WRITE, REVERSIBLE). Missing idempotency guarantees and confirmation patterns for destructive ops.

• Document output schemas for all 9 tools. Example: goalos_list_goals returns {goals: [{id, title, status, priority, deadline, parent_id}], total_count, has_more}. Include field types and which IDs are safe to pass to downstream tools.
• Add tool annotations to source code: readOnlyHint=true for get_*/list_*/search_*; destructiveHint=true for complete_goal/update_goal with status changes; idempotentHint=true for add_goal (if duplicate title is rejected, not created).
• Expand descriptions to 80-150 chars with decision guidance. Example: 'List all goals with optional filtering by status/priority/domain. Use this to discover available goals; for top priorities by deadline, call goalos_get_priorities instead.'
• Add error handling: return structured errors with actionable guidance. Example: {error: 'goal_not_found', goal_id: 'xyz', suggestion: 'Call goalos_search(query=...) to find goals by title or tag.'}
• Implement confirmation pattern for destructive ops: add optional 'confirm=true' parameter to goalos_complete_goal and goalos_update_goal. When confirm=false (default), return {requires_confirmation: true, preview: {...}} instead of executing.