> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/mcp-server/tools-reference/data-tools.md).

# Data tools

Data tools cover everything between your agent and the data: exploring connections and tables, running SQL, geocoding and routing, importing and exporting, moving data between warehouses, working with named sources, and enriching from the Data Observatory.

## Explore and query

### `explore_data`

**Title:** Explore Data

**Explores connections and their data, read-only.** Lists connections, inspects one, browses databases/schemas/tables, searches tables by name, and describes a table's or query's columns with per-column statistics.

**Method:** `list_connections` · `get_connection` · `list_resources` · `search` · `describe`

{% hint style="info" %}
On a [token session](/carto-for-agents/mcp-server/connecting-with-api-tokens.md#what-a-token-unlocks), `list_connections`, `list_resources`, and `search` work with just the **MCP Server** scope; `describe` additionally needs the **Maps** API, and `get_connection` isn't offered — use OAuth for the full method set.
{% endhint %}

| Parameter         | Type   | Required                                   | Description                                                     |
| ----------------- | ------ | ------------------------------------------ | --------------------------------------------------------------- |
| `connection_name` | string | For `list_resources`, `search`, `describe` | The connection to work in.                                      |
| `fqn`             | string | No                                         | A fully-qualified name to browse (for `list_resources`).        |
| `query`           | string | For `search`; optional for `describe`      | The search string, or the SQL query to describe.                |
| `table_fqn`       | string | For `describe`                             | The table to describe (alternative to `query`).                 |
| `column`          | string | No                                         | Return per-column stats instead of the schema (for `describe`). |

*Read-only.*

### `execute_query`

**Title:** Execute SQL Query

**Runs a SQL query synchronously and returns rows.** Best for quick `SELECT`s (about a one-minute timeout). For longer queries or `DDL`/`DML`, the agent uses [`execute_async_query`](#execute_async_query).

| Parameter         | Type   | Required | Description                           |
| ----------------- | ------ | -------- | ------------------------------------- |
| `connection_name` | string | Yes      | The connection to run against.        |
| `sql`             | string | Yes      | The SQL to execute.                   |
| `queryParameters` | any    | No       | Named or positional query parameters. |

*Can modify data: runs arbitrary SQL.*

### `execute_async_query`

**Title:** Execute Async SQL Query

**Runs SQL too slow or large for `execute_query`, or that changes data.** Submits a job, reports status, and cancels.

**Method:** `submit` · `status` · `cancel`

| Parameter    | Type   | Required               | Description                    |
| ------------ | ------ | ---------------------- | ------------------------------ |
| `connection` | string | Yes                    | The connection to run against. |
| `body`       | object | For `submit`           | The query and any parameters.  |
| `jobId`      | string | For `status`, `cancel` | The job to check or cancel.    |

*Can modify data.*

## Move data

Each of these submits a job and tracks it to completion via a `submit` / `status` method.

### `import_data`

**Title:** Import Data

**Loads a file into the warehouse from a URL**, then tracks the job. `body` carries the connection, source URL, destination, and options. For the supported formats and the size limit, see:

CARTO supports importing **CSV**, **GeoJSON**, **GeoPackage**, **KML**, **KMZ**, **TAB**, **Shapefiles** (in a `.zip` package), and [**GeoParquet**](https://geoparquet.org/) files. These formats can be imported into any connected data warehouse.

**GeoTIFF** raster files are also supported when importing into **BigQuery**, **Snowflake**, and **Databricks** connections. The resulting table follows the [**Raquet**](https://github.com/CartoDB/raquet) specification.

The size limit for file imports is **5 GB** for all formats.

### `export_data`

**Title:** Export Data

**Exports a table or query result to a downloadable file** (GeoParquet, GeoJSON, Shapefile, GeoPackage, CSV, and more). `body` carries the connection, source (table or SQL), and format.

### `transfer_data`

**Title:** Transfer Data

**Copies a table from one connection to another**, with optional reprojection. `body` carries the source and destination connections and tables.

*All three can modify data: they write to the warehouse or produce exports.*

## Location Data Services

These call CARTO's Location Data Services, and are read-only. Each takes an `operation` that includes a `capabilities` value to discover provider support.

### `geocode`

**Title:** Geocode

**Geocodes addresses to coordinates, or reverse-geocodes coordinates to addresses.** `operation`: `geocode` · `reverse` · `capabilities`. Geocoding takes an `addresses` array (batched in one call); reverse takes `lat`/`lon`.

### `route`

**Title:** Compute Route

**Computes a route** between an origin and destination with optional waypoints, returning geometry plus time and distance. `operation`: `route` · `capabilities`. Takes `origin`, `destination`, and travel `mode`.

### `calculate_isolines`

**Title:** Calculate Isolines

**Computes an isoline** (catchment area) around an origin. `operation`: `isolines` · `capabilities`. Takes `origin`, `mode`, `range`, and `range_type` (`time` or `distance`).

### `calculate_od_matrix`

**Title:** Calculate OD Matrix

**Computes an origin-destination time/distance matrix.** `operation`: `od_matrix` · `capabilities`. Takes `origins` and `destinations` arrays of `[lon, lat]` points.

*All four are read-only.*

## Named sources and Data Observatory

### `manage_named_sources`

**Title:** Manage Named Sources

**Lists, inspects, creates, and updates named sources** — reusable SQL or table references under a stable name. To remove one, the agent uses [`delete`](/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#delete).

**Method:** `list` · `get` · `create` · `update`

| Parameter | Type   | Required                      | Description                                       |
| --------- | ------ | ----------------------------- | ------------------------------------------------- |
| `name`    | string | For `get`, `create`, `update` | The named source's name.                          |
| `source`  | string | For `create`, `update`        | A SQL query or a fully-qualified table reference. |

*Can modify data.*

### `search_data_observatory`

**Title:** Search Data Observatory

**Searches and browses the CARTO Data Observatory catalog** of public and premium datasets.

**Method:** `list_datasets` · `list_filters` · `search_variables` · `get_dataset` · `sample`

| Parameter    | Type   | Required                    | Description                                     |
| ------------ | ------ | --------------------------- | ----------------------------------------------- |
| `searchText` | string | No                          | Free-text catalog search (for `list_datasets`). |
| `id`         | string | For `get_dataset`, `sample` | The dataset to inspect or sample.               |

*Read-only.*

### `manage_data_observatory_subscriptions`

**Title:** Manage Data Observatory Subscriptions

**Lists your Data Observatory subscriptions, subscribes to a dataset, or unsubscribes.**

**Method:** `list` · `subscribe` · `unsubscribe`

*Can modify data: subscribe and unsubscribe change your subscriptions.*

***

## Connections

### `manage_connections`

**Title:** Manage Connections

**Creates or updates a data warehouse connection** (BigQuery, Snowflake, Databricks, Postgres, Redshift, Oracle). To list or inspect connections, the agent uses [`explore_data`](#explore_data); to remove one, [`delete`](/carto-for-agents/mcp-server/tools-reference/workspace-tools.md#delete).

**Method:** `create` · `update`

| Parameter | Type   | Required     | Description                                                       |
| --------- | ------ | ------------ | ----------------------------------------------------------------- |
| `body`    | object | Yes          | The connection payload — full for `create`, partial for `update`. |
| `id`      | string | For `update` | The connection to update (id or name).                            |

*Can modify data.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-for-agents/mcp-server/tools-reference/data-tools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.