Generate Insight Cards
Generates a set of deterministic, governed insight cards for a published data source. Each card summarizes one numeric measure's period-over-period movement (current month-to-date vs. the prior period), the top contributing dimension members, where the change is most and least pronounced, what is unusual, and suggested follow-ups. A single call fans out across the REST API, the VizQL Data Service, and the Pulse Insights service, issuing one Pulse bundle request per measure.
Registered only when
INSIGHTS_TOOLS_ENABLED``=true.
When the
flag is unset the tool is not registered and is unavailable to callers. Once enabled, it can be
scoped further with INCLUDE_TOOLS /
EXCLUDE_TOOLS (its tool group is
insights, e.g. INCLUDE_TOOLS=insights).
APIs called
This tool talks to the Tableau REST API (Tableau Cloud or Server), the VizQL Data Service
(VDS) API, and the Pulse Insights service. It resolves the data source, reads its field
metadata to pick a time field and measures, then requests one Pulse bundle per measure. The
MCP-layer OAuth gate requires the tableau:mcp:insight:create and tableau:mcp:datasource:read
scopes; the union of Tableau API scopes it uses is tableau:content:read,
tableau:viz_data_service:read, tableau:insights:read, and tableau:mcp_site_settings:read.
- Resolve the data source. Turns the
datasourceargument into a LUID and display name. The bounded-context allow-list is enforced here, before any metadata or Pulse call.GET /api/{version}/sites/{siteId}/datasources?filter=contentUrl:eq:<contentUrl>— resolve a content URL string to a data source. Issued against the Tableau REST API; requires thetableau:content:readOAuth scope. Query Data SourcesGET /api/{version}/sites/{siteId}/datasources/{datasourceId}— look up the display name whendatasourceis given as{ luid }. Issued against the Tableau REST API; requires thetableau:content:readOAuth scope. Query Data Source
- Read the data source's field metadata. Enumerates fields and their data types to auto-select
the time field, measures, and dimensions, and to validate any caller-supplied overrides before
calling Pulse.
POST /api/v1/vizql-data-service/read-metadata— request the data source's field metadata. Issued against the VizQL Data Service (VDS) API; requires thetableau:viz_data_service:readOAuth scope. Request data source metadata
- Generate the insight bundle for each selected measure. Called once per measure to build the
card's trend, contributors, and insight text.
POST /api/-/pulse/insights/detail— generate thedetailbundle for one measure. Issued against the Tableau REST API Pulse Insights service; requires thetableau:insights:readOAuth scope. Pulse is served at the fixed/api/-base, not a{version}path. Detail
tableau:mcp_site_settings:read is used across these calls to read per-site MCP configuration
overrides when MCP site settings are enabled.
Required arguments
datasource
The published data source to build cards for, given either as an exact, case-sensitive contentUrl
string, or as an object { luid }.
Example
"Superstore"
{ "luid": "2d935df8-fe7e-4fd8-bb14-35eb4ba31d45" }
When the server limits which data sources may be queried, a data source outside the allowed set resolves to the same "could not resolve" outcome as one that does not exist — there is no existence oracle for non-allowed data sources, and no metadata or Pulse call runs for them.
The tool refuses with one of these messages. Could not resolve datasource from provided input. Could not determine a DATE/DATETIME time field for this datasource. Could not determine numeric measures for this datasource. timeField "the supplied caption" is not a DATE/DATETIME field in this datasource. measure "the supplied caption" is not a numeric field in this datasource. filter field "the supplied field" is not a categorical field in this datasource.
Optional arguments
measures
Array of numeric field captions to build cards for. When omitted, the tool deterministically picks
the alphabetically-first numeric (INTEGER/REAL) fields, up to maxCards. Each supplied measure
is validated against the data source metadata (it must be a numeric field) before any Pulse call.
timeField
The DATE/DATETIME field caption to trend against. When omitted, the alphabetically-first
DATE/DATETIME field is used. A supplied value is validated against the metadata.
maxCards
The maximum number of measures (and therefore cards) to produce. Integer between 1 and 10. Defaults
to 4.
breakdownDimension
A single categorical (STRING) field caption to scope the breakdown group to. When omitted, up to
the first five categorical fields are used as the active dimension set. Validated against the
metadata.
breakdownDimension "the supplied caption" is not a categorical field in this datasource.
filters
Array of { field, value } categorical equality filters that scope the metric instance to specific
dimension members (drill-down). Each field must be a categorical field in the data source.
Example
[{ "field": "Region", "value": "West" }]
Notes and caveats
- Every card's
provenanceisgoverned. The only non-governed fields are the staticactionsbutton labels. warningsreports measures whose bundle call failed while others succeeded (partial failure). If every measure fails, the tool returns the first bundle error instead of an empty success, so a Pulse contract failure is not mistaken for a legitimately empty data source.briefConfigechoes the exactgenerate-pulse-metric-value-insight-bundlecall that produced the card, so a client can re-run or deep-link the underlying bundle.- Measure aggregation is summed (
AGGREGATION_SUM), and the measurement period is fixed to the current partial month compared with the previous period.
Example result
{
"datasource": {
"luid": "2d935df8-fe7e-4fd8-bb14-35eb4ba31d45",
"contentUrl": "Superstore",
"name": "Superstore"
},
"dimensions": ["Region", "Segment", "Category"],
"cards": [
{
"id": "2d935df8-fe7e-4fd8-bb14-35eb4ba31d45:Sales:trend",
"measure": "Sales",
"timeField": "Order Date",
"label": "Sales vs prior period",
"headline": "1.2M",
"deltaPct": 5,
"direction": "up",
"explanation": "Sales up 5% month to date compared to the prior period.",
"context": "3× the trailing average of +4%",
"comparison": {
"current": { "label": "May 2026", "subLabel": "MTD", "value": 1200000, "formatted": "1.2M" },
"prior": { "label": "Apr 2026", "subLabel": "", "value": 1140000, "formatted": "1.1M" }
},
"series": [
{ "date": "2026-05-01", "label": "May 1", "value": 100, "lower": 90, "upper": 110, "dashed": false }
],
"breakdown": [{ "label": "West", "value": 500 }],
"breakdownDimension": "Region",
"contributors": [
{ "label": "West", "value": 500, "formatted": "$500", "sharePct": 40 }
],
"pronounced": {
"strongest": { "label": "West", "value": 12, "formatted": "+12%" },
"weakest": { "label": "East", "value": -3, "formatted": "-3%" }
},
"unusual": { "text": "Within the expected range considering seasonal patterns.", "factor": null, "baselineWindow": null },
"followUps": ["What's driving West?", "Compare across Region"],
"actions": [{ "id": "drill", "label": "Drill into this", "primary": true }],
"provenance": "governed",
"briefConfig": {
"tool": "generate-pulse-metric-value-insight-bundle",
"args": { "bundleRequest": {}, "bundleType": "detail" }
}
}
],
"warnings": [{ "measure": "Profit", "error": "..." }]
}
Related
generate-pulse-metric-value-insight-bundle— the per-measure Pulse primitive this tool orchestratesquery-datasource— same VizQL Data Service metadata path