Analytics tools

Datasets, charts, dashboards, and running SQL / NL→SQL queries.

24 tools. Each is callable over MCP with a Bearer agx_ key that holds the required scope. The catalog is public (tools/list isn't scope-filtered); the scope below is enforced when the tool is called (tools/call) — a key without it is refused (default-deny).

get_chart

Get one chart's config. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
chart_id	string	✓

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_chart",
    "arguments": {
      "chart_id": "\u2026"
    }
  }
}

get_dashboard

Get one dashboard + the charts it contains. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
dashboard_id	string	✓

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_dashboard",
    "arguments": {
      "dashboard_id": "\u2026"
    }
  }
}

get_dashboard_with_data

Get a dashboard AND every chart's plotted data in one call — the batch loader. Optional dashboard-wide date filter: date_preset (today/yesterday/last_7_days/last_30_days/this_month/this_quarter/this_year/last_month/…) OR date_start+date_end (YYYY-MM-DD). The filter applies per chart via its date-column mapping. Each chart's data is under _chart_data (with a per-chart error if that one failed). Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
dashboard_id	string	✓
date_preset	string		e.g. last_30_days, this_month (omit for all-time).
date_start	string		YYYY-MM-DD (custom range; needs date_end).
date_end	string		YYYY-MM-DD (custom range; needs date_start).
fresh	boolean		Bypass the analytics cache.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_dashboard_with_data",
    "arguments": {
      "dashboard_id": "\u2026"
    }
  }
}

get_data_model

The org's grounded analysis data model: tables + columns/types, the REAL enum values per column, custom-field sql_refs (e.g. (custom_fields->>'budget')::numeric), the join graph, and deal/lifecycle stages. Read this BEFORE writing SQL for run_query so you use real column/value/stage names instead of guessing. Org database only — for external DBs use list_data_sources + describe_analytics_table. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
force_refresh	boolean		Rebuild the cached manifest (after a schema change).

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_data_model",
    "arguments": {}
  }
}

get_dataset

Get one dataset with its SQL + column manifest. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
dataset_id	string	✓

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_dataset",
    "arguments": {
      "dataset_id": "\u2026"
    }
  }
}

create_chart

Create a chart on a dataset. chart_type ∈ bar/line/pie/area/table/stacked_bar/horizontal_bar/donut/scatter/kpi/… chart_config holds dimensions[], metrics[], breakdownBy, filters[], topN. Requires analytics:write.

Required scope: analytics:write

Input

Parameter	Type	Required	Description
name	string	✓
chart_type	string	✓
query_id	string		The dataset id this chart visualizes (required unless chart_type='text').
chart_config	object
is_shared	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_chart",
    "arguments": {
      "name": "\u2026",
      "chart_type": "\u2026"
    }
  }
}

create_dashboard

Create a dashboard composing existing charts (by chart_ids). Optional layout (grid positions). Requires analytics:write.

Required scope: analytics:write

Input

Parameter	Type	Required	Description
name	string	✓
description	string
chart_ids	array<string>		Chart ids to include.
layout	object
is_shared	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_dashboard",
    "arguments": {
      "name": "\u2026"
    }
  }
}

create_dataset

Save a reusable dataset from a read-only SQL SELECT. The column manifest is auto-extracted. Charts are built on datasets. Requires analytics:write.

Required scope: analytics:write

Input

Parameter	Type	Required	Description
name	string	✓
sql	string	✓	A read-only SELECT.
description	string
integration_id	string		Build the dataset on an external database (from list_data_sources). Omit for the org DB.
is_shared	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_dataset",
    "arguments": {
      "name": "\u2026",
      "sql": "\u2026"
    }
  }
}

update_chart

Update a chart's name/type/config/dataset/sharing. Requires analytics:write.

Required scope: analytics:write

Input

Parameter	Type	Required	Description
chart_id	string	✓
name	string
chart_type	string
query_id	string
chart_config	object
is_shared	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_chart",
    "arguments": {
      "chart_id": "\u2026"
    }
  }
}

update_dashboard

Update a dashboard's name/description/layout/chart_ids/sharing. Requires analytics:write.

Required scope: analytics:write

Input

Parameter	Type	Required	Description
dashboard_id	string	✓
name	string
description	string
chart_ids	array<string>
layout	object
is_shared	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_dashboard",
    "arguments": {
      "dashboard_id": "\u2026"
    }
  }
}

update_dataset

Update a dataset's name/description/sql/sharing (changing sql re-extracts columns). Requires analytics:write.

Required scope: analytics:write

Input

Parameter	Type	Required	Description
dataset_id	string	✓
name	string
description	string
sql	string
integration_id	string		Move the dataset onto an external database (or 'current_org' for the org DB).
is_shared	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_dataset",
    "arguments": {
      "dataset_id": "\u2026"
    }
  }
}

delete_chart

Delete a chart. Requires analytics:write.

Required scope: analytics:write

Input

Parameter	Type	Required	Description
chart_id	string	✓

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_chart",
    "arguments": {
      "chart_id": "\u2026"
    }
  }
}

delete_dashboard

Delete a dashboard (its charts are not deleted). Requires analytics:write.

Required scope: analytics:write

Input

Parameter	Type	Required	Description
dashboard_id	string	✓

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_dashboard",
    "arguments": {
      "dashboard_id": "\u2026"
    }
  }
}

delete_dataset

Delete a dataset (its dependent charts cascade). Requires analytics:write.

Required scope: analytics:write

Input

Parameter	Type	Required	Description
dataset_id	string	✓

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_dataset",
    "arguments": {
      "dataset_id": "\u2026"
    }
  }
}

list_analytics_tables

List the tables available to query for analytics (name + column count). Call describe_analytics_table for a table's columns and row count. Use to discover what you can build a dataset/query from. Pass integration_id (from list_data_sources) to list an external database's tables instead. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
integration_id	string		External database integration. Omit for the org DB.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_analytics_tables",
    "arguments": {}
  }
}

list_charts

List saved charts. Optional dataset_id filters to charts on one dataset. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
dataset_id	string

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_charts",
    "arguments": {}
  }
}

list_dashboards

List saved dashboards. Requires analytics:read.

Required scope: analytics:read

Input

No input parameters.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_dashboards",
    "arguments": {}
  }
}

list_data_sources

List the databases you can analyze: the org database plus every connected external database integration (PostgreSQL/MySQL/…), each with its integration_id. External DBs have no pre-loaded schema — discover it live: list_analytics_tables(integration_id) → describe_analytics_table → preview → run_query. Note generate_sql/get_data_model are org-DB only; for external DBs hand-write SQL from the discovered schema. Requires analytics:read.

Required scope: analytics:read

Input

No input parameters.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_data_sources",
    "arguments": {}
  }
}

list_datasets

List saved analytics datasets (saved SQL queries). Requires analytics:read.

Required scope: analytics:read

Input

No input parameters.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_datasets",
    "arguments": {}
  }
}

describe_analytics_table

Get a table's columns + types (including custom fields). Pass integration_id to introspect a table in an external database. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
table_name	string	✓
integration_id	string		External database integration. Omit for the org DB.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_analytics_table",
    "arguments": {
      "table_name": "\u2026"
    }
  }
}

generate_sql

Turn a natural-language question into grounded, validated, read-only SQL — the SAME NL→SQL agent the in-product dataset builder uses (it knows your real schema, enum values, custom-field sql_refs, join graph, and deal/lifecycle stages, and self-corrects against the DB). Prefer this over hand-writing SQL. mode: validate (default, self-corrects + returns sample rows), preview (more rows), generate_only (no DB). Feed the returned sql to run_query or create_dataset. Org database only — for external DBs discover schema via list_data_sources + describe_analytics_table and hand-write SQL. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
question	string	✓	The business question in plain English.
mode	enum(validate, preview, generate_only)

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_sql",
    "arguments": {
      "question": "acme"
    }
  }
}

preview_analytics_table

Preview the first rows of a table. Pass integration_id for a table in an external database. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
table_name	string	✓
integration_id	string		External database integration. Omit for the org DB.
limit	integer

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "preview_analytics_table",
    "arguments": {
      "table_name": "\u2026"
    }
  }
}

run_chart

Get server-side aggregated data for a chart (GROUP BY dimensions + metrics, breakdownBy, filters, topN). Provide chart_id (saved chart) OR (dataset_id and/or sql) plus a chart_config. Returns the plotted rows. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
chart_id	string		A saved chart (uses its dataset + config).
dataset_id	string		Aggregate a saved dataset.
sql	string		Ad-hoc base SELECT to aggregate.
integration_id	string		With ad-hoc sql: aggregate against an external database. Saved charts/datasets carry their own.
chart_config	object		dimensions[], metrics[], breakdownBy, filters[], topN, sortByMetric.
limit	integer
fresh	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run_chart",
    "arguments": {}
  }
}

run_query

Run a read-only SQL query and get rows back — the way to ANALYZE data. Provide sql (ad-hoc SELECT), dataset_id (a saved dataset), OR question (plain English — the NL→SQL agent grounds + validates it, then it's executed; the response includes the generated_sql). Only SELECTs are allowed (DROP/DELETE/etc. blocked); org-scoped. Paginated via limit/offset. Tip: call get_data_model first to learn real columns/values. Requires analytics:read.

Required scope: analytics:read

Input

Parameter	Type	Required	Description
sql	string		A read-only SELECT (ad-hoc).
dataset_id	string		Run a saved dataset.
question	string		Natural-language question; auto-converted to SQL and run (org database only).
integration_id	string		Run against a connected external database (from list_data_sources). Omit for the org DB.
limit	integer
offset	integer
fresh	boolean		Bypass cache.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run_query",
    "arguments": {}
  }
}