docs: document run_sql structuredContent response shape

references/integrations/lightdash-mcp.mdx

@@ -277,6 +277,41 @@ MCP provides AI assistants with powerful tools to interact with your Lightdash d
   **Run SQL** requires the `manage SqlRunner` permission. The SQL is executed directly against your warehouse, so use the appropriate SQL dialect for your connection (e.g., PostgreSQL, BigQuery, Snowflake).
 </Info>
 
+<Accordion title="run_sql response shape (for developers)">
+  When you call `run_sql` from a custom MCP client or live artifact, the tool returns both a CSV text payload and a `structuredContent` object. Prefer `structuredContent.rows` over parsing the CSV — values arrive as JSON-serializable primitives (numbers, strings, booleans, ISO date strings, or `null`), so you don't need `parseFloat` or `parseInt` on numeric columns.
+
+  **Response envelope:**
+
+  ```json
+  {
+    "content": [
+      { "type": "text", "text": "<CSV string with header row + data rows>" }
+    ],
+    "structuredContent": {
+      "rows": [
+        { "status": "completed", "n": 94, "total_amount": 2397 }
+      ],
+      "columns": ["status", "n", "total_amount"],
+      "rowCount": 1
+    }
+  }
+  ```
+
+  **Example usage:**
+
+  ```ts
+  const result = await callMcpTool('run_sql', { sql, limit });
+  const rows = result.structuredContent.rows;       // [{ status: 'completed', n: 94, ... }, ...]
+  const columns = result.structuredContent.columns; // ['status', 'n', 'total_amount']
+  ```
+
+  **Notes:**
+
+  - Empty results still return `structuredContent` as `{ rows: [], columns, rowCount: 0 }` — distinct from a parse failure.
+  - On error, the response has `isError: true` and `content[0].text` contains the error message; `structuredContent` is omitted.
+  - `content[0].text` continues to carry the raw CSV, so existing clients that parse the text payload keep working.
+</Accordion>
+
 <Warning>
   **Security best practice:** Ensure the database credentials configured in your Lightdash connection have **read-only (viewer) access** to your warehouse. Since `run_sql` executes arbitrary SQL, a connection with write permissions could allow AI agents to modify or delete warehouse data.
 </Warning>