> 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/maps-tools.md).

# Maps tools

Maps tools let your agent create Builder maps from your data, edit them in place, validate them before saving, find existing maps, and render a map inline in the conversation.

<img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FFPyYjwoHP1bcOItL2CBM%2Funknown.png?alt=media&amp;token=d7f79f91-865c-40a2-860b-ba168acad474" alt="" height="392" width="624">

## `create_map`

**Title:** Create Map

**Creates a new Builder map** from a full map definition. The agent runs the complete pipeline — offline validation, SQL-parameter planning, and dataset creation and verification — so the map is ready to open. To change an existing map, the agent uses [`update_map`](#update_map).

| Parameter | Type   | Required | Description                                                                                                                                                                |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bundle`  | object | Yes      | The map definition: datasets (SQL or table sources plus a connection), layers, widgets, basemap, privacy, and optional agent config. Layers link to datasets by reference. |

*Can modify data: creates a new map.*

## `update_map`

**Title:** Update Map

**Changes an existing map.** Applies a partial update, patches a single dataset, or publishes the saved state. Fields you don't mention are preserved.

**Method:** `update` · `update_dataset` · `publish`

| Parameter             | Type                 | Required             | Description                                                           |
| --------------------- | -------------------- | -------------------- | --------------------------------------------------------------------- |
| `id`                  | string               | Yes                  | The map to update.                                                    |
| `bundle`              | object               | For `update`         | A partial bundle; unmentioned fields are kept.                        |
| `datasetsMode`        | `merge` \| `replace` | No                   | `merge` (default) keeps unmentioned datasets; `replace` removes them. |
| `dryRun`              | boolean              | No                   | Preview the change without writing.                                   |
| `datasetId` / `patch` | string / object      | For `update_dataset` | The dataset to patch and the fields to change.                        |

*Can modify data.*

## `validate_map`

**Title:** Validate Map

**Checks a map definition without creating or changing anything.** `validate` runs offline structural and type checks; `verify` additionally dry-runs each dataset's SQL against the warehouse.

**Method:** `validate` · `verify`

| Parameter | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| `bundle`  | object | Yes      | The map bundle to check. |

*Read-only.*

## `read_maps`

**Title:** Browse Maps

**Finds and inspects saved maps.** Lists maps with search and paging, gets one map's full definition, or lists a map's datasets.

**Method:** `list` · `get` · `list_datasets`

| Parameter            | Type    | Required                   | Description                                       |
| -------------------- | ------- | -------------------------- | ------------------------------------------------- |
| `id`                 | string  | For `get`, `list_datasets` | The map to read.                                  |
| `search`             | string  | No                         | Free-text name search (for `list`).               |
| `page` / `page_size` | number  | No                         | Paging for `list` (default 20, max 100 per page). |
| `mine_only`          | boolean | No                         | Only maps you own.                                |

*Read-only.*

## `view_map`

**Title:** View Map

**Renders an interactive map inline in the chat.** Two modes: pass a `@deck.gl/json` spec the agent generates for an ad-hoc visualization, or a `mapId` to open a saved Builder map. The agent composes the spec from your request over any table or SQL query — you don't write it yourself.

| Parameter     | Type   | Required       | Description                                   |
| ------------- | ------ | -------------- | --------------------------------------------- |
| `deckglProps` | object | One of the two | A deck.gl declarative spec for an ad-hoc map. |
| `mapId`       | string | One of the two | The UUID of a saved Builder map you can read. |

*Read-only.*

{% hint style="info" %}
`view_map` renders inline only on hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview#client-support) — Claude.ai, ChatGPT, and Claude Desktop. On other hosts it returns a text confirmation; ask the agent for the map URL and open it in CARTO.
{% endhint %}

### Previewing a saved Builder map

With a `mapId`, `view_map` shows a lightweight, read-only preview of the saved map. It renders the layers with their styling, the basemap, the saved viewport, popups, and the legend. You can pan, zoom, open popups, and turn layers on and off.

Some Builder features are only available in Builder itself. The table below shows how the preview handles them.

| Builder feature                  | In the preview                                                               |
| -------------------------------- | ---------------------------------------------------------------------------- |
| Widgets                          | Widgets are hidden, and the layers show all their data.                      |
| SQL parameters                   | The parameter controls are hidden. Layers use the values saved with the map. |
| Custom markers                   | Custom marker icons appear only in Builder.                                  |
| Google Maps and custom basemaps  | The preview uses the closest CARTO basemap. Positron is the default.         |
| AI Agents                        | The map's agent is available in Builder.                                     |
| Map description and other panels | Only the map title, legend, and zoom controls are shown.                     |

To see the complete map, use the link in the preview header to open it in CARTO.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.