# Tool reference (/docs/agents/tools)

The same tools are available over [MCP](/docs/agents/mcp) and through the [CLI](/docs/agents/cli) (`rochart 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. |
| `get_schema` | | `type?` (`events` by default, or `person`, `group`), `groupTypeIndex?`, `includeHidden?` | Every event with 30-day volume, change against the 30 days before, people, last seen, how many saved things use it and look-alike names. For `person` or `group`: each property's type, coverage, top values and where it's set from. |
| `get_event_usage` | | `event` | One event's daily volume, its properties (coverage and top values) and every insight, dashboard, cohort, flag, experiment, alert, destination and saved SQL query that uses it. |
| `describe_event` | W | `event`, `description?`, `tags?`, `verified?`, `hidden?` | Saves an event's description and tags, and marks it verified or hidden. Hidden events stay out of pickers but are still collected. |

## 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 game analytics (`game_*`) query. Returns a summary plus the data. Game analytics queries need that product on. |
| `tail_events` | | `seconds?` (default 60), `cursor?`, `events?`, `pageviews?`, `autocapture?`, `filters?`, `person?`, `search?`, `limit?` | Events as they're ingested, seconds old. Without a cursor: the last `seconds`, newest first. With the `cursor` from the previous call: only events since then, oldest first. See [Live view](/docs/live). |
| `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, an outline of its layout (sections, rows and card widths) with any layout issues, and every card with its result summary. |
| `create_dashboard` | W | `name`, `description?`, `template?` (`blank` or `overview`), `filters?`, `sections?` | Creates a dashboard: empty, from the Overview template, or fully built from `sections` (see `set_dashboard_layout`). |
| `set_dashboard_layout` | W | `dashboardId`, `sections?`, `removeUnlisted?` | Lays out the whole dashboard. Each section has an optional `heading` and `rows` of cards (or a flat `tiles` list). A card is `{ tileId }` for an existing card or `{ tile }` for a new one, with optional `size` (`small`, `medium`, `large`, `full`) and `height` (`short`, `medium`, `tall`). Rows fill the width with no gaps. Leave out `sections` to tidy the current layout. |
| `update_dashboard` | W | `id`, `name?`, `description?`, `isHome?`, `filters?`, `layouts?` | Renames it, sets the date range and comparison, or makes it the home page. Raw `layouts` are accepted and fixed up: sizes are kept within limits, overlaps are pushed down and gaps are closed. The response says what changed. |
| `add_dashboard_tile` | W | `dashboardId`, `tile`, `size?`, `height?`, `layout?` | Adds a metric, chart, insight, saved SQL query, text or widget card and places it automatically. Cards take display options: `description`, `format`, `display`, `colors`, `compare` and `goodWhen`. See [Dashboards](/docs/product-analytics/dashboards#card-options). |
| `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, including display options. `null` clears a setting. |
| `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 = clan`) 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 group aren't supported yet.

## Feedback [#feedback]

Listed only when Feedback is on.

| Tool | | Inputs | What it does |
| --- | --- | --- | --- |
| `list_feedback_boards` | | | Feedback pages with open and total counts. |
| `create_feedback_board` | W | `name`, `key?`, `description?` | Creates a feedback page for one flow. |
| `list_feedback` | | `board?`, `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), `board?` | 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 | 68 |
| Read-only key, every product on | 36 |
| Read & write key, with Feature flags, Experiments, Feedback, Alerts and Destinations off | 41 |