Avo MCP tools reference

Every tool except list_workspaces operates on a workspace. Pass workspaceId as a parameter; stdio clients can also set the WORKSPACE_ID environment variable.

The MCP exposes five canonical tools mapped to agent intents:

Branch read flows are covered by get and search. One transitional tool — list_branches — remains available while branch enumeration is folded into search (as itemType: "branch").

list_workspaces

Scope: read

List the Avo workspaces the authenticated user has access to. Call this first to discover workspace IDs before invoking any workspace-scoped tool.

Parameters

None.

Returns

One row per workspace: name, workspace ID, and the user’s role.

Examples

Discover the workspaces you can access

Prompt: “What Avo workspaces do I have access to?”

Claude calls list_workspaces with no parameters and uses the returned workspaceId to scope every other tool call in the session.

search

Scope: read

Find tracking plan items in one of two modes — the mode is selected automatically by which parameters you pass. Combining query with structural filters is rejected (the tool returns an error message, not an HTTP status) — pick one mode. branch and pageToken are filter-mode only and likewise cannot be combined with query. For ID-based lookups use get.

• Semantic search — pass query to find items by meaning across events, properties, metrics, categories, property bundles, and event variants. Avo embeds each item with OpenAI embeddings and runs a vector-similarity search at query time, so "user signed up" matches Account Created or Registration Completed even when no keyword overlaps.
• Structured listing — omit query and pass filters to enumerate exact matches with keyset pagination.

Parameters

Shared across modes

Semantic mode (pass query)

Semantic search is performed against the main branch only. The semantic index may lag slightly for very recently created or updated items.

Filter mode (omit query, pass any of the filter fields)

Multiple values inside one array are OR’d; values across different filter keys are AND’d.

Returns

A Markdown document (not JSON) — a # Search Results heading, a result count, and a ranked table. Rows are ordered best-match first; there is no relevance score (ranking uses a fused rank, not an intuitive 0–100% relevance). Descriptions are truncated to ~80 characters.

• Semantic mode columns: Rank | Name | Type | Item ID | Branch | Description.
• Filter mode columns: Rank | Name | Type | Item ID | Description — event-variant rows instead use Rank | Name | Base Event | Variant ID | Description.

In filter mode, when more results are available the document ends with a Next page instruction: call search again with the same itemType / filters / branch plus the supplied pageToken (the token alone is not enough — you must repeat the original filters). Any filters that were ignored or coerced are listed under a Filter warnings section.

# Search Results
 
Found 2 results for "user signed up"
 
| Rank | Name | Type | Item ID | Branch | Description |
|------|------|------|---------|--------|-------------|
| 1 | **Account Created** | event | evt-9f2b… | main | Sent when a new account is successfully created. |
| 2 | **Signup Started** | event | evt-3c11… | main | Sent when the user opens the signup screen. |

Examples

Find events by meaning (semantic)

Prompt: “What events do we have for signup?”

Claude passes the user’s phrasing directly to query. Semantic mode returns events whose meaning matches the query, even when the exact words differ — "user signed up" will match Account Created or Registration Completed.

{
  "query": "user signed up",
  "itemType": "event",
  "maxResults": 5
}

List events using a specific property (filter)

Prompt: “Which events on iOS use the product_id property?”

Filter mode is selected by omitting query. Multiple filter keys are AND’d, so this returns only events that reference product_id and are tracked from the iOS source.

{
  "itemType": "event",
  "properties": ["product_id"],
  "sources": ["iOS"],
  "maxResults": 50
}

Common errors

• query and structural filters combined — rejected with an error (no HTTP status). Choose one mode.
• query combined with branch or pageToken — rejected; those are filter-mode-only parameters.
• Smart Search not enabled in the workspace — semantic mode fails; fall back to filter mode or get.
• Workspace access denied.

get

Scope: read

Get item details for any of four type families:

• Tracking-plan items — event, property, metric, category, propertyBundle, eventVariant. Look up by id or exact name — except eventVariant, which is identified by the base event’s id plus variantId (never by name). For events, includePropertyDetails: true returns each property’s type, constraints, and allowed values inline.
• Workspace metadata — source, destination, groupType. get returns a single item, so pass id or name. To enumerate the workspace list, use search (itemType: "source" / "destination" / "groupType").
• Workspace config — workspaceConfig. Naming/casing rules and event/property validation rules (with the enforcement point), custom-field definitions, the PII type list, and the workspace’s tags and categories. Custom-field and PII-type names plug straight into search’s customField and pii filters.
• Branches — branch. Identify with branchId or branchName. Use include to pick content: "overview" (branch metadata + baseline status + resolved creator/reviewer/collaborator emails + impacted sources + comments/approvals stats), "all_changes" (full diff vs. main, like the web branch screen), "event_changes" (events + event variants only), "property_changes" (properties + property bundles + categories only), "code_snippets" (per-source generated code; requires sourceId), "implementation_guide" (numbered implementation steps + per-event codegen instructions). Multiple values union, and event_changes + property_changes equals all_changes. include defaults to ["overview"].

Defaults to the main branch when no branch is specified.

Parameters

Returns

Full details for the item, shaped per item type.

• type: "event" \| "property" \| "metric" \| "category" \| "propertyBundle" \| "eventVariant" — the item’s full definition.
• type: "source" \| "destination" \| "groupType" — a single entity; id or name is required (enumerate the workspace list with search).
• type: "branch" — branch facets requested via include. overview returns resolved emails for the creator, reviewers, and collaborators, branch status, impacted source IDs, comments/approvals stats, and description. all_changes returns the full structured diff vs. main (new, modified, and deleted events and properties with their descriptions); event_changes and property_changes return just the event- or property-side of that diff. code_snippets returns per-event code diffs for the source named in sourceId — exact unified diffs for Avo Codegen sources and illustrative pseudocode for manually-instrumented sources. implementation_guide returns numbered implementation steps plus per-event codegen instructions (scoped to sourceId when provided).
• type: "workspaceConfig" — the workspace’s event/property naming conventions and casing rules, the event and property validation rules (with their severities and the enforcement point — where Avo blocks), custom field definitions, the list of recognized PII types, and the workspace’s tags and categories listings. Use this before proposing new events or properties so names match the workspace’s audit rules.

Examples

Look up an event by exact name

Prompt: “How is the Account Created event defined?”

Claude calls get with the exact name and includePropertyDetails: true so the response includes each attached property’s type, constraints, and allowed values. Useful when the agent already knows the canonical name and wants the full schema in one call.

{
  "type": "event",
  "name": "Account Created",
  "includePropertyDetails": true
}

Read what changed on a branch

Prompt: “What’s on the checkout-v2 branch — and can you show me the iOS code diff?”

Claude calls get with type: "branch" and combines all_changes and code_snippets in include. sourceId scopes the diff to a single source.

{
  "type": "branch",
  "branchName": "checkout-v2",
  "include": ["all_changes", "code_snippets"],
  "sourceId": "src-ios"
}

Common errors

• Item not found.
• Ambiguous name (returns multiple matches — narrow by ID).
• sourceId missing when include contains code_snippets.
• Workspace access denied.

save_items

Scope: write · Destructive: archive (and legacy remove)

Batch create, update, archive, and unarchive events, properties, event variants, property bundles, metrics, categories, sources, destinations, and group types on a branch. A single call can mix item types and operations, and can cross-reference new items via temporary IDs.

Parameters

Top-level

The request is capped at 50 items per call.

Item shape

Every item shares these fields:

Supported ops by type:

Create-event fields:

Create-property fields:

Create-event_variant fields:

Create-property_bundle fields:

Create-metric fields:

Update-event fields: (require eventId)

Update-event_variant fields: (require baseEventId + variantId)

The variant override surface uses a three-state lattice — add* / remove* / clear* — for attached properties, source overrides, bundle overrides, and variant property regex overrides. Use add* / remove* for incremental changes; use clear* only when you need to wipe the whole set in one call.

Update-property fields: (require propertyId)

Update-property_bundle fields: (require propertyBundleId)

Update-metric fields: (require metricId)

Update-category fields: (require categoryId)

Source, destination, and group-type items:

These workspace-metadata types also support create / update / archive / unarchive. On create, set the shared name field and supply either the type’s ID or a tempId; on update / archive / unarchive, supply the type’s ID (sourceId / destinationId / groupTypeId).

The tool’s per-field schema (the describe text on each parameter) is the authoritative reference for the full set of accepted fields.

Archive and unarchive (every archivable type). op: "archive" archives an item on the branch; op: "unarchive" restores it. Both take the type’s lookup-ID field (eventId, propertyId, propertyBundleId, metricId, categoryId, sourceId, destinationId, groupTypeId) — or, for event variants, baseEventId + variantId. All archives are reversible from the Avo app.

op: "remove" on any type other than event / property is rejected with an error directing you to op: "archive".

Owner and stakeholder fields

owner and stakeholders fields are accepted on event, property, and event variant items (both create and update):

Merging categories

The MCP has no dedicated “merge categories” op. To merge category A into category B, send a single save_items batch containing:

1. An update item for every event, property, and metric in A carrying addCategories: ["B"], removeCategories: ["A"].
2. A { op: "archive", type: "category", categoryId: "<id of A>" } item.

Both must travel in the same batch — the category archive in step 2 does not cascade to its members, so step 1 has to move the members first.

Per-event property settings (eventConfigs)

eventConfigs is a top-level array on an update-property item (and, restricted to events: { kind: "allEvents" }, on a create-property item). Each entry adjusts how the property behaves on a specific event or across all events:

• setPresence — change presence to alwaysSent, sometimesSent, or neverSent. Can be scoped per source.
• setPinnedValue — pin a value for the property. With events: { kind: "onEvent" } pins per-event; with events: { kind: "allEvents" } pins property-wide.
• restrictAllowedValues — change the property’s allowed value list for an event. Carries a valuesChange delta: addValues (non-empty), removeValues, or clear (no payload).

eventConfigs entries reference events by eventId, and $tmp: references are supported here: an eventConfigs[*].events.eventId (or eventIds) may point at a create-event item earlier in the same batch via $tmp:, and preprocessing rewrites it to the real event ID before saving — no separate call needed. (On a property create, the referenced event must also attach this property in the same batch, otherwise the call fails with UnresolvableReference.)

Temporary IDs (tempId / $tmp:)

To reference a newly-created item from another item in the same call, declare a tempId on the create item and reference it elsewhere as "$tmp:<name>":

• tempId is create-only — setting it on an update, remove, or archive returns an error.
• tempId names must be unique within a single save_items call.
• $tmp: references are resolved in these array fields: properties, addProperties, removeProperties, attachProperties, propertyBundles, addPropertyBundles, removePropertyBundles, attachToEvents, addSources, removeSources, bundleOverrides; inside overrides[].propertyId / addComponentOverrides[].propertyId; within eventConfigs[*].events.eventId / eventIds; and within nested metric fields (items[].metricId / eventId / baseEventId, cohortConditions[].eventId / propertyId). In addCategories / removeCategories / addGroupTypes / removeGroupTypes, a $tmp: ref instead rewrites to the sibling create item’s name (those fields take names, not IDs). Sources, destinations, and group types can be created in the same batch and referenced by their tempId too.
• If a $tmp: ref names a tempId that wasn’t declared on any item, the server returns a validation error.

Returns

A structured result with:

• createdEntities, updatedEntities, removedEntities, unarchivedEntities — each entry has name, entityId, and entityType (event, property, event_variant, property_bundle, metric, category, source, destination, or groupType). Archived items are reported under removedEntities (a legacy field name); restored items under unarchivedEntities. (updatedEntities entries may also carry a reason when the update was a no-op.)
• errors — per-item validation or audit errors, each with the item index, name, and a message.
• warnings — non-fatal notices, same shape as errors.
• success — overall boolean.

{
  "success": true,
  "createdEntities": [
    { "name": "Checkout Method", "entityId": "prop-9d44…", "entityType": "property" }
  ],
  "updatedEntities": [
    { "name": "Checkout Completed", "entityId": "evt-3f01…", "entityType": "event" }
  ],
  "removedEntities": [],
  "unarchivedEntities": [],
  "errors": [],
  "warnings": []
}

Examples

Create a new event with a new property in one call

Prompt: “Add a Checkout Completed event with a Checkout Method property for Web and iOS.”

Claude declares a tempId on the new property so the new event can attach it before the server has allocated a real ID. The server resolves the $tmp: reference, allocates the real propertyId, attaches the property to the event, and includes the event in both sources — all atomically.

{
  "branchId": "br-abc123",
  "items": [
    {
      "op": "create",
      "type": "property",
      "tempId": "checkout_method",
      "name": "Checkout Method",
      "propertyType": "string",
      "sendAs": "event",
      "description": "How the user completed checkout"
    },
    {
      "op": "create",
      "type": "event",
      "name": "Checkout Completed",
      "description": "Fired when the user finishes checkout",
      "properties": ["$tmp:checkout_method"],
      "sources": ["src-web", "src-ios"]
    }
  ]
}

Define a checkout funnel metric

Prompt: “Add a funnel metric on this branch that tracks the share of users who start checkout and complete it.”

Claude creates a Funnel metric whose items reference two existing events in order. The same call could chain in new events with $tmp: references if the funnel needed events that don’t exist yet.

{
  "branchId": "br-abc123",
  "items": [
    {
      "op": "create",
      "type": "metric",
      "name": "Checkout Funnel",
      "description": "Share of users who start checkout and complete it.",
      "metricType": "Funnel",
      "items": [
        { "eventId": "evt-checkout-started" },
        { "eventId": "evt-checkout-completed" }
      ]
    }
  ]
}

Common errors

• Missing write scope — the client must re-authorize with write.
• branchId is required / items is required — malformed request.
• tempId is only valid on create items — don’t set tempId on update or remove.
• Duplicate tempId "<name>" — each tempId must be unique across items in the batch.
• Unknown $tmp: reference — a $tmp: ref names a tempId that wasn’t declared.
• <idField> is required for <op> <entity> items — missing eventId / propertyId / baseEventId / variantId / propertyBundleId / metricId.
• too many items (got N, max 50) — batch is over the 50-item cap.
• NotYetImplemented — one of the unsupported operations above.
• Per-item audit-pipeline validation failures (e.g. illegal name, duplicate property, etc.) — returned inside the errors array rather than failing the whole call.

workflow

Scope: write · Destructive: import with importMethod: "add_update_and_remove"

Branch-lifecycle write operations, selected by the action parameter. Five actions are supported:

• create_branch — open a new branch.
• update_branch_description — set the description on an existing open branch.
• pull_main — pull the latest changes from main into an open branch. Requires Codegen access; on overlapping changes, incoming main changes win.
• set_source_language — set a source’s programming language on an open branch.
• import — bulk-import a tracking-plan export (CSV or Avo JSON Schema) into an open branch. Requires Admin role; never targets main.

Parameters

Which parameters apply depends on action — see “Required” below.

Returns

• create_branch — the new branch’s branchId, branchName, and a branchUrl that opens it in the Avo web app.
• update_branch_description — confirmation with the resolved branchId and the updated description.
• pull_main — confirmation that main was pulled into the branch.
• set_source_language — confirmation with the resolved source and language.
• import — a summary of what the import added, updated, and removed on the branch.

Examples

Create a branch for a new feature

Prompt: “Start an Avo branch for the new checkout flow we’re shipping next sprint.”

Claude calls workflow with action: "create_branch" and a descriptive branchName. The returned branchId is required for the follow-up save_items calls that write the new events and properties.

{
  "action": "create_branch",
  "branchName": "add-checkout-tracking"
}

Update a branch’s description

Prompt: “Update the description on the add-checkout-tracking branch to mention that we’re now also tracking abandonment.”

Claude looks up the branch by name (no separate branchId lookup needed for this action) and replaces the description in one call.

{
  "action": "update_branch_description",
  "branchName": "add-checkout-tracking",
  "description": "Adds the Checkout Completed and Checkout Abandoned events with the Checkout Method property."
}

Set a source’s codegen language

Prompt: “Set the iOS source on the add-checkout-tracking branch to Swift.”

Claude resolves the sourceId with get (type: "source"), then sets the language on the branch.

{
  "action": "set_source_language",
  "branchName": "add-checkout-tracking",
  "sourceId": "src-ios",
  "language": "Swift"
}

Bulk-import a tracking plan onto a branch

Prompt: “Import this Amplitude CSV export onto a fresh branch.”

Claude opens a branch with create_branch, then calls import with the CSV payload on the returned branchId. add_only (the default) only appends new items, so it never removes anything.

{
  "action": "import",
  "branchId": "br-abc123",
  "format": "csv",
  "payload": "Event Name,Property Name,...\nCheckout Completed,checkout_method,...",
  "importMethod": "add_only"
}

Common errors

• Missing write scope — re-authorize with write.
• Workspace access denied.
• Unsupported action value.
• Both branchId and branchName provided — update_branch_description and set_source_language require exactly one.
• pull_main without Codegen access, or import without Admin role — permission error.
• set_source_language with a language the source’s platform doesn’t support — the error lists the supported tokens.
• import missing format or payload, or with an unknown format / importMethod token.

list_branches

Scope: read

Browse branches in a workspace with filtering and pagination. Results are paginated newest-first.

Parameters

By default Merged and Closed branches are excluded. Pass branchStatuses: ["Merged"] (or any other value) to include them.

Returns

Compact per-branch summary — name, status, ID, creation date, and (when present) creator email, reviewer count, and description — plus a nextPageToken when more results are available. Call get with type: "branch" and include: ["overview"] for full resolved data.

Examples

Find branches I’m reviewing

Prompt: “What branches am I assigned to review?”

Claude passes the user’s email as reviewerEmail and filters status to ReadyForReview. The tool does not auto-inject the caller’s identity, so the email has to be supplied explicitly.

{
  "reviewerEmail": "thora@avo.sh",
  "branchStatuses": ["ReadyForReview"]
}

Common errors

• Workspace access denied.
• Invalid pageSize (outside 1–50).
• Invalid date format on createdAfter / createdBefore.

Troubleshooting

Tool-specific behavior issues. Authentication and workspace access issues are covered in Troubleshooting on the overview page.

search returns nothing for a clearly relevant query. Semantic search requires Avo Intelligence Smart Search to be enabled. Workspace admins can turn it on in Workspace Settings. Without it, fall back to get with an exact name or search in filter mode.

The wrong branch is returned by name. branchName resolves to a best match and prioritizes open branches, so an ambiguous name can pick the wrong one. Resolve the name to a branchId with list_branches first and pass branchId to the follow-up call.

save_items returns a NotYetImplemented error. Changing a property’s sendAs is not supported — it is immutable after create. (To remove an event variant, use op: "archive"; op: "remove" on a variant is rejected, not NotYetImplemented.) See the save_items reference.