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 its replacement in search(type:"branch") ships.

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 returns 400. 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. Uses vector similarity, not keyword matching — "user signed up" matches Account Created or Registration Completed.
• 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

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
}

Common errors

• query and structural filters combined — returns 400. Choose one mode.
• 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. For events, includePropertyDetails: true returns each property’s type, constraints, and allowed values inline.
• Workspace metadata — source, destination, groupType. Pass id or name for one item; omit both to enumerate the workspace list.
• Workspace config — workspaceConfig. 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.
• Branches — branch. Identify with branchId or branchName. Use include to pick content: "overview" (branch metadata + baseline status), "changes" (diff vs. main, like the web branch screen), "code_snippets" (per-source generated code; requires sourceId). 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 when id/name is provided, or a workspace-level list when both are omitted.
• type: "branch" — branch facets requested via include. overview returns resolved emails for the creator, reviewers, and collaborators, branch status, impacted source IDs, and description. changes returns the structured diff (new, modified, and deleted events with their properties and descriptions). 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: "workspaceConfig" — 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.

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 changes and code_snippets in include. sourceId scopes the diff to a single source.

{
  "type": "branch",
  "branchName": "checkout-v2",
  "include": ["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

Batch create, update, remove, and archive events, properties, event variants, property bundles, and metrics 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 100 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)

Update-property fields: (require propertyId)

Update-property_bundle fields: (require propertyBundleId)

Update-metric fields: (require metricId)

Archive-event: (require eventId)

{ op: "archive", type: "event", eventId: "..." } archives the event on the branch. { op: "remove", type: "event", eventId: "..." } is accepted as a legacy alias and behaves identically.

Remove-property: (require propertyId)

{ op: "remove", type: "property", propertyId: "..." } archives the property on the branch and cascades removal references on every event that uses it, mirroring the Avo UI. Properties use op: "remove" for archive — there is no separate op: "archive" for properties. The action is destructive but reversible from the Avo app. If you only have the property name, look up the ID first with get or search so that any name-conflict ambiguity is surfaced before the mutation runs.

Remove-property_bundle: (require propertyBundleId)

{ op: "remove", type: "property_bundle", propertyBundleId: "..." } archives the bundle on the branch. Bundles use op: "remove" for archive — there is no separate op: "archive" for bundles.

Archive-metric: (require metricId)

{ op: "archive", type: "metric", metricId: "..." } archives the metric on the branch.

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 pre-existing events — a same-batch create-event item isn’t visible to eventConfigs yet, so create the event in an earlier call (or the same batch, ordered before the property update that references it).

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; and within nested metric fields (items[].metricId / eventId / baseEventId, cohortConditions[].eventId / propertyId). Source and destination IDs must be real IDs — save_items does not create those entity 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, archivedEntities — each entry has name, entityId, and entityType (event, property, event_variant, property_bundle, or metric).
• 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": [],
  "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 100) — batch is over the 100-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

Branch-lifecycle write operations. Currently supports two actions:

• create_branch — open a new branch.
• update_branch_description — set the description on an existing open branch.

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.

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."
}

Common errors

• Missing write scope — re-authorize with write.
• Workspace access denied.
• Unsupported action value.
• Both branchId and branchName provided — update_branch_description requires exactly one.

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 pageSize (outside 1–50).
• Invalid date format on createdAfter / createdBefore.