data-designer

# Avo MCP

This skill teaches the agent how to use the Avo MCP server to read and write a customer's *existing* tracking plan. It is the playbook for exploring, searching, designing-against, reviewing, and implementing a plan that already has a meaningful taxonomy, plus the policies and gotchas that keep agents from breaking main.

If the workspace is empty or brand-new and the team is deciding what to track from scratch, use the **data-designer-new-plan** skill instead. Quick empty check: run `search` with `itemType: "event"` and no `query`; very few results means greenfield — switch to that skill.

The Avo MCP server runs at `https://mcp.avo.app/mcp` and exposes these tools:

Read tools: `health_check`, `list_workspaces`, `get`, `search`, `list_branches`, `get_branch_details`, `get_branch_implementation_guide`, `get_branch_code_snippets`.

`get` looks up a single item by id or exact name. It supports `type` values `event`, `property`, `metric`, `category`, `propertyBundle`, `source`, `destination`, `groupType`, `eventVariant`, and `workspaceConfig`. Use `type: "workspaceConfig"` to retrieve the workspace's tracking plan audit rules — i.e. the workspace-wide event naming, property naming, casing, and validation rules — before proposing any new events or properties.

Write tools (require the `write` scope): `workflow`, `save_items`.

The MCP never merges. Merging a branch to main always remains a human step in the Avo web app.

---

## Flow 1: Start session (bootstrap)

Runs once per session, on the first prompt of any kind. Required before any other workspace-scoped tool.

Trigger: any prompt.

Steps:

1. Call `list_workspaces`.
2. If the user named a workspace (by name or id) in their prompt: set that as the active workspace, respond "Workspace set to [Workspace Name]", and continue answering the original question.
3. Else if the user has access to exactly one workspace: set it active silently and continue.
4. Else: return a numbered list of workspaces the user has access to and ask which one they would like to use. Wait for the user to select, then set it active and continue.

Hold the active `workspaceId` in conversation state for the rest of the session. Every workspace-scoped tool needs it.

---

## Flow 2: Explore the tracking plan

Open-ended discovery by meaning.

Trigger prompts:
- "What events do we have for signup?"
- "How do we track a successful checkout?"
- "Is there anything that captures onboarding completion?"

Steps:

If Smart Search is enabled in the workspace:

1. `search` with `query` set to the user's phrasing (semantic mode). Default `itemType` is `event`; widen to other types when the user's phrasing implies it.
2. When the user's phrasing also constrains structurally (e.g. "events on the iOS source", "metrics in category Y", "events with the `product_id` property"), combine the semantic `query` with filter fields (`sources`, `categories`, `properties`, etc.) on the same `search` call to narrow the result set before paging through hits.
3. `get` on each promising hit by id.
4. Report back with the real names returned by `get`, not the semantic paraphrase. Ask if that answered the user's question.

If Smart Search is not enabled:

Return: "You don't have Smart Search enabled in your workspace, so I can only search by exact item names or IDs."
- If the user is a workspace admin: include a short guide on how to turn Smart Search on.
- If the user is not an admin: recommend they ask a workspace admin to enable it.

---

## Flow 3: Find by exact name or ID

Targeted lookup of one item.

Trigger prompts:
- "How is the Signup Completed event defined?"
- "What does the `product_id` property look like?"
- User pastes a name or id.

Steps:

1. `get` with the exact name or id.
2. If `get` finds a match: return the spec of the item in a format that answers the user's question. Ask if that answered their question.
3. If the user pasted multiple names or ids at once: prefer a single filter-mode `search` call (e.g. `itemType: "event", eventNames: ["A", "B", "C"]`) over calling `get` once per name. One call returns the whole set and respects `maxResults` / pagination.
4. If `get` does not find a match:
   - If Smart Search is on: `search` as a fallback (the miss is likely a slight mismatch).
     - If `search` returns at least one hit: `get` on the top hit's id, then return the spec.
     - If `search` returns no hits: tell the user no close match was found, and ask for an exact name/id or a more specific phrasing.
   - If Smart Search is off: tell the user the exact name or id wasn't found, and explain Smart Search would enable fuzzy fallback.

---

## Flow 4: Get a filtered list of items

Structured listing across the plan. Uses `search` in filter mode (no `query`, structural filters instead).

Trigger prompts and how each maps to filter fields:

- "What events is the `product_id` property on?" → `itemType: "event"`, `properties: ["product_id"]`
- "Which events have the `signup` category?" → `itemType: "event"`, `categories: ["signup"]`
- "Which events are name-mapped to `page_view`?" → `itemType: "event"`, `nameMapping: { kind: "matchesAny", names: ["page_view"] }`
- "Which properties are on the `Account Created` event?" → `itemType: "property"`, `eventNames: ["Account Created"]`
- "Which events are tracked from the iOS source?" → `itemType: "event"`, `sources: ["iOS"]`
- "Which events have variants?" → `itemType: "event"`, `includeVariants: true`

Steps:

1. Pick `itemType` from the user's phrasing: `event` (default), `property`, `metric`, `eventVariant`, `category`, or `propertyBundle`.
2. Translate the phrasing into one or more filter fields: `tags`, `categories`, `sources`, `eventNames`, `variantNames`, `properties`, `nameMapping`. Multiple values in one array are OR'd. Multiple keys are AND'd.
3. Call `search` with those filters and no `query` field. This is filter listing mode (cap 500, default 10). Set `includeVariants: true` when the user asks for events with their v