insights/services/mcp/tests/unit/__snapshots__/instructions/exec-command-reference-claude-chat.txt

CLI-style command string. Supported commands:

```text
learn <topic...> - load one or more learning topics
tools — list available tool names
search <regex_pattern> — search tools by JavaScript regex (matches name, title, description)
info [--json] <tool_name> — show tool name, description, and input schema (summarized if too large). Pass `--json` for raw JSON output.
schema <tool_name> [field_path] — drill into a specific field schema (supports dot-notation, e.g. series, breakdownFilter.breakdowns)
call [--json] [--confirm] <tool_name> <json_input> — call a tool with JSON input (--json returns JSON instead of optimized output in supported tools. Informational responses remain tagged and escaped in both MCP and the agent CLI. --confirm is required by the CLI for destructive tools.)
```

**Namespaced references (`insights:<tool-name>`):** strip the `insights:` prefix and route through `exec`. Run `info <name>` to inspect, then `call <name> <json>`. E.g. `insights:insights-list` → `insights:exec({ "command": "info insights-list" })` then `insights:exec({ "command": "call insights-list {}" })`. If the bare name isn't found, fall back to `search <pattern>` — it may have been renamed.

**LEARN FIRST: HARD REQUIREMENT**

Load all matching topics in one `learn` command first. Topics are cumulative.

- analytics: Query or analyze Insights data, metrics, and events.
- visualizations: Create or render a visualization.
- feedback: Send feedback about Insights.

**SCHEMA DRILL-DOWN RULE — HARD REQUIREMENT**

The `info` command may return the full schema (for simple tools) or a top-level summary with drill-down hints (for complex tools). Look for `hint` fields in the response.

If `info` returned a summary (fields have `hint` values), call `schema <tool_name> <field_name>` for each field you need to populate BEFORE constructing that field's value in a `call` command.

If `schema` also returns a summary (because the field is too large), drill deeper using dot-notation: `schema <tool> <field>.<subfield>`.

**NEVER** guess the structure of fields that have hints. **ALWAYS** drill down first.

For query tools, you will typically need:

- `schema <tool> series` — to see EventsNode/ActionsNode structure
- `schema <tool> series.properties` — to see property filter structure of series

**For multiple tools:** Run `info` for ALL tools first, then make your `call` commands.

**Data discovery:** Before any analytical `call` that touches collected data (`query-*`,
`execute-sql` against `events`/`persons`/`sessions`), confirm the event/property exists via
`call read-data-schema`. Applies to canonical-looking names like `$pageview` too — they vary
per team. If the event isn't in the schema, tell the user instead of querying a guessed name.

Always run `info read-data-schema` first — the recipes below are common cases, not the full schema.

- Events/Actions: `call read-data-schema {"query": {"kind": "events"/"actions"}}` (paginate with `limit`/`offset` if needed)
- Properties: `call read-data-schema {"query": {"kind": "event_properties", "event_name": "<event>"}}`
- Values: `call read-data-schema {"query": {"kind": "event_property_values", "event_name": "<event>", "property_name": "<prop>"}}`

**CORRECT usage pattern:**

<example>
User: create pageviews visualization
Assistant: This needs analytics and visualization guidance, so I'll load both first.
[Runs `insights:exec({"command":"learn analytics visualizations"})`]
</example>

<example>
User: How many weekly active users do we have?
Assistant: This needs analytics and visualization guidance, so I'll load both before any other command.
[Runs `insights:exec({"command":"learn analytics visualizations"})`]
Assistant: I need the query and data schema tools.
[Runs `insights:exec({"command":"search query-trends"})` and `insights:exec({"command":"search read-data"})` in parallel]
Assistant: I'll inspect both schemas.
[Runs `insights:exec({"command":"info query-trends"})` and `insights:exec({"command":"info read-data-schema"})` in parallel]
Assistant: The hinted series needs its full schema, and I need the team's events.
[Runs `insights:exec({"command":"schema query-trends series"})` and `insights:exec({"command":"call read-data-schema {\"query\":{\"kind\":\"events\"}}"})` in parallel]
Assistant: I now have the inputs for the query.
[Runs `insights:exec({"command":"call query-trends {...}"})`]
Assistant: [Briefly summarizes the weekly active user trend.] I'll render it so you can verify the result.
[Runs `render-ui({ "tool_name": "query-trends", "tool_input": {...} })` with the same query input]
</example>

<example>
User: Create a dashboard for our key revenue metrics
Assistant: Analytics applies. I'll load it before any other command.
[Runs `insights:exec({"command":"learn analytics"})`]
Assistant: I need dashboard and query tools.
[Runs `insights:exec({"command":"search dashboard"})` and `insights:exec({"command":"search execute-sql"})` in parallel]
Assistant: I'll inspect both schemas.
[Runs `insights:exec({"command":"info dashboard-create"})` and `insights:exec({"command":"info execute-sql"})` in parallel]
Assistant: I have the inputs to create the dashboard.
[Makes call commands with correct parameters]
</example>

**INCORRECT usage patterns: NEVER do this**

<bad-example>
User: Show me our feature flags
Assistant: [Calls `feature-flag-get-all` with guessed parameters]
WRONG: Run `info feature-flag-get-all` first.
</bad-example>

<bad-example>
User: Query our events
Assistant: [Loads analytics, then calls three tools without inspecting them]
WRONG: Run `info` for all tools before any `call` commands.
</bad-example>

<bad-example>
User: Show me a trends chart of signups
Assistant: [Runs `learn analytics visualizations`, then runs `info query-trends` and guesses the hinted series structure]
WRONG: Run `schema query-trends series` before populating a field with a drill-down hint.
</bad-example>

<bad-example>
User: query pageviews for the last 7 days
Assistant: [Runs `learn analytics`, then queries the guessed `$pageview` event]
WRONG: Confirm the event with `call read-data-schema {"query":{"kind":"events"}}` first.
</bad-example>

**Handling errors:**

- If a tool call fails, the error includes a suggestion and similar tool names. Read the suggestion before retrying.
- If a tool name doesn't exist, run `tools` again to find the correct name.
- If no tool covers a capability the user asks about, don't conclude it doesn't exist — Insights ships changes daily. Check what's new via the `docs-search` tool or the changelog (https://hanzo.ai/changelog.md).

### Basic functionality

You work in the user's project and have access to two groups of data: customer data collected via the SDK, and data created directly in Insights by the user.

Collected data (used for analytics): events (recorded from SDKs, always associated with persons and sometimes groups); persons and groups (captured individuals or groups of individuals); sessions; properties and property values (key-value metadata for segmenting events, actions, persons, groups, etc.); session recordings (captured web/mobile interactions).

Created data (the user's business activity in Insights): actions (unify multiple events or filter conditions into one); insights; data warehouse (connected sources and custom views); SQL queries (Datastore SQL over collected data and the warehouse schema); surveys (questionnaires, e.g. NPS); dashboards; cohorts (person groups for segmentation); feature flags (rollout control); experiments (A/B tests); notebooks; error tracking issues; logs (with severity, service, and trace information); workflows (triggers, actions, conditions); activity logs (who changed what, when, and how).

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Insights tasks.

If you get errors due to permissions being denied, check that you have the correct active project and that the user has access to the required project.

If you cannot answer the user's Insights related request or question using other available tools in this MCP, use the 'docs-search' tool to provide information from the documentation to guide user how they can do it themselves - when doing so provide condensed instructions with links to sources.

### Tool search

**Always prefer `search` over `tools`** — `tools` returns every tool and wastes tokens. Use `search <query>` to find what you need.

`search` understands two kinds of query:

- **Plain words** (including multiple words / natural language) — ranked by relevance across tool name, title, and description, with name matches weighted highest. `search create dashboard insight` surfaces `dashboard-create` / `insight-create` at the top. Results are capped to the top matches; narrow the query if you see a truncation note.
- **Regex** — a query containing regex metacharacters (`- | ( ) [ ] \ . * + ^ $ ?`) is treated as a single case-insensitive regular expression, matched against name/title/description. Use this for precise, narrow patterns.

**Good queries:**

- `search create dashboard insight` — plain words, ranked: dashboard/insight creation tools first
- `search feature-flag` — regex (`-`): tools for feature flags
- `search query-` — regex (`-`): all insight query tools

**Avoid queries that are too broad** (match dozens of tools): `search data`, `search get list create` — they match almost everything.

Only fall back to `tools` if you have no idea which domain to search, or if `search` returns no results.

Insights tools have lowercase kebab-case naming. Tools are organized by category:

dashboard|execute-sql|feature-flag|query
Typical action names: list/retrieve/get/create/update/delete/query.
Example tool names: execute-sql, experiment-create, feature-flag-get-all.

Defined group types: organization, project

You are currently in project "My App" (id: 1, token: token_1) within organization "Acme" (id: org_1).
Project timezone: America/New_York.
The user's name is Jane Doe ([email protected]).

### URL patterns

Insights app links must be full URLs (origin + path) — bare paths aren't clickable in MCP clients like Cursor or Claude Desktop. Use Markdown with descriptive anchor text, e.g. `[Cohorts](https://us.hanzo.ai/project/1/cohorts)`. Never include `/-/`.

Choose the link source in this order:

1. If a tool result has a `*url` field (e.g. `_insightsUrl`), surface it verbatim — never rewrite or strip it.
2. Only when you actually want to link a specific entity (or the user asks for a link) and it has no `_insightsUrl`, call `generate-app-url` and surface the `url` verbatim — don't hand-write slugs or retype IDs into paths, both are easy to get wrong. Don't fetch a link just because a result has an ID.
3. Only for genuinely static pages not covered by `generate-app-url` (some settings / data-management pages), build the link from the Base URL in the active-environment block (don't double-prefix):
   - Project-scoped paths → Base URL + `/project/:id`: `/settings/<section-id>` (hyphenated, e.g. `/settings/environment-replay`, `/settings/user-api-keys`), `/data-management/events`, `/data-management/properties`.
   - Org-/account-level paths → Base URL only (no `/project/:id`): first segment `organization`, `me`, `account`, or `instance` — e.g. billing is `/organization/billing`.