Available Tools

The Intelligems MCP Server exposes your Intelligems to AI assistants as a set of tools. This page lists every tool, what it does, and its parameters.

Conventions

A few things apply to nearly every tool:

organization — Every tool accepts an optional organization parameter (name or ID). If omitted, the tool runs against your current organization. Agencies and multi-store users can pass it per call to work across stores in one session.
IDs — Experience and experiment IDs are UUIDs. Get them from search_experiments, search_experiences, list_experiments, or get_experiences_list_full.
Currency — Money values are returned in the store's default currency. Use get_shop_info to check which.
Large results — Tools that can return very large datasets (exports, full price matrices) return a presigned S3 download URL valid for roughly 15 minutes rather than inlining the data.

Organization & Configuration

list_organizations

List all Intelligems organizations you have access to. Supports filtering by installation status and sorting.

Parameters:

isInstalled (optional): Filter by installation status. Default: true
sortBy (optional): "name", "shopId", "createdAt", "lastLogin"
nameContains (optional): Filter by name (case-insensitive substring match)
limit (optional): Maximum results to return

Example response:

json

{
  "organizations": [
    {
      "id": "org_123abc",
      "name": "My Shopify Store",
      "shopId": "12345",
      "isInstalled": true,
      "createdAtTs": "2024-01-15T10:30:00Z",
      "lastLoginTs": "2024-12-01T14:22:00Z"
    }
  ],
  "totalCount": 5,
  "returnedCount": 5,
  "truncated": false
}

get_organization

Get detailed information about a specific organization, including currency, timezone, Shopify settings, and enabled features.

Parameters:

organization (optional): Organization name or ID

get_shop_info

Get basic store metadata — store name, domain, currency, Shopify plan, and timezone. Useful for confirming which currency and timezone analytics results are expressed in.

Parameters:

organization (optional): Organization name or ID

list_integrations

List all active integrations for an organization (Google Analytics, Klaviyo, Recharge, Slack, etc.).

Parameters:

enabled (optional): Filter by enabled status
integrationName (optional): Filter by exact integration name
nameContains (optional): Filter by name (case-insensitive substring match)
limit (optional): Maximum results to return
organization (optional): Organization name or ID

Example response:

json

{
  "integrations": [
    { "name": "google_analytics", "enabled": true },
    { "name": "recharge", "enabled": true }
  ]
}

Finding Experiences & Experiments

These four tools cover discovery. Use the search_* tools when you need to find something by name or status; use the list_* tools when you need full configuration.

search_experiments

Find or discover A/B tests, price tests, and experiments. Returns minimal info (id, name, status, description, type, timestamps, variation count).

Parameters:

status (optional): "pending", "started", "ended", "paused"
nameContains (optional): Case-insensitive partial name match
sortBy (optional): "name", "createdAt", "lastUpdate", "startedAt", "endedAt"
sortOrder (optional): "asc" or "desc" (default)
limit (optional): Maximum results per page
page (optional): Page number, 1-based
organization (optional): Organization name or ID

search_experiences

Same as above, but for experiences (long-running, evergreen shopper experiences rather than A/B tests).

Parameters: Same as search_experiments

list_experiments

Full experiment details including variations, targeting rules, and configuration.

Parameters: Same as search_experiments

Example response:

json

{
  "experiences": [
    {
      "id": "exp_456def",
      "name": "Holiday Price Test",
      "type": "experiment",
      "status": "started",
      "createdAtTs": "2024-12-01T00:00:00Z",
      "variations": [
        { "id": "var_1", "name": "Control", "trafficAllocation": 50 },
        { "id": "var_2", "name": "10% Discount", "trafficAllocation": 50 }
      ],
      "targeting": {
        "countries": ["US", "CA"],
        "deviceTypes": ["desktop", "mobile"]
      }
    }
  ]
}

get_experiences_list_full

Full experience details including variations, targeting rules, and configuration.

Parameters: Same as search_experiments

get_experience

Detailed information about one specific experiment or experience: variations, targeting rules, and configuration.

Parameters:

id (required): UUID of the experiment or experience
organization (optional): Organization name or ID

get_experience_metrics_config

The success metrics configured for a specific test (revenue, conversion rate, AOV, custom goals). Returns configuration only, not performance data — use analyze_experience for results.

Parameters:

experienceId (required): UUID of the experiment or experience
organization (optional): Organization name or ID

Creating & Managing Experiences

These tools write to your Intelligems account. Your AI client will ask you to confirm before running them.

create_experience

Create a new experience or experiment. Available fields depend on the experience type (content, offers, and so on).

Parameters:

Experience configuration fields — name, type, variations, targeting, and traffic allocation
organization (optional): Organization name or ID

New experiences are created as drafts. They reach no shoppers until explicitly started.

update_experience

Update the non-price fields of an existing experience: metadata, variations, targeting rules, traffic allocation, and other configuration. To change prices on a price test, use the price test tools below.

Parameters:

id (required): UUID of the experience to update
Fields to change
organization (optional): Organization name or ID

experience_action

Perform a lifecycle action on an experience: start, pause, or end it.

Parameters:

id (required): UUID of the experience
action (required): "start", "pause", or "end"
organization (optional): Organization name or ID

Price Test Products

Price changes use a prepare → review → commit pattern. The prepare tools stage a change and return a human-readable diff plus a productVariantAction reference; nothing is applied until you pass that reference to commit_price_test_products. Commits update prices only — audience targeting, page targeting, and every other field are preserved.

get_price_test_products

Read the current per-variant prices and test groups for an existing price test. Returns each product with its variants and per-group prices, each row carrying its variationId and group name (e.g. Control Group, New Group 1).

Small result sets return inline; large ones return a presigned S3 URL. Use the title filters for targeted edits so you don't pull the whole product matrix.

Parameters:

experienceId (required): UUID of the price test
productTitleContains (optional): Return only products whose title contains this substring
variantTitleContains (optional): Within those products, keep only matching variants
organization (optional): Organization name or ID

prepare_price_test_products

Quick-fill prices across a test group by intent. Applies a relative price transform (percent or dollar delta, with optional rounding) to the targeted group and stages the result.

Parameters:

experienceId (required): UUID of the price test
scope (required): What to transform — a whole test group ({ type: "variation", variationId }), specific products ({ type: "products", variationId, productIds }), or specific variants ({ type: "variants", variationId, variantIds })
transform (required):
- change (required): Magnitude of the change; negative to lower prices
- changeUnit (required): "percent" or "dollar"
- roundingType (optional): "none", "nearest", "up", "down"
- roundingAmount (optional): Fractional target, e.g. 0.99
organization (optional): Organization name or ID

This tool applies relative changes only. To set an exact price, read current prices first and pass the difference as a dollar change.

commit_price_test_products

Apply a staged price change to a price test. Processed asynchronously — the response reports the change as queued, not live.

Parameters:

experienceId (required): UUID of the price test
productVariantAction (required): The staged reference returned by a prepare tool, passed through unchanged
organization (optional): Organization name or ID

Test Results & Analytics

analyze_experience

The main results tool. Returns performance metrics, statistical significance, and variation comparisons for both experiments and experiences.

Parameters:

experienceId (required): UUID of the experiment or experience
view (optional): "overview" (default) for aggregate metrics, "audience" for a segment breakdown, "post_test" for post-test customer value
audience (optional): Required when view="audience" — device_type, visitor_type, source_channel, source_site, country_code, landing_page_full_path
testResult (optional): When true, also returns a verdict — strong_win, directional_win, directional_loss, strong_loss, mixed_signals, or not_ready until the test has roughly 7+ days live and 300+ orders per group
analyticsViewType (optional): "sitewide_orders" or "test_orders_only". Defaults to the experience's configured value.
includeInTestOrders (optional): Only for view="post_test". Default true.
topN (optional): Only for view="audience". Caps the breakdown at the top N segments by visitor count (1–1000).
graphs (optional): { ids: [...], outputFormat: "png" | "base64" } to render branded charts inline. See Charts for the 30 available chart IDs.
start / end (optional): ISO 8601 or 10-digit epoch seconds
filters (optional): See Filters reference
organization (optional): Organization name or ID

Every statistical metric in the response includes:

value — the metric value
ci_low / ci_high — 95% confidence interval bounds
plus_minus — half-width of the confidence interval
p2bb — probability to be best (0–1)
p2bc — probability to beat control (0–1)
uplift — relative lift over control, with its own confidence interval

p2bc and uplift are relative to control and appear only on non-control variations.

get_variation_overview

Overall performance metrics for each variation. The fastest way to answer "how's my test doing?" Each metric returns with uplift vs. control, p2bb, p2bc, and confidence intervals.

Parameters:

id (required): UUID of the experiment or experience
metrics (optional): conversion_rate, n_orders, n_visitors, net_revenue, net_revenue_per_visitor, gross_profit_per_visitor, net_product_revenue_per_order, net_shipping_revenue_per_order, net_revenue_per_order
startTs / endTs (optional): Time range. Defaults to the experiment window.
Filters: deviceType, visitorType, customerType, countryCodes, sourceSitesOrChannels, addedToCart, reachedCheckoutStage, triggeredCustomEvents + customEventsFilterType, experimentProductsOnly, maxZScore
organization (optional): Organization name or ID

get_variation_audience

The same metrics as get_variation_overview, broken out per segment per variation. Use it to answer "is mobile dragging down conversion?" or "which country is driving the uplift?"

Parameters:

id (required): UUID of the experiment or experience
audience (required): device_type, visitor_type, source_channel, source_site, country_code, landing_page_full_path
topN (optional): Caps the breakdown at the top N segments (1–1000). By default only country_code and landing_page_full_path are capped, at 10.
metrics, time range, and filters: same as get_variation_overview
organization (optional): Organization name or ID

get_variation_products

Product-level or variant-level test metrics per variation. Use it to find which products are driving or dragging variation-level results.

Returns per product per variation: n_orders, pct_orders, orders_per_visitor, unit_quantity, units_per_visitor, net_product_revenue, net_product_revenue_per_visitor, gross_product_profit, gross_profit_per_visitor, atc_rate, and is_experiment_product.

Parameters:

id (required): UUID of the experiment or experience
returnVariants (optional): true for Shopify variant-level metrics. Default false.
topN (optional): Number of top products or variants by revenue. Default 20.
includeCheckoutUpsellBreakdown (optional): Adds per-product checkout-upsell columns
includePostPurchaseOfferBreakdown (optional): Adds per-product post-purchase-offer columns
Time range and filters: same as get_variation_overview
organization (optional): Organization name or ID

Profit columns require COGS to be configured for the store.

get_variation_timeseries

Test metrics over time for each variation. Use it to check whether results have stabilized, spot promo distortion, or find when a variant started winning.

Parameters:

id (required): UUID of the experiment or experience
interval (required): HOUR, DAY, or WEEK
mode (required): "cumulative" (running totals — has the test stabilized?) or "discrete" (per-period values — where's the variance?)
metrics, time range, and filters: same as get_variation_overview
organization (optional): Organization name or ID

get_experience_timeseries

Per-variant metrics over time with a filters object rather than flat filter parameters.

Parameters:

experienceId (required): UUID of the experience
granularity (optional): hour, day, week, month. Default day.
mode (optional): "cumulative" (default) or "noncumulative"
metrics (optional): conversion_rate, net_revenue_per_visitor, gross_profit_per_visitor, aov, n_visitors, n_orders, net_revenue. Defaults to the first three.
startTs / endTs (optional): 10-digit Unix epoch strings in seconds
filters (optional): See Filters reference
organization (optional): Organization name or ID

Profit metrics return null when COGS are not configured. Check the top-level cogsConfigured and cogsCoveragePct fields.

get_experience_export

Download order-level or line-item-level CSV export data for an experience. Returns a presigned S3 URL valid for roughly 15 minutes; check the expiresIn field for the exact TTL.

Use it to investigate order discrepancies, analyze individual transactions, audit test assignment, or run custom analysis outside the standard metrics.

Parameters:

experienceId (required): UUID of the experience
exportType (required):
- orders — every order with variation assignment, revenue, shipping, discount, and visitor metadata
- order_line_items — individual product line items within each order
- order_reconciliation — reconciliation data for auditing order and revenue attribution
startTs / endTs (optional): 10-digit Unix epoch strings in seconds
filters (optional): See Filters reference
organization (optional): Organization name or ID

Sitewide Store Analytics

These tools report on overall store performance, independent of any specific test.

get_sitewide_snapshot

Current-state KPIs with period-over-period percent change. Answers "how's my store doing?"

Parameters:

feature (optional): Metric set — pass "performance", "order", "conversion", or { "name": "audience", "audience": "<dimension>" }. Omit to receive every metric this endpoint produces.
- performance: gross_profit_per_visitor, net_revenue_per_visitor, conversion_rate, aov, gross_margin_pct, gross_profit, net_revenue, n_orders, n_visitors, average_discount, pct_revenue_with_cogs
- order: aov, n_visitors, n_orders, median_order_value, average_units_per_order, pct_orders_with_free_shipping, net_shipping_revenue_per_order
- conversion: viewed_collection_page_rate, viewed_product_page_rate, add_to_cart_rate, checkout_begin_rate, conversion_rate, bounce_rate, abandoned_cart_rate, abandoned_checkout_rate
- audience: the sitewide metric set broken down by device_type, visitor_type, source_channel, source_site, country_code, or landing_page_full_path
start / end (optional): ISO 8601 datetime strings. start defaults to one week ago.
filters (optional): See Filters reference
organization (optional): Organization name or ID

get_sitewide_timeseries

The same territory as the snapshot, but over time. Answers "how has my conversion rate trended this month?"

Parameters:

feature (optional): Same selector as the snapshot, but the underlying metric sets differ. Omitting feature here also returns per-session and per-unit rates (sessions_per_visitor, conversion_rate_per_session, net_revenue_per_session, gross_profit_per_session, cost_of_revenue) that the snapshot cannot compute. Conversely, median_order_value and average_discount are snapshot-only.
granularity (optional): day, week, month. Default week.
start / end (optional): ISO 8601 datetime strings. start defaults to 12 weeks ago.
filters (optional): See Filters reference
organization (optional): Organization name or ID

get_sitewide_order_distribution

Order-value distribution for the store — a histogram plus unit-mix breakdown. Useful for setting free-shipping thresholds and tier boundaries.

Parameters:

start / end (optional): ISO 8601 datetime strings
filters (optional): See Filters reference
organization (optional): Organization name or ID

get_sitewide_conversion_funnel

The sitewide conversion funnel as a Sankey graph — nodes and links across traffic source, landing page, cart, checkout, and conversion.

Parameters:

start / end (optional): ISO 8601 datetime strings
filters (optional): See Filters reference
organization (optional): Organization name or ID

Seasonal Event Benchmarking

get_event_snapshot

A KPI snapshot for a seasonal event — BFCM, Labor Day, Memorial Day, Presidents' Day, and others — so you can compare this year's performance to prior years.

Parameters:

Event selector and comparison period
organization (optional): Organization name or ID

get_event_timeseries

The same seasonal event benchmarking data as a time series across the event window.

Parameters:

Event selector, comparison period, and granularity
organization (optional): Organization name or ID

Shopify Catalog & Content

search_products

Search the Shopify product catalog by keyword, title, description, or tags.

Parameters:

query (required): Search term
limit (optional): Maximum results. Default 20.
organization (optional): Organization name or ID

Example response:

json

{
  "results": [
    {
      "id": "7234567890",
      "title": "Organic Cotton T-Shirt",
      "vendor": "My Brand",
      "price": "29.99",
      "variants": 3,
      "tags": ["organic", "sustainable"]
    }
  ],
  "query": "organic cotton"
}

list_products

List products in the store via the Shopify Admin API, with filtering by title, vendor, or tag. Use this when browsing rather than searching for a known term.

Parameters:

Filters for title, vendor, and tag, plus pagination
organization (optional): Organization name or ID

get_product

Detailed information about a single product, by handle or ID. Pass format: "json" when you need variant IDs — the markdown format omits them.

Parameters:

Product handle or ID
format (optional): "markdown" (default) or "json"
organization (optional): Organization name or ID

get_products

Title, product type, and collection membership for many products by ID in a single call. Use it instead of looping get_product.

Parameters:

Array of product IDs
organization (optional): Organization name or ID

list_collections

Browse or search product collections.

Parameters:

first (optional): Number of collections to fetch. Default 20.
after (optional): Pagination cursor
query (optional): Search filter for collection name
organization (optional): Organization name or ID

Example response:

json

{
  "collections": [
    {
      "id": "123456789",
      "title": "Holiday Collection",
      "handle": "holiday-collection",
      "productsCount": 24
    }
  ],
  "pageInfo": { "hasNextPage": true, "endCursor": "abc123" },
  "totalFetched": 20
}

get_collection_products

Get the products within a specific collection, by the collection's URL handle. The usual way to scope a price test to a collection.

Parameters:

Collection handle
organization (optional): Organization name or ID

list_pages

Browse or search content pages in the store — About, Contact, FAQ, Terms, and so on.

Parameters:

first (optional): Number of pages to fetch. Default 20.
after (optional): Pagination cursor
query (optional): Search filter for page title
organization (optional): Organization name or ID

search_policies

Search store policies, FAQs, shipping info, returns, privacy, and other store rules.

Parameters:

query (required): Search term
organization (optional): Organization name or ID

Shopify Sales Data

These tools read Shopify's own sales reporting through ShopifyQL.

get_sales_overview

Start here for overall store performance from Shopify's data: total sales, orders, AOV, and returning customer rate, grouped by time period.

Parameters:

period (optional): Relative window, e.g. "7d", "30d", "90d", "1y". Default "1y". Ignored if start_ts is provided.
start_ts / end_ts (optional): Absolute dates in YYYY-MM-DD format
group_by (optional): day, week, month, quarter, year. Default month.
format (optional): "markdown" (default) or "json"
organization (optional): Organization name or ID

get_revenue_by_product

Product revenue rankings. Returns per product: net_sales, orders, net_items_sold, and pct_revenue.

Parameters:

sort (optional): "top" (default) or "bottom"
limit (optional): Maximum products. Default 20, max 1000.
period (optional): Relative window. Default "30d".
start_ts / end_ts (optional): Absolute dates in YYYY-MM-DD format
format (optional): "markdown" (default) or "json"
organization (optional): Organization name or ID

get_revenue_by_product_timeseries

Product metrics over time. Returns a pivot table per metric with products as rows and time buckets as columns.

Parameters:

Same time-window and formatting parameters as get_revenue_by_product, plus a granularity selector
organization (optional): Organization name or ID

get_shopifyql_reference

Discover the ShopifyQL datasets and fields available to your store. Run this before writing a custom query.

Parameters:

organization (optional): Organization name or ID

run_shopifyql_query

Execute an arbitrary ShopifyQL query for custom analyses the convenience tools don't cover. Queries run against the Shopify Analytics API — see Shopify's ShopifyQL reference for syntax, and use get_shopifyql_reference to discover available datasets and fields.

Results are paginated automatically up to 10,000 rows. Include an explicit LIMIT or OFFSET to control pagination yourself.

Parameters:

query (required): The ShopifyQL query, e.g. FROM sessions SHOW sessions, online_store_visitors GROUP BY referrer_source SINCE -30d ORDER BY sessions DESC LIMIT 10
format (optional): "markdown" (default) or "json"
organization (optional): Organization name or ID

Charts & Visualization

generate_intelligems_graph

Generate branded Intelligems chart images for an experiment. Returns S3 URLs to PNG images.

Parameters:

experienceId (required): UUID of the experiment or experience
graphs (optional): Array of chart IDs to render
organization (optional): Organization name or ID

Available chart IDs (30):

conversion_rate, add_to_cart_rate, abandoned_cart_rate, abandoned_checkout_rate, checkout_begin_rate, checkout_enter_contact_info_rate, checkout_address_submitted_rate, view_product_page_rate, view_collection_page_rate, net_revenue_per_visitor, net_revenue_per_order, net_product_revenue_per_order, net_shipping_revenue_per_order, avg_units_per_order, avg_product_revenue_per_unit, profit_per_visitor, subscription_product_revenue_per_order, subscription_revenue_per_order, subscription_orders_per_visitor, subscription_revenue_per_visitor, subscription_profit_per_visitor, profit_per_order, pct_orders_free_shipping, avg_discount_per_discounted_order, avg_discount_per_all_orders, pct_subscription_orders, pct_orders_with_post_purchase_offer, net_revenue_from_post_purchase_offer, pct_orders_with_upsell, net_revenue_from_upsell

Note that revenue_per_visitor is not a valid ID — use net_revenue_per_visitor.

generate_custom_graph

Generate a branded Intelligems chart image from raw data. Use it for custom datasets or metrics that aren't tied to a specific experiment — for example, plotting probability to beat control per variation across a test's duration.

Parameters:

data (required): The raw data to visualize
organization (optional): Organization name or ID

Custom Events & Offers

list_custom_events

List all custom tracking events configured for your organization: page views, click events, scroll depth tracking, and custom JavaScript events. Returns configuration, not event data.

Parameters:

organization (optional): Organization name or ID

Example response:

json

{
  "customEvents": [
    {
      "name": "add_to_wishlist",
      "type": "custom",
      "description": "User adds product to wishlist"
    },
    {
      "name": "scroll_depth_50",
      "type": "scroll",
      "description": "User scrolled 50% of page"
    }
  ]
}

list_offers

List all offers configured for your organization: tiered discounts, cart discounts, free gifts, and free shipping.

Parameters:

enabled (optional): Filter by enabled status
isTest (optional): Filter by test mode status
isArchived (optional): Filter by archived status
applicationType (optional): Filter by discount application type
nameContains (optional): Filter by name (case-insensitive substring match)
limit (optional): Maximum results to return
organization (optional): Organization name or ID

Example response:

json

{
  "offers": [
    {
      "id": "offer_789ghi",
      "name": "Free Shipping Over $50",
      "discountApplicationType": "free_shipping",
      "enabled": true,
      "isTest": false,
      "isArchived": false
    }
  ]
}

Filters reference

Several analytics tools accept a shared filters object. The experiment-level tools (get_variation_*) accept these same fields as flat top-level parameters instead.

Audience

deviceType: "mobile", "desktop", or "any"
visitorType: "new", "returning", or "any"
customerType: "new" or "returning"
countryCodes: Array of ISO 3166-1 alpha-2 codes, e.g. ["US", "GB"]
countryCodesFilterType: "include" (default) or "exclude"
sourceSitesOrChannels: Array of channel names, e.g. ["Paid Social", "Google", "Email"]

Landing page

landingPageFilters: Array of { filterType, values } items. Operators: equals, contains, startsWith, endsWith, doesNotEqual, doesNotContain, doesNotStartWith, doesNotEndWith, isNull, isNotNull. Values within an item are OR'd.
landingPageFiltersOperator: "or" (default) or "and"
landingPageTypes: PDP, Collection, Content, Blog, Homepage, Search, Cart, Other
landingPage: Deprecated. Single-path filter retained for backwards compatibility. Use landingPageFilters in new integrations.

Behavior

userBehavior: Object with optional boolean flags viewedCheckout, addedToCart, viewedProductPage, viewedCollectionPage. Multiple true flags are combined with AND.
reachedCheckoutStage: "started", "contact_info_submitted", "address_info_submitted"
triggeredCustomEvents: Array of custom event identifiers. Requires customEventsFilterType ("any", "all", or "none") to have any effect.
urlParam: Object with queryParam, queryParamValue, and queryParamFilterType

Product

onlyProductIds: Array of Shopify product IDs as numeric strings
onlyProductHandles: Array of Shopify product handles
experimentProductsOnly: When true, only include orders containing configured target products

Order

minNetRevenue / maxNetRevenue: Inclusive bounds on order net revenue
minShippingRevenue / maxShippingRevenue: Inclusive bounds on shipping revenue
shippingMethods: Array of shipping method names
maxZScore: Outlier threshold on order net revenue. Default 3. Null disables outlier filtering.
currencyCodes and currencyCodesFilterType: Sitewide tools only — filter by ISO 4217 order currency

Filter operators that expect values (everything except isNull and isNotNull) will return a 400 if the value is missing or empty, rather than silently matching nothing.

PreviousGoogle Gemini NextExamples & Best Practices

Last updated 11 days ago

Was this helpful?