# Tidings analytics (MCP)

The Tidings MCP server (`tidings`) is connected. Tidings is product analytics: the app sends events (`signup_completed`, `page_view`, …) with a `distinct_id` per person, and these tools read them back. Use them whenever the question is about what users did, how many, where they dropped off, or whether they came back.

## Start

- Call `list_projects` first. Every other tool takes the `org` and `project` slugs it returns; never guess a slug.
- With one project, use it. With several, ask which one unless the question names it.
- Call `get_overview` before anything specific: the totals, the previous window and the top event names tell you what the product calls things in its own data.
- Before filtering or breaking down on a property, call `get_event_schema`. It is the only way to know a key exists and whether its values are strings or numbers. Do not guess property names.

## Picking the tool

- How much, how many, trend → `get_overview` (events, users, a series of up to 90 points).
- Which events exist, what a given event carries → `list_event_names`, `get_event_schema`.
- What happened just now, show me examples → `recent_events` (20 at most; the one tool that includes `$` internals).
- Where do people drop off → `run_funnel` with 2–5 steps; `window_days` bounds the time from step 0; `breakdown` splits by a property (top 5 + Other), read off step 0 — pass `breakdown_step` when only a later step carries it (`product` on a purchase); people who never reached that step are `(not set)`. Version-like breakdown values come back in version order, newest first, and `new: true` marks a value first seen in the window.
- Did a conversion rate change after a date (a release, a campaign) → `run_funnel` with `over_time: "day"|"week"`: its `series` groups people by the day or week they entered, with each step's count and the rates per point (at most 120). Recent points have had less time to convert.
- Who are those people → `funnel_users` (one step, converted or dropped), `retention_users` (one cohort cell), `query_users` (a filtered list), `get_user` (one person).
- Do people come back → `get_retention` (weekly cohorts over 84 days by default).
- What do people do after X → `get_paths`.
- How long are visits, bounce rate → `get_session_stats`.
- Where do people click, how far do they scroll → `list_heatmap_pages`, then `get_heatmap_summary`.
- What has the team already saved or noted → `list_saved_insights`, `list_segments`, `list_dashboard_tiles`, `list_annotations`.
- What is being watched, and has it gone off → `list_alerts` (each alert's state: ok, firing or unknown), then `get_alert_events` for what one alert did.
- Is my instrumentation arriving → `check_events` (each expected event and property key, over the last 60 minutes by default).

## Setting Tidings up for the team

Each write needs its area's grant on the token — annotations, segments, insights, dashboards or alerts — and `tools/list` only shows the tools your token may call; if a write you need is missing, tell the user which grant to add rather than working around it. A token may also be limited to certain projects: `list_projects` shows only those. Use the writes when the user asks you to set something up, never on your own initiative. A token can rearrange and remove dashboard tiles, but never delete segments, saved insights, annotations or alerts.

- `create_annotation` — a dated note on the project's timeline ("v1.6 released").
- `create_segment` / `update_segment` — a named group of people, in `query_users`' filter vocabulary.
- `save_funnel` — save a funnel with `run_funnel`'s arguments; run it first and save what produced the answer.
- `save_insight` / `update_saved_insight` — save a funnel, paths, retention or sessions question under Insights.
- `add_dashboard_tile` — pin a chart, or a saved funnel/retention/sessions insight by its id, to the custom dashboard (check `list_dashboard_tiles` first). For a rate shown as one number, pin `type: "ratio"` with a `numerator` and a `denominator`, each `{event_name, filters?, measure}` — e.g. `trial_started` users over `paywall_shown` users. A tile follows the dashboard's range unless you pin its own `range`: `{days: 1|7|30|90}`, `{start, end}` (end exclusive), `{since: "YYYY-MM-DD"}` or `{since_annotation: <id from list_annotations>}` — only when the user asks for a tile that keeps its range ("since launch").
- `apply_dashboard_template` — add a ready-made dashboard from `list_dashboard_templates`.
- `update_dashboard_tile` — move, resize or rename a tile (`layout`, `label`), pin or clear its `range` (`null` clears), or switch its `compare`/`measure` (on a ratio tile, its `numerator`/`denominator`/`format`); only the fields you pass change.
- `remove_dashboard_tile` — remove one tile; the result carries the whole tile, so `add_dashboard_tile` can put it back.
- `create_alert` — be told when a number crosses a line or leaves its usual range: a stat or ratio `query` (the `add_dashboard_tile` vocabulary), a `period` (60, 360, 1440 or 10080 minutes), and either `kind: "threshold"` with a `condition` and `threshold` — "crash > 0 in the last hour" is `{type: "stat", event_name: "crash"}`, period 60, `gt` 0; "new installs down more than 30 % vs the previous day" is period 1440, `change_down_pct` 30 — or `kind: "anomaly"` (`sensitivity` 2–4 standard deviations, `direction`). Notifies org members by email and/or a signed https webhook; the webhook secret is returned once. Check `list_alerts` first, then `test_alert` to prove delivery.
- `update_alert` — rename, pause (`enabled: false`), change recipients, threshold, sensitivity, period or cooldown; what an alert watches cannot change — create a new one instead.

A release, for example version 1.6 of an app:

1. `create_annotation` on the release day.
2. `create_segment` "Users on 1.6" — `person_property app_version eq 1.6`, or `did_event` on an event only 1.6 sends.
3. `save_funnel` / `save_insight` for the onboarding funnel and a paths comparison (paths with `breakdown_event` + `breakdown_property: app_version`).
4. `add_dashboard_tile` to pin them.

To tidy a dashboard, `list_dashboard_tiles`, then `update_dashboard_tile` (layout) or `remove_dashboard_tile`; never remove a tile you were not asked to.

After adding or changing events, call `check_events` with the names and property keys you expect, and confirm they arrive before telling the user it works. When you are done, tell the user what you created, by name, with the URLs the tools returned.

## Reading the answers

- All times are UTC. Every time-scoped tool takes `days` (default 30) or `start`/`end`, and echoes the window and bucket `interval` it actually applied. Report that, not the one you asked for.
- Outputs are capped (20 recent events, 25 users, 90 series points, 40 schema events) and each tool states its cap. A full-looking list is truncated: narrow the question rather than paging or asking for everything.
- Event names starting with `$` are the SDK's own instrumentation (`$click`, `$scroll`, `$identify`). They are excluded from every aggregate unless you name one explicitly.
- The team's own devices and test accounts (`list_internal_identities`) are excluded from every aggregate, named event or not. Pass `include_internal: true` only when the user asks to include them; `recent_events` and `get_user` always show them.
- A result marked `sampled` was computed on a sample of users and scaled back up. Say so when quoting its counts.
- A tool error says what was wrong. Read it and correct the call once; do not retry the same arguments.

## Answering

- Lead with the number and its window ("Signups: 412 in the last 7 days, down 18% on the week before"), then the one comparison or split that explains it, then what you would check next.
- Quote figures as returned; round percentages to whole numbers. Never invent a figure the tools did not return.
- A typical question takes three to five calls. If you need more, say what you are looking for and why.
- Do not paste raw event rows or lists of distinct ids into the answer unless asked. Summarise, and offer to show them.
- Distinct ids and person properties may be personal data. Do not copy them into files or other tools beyond what the user asked for.
