Tool reference
All 62 MCP tools, grouped by area, with their inputs, whether they change data and the product they need.
The same tools are available over MCP and through the CLI (datahop call <tool>). W marks tools that change something. Read-only keys don't see them. Optional inputs are marked ?.
Orientation & schema
| Tool | Inputs | What it does | |
|---|---|---|---|
project_overview | — | Start here. Products that are on, top events with counts and descriptions, group types, cohorts, insights, dashboards, flags, experiments and recent changes. | |
list_events | search? | Event names with volume and description. | |
get_event | event | Properties seen on one event, with type, sample values and description. Use it before filtering or breaking down. | |
list_properties | type? (person by default, or event, group), search? | Properties with types and sample values. | |
get_property_values | key, type? (event by default), event?, groupTypeIndex? | The 50 most common values with counts. For event properties, this covers the last 30 days. | |
describe_event | W | event, description | Saves an event description that people and agents read. |
Querying
| Tool | Inputs | What it does | |
|---|---|---|---|
query | query: a query object | Runs a trend, funnel, retention, paths, lifecycle, stickiness, raw events, SQL or web analytics query. Returns a summary plus the data. Web analytics queries need that product on. | |
sql | sql | Read-only SQL over events, persons, sessions, groups and saved queries. See the SQL editor. | |
sql_schema | — | Tables and columns, saved queries, top events, property keys with types, cohort ids and example queries. Call it before writing SQL. | |
list_saved_queries | — | Saved SQL queries. Each one is also a table other queries can select from. | |
save_query | W | name, sql, description?, display?, syncProperties? | Saves SQL under a name, so it can be used as a table (SELECT … FROM active_accounts). Updates the query with that name if there is one. The SQL must run. With syncProperties and a person_id column, the other columns become person properties. |
delete_saved_query | W | id | Deletes a saved query, unless another saved query reads from it. |
Insights & dashboards
| Tool | Inputs | What it does | |
|---|---|---|---|
list_insights | search? | Saved insights. Search matches name and description. | |
get_insight | id | A saved insight with fresh results. | |
save_insight | W | name, query (trends, funnel, retention, paths, lifecycle or stickiness), description?, dashboardId? | Saves a query as an insight, optionally straight onto a dashboard. |
update_insight | W | id, name?, description?, query? | Changes a saved insight. |
list_dashboards | — | Dashboards, with whether each has a public link. The home dashboard comes first. | |
get_dashboard | id (a number, or "home") | The dashboard's date range and every card with its result summary. | |
create_dashboard | W | name, description?, template? (blank or overview) | Creates a dashboard, empty or with headline metrics, active people and top events. |
update_dashboard | W | id, name?, description?, isHome?, filters?, layouts? | Renames it, sets the date range and comparison, makes it the home page, or moves and resizes cards. |
add_dashboard_tile | W | dashboardId, tile, layout? | Adds a metric, chart, insight, saved SQL query, text or widget card. See Dashboards. |
add_to_dashboard | W | dashboardId, insightId | Adds a saved insight as a card. |
update_dashboard_tile | W | dashboardId, tileId, config?, layout? | Changes a card's settings or position. |
remove_dashboard_tile | W | dashboardId, tileId | Removes a card. A saved insight itself stays. |
share_dashboard | W | id, enabled, rotate? | Turns the public link on or off, or replaces it. Returns the URL. Agents are told to ask you first. |
People, cohorts & groups
| Tool | Inputs | What it does | |
|---|---|---|---|
find_persons | search?, cohortId?, limit? (25 by default, at most 200), offset? | Searches people by email, name or id, optionally within a cohort. | |
get_person | id (person id or distinct id) | A person's properties, ids, cohorts, groups and recent events. | |
list_cohorts | — | Cohorts with their rules and sizes. | |
create_cohort | W | name, description?, isStatic?, definition?, queryId? | Creates a dynamic cohort from rules, an empty static one, or a SQL cohort from a saved query with a person_id column. Returns its size. |
update_cohort | W | id, name?, description?, definition? | Changes a cohort. |
add_to_static_cohort | W | id, personIds?, distinctIds? | Adds people to a static cohort. |
list_group_types | — | Group types (for example 0 = company) with how many groups each has. | |
find_groups | groupTypeIndex, search?, limit? | Searches groups of one type by key or name. | |
get_group | groupTypeIndex, key | A group's properties, stats and most recently active people. |
Feature flags
Listed only when Feature flags is on.
| Tool | Inputs | What it does | |
|---|---|---|---|
list_flags | — | All flags, with the experiment that uses each one. | |
create_flag | W | key, filters, name?, description?, active? (off by default) | Creates a boolean or multivariate flag. See Feature flags. |
update_flag | W | id, active?, filters?, description? | Switches a flag on or off, or changes who gets it. |
evaluate_flags | distinctId, groups? | Every flag value that user gets right now. |
Experiments
Listed only when Experiments is on.
| Tool | Inputs | What it does | |
|---|---|---|---|
list_experiments | — | Experiments with status, metrics and flag key. | |
draft_experiment | description | Turns a plain-language idea ("Does an annual-plan discount banner get more trials to upgrade?") into a complete plan on your real events and cohorts, with a rationale and warnings. Creates nothing. Offered to read & write keys only. | |
create_experiment | W | name, hypothesis, flagKey, primaryMetric, description?, variants?, secondaryMetrics?, minimumDetectableEffect?, segmentCohortIds?, targeting?, rolloutPercentage? | Creates a draft and its flag (control/test, 50/50 by default). |
launch_experiment | W | id | Starts a draft and switches its flag on. |
get_experiment_results | id | Results per variant, the split check, segments, the recommendation and a summary. See Read results. | |
stop_experiment | W | id | Stops new people from entering. |
conclude_experiment | W | id, winner, reason, rollOut? (on by default) | Records the decision and optionally rolls the winner out to everyone. |
Experiments split by person. Experiments per company aren't supported yet.
Feedback
Listed only when Feedback is on.
| Tool | Inputs | What it does | |
|---|---|---|---|
list_feedback | status? (new by default), category?, minRating?, maxRating?, search?, cohortId?, person?, groupTypeIndex? + groupKey?, days?, limit?, offset? | Feedback, newest first, with who sent it. | |
feedback_stats | days? (30 by default) | Counts per status, top categories and the average rating. | |
update_feedback | W | id, status (new, resolved or archived) | Triages one item. |
Alerts
Need Alerts on.
| Tool | Inputs | What it does | |
|---|---|---|---|
list_alerts | — | Alerts with state (ok, firing, error, pending), last value and recent values. | |
get_alert | id | One alert with its check history and delivery results. | |
create_alert | W | name, source, condition, frequency?, destinations?, description? | Watches an event metric, a saved insight or a saved SQL query. See Alerts. Checks once straight away. |
update_alert | W | id, any field, enabled? | Changes, pauses or resumes an alert. |
check_alert | W | id | Checks now and notifies if the state changes. |
delete_alert | W | id | Deletes an alert and its history. |
Destinations
Need Destinations on.
| Tool | Inputs | What it does | |
|---|---|---|---|
list_destinations | — | Destinations with sent and failed counts. | |
get_destination | id | One destination with its recent deliveries. | |
create_destination | W | name, type (webhook, slack or telegram), url or chatId, events?, filters?, template?, headers? | Forwards matching events as they arrive. See Destinations. |
update_destination | W | id, any field, enabled? | Changes, pauses or resumes a destination. |
delete_destination | W | id | Deletes a destination. |
Context
| Tool | Inputs | What it does | |
|---|---|---|---|
create_annotation | W | date, content (up to 500 characters) | Marks a moment on every chart, such as a release, a campaign or an experiment decision. |
list_annotations | — | All annotations, newest first. | |
recent_activity | limit? (30 by default) | What people and agents changed recently. |
How many tools an agent sees
| Tools | |
|---|---|
| Read & write key, every product on | 62 |
| Read-only key, every product on | 31 |
| Read & write key, with Feature flags, Experiments, Feedback, Alerts and Destinations off | 37 |