Avo MCP tools reference

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

The MCP exposes a small set of tools mapped to agent intents:

Two more tools round out the surface: list_branches (transitional, stays available while branch enumeration is folded into search) and give_feedback (send product feedback about the MCP to the Avo team — call it when the MCP could not do what you set out to do).

How discovery works

The advertised tool list is deliberately small: the save_items input schema is an index, not the full contract. Many MCP clients silently drop tools whose schema is too large, so the per-type field contracts are served on demand by describe_tool instead of being advertised up front. The flow an agent should follow:

1. Connect. The server’s instructions (what your client receives on initialize) are the capability map — every tool, its item types and actions, and what to call next.
2. describe_tool() — the same capability map plus a short “Designing tracking” guide.
3. describe_tool(tool:"save_items", type:"<type>", op:"<op>") — the exact fields for the item type and operation you are about to write.
4. Write with save_items.

If a save_items item carries an unknown field or an out-of-domain value, the error echoes that type’s contract, so an agent can self-correct without a second describe_tool call.

Item type vocabulary

save_items, search, and get share one snake_case entity vocabulary:

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.

describe_tool

Scope: none — read-only, rendered locally by the MCP server. No workspace data, no branch, no authentication, no side effects.

The on-demand schema and contract index. Call it to get the exact shape of the call you are about to make: the capability map, the save_items item envelope, the per-type field contract for a given operation, the workflow action parameters, and the search / get vocabularies.

Parameters

All parameters are optional strings. There are no nested objects or unions.

Returns

Plain text, shaped by what you asked for:

• describe_tool() — the capability map (the same text as the server instructions) followed by a “Designing tracking” guide and the link to the avo-mcp plugin. The guide only lives in this response, not in the advertised instructions.
• describe_tool(tool:"save_items") — the item envelope explanation and a pointer to call again with a type.
• describe_tool(tool:"save_items", type:"property") — the fields table for that type: one line per field with its name, JSON type, whether it is required, which ops accept it, and a one-line doc. Fields with a closed value set list the accepted values (One of: …); the set object lists its accepted nested keys. Add op:"update" to narrow to one operation.
• describe_tool(tool:"workflow") — the list of actions. Add action:"<action>" for that action’s parameters and an example call.
• describe_tool(tool:"search") / describe_tool(tool:"get") — each read tool’s item-type vocabulary, and for get(type:"branch") the accepted include values.
• Unknown type or action — an error that lists the valid values, so an agent can self-correct from the message alone.

Examples

Learn what a property update accepts before writing one

Prompt: “Rename the product_id property and add two allowed values.”

Before its first property write of the session, Claude fetches the update contract for properties and reads that renames go in set.name while allowed-value changes go in the top-level addAllowedValues.

{
  "tool": "save_items",
  "type": "property",
  "op": "update"
}

The response (abridged):

Fields for property (op: update):
- propertyId (string, required; update/archive/unarchive) — The property's id. Required for update/archive/unarchive.
- addAllowedValues (array; create/update) — Create/update (string property): allowed values to add.
- removeAllowedValues (array; update) — Update only: allowed values to remove …
- isList (boolean; update) — Update: toggle whether the property holds a list of values.
- addCategories (array; update) — Update: category names to attach …
- set (object; update) — Update only: scalar field changes … Nested keys (set.<key>): nameSuffix, description, propertyType, sendAs, name, platform, programmingLanguage, libraryName, libraryDestination, analyticsTool, triggers.

Placement: scalar renames go in set.*; collection deltas at the item top level.
Limits: up to 50 items per call; $tmp: refs resolve within one call.

Get the capability map

Prompt: “What can the Avo MCP do?”

Claude calls describe_tool with no parameters and summarizes the capability map for the user.

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 returns 400. An empty call (no query, no filter, no branch scope) is rejected. 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. Pass itemType alone (no query, no filter) to enumerate sources, destinations, group types, gateways, or journeys.

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.

Pagination

Filter-mode responses include a nextPageToken when more results are available, and end with a “Next page” note. To fetch the next page, call search again with the same parameters — workspaceId, itemType, every filter, the branch, maxResults, and checkpoint when you used it — plus pageToken. The token alone is not sufficient: omitting maxResults reverts the page size to the default, and omitting workspaceId can resolve the next page against a different workspace.

Returns

Ranked results with rank, name, type, item ID, relevance percentage, and a truncated description (80 characters). Filter-mode responses include a nextPageToken when more results are available.

{
  "results": [
    {
      "rank": 1,
      "name": "Account Created",
      "itemType": "event",
      "itemId": "evt-9f2b…",
      "relevance": 0.91,
      "description": "Sent when a new account is successfully created."
    },
    {
      "rank": 2,
      "name": "Signup Started",
      "itemType": "event",
      "itemId": "evt-3c11…",
      "relevance": 0.87,
      "description": "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
}

Enumerate the workspace’s sources

Prompt: “Which sources do we have?”

{
  "itemType": "source"
}

Common errors

• query and structural filters combined — returns 400. Choose one mode.
• Empty call (no query, no filter, no branch scope) — rejected.
• 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, property_bundle, event_variant. Look up by id or exact name. For events, includePropertyDetails: true returns each property’s type, constraints, and allowed values inline. event_variant takes the base event’s id plus variantId.
• Workspace metadata — source, destination, group_type, gateway. Pass id or name for one item; to enumerate the list, use search with that itemType and no query.
• Workspace config and journeys — workspace_config (takes no id) returns naming/casing rules, custom-field definitions, and the PII type list; custom-field and PII-type names plug straight into search’s customField and pii filters. journey requires an id (enumerate with search(itemType:"journey")).
• Branches — branch. Identify with branchId or branchName. Use include to pick content. 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" \| "property_bundle" \| "event_variant" — the item’s full definition. Events, properties, and event variants include owner and stakeholders.
• type: "source" \| "destination" \| "group_type" \| "gateway" — a single entity.
• type: "branch" — the facets requested via include. overview returns resolved emails for the creator, reviewers, and collaborators, branch status, impacted source IDs, and description. all_changes (or the narrower event_changes / property_changes) returns the structured diff (new, modified, and deleted items with their properties and descriptions). implementation_guide returns the diff organized for an implementer. 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.
• type: "workspace_config" — the workspace’s event/property naming conventions and casing rules, plus custom field definitions and the list of recognized PII types. Use this before proposing new events or properties so names match the workspace’s audit rules.
• type: "journey" — the journey’s definition.

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 ops

Batch create, update, archive, and unarchive tracking-plan items on a branch: events, properties, event variants, property bundles, metrics, categories, sources, destinations, group types, and gateways. 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 envelope

Every item has the same six-key shape. The type-specific content goes inside fields:

{ "op": "create", "type": "event", "id": "…", "name": "…", "tempId": "…", "fields": { } }

Identity ID per type (for update / archive / unarchive):

Inside fields, three placement rules apply to every type:

• Scalar edits go in set (update only). set is a nested object with a closed key set: name, description, nameSuffix, propertyType, sendAs, platform, programmingLanguage, libraryName, libraryDestination, analyticsTool, triggers. Not every key applies to every type; unknown keys are rejected. set.sendAs is accepted only on create — a property’s sendAs is immutable after creation.
• Collection changes stay at the top level of fields — addProperties / removeProperties, addCategories / removeCategories, addAllowedValues / removeAllowedValues, and every other add* / remove* / clear* field.
• description is create-only, and only for types whose create reads it: event, property, event_variant, property_bundle, metric, category. A create for a source, destination, group_type, or gateway that carries description is rejected. On update, use set.description.

Validation is strict. An unknown key in fields, a field the current op doesn’t accept (set on a create, description or tempId on an update, removeAllowedValues on a create), or a value outside a field’s domain is rejected up front. The error names the (type, op) and echoes the type’s field contract.

Field contracts by type

The tables below are the describe_tool(tool:"save_items", type:"<type>") output at the time of writing. The live response is authoritative. Fields marked create/update are accepted on both ops; the identity ID field is required on update / archive / unarchive. tempId (create only) and set (update only) apply to every type and are omitted from the tables.

event

property

event_variant

The override surface is a three-state lattice — add* / remove* / clear* — for attached properties, source overrides, bundle overrides, and regex overrides. Use add* / remove* for explicit overrides; use clear* to fall back to the base event.

property_bundle

Bundle-to-event attachment after creation is managed from the event side via addPropertyBundles / removePropertyBundles on an event update.

metric

category

Category membership is managed from the member side: addCategories / removeCategories on event, property, and metric updates.

source

A create for a source does not accept description.

destination

A create for a destination does not accept description.

group_type

A create for a group type does not accept description. Attach group types to events with addGroupTypes on an event update.

gateway

A property ID may appear in only one of add / remove / clear transformation fields per item. A create for a gateway does not accept description.

Name mappings

nameMappings is accepted on event and property items, on create and update. Each entry is { destination, name }, where destination is { kind: "allDestinations" } or { kind: "destination", destinationId: "…" }. name must be a non-empty string when present; pass name: null (or omit it) to remove the mapping for that destination. On a create there is nothing to remove yet, so a name: null entry is a harmless no-op. Multiple entries are allowed, one per destination scope.

Owner and stakeholder fields

owner and stakeholders are accepted inside fields 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 fields: { addCategories: ["B"], removeCategories: ["A"] }.
2. A { op: "archive", type: "category", id: "<id of A>" } item.

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

Per-event property settings (eventConfigs)

eventConfigs is an array inside fields on a property item (create or update; max 50 entries). Each entry adjusts how the property behaves on a specific event, on several events, or across all events:

• setPresence — change presence to alwaysSent, sometimesSent, or neverSent. Can be scoped per source. sometimesSent on allEvents requires a migrated workspace.
• 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).

Per-event scopes (events.kind = "onEvent" / "onEvents") name events by persisted ID or $tmp: reference, on update and create. On a create, the batch must also attach the property to the referenced event (via $tmp:), otherwise the reference is unresolvable. allEvents entries apply to the freshly created property directly.

Temporary IDs (tempId / $tmp:)

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

• tempId is create-only — setting it on an update, archive, or unarchive returns an error.
• tempId names must be unique within a single save_items call and match ^[\w-]+$ (max 64 characters).
• $tmp: references resolve within one call only. Across calls, use the real ID returned from the previous call.
• ID fields that accept $tmp: are ID-or-$tmp: only — a literal name is rejected. Fields that take names (addCategories / removeCategories, addGroupTypes / removeGroupTypes) rewrite a $tmp: ref to the sibling create’s name instead.
• Sources and destinations created in the same batch can be referenced by $tmp: too, since save_items creates those types.
• 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. Created entries also echo the tempId you supplied, so you can map temporary handles to real IDs.
• 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", "tempId": "checkout_method" }
  ],
  "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",
      "fields": {
        "description": "How the user completed checkout",
        "propertyType": "string",
        "sendAs": "event",
        "addAllowedValues": ["Card", "Apple Pay", "PayPal"]
      }
    },
    {
      "op": "create",
      "type": "event",
      "name": "Checkout Completed",
      "fields": {
        "description": "Sent when a user successfully pays and their order is placed.",
        "properties": ["$tmp:checkout_method"],
        "sources": ["src-web", "src-ios"]
      }
    }
  ]
}

Rename a property and add an allowed value

Prompt: “Rename user_email to email and allow the value Unknown on Checkout Method.”

Scalar edits go in set; collection changes stay at the top level of fields.

{
  "branchId": "br-abc123",
  "items": [
    {
      "op": "update",
      "type": "property",
      "id": "prop-1a2b…",
      "fields": { "set": { "name": "email" } }
    },
    {
      "op": "update",
      "type": "property",
      "id": "prop-9d44…",
      "fields": { "addAllowedValues": ["Unknown"] }
    }
  ]
}

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",
      "fields": {
        "description": "Share of users who start checkout and complete it.",
        "metricType": "Funnel",
        "items": [
          { "kind": "Event", "id": "step1", "eventId": "evt-checkout-started" },
          { "kind": "Event", "id": "step2", "eventId": "evt-checkout-completed" }
        ]
      }
    }
  ]
}

Archive an event

{
  "branchId": "br-abc123",
  "items": [
    { "op": "archive", "type": "event", "id": "evt-3f01…" }
  ]
}

Common errors

• Missing write scope — the client must re-authorize with write.
• branchId is required / items is required — malformed request.
• Unknown field, wrong-op field, or out-of-domain value in fields — the error names the (type, op) and echoes the type’s contract. Call describe_tool with that type and op.
• name missing on a create.
• tempId is only valid on create items — don’t set tempId on update, archive, or unarchive.
• 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 identity ID.
• id and fields.<idField> both present with different values.
• too many items (got N, max 50) — batch is over the 50-item cap.
• 403 on a gateway write — the workspace does not have gateways enabled.
• Per-item audit-pipeline validation failures (e.g. illegal name, duplicate property) — returned inside the errors array rather than failing the whole call.

workflow

Scope: write

Branch-lifecycle write operations, dispatched by action:

Call describe_tool with tool:"workflow" and an action for that action’s parameters and an example call.

Parameters

Returns

For create_branch: the new branch’s branchId, branchName, and a branchUrl that opens it in the Avo web app. For update_branch_description: confirmation with the resolved branchId and the updated description. The other actions return a confirmation of what changed 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."
}

Import a JSON Schema tracking plan into a branch

{
  "action": "import",
  "branchId": "br-abc123",
  "format": "json_schema",
  "importMethod": "add_and_update",
  "payload": "{ \"$schema\": … }"
}

Common errors

• Missing write scope — re-authorize with write.
• Workspace access denied.
• Unsupported action value — the error lists the valid actions.
• Both branchId and branchName provided where exactly one is expected.
• language not valid for the source’s platform.

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, creator email — 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 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 rejects an item with a contract in the error. The item carried a field that type or op does not accept, or a top-level field that belongs inside fields. Read the echoed contract, or call describe_tool with the same type and op, and retry. Older examples that put fields like propertyType directly on the item (outside fields) no longer work.

My client does not show save_items at all. Some MCP clients drop tools whose advertised schema exceeds their size limits. The Avo MCP keeps every advertised schema small precisely so this does not happen; if it still does, make sure the client is talking to https://mcp.avo.app/mcp and report it to support@avo.app.