Linear MCP server has 7 tools with basic schemas and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-50 chars, mostly adequate) and input schemas with type definitions. However, parameter descriptions are sparse or missing context. Output schemas are not documented. Error handling is minimal, no recovery guidance, no categorization of retryable vs fatal errors. No tool annotations (readOnlyHint/destructiveHint). Naming follows verb_noun convention well (list_issues, get_issue, create_issue, search_issues, update_issue, add_comment). The search_issues tool accepts 9 parameters but lacks enum constraints for status/priority, inviting hallucinated values. No pagination guidance in list_issues (returns 50 hardcoded, no limit param). Rate limiter is implemented but not exposed to LLM for visibility. Missing: output schema documentation, error recovery patterns, parameter validation rules in descriptions.

• Add output schema documentation to all tools. E.g., 'Returns: {identifier: string, title: string, priority: number|null, status: string, url: string, assignee: {id, name, email}?, team: {id, name}?}' so LLMs know what fields to extract.
• Convert search_issues 'status' and 'priority' parameters to enums. Document valid Linear workflow states (e.g., 'Backlog', 'Todo', 'In Progress', 'Done') and priority levels (0-4 or 'None', 'Urgent', 'High', 'Medium', 'Low').
• Add tool annotations: mark create_issue, update_issue, add_comment with destructiveHint=true; mark list_issues, get_issue, search_issues, get_user_issues with readOnlyHint=true. This enables agents to reason about side effects.
• Enhance error messages with recovery guidance. E.g., 'Issue ID "LIN-999" not found. Try search_issues(query="...") to find the correct issue ID.' Include available alternatives when resources are not found.
• Add pagination to list_issues: accept optional 'limit' (1-100, default 20) and 'offset' parameters. Return total_count and next_offset in response so agents can iterate through large result sets without blowing context.