diff --git a/airbyte/_direct_connectors/actions.py b/airbyte/_direct_connectors/actions.py
index e9b4dd8fd..eb3fa3282 100644
--- a/airbyte/_direct_connectors/actions.py
+++ b/airbyte/_direct_connectors/actions.py
@@ -26,8 +26,9 @@ class AgentReadAction(str, Enum):
"""Connector actions that only read data.
The `search` action is the connector's native API search, parallel to `get` and `list`.
- The `sql_select` action runs one read-only SQL statement (or `SHOW TABLES`) on the query
- engine behind a destination connector. Pass `sql` and `sql_dialect` (and optionally
+ The `sql_select` action runs one read-only SQL statement on the query engine behind a
+ destination connector: a `SELECT`/`WITH` query or the `SHOW TABLES`, `SHOW DATABASES`,
+ or `DESCRIBE TABLE
` macro. Pass `sql` and `sql_dialect` (and optionally
`dry_run`) in `api_args`; `entity_type` is ignored for this action.
The `download` action is deliberately absent even though it reads: it returns a binary
diff --git a/airbyte/cloud/connectors.py b/airbyte/cloud/connectors.py
index e1ae7693f..5dbda6bf0 100644
--- a/airbyte/cloud/connectors.py
+++ b/airbyte/cloud/connectors.py
@@ -461,7 +461,10 @@ def execute_sql_query(
cursor: str | None = None,
dry_run: bool = False,
) -> ExternalApiExecuteResult:
- """Run a read-only SQL `SELECT` (or `SHOW TABLES`) through SQL passthrough.
+ """Run a read-only SQL statement through SQL passthrough.
+
+ Accepted statements are a single `SELECT`/`WITH` query or the `SHOW TABLES`,
+ `SHOW DATABASES`, or `DESCRIBE TABLE ` macro.
`sql_dialect` defaults to the dialect registered for this connector's definition.
`dry_run=True` validates the statement and returns the result columns without
diff --git a/airbyte/mcp/cloud.py b/airbyte/mcp/cloud.py
index 05124c5f2..7dee6b512 100644
--- a/airbyte/mcp/cloud.py
+++ b/airbyte/mcp/cloud.py
@@ -1818,7 +1818,12 @@ def execute_external_sql_query(
],
sql: Annotated[
str,
- Field(description="The read-only SQL statement to run, for example `SHOW TABLES`."),
+ Field(
+ description=(
+ "The read-only SQL statement to run: a `SELECT`/`WITH` query or the "
+ "`SHOW TABLES`, `SHOW DATABASES`, or `DESCRIBE TABLE ` macro."
+ )
+ ),
],
sql_dialect: Annotated[
str | None,
@@ -1869,12 +1874,14 @@ def execute_external_sql_query(
Only SQL-passthrough destinations (Snowflake/BigQuery) support this tool.
- Run `SHOW TABLES` first to discover tables; `sql_dialect` defaults to the
- destination's registered dialect. Use `dry_run=True` with
- `SELECT * FROM LIMIT 1` to discover a table's columns.
+ Run `SHOW TABLES` first to discover tables and `SHOW DATABASES` to see the
+ databases the destination is scoped to; `sql_dialect` defaults to the
+ destination's registered dialect. Use `DESCRIBE TABLE ` to return a
+ table's columns without reading rows.
- `SHOW TABLES` is the only non-`SELECT` statement accepted and takes no
- `LIMIT`; add a `LIMIT` to every `SELECT`. On Snowflake prefer unquoted
+ Accepted statements are a single `SELECT`/`WITH` query plus the `SHOW TABLES`,
+ `SHOW DATABASES`, and `DESCRIBE TABLE ` macros. The `SHOW` macros take
+ no `LIMIT`; add a `LIMIT` to every `SELECT`. On Snowflake prefer unquoted
identifiers: double-quoting makes them case-sensitive.
"""
connector = _get_cloud_workspace(ctx, workspace_id).get_connector(connector_id)