Tools reference

Every tool is read-only and marked with readOnlyHint, except the 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.

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.

{"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"]:

{"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).

{"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

{"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: 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

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 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

{"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:

{"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: set it up in your assistant.
• Prompt recipes: questions that make good use of these tools.