Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The Rootly MCP server exposes 77 tools covering incident management, scheduling, and on-call workflows. Tool names follow verb_noun conventions consistently (get_, list_, create_, update_, search_). However, schema and description quality varies significantly. Many tools lack visible parameter type definitions and descriptions in the source code provided. The server uses FastMCP with HTTP transport and includes tool annotations (readOnlyHint/destructiveHint). Error handling guidance is present but inconsistent across tools. Output pagination support is documented in some list_ tools but not universally applied. Security patterns (secret injection via environment variables, no credentials in parameters) are properly implemented. Composition is generally sound, tools have single responsibilities and tool chains are supported through ID references. The primary gaps are: (1) parameter descriptions are not uniformly detailed in the visible source; (2) output schemas for complex objects lack documentation; (3) some tools combine multiple concerns (e.g., create_incident_action_item could be more granular). Average tool description length estimated at ~150 chars based on visible docstrings, which meets the 10-1024 char baseline but could be more LLM-optimized (target 50-200 chars for A-grade tools).
Parameter descriptions and type definitions are not fully visible in the provided source code. While tool names follow verb_noun conventions, the actual JSON Schema parameter definitions (required, types, descriptions) cannot be verified from server_defaults.py snippet alone. This prevents scoring parameter quality at A-grade levels.
Output schema documentation is implicit (derived from OpenAPI spec bundle at data/swagger.json) rather than explicitly documented in tool definitions. LLMs need explicit documentation of response fields, types, and pagination structure inline with tool definitions.
No visible confirmation/dry-run pattern for destructive operations (delete_* tools do not appear to exist, but create_*, update_* operations lack explicit dry-run or confirmation step). Agents should be able to preview changes before committing irreversible modifications.
Recommendations
Extract and inline the parameter schema definitions from the OpenAPI spec bundle. For each tool, document the JSON Schema input properties with explicit types (string, number, boolean, array, object), descriptions (50-150 chars explaining the parameter's purpose and format), and constraints (enum values, min/max, pattern). Example: 'severity': { 'type': 'string', 'enum': ['critical', 'high', 'medium', 'low'], 'description': 'Incident severity level. Use critical for service-impacting outages.' }
Add pagination documentation to all list_* tools. State the default limit (e.g., 20 items), maximum limit (e.g., 100), and whether cursor-based or offset-based pagination is supported. Example: 'Returns up to 20 incidents per page. Pass next_cursor to fetch the next page. Total count is included in the response.'
Enhance tool descriptions to include recovery hints for common failure modes. Example for get_incident: 'Retrieve a single incident by ID. If the incident is not found, try search_incidents or collect_incidents to locate it by name or timeframe.'
Implement a dry-run or preview mode for all create_* and update_* operations. Add an optional 'dry_run' boolean parameter (default false). When true, return the expected result without committing changes. This prevents accidental data corruption.
Add explicit error categorization in tool descriptions. Use a structured note like: 'Errors: retryable (rate_limit, timeout), user-fixable (invalid_id, missing_field), fatal (permission_denied). On failure, the response includes an error_code and recovery_suggestion.'
Spec posture evidence
Inferred effective spec: 2026-07-28+.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Error handling guidance is not uniformly documented. Tools lack explicit error categorization (retryable, user-fixable, fatal) and recovery suggestions in descriptions. E.g., 'incident not found' should suggest search_incidents or collect_incidents.
Some tool names are overly long or compound similar concerns. E.g., 'get_incident_meeting_transcripts', 'get_oncall_handoff_summary' are clear, but 'list_incident_form_field_selections', 'list_schedule_rotation_active_days' could benefit from consolidation or clearer hierarchy.
Validate that all tools accepting IDs (user_id, incident_id, team_id) also accept human-readable names (user_name, incident_name, team_name) with fallback lookup inside the tool. This reduces the cognitive load on agents.
Ensure tool output always includes the IDs and references needed for downstream tool calls. E.g., get_incident must return incident_id, team_id, and service_id so agents can immediately call update_incident, list_incident_alerts, etc. without extra lookups.
Document which tools are idempotent. E.g., 'Creating an incident with the same external_id twice returns the same incident; no duplicate is created.' This signals to agents that retries are safe.
Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to the tool definition output. These are already mentioned as supported by FastMCP, ensure they are consistently applied. Example: 'create_incident' should have destructiveHint=true if it auto-escalates or triggers notifications.