> 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.
## `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 %}
{% hint style="warning" %}
**The `mapId` mode is a lightweight, read-only preview — not the full Builder experience.** It renders the saved map's layers, basemap, viewport, popups, and legend. Many Builder elements — widgets, SQL parameters, AI Agents, and other interactive panels — are not rendered, and when the saved map uses a non-CARTO basemap (Google Photorealistic 3D Tiles, a custom Mapbox style, and so on) the renderer falls back to a CARTO basemap. Open the map in CARTO Builder for the full experience.
{% endhint %}
---
# 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/maps-tools.md?ask=&goal=
```
`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.