fix(mcp): Improve validation errors and field aliases to reduce failed LLM tool calls (#38625)

(cherry picked from commit d91b96814e)

superset/mcp_service/sql_lab/tool/execute_sql.py

@@ -186,7 +186,20 @@ def _convert_to_response(result: QueryResult) -> ExecuteSqlResponse:
 
     if data_stmt is not None and data_stmt.data is not None:
         # SELECT query - convert DataFrame
+        import pandas as pd
+
         df = data_stmt.data
+        if not isinstance(df, pd.DataFrame):
+            logger.error(
+                "Expected DataFrame but got %s for statement data",
+                type(df).__name__,
+            )
+            return ExecuteSqlResponse(
+                success=False,
+                error=f"Internal error: unexpected data type ({type(df).__name__})",
+                error_type="data_conversion_error",
+                statements=statements,
+            )
         rows = df.to_dict(orient="records")
         columns = [ColumnInfo(name=col, type=str(df[col].dtype)) for col in df.columns]
         row_count = len(df)

superset/mcp_service/sql_lab/tool/open_sql_lab_with_context.py

@@ -18,7 +18,7 @@
 """
 Open SQL Lab with Context MCP Tool
 
-Tool for generating SQL Lab URLs with pre-populated query and context.
+Tool for generating SQL Lab URLs with pre-populated sql and context.
 """
 
 import logging
@@ -43,9 +43,9 @@ logger = logging.getLogger(__name__)
 def open_sql_lab_with_context(
     request: OpenSqlLabRequest, ctx: Context
 ) -> SqlLabResponse:
-    """Generate SQL Lab URL with pre-populated query and context.
+    """Generate SQL Lab URL with pre-populated sql and context.
 
-    Returns URL for direct navigation.
+    Pass the sql parameter to pre-fill the editor. Returns URL for direct navigation.
     """
     try:
         from superset.daos.database import DatabaseDAO