Rapid7 MCP presents well-structured tool definitions with consistent naming conventions (all tools follow verb_noun pattern), explicit enum constraints, and reasonable parameter descriptions. However, several tools lack comprehensive output schema documentation, and parameter descriptions often lack actionable format/constraint details expected in production tools. The server registers 7 tools with proper input schemas using Zod validation, but output schemas are not explicitly documented in the visible code. Descriptions are present but average 100-150 characters, below the 194-char production baseline, and lack dependency hints or recovery guidance. Schema completeness is moderate: constraints are declared (enums for severity/status/type), but many parameters lack minimum/maximum bounds or format specifications. Error handling mechanisms are not visible in the sampled code.

• Add explicit output schema documentation for each tool. Use TypeScript interfaces or JSON Schema blocks in comments (e.g., '@returns {object} {alerts: [{id: string, severity: string, created_time: string, ...}], total_count: number, next_cursor?: string}'). This allows LLMs to plan downstream calls without discovery overhead.
• Expand parameter descriptions to include format/constraint details and default behavior. E.g., for 'start_time': 'ISO 8601 UTC timestamp (e.g. 2024-12-15T09:30:00Z). If omitted, defaults to 24 hours ago. Timezone must be UTC; local times are rejected.'
• Add recovery hints to tool descriptions. E.g., 'Get full details of a specific InsightIDR alert. Call this after list_alerts() identifies an alert of interest, or pass an alert_id from an email/API response. Returns full event context, linked investigation ID, and indicators.'
• Document error conditions and recovery paths. Add a '@throws' or 'Errors' section to each tool (in code or README): 'Invalid alert_id: Use list_alerts() to find valid IDs. Alert not found (404): The alert may have been deleted; try searching by affected asset instead.'
• Validate and document assignee_email resolution. Add parameter description: 'Email address of an InsightIDR user. Must be an active member of the org. Invalid/inactive emails are rejected with a 400 error listing available users.'
• Add minimum/maximum bounds to numeric parameters where not present. E.g., 'index': 'Pagination offset (0-based, max 10000 to prevent abuse)' or 'size': 'Results per page. Defaults to 20; must be 1 - 100.'