# 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 requried 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 %}