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.

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.

view_map renders inline only on hosts that support MCP Apps — 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.

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.