Platform tools

Platform tools help your agent find the right data and the right map before any visualization or analysis happens. They return JSON for the agent to reason over; no inline UI is rendered. Use them to enumerate connections, browse the warehouse hierarchically, search for tables by name, inspect column distributions, and locate saved Builder maps.

Data discovery

list_connections

Description

Lists all available data warehouse connections for the account. Returns connection names, provider types, and IDs.

Example: An agent asked "What data do I have access to?" would call list_connections to get a list:

[
  { "name": "carto_dw", "provider": "bigquery" },
  { "name": "my_snowflake", "provider": "snowflake" }
]

Input properties:

No parameters

Output:

A JSON array of connection objects, each containing the connection name, provider type, and ID.

Response example

{
  "status": 200,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "carto_dw",
      "provider_id": "bigquery",
      "privacy": "shared",
      "carto_dw": true,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-06-20T14:22:00.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "my_snowflake",
      "provider_id": "snowflake",
      "privacy": "shared",
      "carto_dw": false,
      "created_at": "2024-03-10T08:00:00.000Z",
      "updated_at": "2024-03-10T08:00:00.000Z"
    }
  ]
}

Example

"What data do I have access to?"

The agent calls list_connections with no parameters and returns a summary of available connections:

list_connections()

---

list_resources

Description

Browses the contents of a data warehouse connection hierarchically. Returns databases, schemas, tables, and views at the requested level.

The hierarchy varies by provider:

• BigQuery: connection > project > dataset > table/view

• Snowflake: connection > database > schema > table/view

• Databricks: connection > catalog > schema > table/view

• PostgreSQL / Redshift: connection > database > schema > table/view

Call with no fqn to see the top level, then pass an fqn to drill into a specific database or schema. Use maxDepth=2 to expand one level deeper in a single call (e.g., see schemas AND their tables).

Input properties

Parameter	Type	Required	Description
connection_name	string	Yes	Name of the connection (from list_connections).
fqn	string	No	Fully qualified name to browse. Omit for top level. Examples: "my_database", "my_database.my_schema".
maxDepth	number	No	How many levels deep to expand (1=current level only, 2=include children, 3=include grandchildren). Default: 1, max: 3.
maxItems	number	No	Maximum total items to return across all levels. Default: 30, max: 500.

Output

A JSON object with a hierarchical structure of resources at the requested level. Each resource includes its name, fully qualified name, type (database, schema, table, or view), and any children if expanded.

Response example

{
  "status": 200,
  "data": {
    "provider": "bigquery",
    "type": "connection",
    "children": [
      {
        "id": "my_project",
        "name": "my_project",
        "type": "database",
        "children": [
          {
            "id": "my_project.retail_data",
            "name": "retail_data",
            "type": "schema",
            "children": [
              {
                "id": "my_project.retail_data.stores",
                "name": "stores",
                "type": "table"
              },
              {
                "id": "my_project.retail_data.sales_regions",
                "name": "sales_regions",
                "type": "table"
              }
            ],
            "childCount": 2,
            "childrenTruncated": false
          }
        ],
        "childCount": 5,
        "childrenTruncated": true
      }
    ],
    "returnedItems": 8,
    "maxItemsApplied": 30,
    "truncated": false,
    "rootChildrenTruncated": false,
    "totalRootChildren": 1
  }
}

Example

"What tables are in the retail_data dataset?"

The agent first discovered the carto_dw connection via list_connections, then drills into a specific dataset:

// First call: list top-level projects
list_resources({ connection_name: "carto_dw" })

// Second call: drill into a dataset and expand tables
list_resources({
  connection_name: "carto_dw",
  fqn: "my_project.retail_data",
  maxDepth: 2
})

---

search_resources

Description

Searches for tables and views by name across a data warehouse connection. Returns a flat, ranked list of matches (exact match first, then prefix, then contains). Use this instead of list_resources when you know part of the table name but not where it lives.

For faster results, pass a scopeFqn to narrow the search to a specific database or schema. Without a scope, multi-database providers (Snowflake, BigQuery, Databricks) search the first 10 databases/datasets alphabetically. The response includes searchedContainers/totalContainers so you know if the search was partial.

Input properties

Parameter	Type	Required	Description
connection_name	string	Yes	Name of the connection (from list_connections).
query	string	Yes	Search string to match against table/view names (case-insensitive).
type	string	No	Filter results to only "table" or only "view".
limit	number	No	Max results to return (1–100). Default: 20.
scopeFqn	string	No	Narrow search to a specific database, schema, or dataset. Makes the search much faster. Examples: "my_database", "my_database.my_schema".

Output

A JSON object containing a flat array of matching resources. Results are ranked by match quality (exact, then prefix, then contains). The searchedContainers and totalContainers fields indicate whether the search covered all databases/datasets or was partial.

Response example

{
  "status": 200,
  "data": {
    "provider": "bigquery",
    "results": [
      {
        "id": "my_project.retail_data.stores",
        "name": "stores",
        "type": "table",
        "database": "my_project",
        "schema": "retail_data",
        "fqn": "my_project.retail_data.stores",
        "_links": {
          "resources": "/connections/carto_dw/resources/my_project.retail_data.stores"
        }
      },
      {
        "id": "my_project.geo_data.stores_backup",
        "name": "stores_backup",
        "type": "table",
        "database": "my_project",
        "schema": "geo_data",
        "fqn": "my_project.geo_data.stores_backup",
        "_links": {
          "resources": "/connections/carto_dw/resources/my_project.geo_data.stores_backup"
        }
      }
    ],
    "returnedResults": 2,
    "truncated": false,
    "query": "stores",
    "scopeFqn": "my_project.retail_data",
    "searchedContainers": 1,
    "totalContainers": 1
  }
}

Example

"Do we have any table with store locations?"

The agent searches across the connection for tables matching "stores":

search_resources({
  connection_name: "carto_dw",
  query: "stores",
  scopeFqn: "my_project.retail_data"
})

---

describe

Description

Inspects a table or a SQL query — returns the column schema (and geometry column, geometry type, row count when available) or, when a column is provided, distribution statistics for that column. One tool, four modes:

Mode	Required parameters	Returns
Table schema	connection_name, table_fqn	Columns + geomField / geometryType / rowCount
Query schema	connection_name, query	Columns + geomField / geometryType / rowCount
Column stats on table	connection_name, table_fqn, column	Stats for that column
Column stats on query	connection_name, query, column	Stats for that column

Use schema mode to discover what columns a table or query has before styling. Use stats mode in declarative view_map flows to drive data-aware styling:

• For colorBins: use the returned quantiles to derive thresholds (e.g., quartiles → 4-bucket scale).

• For colorContinuous: use min and max for the domain.

• For colorCategories: use the returned categories.

Query mode lets the agent inspect the columns of an arbitrary SQL query without running it against the warehouse. Pass the same SQL string that goes in the source's sqlQuery so schema/stats are computed over the same rows the map renders.

describe only covers tables, views, and SQL queries. Tilesets and rasters are pre-baked formats whose schema isn't exposed by this endpoint — fall back to list_resources, which also surfaces per-band raster metadata (colorinterp, colortable, nodata, minresolution).

Input properties

Parameter	Type	Required	Description
connection_name	string	Yes	Name of the connection (from list_connections).
table_fqn	string	No*	Fully qualified table name (e.g., "db.schema.table"). Provide this OR query, not both.
query	string	No*	SQL query to inspect. Provide this OR table_fqn, not both.
query_parameters	object	No	Parameter bindings for query. Only valid when query is set.
column	string	No	Column to compute statistics for. When present, switches from schema mode to stats mode.
max_categories	number	No	Stats mode only. Max categories returned for string/boolean columns. Default 20.
categories_order_by	string	No	Stats mode only. Order categories by: frequency_asc | frequency_desc | alphabetical_asc | alphabetical_desc.
spatial_data_type	string	No	Stats mode only, for geometry columns: h3 | h3int | quadbin | geo.

* Exactly one of table_fqn or query is required.

Output

Schema mode:

{
  "source":       { "type": "table", "fqn": "..." },     // or { "type": "query", "sql": "..." }
  "schema":       [{ "name": "pop_max", "type": "Number" }, ...],
  "geomField":    "geom",          // optional — present when the source has a geometry column
  "geometryType": "Point",         // optional — "Point" | "LineString" | "Polygon"
  "rowCount":     12345            // optional
}

Stats mode (discriminated by type):

• Number → { type, min, max, avg, sum, quantiles: { 3: [...], 4: [...], …, 20: [...] } } — quantiles[N] is an array of N+1 numbers [min, t1, t2, …, t(N-1), max].

• String / Boolean → { type, categories: [{ category, frequency }, …] }.

• Timestamp → { type, min, max } as ISO 8601 strings (or null when empty).

• Geometry → { type, extent: { xmin, ymin, xmax, ymax } | null }.

Examples

"What columns does this table have?"

describe({
  connection_name: "carto_dw",
  table_fqn: "carto-demo-data.demo_tables.populated_places"
})
// → { source, schema: [...], geomField: "geom", geometryType: "Point", rowCount: 7322 }

"Color the population layer by quartiles"

describe({
  connection_name: "carto_dw",
  table_fqn: "carto-demo-data.demo_tables.populated_places",
  column: "pop_max"
})
// → { type: "Number", min: 0, max: 30000000, quantiles: { 4: [0, 5000, 50000, 250000, 30000000] } }

// Drop the first and last (natural extremes); use the inner three as colorBins domain.

"What columns does this SQL query produce?"

describe({
  connection_name: "carto_dw",
  query: "SELECT name, COUNT(*) AS n FROM carto-demo-data.demo_tables.populated_places GROUP BY name"
})
// → { source: { type: "query", sql: "..." }, schema: [{ name: "name", type: "String" }, { name: "n", type: "Number" }] }

Saved maps

list_maps

Description

Lists the user's saved CARTO Builder maps. Returns paginated entries with id, name, privacy, owner, thumbnail, and timestamps. The returned id is the input for load_builder_map.

Common usage:

• Call without arguments for the most recent maps the user can access (owned + shared with them).

• Use search to filter by name when the user mentions a specific map by title.

• Use mine_only=true when the user explicitly asks for "my maps" (filters out maps shared with them by others).

• Default sort is updated_at desc — most recently edited first. Override with order_by / order_direction if needed.

Input properties

Parameter	Type	Required	Description
search	string	No	Free-text search by map name (case-insensitive substring match).
page	number	No	1-indexed page number. Default 1.
page_size	number	No	Items per page. Default 20, max 100.
order_by	string	No	Sort field: title | created_at | updated_at | views | demo. Default updated_at.
order_direction	string	No	asc or desc. Default desc.
privacy	string	No	Filter by privacy: private | shared | public.
mine_only	boolean	No	When true, only maps owned by the calling user. Default false (includes maps shared with them).

Output

A JSON object with a paginated array of map entries. Each entry includes the map id, name, privacy, owner, thumbnail URL, and timestamps.

Example

"What are my recent maps?"

list_maps({ mine_only: true, page_size: 5 })