Two tools with clear verb-noun naming (linear_get_issue, linear_get_issue_with_comments) and good descriptions (120-130 chars, within baseline 34-392). Input schemas present with Zod validation and parameter descriptions. Tool annotations (readOnlyHint, idempotentHint, openWorldHint) correctly applied. However, output schema is undocumented, responses are JSON strings without formal schema declaration. Error handling returns text blobs rather than structured error objects with recovery guidance. No pagination, rate limiting, or per-item error reporting. Parameter descriptions include examples (e.g., 'ENG-123') which LLMs may reuse literally. Missing dependency hints and prerequisites (LINEAR_API_TOKEN requirement buried in server instructions, not in tool descriptions).

• Document output schema formally. Define the structure of issue objects (identifier, title, url, description, state, priority, assignee, createdAt, updatedAt, comments) with types and field descriptions. Return structured objects, not JSON strings.
• Replace unstructured error text with categorized error objects: {error_type: 'not_found'|'invalid_input'|'auth_failed'|'rate_limited', message: '...', recovery_hint: '...'}. E.g., 'User not found. Try searching with a partial name first.'
• Remove example values from parameter descriptions. Replace 'e.g., ENG-123' with a format constraint: 'Linear issue identifier (format: [A-Z]+-[0-9]+) or full URL'.
• Add prerequisite documentation to tool descriptions: 'Requires LINEAR_API_TOKEN environment variable. Set it in your MCP server configuration before calling this tool.'
• Add pagination to linear_get_issue_with_comments: accept optional limit (default 20, max 100) and offset parameters. Return total_comments count and next_offset cursor.