---
url: https://simpledatalogs.com/docs/mcp/tools.md
description: >-
  Every tool on the simpledatalogs MCP server, the read-only ones and the setup
  tools, with their inputs, outputs and limits.
---

# Tools reference

Every tool is read-only and marked with `readOnlyHint`, except the [setup tools](#setup-tools), which only a setup token sees. Each one reads only environments you are a member of, at most 90 days back and 100 rows per answer. Results come back as JSON, both as text content and as `structuredContent`.

You rarely call these yourself. Your assistant picks them; this page helps you know what it can ask.

::: tip Start with `list_environments`
Every other tool takes an `environment_id`. Assistants call `list_environments` first to find it, so you can just say "production of the Mac app".
:::

## Shared inputs

| Input | Type | Default | Meaning |
|---|---|---|---|
| `environment_id` | string | — | An id from `list_environments`. Required by every tool but `list_projects` and `list_environments` |
| `range` | `1h`, `24h`, `7d`, `30d`, `90d` | `24h` | How far back from now |
| `name` | string | — | Only this event name |

## `list_environments`

Every environment you can read, with its project and organization. No inputs.

```json
{"environments": [{"id": "0199…", "name": "production", "project": "Screenshotter", "organization": "XKD"}]}
```

## `event_totals`

Event counts and unique devices over a range, optionally per event name and level; busiest groups first.

| Input | Type | Default |
|---|---|---|
| `environment_id`, `range`, `name` | see above | |
| `group_by` | array of `name`, `level` | none (one total) |
| `limit` | 1–100 | `20` |

With `"group_by": ["name"]`:

```json
{"totals": [{"name": "screenshot_taken", "events": 4210, "devices": 388}, {"name": "app_launched", "events": 1022, "devices": 391}]}
```

## `event_series`

Counts per hour or per day over a range, in the project's time zone.

| Input | Type | Default |
|---|---|---|
| `environment_id`, `range`, `name` | see above | |
| `bucket` | `hour` or `day` | `day` |

Hourly series go back at most 7 days (`1h`, `24h`, `7d`).

```json
{"time_zone": "America/Los_Angeles", "points": [{"bucket_start": "2026-10-16T07:00:00Z", "events": 612, "devices": 140}]}
```

## `search_logs`

The newest events and log lines in a range, filtered by text, level or name.

| Input | Type | Default |
|---|---|---|
| `environment_id`, `range`, `name` | see above | |
| `query` | string | — a substring of the message |
| `level` | `debug`, `info`, `notice`, `warning`, `error`, `critical` | — |
| `limit` | 1–100 | `50` |

```json
{"events": [{"ts": "2026-10-17T09:14:02.000Z", "name": "", "level": "error", "message": "Card declined", "device": "c0ffee-42", "props": {"status": 402}}]}
```

A long message is cut to 4,000 characters, and very large props stay as text.

## `list_projects`

Every project you can read, with its organization, time zone and environments. No inputs.

## `list_deployments`

An environment's deployments (one per build or source), with their platform.

| Input | Type | Default |
|---|---|---|
| `environment_id` | see above | |

## `prop_breakdown`

How many events had each value of one property, most common first. Ask for one event name to split just that event.

| Input | Type | Default |
|---|---|---|
| `environment_id`, `range`, `name` | see above | |
| `property` | string, required | — a property path such as `plan` or `device.os` |
| `limit` | 1–100 | `20` |

## `device_stats`

Unique devices in a range, and the most recently active devices with their busiest events.

| Input | Type | Default |
|---|---|---|
| `environment_id`, `range` | see above | |
| `query` | string | — a substring of the device id |
| `limit` | 1–100 | `20` |

## `unparsed_summary`

How much input couldn't be parsed (kept 7 days in Unparsed), with recent samples and their reasons.

| Input | Type | Default |
|---|---|---|
| `environment_id`, `range` | see above | |
| `limit` | 1–20 samples | `5` |

## `list_counters`

An environment's published [public counters](/guide/public-counters): label, event, window, public URL and the count over that window.

| Input | Type | Default |
|---|---|---|
| `environment_id` | see above | |

## `spend_summary`

The estimated spend from the environment's price table over a range: the total, the costliest combinations, and events with no price.

| Input | Type | Default |
|---|---|---|
| `environment_id`, `range` | see above | |
| `limit` | 1–100 | `20` |

## `list_alerts`

An environment's threshold alerts and their state: ok or firing, since when, the last value, snoozes, and the chat channels (Slack, Discord, webhook) each sends to besides email.

| Input | Type | Default |
|---|---|---|
| `environment_id` | see above | |

## `list_dashboards`

The environment's saved dashboard: the Overview's sections and custom widgets in display order, with hidden and pinned flags, and each custom board (name, emoji and widgets).

| Input | Type | Default |
|---|---|---|
| `environment_id` | see above | |

::: tip Top events
There's no separate top-events tool: `event_totals` with `"group_by": ["name"]` lists event names busiest first.
:::

## Setup tools

Only a [setup token](/mcp/#setup-tokens-for-a-first-setup) lists and runs these. Every create needs an `idempotency_key` (any unique text, up to 100 characters); sending the same one again answers the first result instead of creating twice.

| Tool | Inputs | Returns |
|---|---|---|
| `create_project` | `name`, `idempotency_key`; optional `organization_id` (when you can create in several), `environments` (1 to 5 names, default `production` and `local` as the plan allows), `emoji`, `logo_base64` (PNG, JPEG or WebP as base64 or a data: URL, at most 256 KB and 1024 × 1024 px, never SVG), `deployments` (1 to 10 `{"name", "platform"}` objects) | The project (with `emoji` and `has_logo`) and its environments, each with the given deployments, else one named `default` |
| `create_environment` | `project_id`, `name`, `idempotency_key`; optional `deployments` (as above) | The environment with the given deployments, else one named `default` |
| `create_deployment` | `environment_id`, `name`, `idempotency_key`; optional `platform` (`ios`, `android`, `macos`, `windows`, `linux`, `web`, `server`, `other`) | The deployment. The first one in an environment takes over its untouched `default` deployment, so no empty default is left behind |
| `create_key` | `deployment_id`, `idempotency_key`; optional `kind` (`public` or `secret`, default secret for a `server` deployment, else public) | The key's full value once, its id, kind, the variable name `SIMPLEDATALOGS_KEY` and the ingest URL |
| `revoke_key` | `key_id` | `{"revoked": true}`; only for a key this same token made |

```json
{"key": "sdl_pub_…", "key_id": "0199…", "kind": "public", "variable_name": "SIMPLEDATALOGS_KEY", "ingest_url": "https://edge.simpledatalogs.com"}
```

List every thing that sends (each app build, site and server) up front and pass it as `deployments`, so each environment gets exactly those and no empty `default`:

```json
{"name": "Tithi", "deployments": [{"name": "Website", "platform": "web"}, {"name": "iOS app", "platform": "ios"}], "idempotency_key": "tithi-1"}
```

A bad logo or deployments list refuses the whole call before anything is created, so fix it and retry with the same `idempotency_key`.

Every setup answer also carries `setup_budget`: the projects this token may still create (`projects_left`), the per-project, per-environment and per-deployment limits, and its `calls_per_minute`.

A repeated `create_key` answers `"is_repeat": true` without the key: its full value shows only once.

## Errors

A tool that can't answer returns `isError: true` with a sentence the model can act on:

| Message | Meaning |
|---|---|
| "No environment with that id among yours; call list_environments." | A wrong or foreign id |
| "range must be one of 1h, 24h, 7d, 30d, 90d." | An unknown range |
| "Hourly series go back at most 7 days; use bucket "day"." | `bucket: hour` with a longer range |
| "Too many rows for this range; pick a shorter range or a name." | The query was too large |
| "The event store didn't answer; try again in a moment." | A temporary outage |
| "This token can only read. …" | A setup tool called with a read token or a chat app |
| "This deployment already has 2 active keys, the setup limit. …" | A setup limit was reached (also 100 projects, 5 environments, 10 deployments); create the rest in the dashboard |
| "Too many setup calls (10 a minute); wait a minute, then repeat this call with the same idempotency_key." | Over the setup call rate; the retry with the same key makes nothing twice |
| "This setup token has expired or was revoked." | A setup token past its 24 hours |

## Next steps

* [Connecting clients](/mcp/clients): set it up in your assistant.
* [Prompt recipes](/agents/recipes#read-your-numbers-back): questions that make good use of these tools.