[Feature Request]: Enhanced Error Messages with Actionable Guidance

[carlosmmatos]

Summary

Enhance error messages to include common causes, suggested actions, and relevant context to help AI agents recover from errors and learn correct tool usage.

Problem

Current error messages provide basic information but lack actionable guidance:

• AI agents don't know why an error occurred
• No suggestions for how to fix or work around issues
• 403 errors don't indicate which API scopes are required
• FQL syntax errors don't point to documentation resources

This leads to AI agents getting stuck or making repeated unsuccessful attempts.

Proposed Solution

Replace simple error descriptions with structured error responses that include:

1. Error message: Human-readable description
2. Common causes: List of likely reasons for this error
3. Suggested actions: Specific steps to resolve the issue
4. Required scopes: (for 403 errors) Which API scopes are needed
5. Resource links: (for FQL errors) Link to relevant FQL guide resource

Example Enhanced Error Structure

ERROR_CODE_DESCRIPTIONS = {
    400: {
        "message": "Bad Request - Invalid parameters or malformed query",
        "common_causes": [
            "Invalid FQL syntax in filter parameter",
            "Parameter value out of valid range",
            "Missing required parameter",
            "Invalid date/timestamp format"
        ],
        "actions": [
            "Check FQL syntax using the falcon://{module}/fql-guide resource",
            "Verify all parameter values are within documented ranges",
            "Review the tool's parameter descriptions",
            "Try simplifying your query to isolate the issue"
        ]
    },
    403: {
        "message": "Permission Denied - Insufficient API scopes",
        "common_causes": [
            "API client doesn't have required OAuth scopes",
            "API client has been disabled or revoked"
        ],
        "actions": [
            "Verify required scopes are granted in CrowdStrike console",
            "Check API client status is 'Active'"
        ]
    },
    429: {
        "message": "Rate Limit Exceeded",
        "common_causes": [
            "Too many requests in short time period",
            "Large result sets triggering API throttling"
        ],
        "actions": [
            "Wait 60 seconds before retrying",
            "Use more specific filters to reduce data volume",
            "Implement pagination with smaller page sizes"
        ]
    }
}

Files Affected

• falcon_mcp/common/errors.py - Enhance ERROR_CODE_DESCRIPTIONS and _format_error_response()

Acceptance Criteria

• Error descriptions include common causes and suggested actions
• 403 errors include required API scopes for the failed operation
• FQL-related errors reference the appropriate resource URI
• Error structure is consistent across all error codes
• Unit tests verify enhanced error formatting
• Documentation updated with error handling guidance