Tools - Grain Analytics

The Grain MCP server has eleven tools in three groups: discovery, query, and investigation. Each tool declares the minimum OAuth scope it needs. The consent screen groups the scopes, so you know what you grant. The tool names (grain.query, grain.segment.compare) are the identifiers that the model sees. You rarely type them. The model picks the tool from your prompt.

Discovery: `mcp:read`

These tools describe what is in the tenant. They consume no query budget. An agent calls them first on an unfamiliar tenant.

`grain.events.list`

Lists the distinct event names that the tenant has received, in alphabetical order.

Field	Type	Required	Meaning
`limit`	integer	No	Maximum number of names to return. Range 1 to 100. Default `100`.

An example prompt is “What events does my site track?”.

`grain.dimensions.discover`

Samples recent events and returns the dimensions (properties) that you can filter or group by, with cardinality hints and redacted sample values.

Field	Type	Required	Meaning
`eventName`	string	No	Limits discovery to one event. Omit it to sample across all events.
`timeRange`	`TimeRange`	No	The window to sample from. Default is the last 7 days.

An example prompt is “What can I break signup down by?”.

`grain.integration.status`

Reports whether the Grain Tag sends data correctly. Call it before an investigation, so that you know the data is complete. An example prompt is “Is my tracking healthy?”.

Query: `mcp:query`

These tools wrap the Grain query engine with the same surprise detection that Kai uses in the dashboard. A response includes structured hints (_surprises, _narrativeHints) about what is concentrated, volatile, or changed in rank.

`grain.query`

Runs a breakdown or a time series query with filters and grouping.

Field	Type	Required	Meaning
`metric`	enum	Yes	What to measure: `events`, `unique_visitors`, `unique_sessions`, and more.
`eventName`	string	Yes	The event to filter on, or `""` for all events.
`mode`	`'breakdown' \| 'timeseries'`	Yes	`breakdown` groups by a dimension. `timeseries` trends over time.
`groupBy`	string[]	No	The dimensions to group by in breakdown mode. Use `[]` for a time series.
`filters`	`Filter[]`	No	Property filters. Operators: `eq`, `neq`, `gt`, `lt`, `gte`, `lte`.
`timeRange`	`TimeRange`	Yes	`{ last: '7d' }` or `{ from: ISO, to: ISO }`.
`limit`	integer	No	Maximum rows for a breakdown. Range 1 to 500. Default `10`.

An example prompt is “Signups by country last week, top 5.”.

`grain.query.count`

Returns the total count of events that match the filters in a window. It costs less than grain.query when you do not need rows. An example prompt is “How many signups did I get this week?”.

`grain.query.compare`

Runs the same query two times, for the current window and a previous window. It returns both results and a comparison with deltas and percent changes.

Field	Type	Required	Meaning
`timeRange`	`TimeRange`	Yes	The current window.
`compareTo`	`TimeRange`	Yes	The previous window. Usually the preceding period of the same length.

An example prompt is “Traffic sources this week versus last week, flag anything that moved more than 20%.”.

`grain.query.digest`

Writes an end-of-period digest: top metrics, biggest movers, and anomalies. This is the tool behind a daily briefing. An example prompt is “Give me yesterday’s digest.”.

Investigation: `mcp:investigate`

These tools answer “why did X happen” questions.

`grain.correlate_event`

Takes a target event and finds other events whose occurrence correlates with it above the baseline. Use it for “what did users do before they converted” questions. An example prompt is “What events do users fire in the 10 minutes before purchase_completed?”.

`grain.track.analyze`

Analyzes a Track, the Grain two-step funnel (a start event, then a goal event, in a time window). It returns the conversion rate, the dimensions with the biggest drop-off, and a breakdown per segment.

Field	Type	Required	Meaning
`startEvent`	string	Yes	The event that starts the funnel.
`goalEvent`	string	Yes	The event that completes the funnel.
`windowSeconds`	integer	No	The time that a user has to complete the funnel. Default 1 hour.

An example prompt is “How many visitors who hit checkout_started finished with purchase_completed within 30 minutes last week? Where did they drop off?”.

`grain.segment.compare`

Compares two cohorts, each defined by filters, on a metric. It returns the dimensions where the cohorts differ most. An example prompt is “Compare users who converted versus users who bounced on the pricing page. What is different about them?”.

`grain.sessions.cluster`

Groups sessions by behavioral signature. It returns representative sessions for each cluster, so an agent can summarize each cluster in one sentence. An example prompt is “Cluster sessions from users who abandoned checkout yesterday.”.

Shared shapes

Every query tool uses the same two shapes.

Shape	Field	Type	Values
`Filter`	`property`	string	A property name, for example `browser` or `utm_source`.
`Filter`	`op`	enum	`eq`, `neq`, `gt`, `lt`, `gte`, `lte`.
`Filter`	`value`	string, number, or boolean	The value to compare with.
`TimeRange`	`last`	enum	`1h`, `24h`, `7d`, `30d`, `90d`.
`TimeRange`	`from`, `to`	ISO 8601 string	An absolute window, for example `2026-04-01T00:00:00Z` to `2026-04-07T23:59:59Z`.

A TimeRange holds last, or from and to, not both.

The backend does not support the in and contains operators. If an agent sends one, grain.query rejects the call with an error.

Every event carries these properties. You can filter or group by them without setup:

device, browser, os, session_id,
utm_source, utm_medium, utm_campaign, utm_term, utm_content,
first_touch_source, first_touch_medium, first_touch_campaign, first_touch_referrer_category,
page, full_url, timestamp, referrer, referrer_domain, referrer_category,
previous_page, landing_page, title, language, timezone,
screen_resolution, viewport

The referrer categories are direct, organic, paid, social, email, and referral. Read Automatic properties for the meaning of each property.

Budgets

Grain enforces a budget per MCP request, so that an agent cannot saturate the tenant.

Budget	Limit	Where
Query calls	16 per MCP request	`grain.query`, `grain.query.count`, and the investigation tools. `grain.query.compare` counts as 2.
Compute time	20 s per MCP request	Wall-clock time for Next.js-native analysis. Not yet exposed over MCP.
Rows	500	The `limit` ceiling of a `grain.query` breakdown.
Event names	100	The `limit` ceiling of `grain.events.list`.

If an agent reaches the budget in a session, it receives a structured error. The agent then asks you to narrow the question. The tools wrap the same engine as the Query API. Read Query API for the HTTP interface.

​Discovery: mcp:read

​grain.events.list

​grain.dimensions.discover

​grain.integration.status

​Query: mcp:query

​grain.query

​grain.query.count

​grain.query.compare

​grain.query.digest

​Investigation: mcp:investigate

​grain.correlate_event

​grain.track.analyze

​grain.segment.compare

​grain.sessions.cluster

​Shared shapes

​Budgets

Discovery: `mcp:read`

`grain.events.list`

`grain.dimensions.discover`

`grain.integration.status`

Query: `mcp:query`

`grain.query`

`grain.query.count`

`grain.query.compare`

`grain.query.digest`

Investigation: `mcp:investigate`

`grain.correlate_event`

`grain.track.analyze`

`grain.segment.compare`

`grain.sessions.cluster`

Shared shapes

Budgets