# AI Tools Reference
This reference provides detailed information about all available Core Tools that AI Agents can use to interact with your geospatial data. Each tool entry includes a description, required parameters, and practical example showing how natural language requests translate into tool usage.
{% hint style="info" %}
Input properties define the required parameters. Output sections show the response structure with example values - actual values will vary based on your data.
{% endhint %}
### Map Tools
These tools let the Agent control the map position as well as extract the area of interest.
#### **add\_marker**
**Description**
Add marker(s) on the map to display specific point locations.
**Input properties:**
* markers (array): Array of markers. Each marker must include:
* latitude (number): Latitude of the marker.
* longitude (string): Longitude of the marker.
* label (string): Human-readable label for the marker.
**Output:** Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Show me data around 31 Ratcliffe Court, Sweetman Place"
The agent geocodes the address and places a marker on the map to highlight the location.
```
{% endcode %}
***
#### **get\_map\_coordinates**
**Description**
Retrieve the current map view coordinates and zoom level.
**Input properties:**
* None required
**Output:** Returns the map center coordinates (latitude, longitude) and the current zoom level.
Response structure
```
{
"latitude": ,
"longitude": ,
"zoom":
}
```
**Example**
{% code overflow="wrap" %}
```
"What coordinates am I currently looking at?"
Agent uses this tool to retrieve the current map center and zoom level.
```
{% endcode %}
***
#### **get\_spatial\_filter**
**Description**
Get current area of interest (viewport or drawn polygon via Feature selection tool).
**Input properties:**
* None required
**Output**: Returns the spatial filter type ('mask' for user drawn polygon, 'viewport' for current map bounds) and its GeoJSON geometry.
Response structure:
```
{
"type": "",
"geometry":
}
```
**Example**
{% code overflow="wrap" %}
```
"What's the total revenue for stores in this region?"
Agent uses this to get the current viewport bounds for spatial filtering.
```
{% endcode %}
***
#### **lds\_geocode**
**Description**
Convert address to coordinates.
**Input properties**
* **address** (string): Input address to geocode.
* **country\_code** (string, optional): ISO 3166-1 alpha-2 country code (e.g., US, ES).
* **limit** (integer, optional): Maximum number of results to return.
**Output:** Returns an array of matching locations with coordinates and formatted address.
Response structure
```
[
{
"latitude": ,
"longitude": ,
"address": ""
}
]
```
**Example**
{% code overflow="wrap" %}
```
"Show me where 123 Main Street, New York is on the map"
Agent this tool to convert the address into coordinates.
```
{% endcode %}
***
#### **set\_map\_center\_and\_zoom**
**Description**
Center the map at specific coordinates with a defined zoom level.
**Input properties:**
* **center** (array): Latitude and longitude coordinates \[lat, lon].
* **zoom** (number): Map zoom level as defined by Google Maps.
**Output:** Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Center the map to 43.6532, -79.3832 at zoom level 12"
Agent uses this tool to reposition the map view to the specified location.
```
{% endcode %}
***
#### set\_map\_center\_and\_zoom\_to\_layer
**Description**
Zoom the map view to a specific layer extent.
**Input properties:**
* **layerId** (string): ID of the layer to frame in the viewport.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Zoom to show all the Stores"
Agent uses this to automatically frame all features in the stores layer.
```
{% endcode %}
***
#### set\_spatial\_filter
**Description**
Set, replace, or remove a spatial filter to focus analysis on a specific geographic area. When a spatial filter is active, all map viewport widgets and layers update to show only data within that region.
**Input properties:**
* geometry (object): Valid and simple GeoJSON polygon geometry to define the spatial filter. Pass null to remove the current filter.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Find the total number of incidents in northwest Canada?"
The agent creates a polygon geometry covering northwest Canada and applies it as a spatial filter to focus the analysis on that region.
```
{% endcode %}
***
#### **get\_active\_filters**
**Description**
Visualize source data as new AI-generated layer on the map. It can generate new layers from existing sources or if query sources capability is available, it can also generate layers from AI-generated sources.
**Input properties:**
* None required
**Output**: Returns an object containing three filter collections: active SQL Parameters, widget filters and the current spatial filter (mask or viewport).
Response structure
```
{
"spatialFilter": {
"type": "",
"geometry":
},
"widgets": [
{
"id": "",
"column": "",
"type": "",
"value":
}
],
"parameters": [
{
"id": "",
"type": "",
"value":
}
]
}
```
**Example**
"What filters are currently active on this map"
Agent uses this tool to retrieve all active filters, returning details about spatial masks, viewport, widget selections, and parameter values currently applied.
***
### Layer Tools
These tools let the Agent add, style and display layers on the map.
#### **add\_layer**
**Description**
Visualize source data as new AI-generated layer on the map. It can generate new layers from existing sources or if query sources capability is available, it can also generate layers from AI-generated sources.
**Input properties:**
* **datasetId** (string): The ID of the dataset to visualize.
* **label** (string): Human-readable name for the layer.
* **hooverColumns** (array, optional): Column names to show on hover (max 5).
* **hooverColumnsAggregation** (object, optional): Aggregation methods for hover columns.
**Output**: Returns the created layer's ID and geometry type.
Response structure
```
{
"layerId": "",
"type": ""
}
```
**Example**
"Visualize the results on the map"
Agent uses this tool to add a new layer to the map using an existing source.
{% hint style="info" %}
AI-generated layers are temporal to the conversation. Once the conversation is deleted or the page is refreshed, AI-generated layers are removed.
If "Query sources" capability is enabled, Agent can generated a layer from an AI-generated source rather than existing source.
{% endhint %}
***
#### **set\_layer\_style**
**Description**
Style AI-generated layers.
**Input properties:**
* **layerId** (string): The ID of the layer to style.
* **opacity** (number, optional): Layer transparency (0.0 to 1.0)
* **fillColor** (string, optional): Hex color for fill (e.g. '`#FF0000`')
* **fillColorColumn** (string, optional): Custom color palette.
* **radius** (integer, optional): Point size in pixels.
* **radiusColumn** (string, optional): Column to determine point sizes.
* **outlineColor** (string, optional): Border color
* **outlineWidth** (integer, optional): Border width in pixels.
Output: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Color the stores by revenue using a green to red gradient"
Agent uses this tool to apply color styling based on the revenue column.
```
{% endcode %}
***
#### **set\_layer\_visibility**
**Description**
Control layer visibility on the map.
**Input properties:**
* **layers** (array): Array of objects with:
* **layerId** (string): The layer to control
* **visibility** (boolean): Show (true) or hide (false)
* **mapIndex** (number, optional): For split maps (0=left, 1=right)
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Hide the competitor locations layer"
Agent uses this tool to set the competitor layer visibility to false.
```
{% endcode %}
***
#### **remove\_layer**
**Description**
Removes a temporal AI-generated layer.
**Input properties:**
* **layerId** (string): The ID of the layer to be remove.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Remove the top locations layer"
Agent uses this tool to remove the specified layer from the map.
```
{% endcode %}
### Widget Tools
These tools let the Agent extract widget values and use them to filter data sources on the map.
#### **filter\_category\_widget**
**Description**
Filter by categories (e.g., type, region).
Input properties:
* **widgetId** (string): The ID of the widget to filter.
* **categories** (array): Selected category values to filter by.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Show only stores in California and Nevada"
Agent uses this tool to filter the category widget with the selected states.
```
{% endcode %}
***
#### **filter\_histogram\_widget**
**Description**
Filter by distribution ranges.
**Input properties:**
* **widgetId** (string): The ID of the widget to filter.
* **intervals** (array): Array of \[min, max] ranges.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Filter to show revenue between 100k and 500k"
Agent uses this tool to apply the specified range to the histogram widget.
```
{% endcode %}
***
#### **filter\_range\_widget**
**Description**\
Filter by min/max values.
**Input properties:**
* **widgetId** (string): The ID of the widget to filter.
* **range** (array): \[min, max] values.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Show stores with 50 to 200 employees"
Agent uses this tool to filter the data within the specified range.
```
{% endcode %}
***
#### **get\_formula\_widget**
**Description**\
Retrieve calculated metrics (KPIs).
**Input properties:**
* **widgetId** (string): The ID of the widget to read.
Output: returns the widget's calculated value.
Response structure
```
```
**Example**
{% code overflow="wrap" %}
```
"What's the total revenue shown in the dashboard?"
Agent uses this tool to retrieve the calculated value from the revenue widget.
```
{% endcode %}
***
#### **get\_category\_widget**
**Description**\
Get category breakdowns.
**Input properties:**
* **widgetId** (string): The ID of the widget to read.
**Output:** Returns an array of category names and their values (up to 5,000 items).
Response structure
```
[
{ "name": "", "value": }
]
```
**Example**
{% code overflow="wrap" %}
```
"What store types are available in the data?"
Agent uses this tool to retrieve the calculated value from the revenue widget.
```
{% endcode %}
***
#### **get\_histogram\_widget**
**Description**\
Get distribution data.
**Input properties:**
* **widgetId** (string): The ID of the widget to read.
Output: Returns histogram bins (value boundaries) and frequencies (count per bin).
Response structure
```
{
"bins": [],
"frequencies": []
}
```
**Example**
{% code overflow="wrap" %}
```
"Show me the revenue distribution across stores"
Agent uses this tool to retrieve histogram data showing the distribution pattern.
```
{% endcode %}
***
#### **get\_time\_series\_widget**
**Description**\
Get temporal patterns.
**Input properties:**
* **widgetId** (string): The ID of the widget to read.
* **timeRange** (array): \[start, end] timestamps in seconds since epoch.
**Output**: Returns time series categories and values array with timestamps (up to 5,000 values).
Response structure
```
{
"categories": [],
"values": [
{ "name": , "value": }
]
}
```
**Example**
{% code overflow="wrap" %}
```
"What were the sales trends for Q1 2024?"
Agent uses this tool to retrieve time series data for the specified period.
```
{% endcode %}
### Parameter Tools
These tools let the Agent update parameter values on the map.
#### **set\_sql\_parameter\_text**
Update text parameter values.
**Input properties:**
* **parameterId** (string): ID of the parameter to update.
* **values** (array): Array of text values to set.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Filter the analysis to only premium and standard customer types"
Agent uses this tool to set the customer type parameter with the specified values.
```
{% endcode %}
***
#### **set\_sql\_parameter\_date\_range**
**Description**\
Update date parameter values.
**Input properties:**
* **parameterId** (string): ID of the parameter to update.
* **min** (string, optional): Start date in ISO-8601 format (YYYY-MM-DD).
* **max** (string, optional): End date in ISO-8601 format (YYYY-MM-DD).
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Analyze data from January to March 2024"
Agent uses this tool to set the date range for the analysis period.
```
{% endcode %}
***
#### **set\_sql\_parameter\_numeric**
**Description**\
Update numeric parameter value.
**Input properties:**
* **parameterId** (string): ID of the parameter to update.
* **value** (number): Numeric value to set.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Set the minimum order value to 1000"
Agent uses this tool to update the numeric threshold parameter.
```
{% endcode %}
***
#### **set\_sql\_parameter\_numeric\_range**
**Description**\
Update numeric range parameter values.
**Input properties:**
* **parameterId** (string): ID of the parameter to update.
* **min** (number, optional): Minimum value.
* **max** (number, optional): Maximum value.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Show transactions between $500 and $2000"
Agent uses this tool to set both minimum and maximum values for the range.
```
{% endcode %}
### Data Tools
These tools let the Agent extract insights by generated SQL that is executed against your map connections. These can be used to provide insights in a conversational manner as well as for adding sources that then can be used to add AI-generated layers on the map.
{% hint style="warning" %}
These tools are off by default. You must enable Query source capability to use them. Maps with this capability enabled cannot be made public.
{% endhint %}
#### **add\_source**
**Description**\
Load data from tables or queries that can be used.
**Input properties:**
* **type** (string): Type of source (table, tileset, query, raster).
* **source** (string): Table name or SQL query.
* **connection** (string): Database connection name.
* **provider** (string): Database provider type.
* **geoColumn** (string, optional): Column containing geometry/geography.
**Output**: Returns the created dataset's metadata including ID, schema, and connection details.
Response structure
```
{
"id": "",
"source": "",
"label": "",
"connectionName": "",
"provider": "",
"type": "",
"schema": [
{ "name": "", "type": "" }
],
"geoColumn": ""
}
```
**Example**
{% code overflow="wrap" %}
```
"Display the top 5 locations to open a new store"
Agent uses this tool to add an AI-generated source that can be used to add an AI-generated layer to render insights on the mpa.
```
{% endcode %}
***
#### execute\_query
**Description**\
Run SQL analysis (sync mode - immediate results).
**Input properties:**
* **connection\_name** (string): Connection name to execute against.
* **sql** (string): The SQL query to execute (SELECT statements only).
**Output**: Returns query results with column names and raw data.
Response structure
```
{
"columns": [],
"rows": []
}
```
Example
{% code overflow="wrap" %}
```
"Calculate the average revenue per store in California"
Agent uses this tool to run SQL analysis and return the results conversationally.
```
{% endcode %}
***
#### remove\_source
**Description**\
Remove AI-generated data sources.
**Input properties:**
* **datasetId** (string): The ID of the dataset to remove.
**Output**: Returns success confirmation.
Response structure
```
{ "success": }
```
**Example**
{% code overflow="wrap" %}
```
"Remove the added source from the map"
Agent uses this tool to clean up the AI-generated data source.
```
{% endcode %}
***
### Insights
These tools let the Agent generate insights such as charts directly in the conversation from analyzing data.
#### generate\_chart
**Description**\
Render interactive [Vega-Lite](https://vega.github.io/vega-lite/) charts in the conversation. Use this to visualize query results when a chart communicates insights more effectively than text or tables.
**Input properties:**
* **spec** (object): A valid Vega-Lite v6 specification object. See the [Vega-Lite documentation](https://vega.github.io/vega-lite/docs/) for supported chart types and [example gallery](https://vega.github.io/vega-lite/examples/) for reference specifications.
**Output**: Returns success confirmation when chart renders, or error details if validation or rendering fails
Response structure
```
// Success
"Chart rendered successfully"
// Error
{
"error": ""
}
```
Example
{% code overflow="wrap" %}
```
"Show me a bar chart of revenue by region"
Agent queries the data, constructs a Vega-Lite specification, and renders an interactive chart in the conversation.
```
{% endcode %}
***
### Workflows Output Tools
If a Workflows MCP Tool is provided to your Agent, your Agent automatically gets access to the following tools:
#### async\_workflows\_check\_results
**Description**\
Check job status from Asynchronous Workflows execution. This is automatically invoked after async workflows execution.
**Input properties:**
* **jobId** (string): The job Id to check status for.
**Output**: Returns the status of each job (running, completed or failed).
Response structure
```
{
"jobs": [
{
"jobId": "",
"status": "",
"progress":
}
]
}
```
**Example**
{% code overflow="wrap" %}
```
Agent uses this tool automatically after workflows async execution to check jobId status. No action is required by user.
```
{% endcode %}
#### async\_workflows\_get\_results
**Description**\
Get the results from Asynchronous Workflows execution.
**Input properties:**
* **jobId** (string): The ID of the dataset to remove.
* **connection** (string): Connection name for the output table.
Output: Returns the workflow output table details.
Response structure
```
{
"workflowOutputTableName": "",
"connectionName": "",
"providerId": ""
}
```
**Example**
{% code overflow="wrap" %}
```
Agent uses this tool automatically after workflows async execution to get results from executed workflows such as the output qualified table name.
```
{% endcode %}
#### add\_source\_from\_workflows
**Description**\
After workflows execution, this tool allows adding a new source on the map using the fully-qualified table result of Workflows, either Sync or Async modes.
**Input properties:**
* **source** (string): The fully-qualified table name from Workflows output.
* **connection** (string): Connection name for the output table.
**Output**: Returns the created dataset's metadata ID, schema and connection details.
Response structure
```
{
"id": "",
"source": "",
"label": "",
"connectionName": "",
"provider": "",
"type": "",
"schema": [
{ "name": "", "type": "" }
],
"geoColumn": ""
}
```
**Example**
{% code overflow="wrap" %}
```
"Obtain 5 top locations to open new store"
Agent executes Workflows MCP Tool to identify top 5 locations, after obtaining the results, it can use output table name to add a new source.
```
{% endcode %}
---
# Agent Instructions: 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:
```
GET https://docs.carto.com/carto-user-manual/ai-agents/ai-tools-reference.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.