# Tool reference (/docs/agents/tools)

The same tools are available over [MCP](/docs/agents/mcp) and through the [CLI](/docs/agents/cli) (`datahop call <tool>`). **W** marks tools that change something. [Read-only keys](/docs/agents/api-keys#read-only-vs-read--write) don't see them. Optional inputs are marked `?`.

## Orientation & schema [#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 [#querying]

| Tool | | Inputs | What it does |
| --- | --- | --- | --- |
| `query` | | `query`: a [query object](/docs/reference/query-language) | 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](/docs/product-analytics/sql). |
| `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 [#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](/docs/product-analytics/dashboards#build-a-dashboard). |
| `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 [#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 [#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](/docs/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 [#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](/docs/experiments/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 [#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 [#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](/docs/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 [#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](/docs/destinations). |
| `update_destination` | W | `id`, any field, `enabled?` | Changes, pauses or resumes a destination. |
| `delete_destination` | W | `id` | Deletes a destination. |

## Context [#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 [#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 |