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.

Input properties define the requried parameters. Output sections show the response structure with example values - actual values will vary based on your data.

Group	Tool
Map	add_marker get_map_coordinates get_spatial_filter lds_geocode set_map_center_and_zoom set_map_center_and_zoom_to_layer set_spatial_filter get_active_filters
Layer	add_layer set_layer_style set_layer_visibility remove_layer
Widget	filter_category_widget filter_histogram_widget filter_range_widget get_formula_widget get_category_widget get_histogram_widget get_time_series_widget
Parameter	set_sql_parameter_text set_sql_parameter_date_range set_sql_parameter_numeric set_sql_parameter_numeric_range
Data	add_source remove_source execute_query
Workflows	async_workflows_check_results async_workflows_get_results add_source_from_workflows

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": <boolean> }

Example

"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.

---

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": <number>,
    "longitude": <number>,
    "zoom": <number>
 }

Example

"What coordinates am I currently looking at?"
Agent uses this tool to retrieve  the current map center and zoom level.

---

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": "<string: mask | viewport>",
    "geometry": <GeoJSON Polygon | MultiPolygon>
}

Example

"What's the total revenue for stores in this region?"
Agent uses this to get the current viewport bounds for spatial filtering.

---

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": <number>,
      "longitude": <number>,
      "address": "<string>"
    }
]

Example

"Show me where 123 Main Street, New York is on the map"
Agent this tool to convert the address into coordinates.

---

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": <boolean> }

Example

"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.

---

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": <boolean> }

Example

"Zoom to show all the Stores"
Agent uses this to automatically frame all features in the stores layer. 

---

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": <boolean> }

Example

"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.

---

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": "<string: mask | viewport>",
      "geometry": <GeoJSON Polygon>
    },
    "widgets": [
      {
        "id": "<string>",
        "column": "<string>",
        "type": "<string: category | histogram | range | timeseries>",
        "value": <array>
      }
    ],
    "parameters": [
      {
        "id": "<string>",
        "type": "<string: Category | Numeric | NumericRange | DateRange>",
        "value": <string[] | number | {min?, max?}>
      }
    ]
 }

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": "<string>",
    "type": "<string: point | polygon | line | h3 | quadbin>"
}

Example

"Visualize the results on the map"
Agent uses this tool to add a new layer to the map using an existing source. 

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.

---

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": <boolean> }

Example

"Color the stores by revenue using a green to red gradient"
Agent uses this tool to apply color styling based on the revenue column. 

---

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": <boolean> }

Example

"Hide the competitor locations layer"
Agent uses this tool to set the competitor layer visibility to false. 

---

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": <boolean> }

Example

"Remove the top locations layer" 
Agent uses this tool to remove the specified layer from the map. 

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": <boolean> }

Example

"Show only stores in California and Nevada"
Agent uses this tool to filter the category widget with the selected states.

---

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": <boolean> }

Example

"Filter to show revenue between 100k and 500k"
Agent uses this tool to apply the specified range to the histogram widget.

---

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": <boolean> }

Example

"Show stores with 50 to 200 employees"
Agent uses this tool to filter the data within the specified range. 

---

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

<number | string>

Example

"What's the total revenue shown in the dashboard?"
Agent uses this tool to retrieve the calculated value from the revenue widget. 

---

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": "<string>", "value": <number> }
  ]

Example

"What store types are available in the data?"
Agent uses this tool to retrieve the calculated value from the revenue widget. 

---

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": [<number>],
    "frequencies": [<number>]
}

Example

"Show me the revenue distribution across stores"
Agent uses this tool to retrieve histogram data showing the distribution pattern. 

---

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": [<string>],
    "values": [
      { "name": <number: timestamp in ms>, "value": <number> }
    ]
 }

Example

"What were the sales trends for Q1 2024?"
Agent uses this tool to retrieve time series data for the specified period. 

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": <boolean> }

Example

"Filter the analysis to only premium and standard customer types"
Agent uses this tool to set the customer type parameter with the specified values. 

---

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": <boolean> }

Example

"Analyze data from January to March 2024"
Agent uses this tool to set the date range for the analysis period. 

---

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": <boolean> }

Example

"Set the minimum order value to 1000"
Agent uses this tool to update the numeric threshold parameter. 

---

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": <boolean> }

Example

"Show transactions between $500 and $2000"
Agent uses this tool to set both minimum and maximum values for the range. 

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.

These tools are off by default. You must enable Query source capability to use them. Maps with this capability enabled cannot be made public.

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": "<string>",
    "source": "<string>",
    "label": "<string>",
    "connectionName": "<string>",
    "provider": "<string>",
    "type": "<string: table | tileset | query | raster>",
    "schema": [
      { "name": "<string>", "type": "<string>" }
    ],
    "geoColumn": "<string>"
 }

Example

"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. 

---

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": [<string>],
    "rows": [<array>]
}

Example

"Calculate the average revenue per store in California"
Agent uses this tool to run SQL analysis and return the results conversationally. 

---

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": <boolean> }

Example

"Remove the added source from the map"
Agent uses this tool to clean up the AI-generated data source.

---

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": "<string>",
        "status": "<string: running | completed | failed>",
        "progress": <number>
      }
    ]
 }

Example

Agent uses this tool automatically after workflows async execution to check jobId status. No action is required by user.

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": "<string>",
    "connectionName": "<string>",
    "providerId": "<string>"
}

Example

Agent uses this tool automatically after workflows async execution to get results from executed workflows such as the output qualified table name. 

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": "<string>",
    "source": "<string>",
    "label": "<string>",
    "connectionName": "<string>",
    "provider": "<string>",
    "type": "<string: table | tileset | query | raster>",
    "schema": [
      { "name": "<string>", "type": "<string>" }
    ],
    "geoColumn": "<string>"
 }

Example

"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.