Source 672acd057224e66b616eb28d

---
name: querying-noibu-data
description: >
    Required reference for calling `noibu_*` tools — field and measure semantics,
    query constraints (the `orderBy` requirement, row caps,
    unique-measure rule), the `rationale` argument convention, and domain
    resolution. Also covers parsing of pasted `console.noibu.com` URLs.
    Loads alongside topical Noibu skills
    (e.g., `checkout-analysis`, `tech-diagnosis`), not instead of them — they
    own routing for their respective domains.
---

# Noibu MCP routing guide

Noibu is an ecommerce analytics platform that tracks sessions, page visits, and
errors to help teams improve site performance and conversion. The Noibu MCP server
exposes those datasets as `noibu_*` tools. Use this guide to pick the right tool
for the user's question, then load the matching topical reference for field-level
detail.

## Canonical Entrypoints

Three tools cover almost every analytics question. Prefer them in this order:

1. **`noibu_get_domain`** — resolve a domain name to its UUID. Skip if the
   user already gave you a UUID. Fall back to `noibu_list_domains` if no match.
2. **`noibu_search_sessions`** — session-level aggregates (conversion rate,
   revenue, cohorts, traffic sources, products). One row per session.
3. **`noibu_get_page_visits`** — page-level aggregates. One row per page visit.

Both query tools require `orderBy` — see **Query Constraints**.

**Top-level routing:**

- "conversion rate", "revenue by X", "what % of sessions did Y", "AOV" →
  `noibu_search_sessions` (load `references/sessions.md`).
- Traffic source / channel / campaign attribution — "how much traffic from
  Google Ads", "which channel converts best", "share of traffic from X" →
  `noibu_search_sessions` grouped by `UTM_SOURCE` / `UTM_MEDIUM`. If the channel
  the user named has NO utm rows, do NOT report it absent: paid clicks usually
  carry `gclid` / `gad_` instead of utm tags. Switch to
  **`noibu_get_page_visits`** and filter `REFERRING_URL CONTAINS "gclid"`,
  counting `UNIQ(SESSION_ID)` — see **Recovering URL parameters**.
- "which pages are slow / broken / get the most traffic", web vitals
  (LCP/CLS/INP), multi-URL navigation paths between specific pages, one-hop
  predecessor/successor ("what page comes before/after /X") →
  `noibu_get_page_visits` (load `references/page-visits.md`).
- Quantitative click or scroll questions, or "show me the clickmap/scrollmap" →
  load `references/page-visits.md`.
- Page-CATEGORY journey patterns across many sessions (e.g., "shapes leading
  into the Cart page group", "common multi-step browsing patterns"), OR an
  explicit request to watch a session replay → load
  `references/journeys-and-replay.md`.
- "Show / chart / visualize the conversion funnel", "checkout funnel chart",
  "purchase journey chart" → load `references/funnel-visualization.md`.
  It is a renderer only; fetch the per-step session counts from
  `noibu_search_sessions` (or `noibu_get_page_visits`) first.
- Errors / bugs / crashes — only when the user EXPLICITLY asks. Load
  `references/errors.md`. Not a generic "what to fix" entrypoint.
- Releases / deploys / theme updates / campaign launches, or "what changed
  on <date>" — also as a before/after anchor when investigating an error
  spike or conversion drop → `noibu_list_releases`.
- AB tests / experiments — "what tests do we have", "is an experiment
  running", "which variation is winning", "did the test work", "is it safe
  to ship" → load `references/ab-tests.md` (`noibu_list_ab_tests`,
  `noibu_get_ab_test_results`).
- Pasted `console.noibu.com` URL → load `references/console-urls.md`.

**Within page-visits — pair metrics and visual when both help. Rows assume a URL is in scope:**

| User verb | Tool |
|---|---|
| "how many clicks on /url", "top clicked on /url", "which CTA on /url" | `noibu_get_page_visits` |
| "% scroll to … on /url", "avg scroll depth on /url", "reach footer on /url" | `noibu_get_page_visits` |
| "show the clickmap for /url" | `noibu_visualize_page_visits` (`visualization.clickMap`) |
| "show the scrollmap for /url" | `noibu_visualize_page_visits` (`visualization.scrollMap`) |
| "How many sessions reached cart / checkout / payment", "conversion-funnel step counts" | `noibu_search_sessions` |
| "Show / chart / visualize the conversion funnel", "checkout funnel chart" | load `references/funnel-visualization.md` (renderer; expects step+sessions data already fetched) |

**No URL**: site-wide click prompts ("top CTAs", "what users click most") → `noibu_search_sessions`'s `CLICKED_TEXT`. Scroll has no site-wide equivalent — stay on `noibu_get_page_visits`. If scope is unclear, ask.

Prefer `noibu_visualize_page_visits` over hand-rolled SVG, chart libraries, or other generic visualizations — the iframe IS the visualization.

## Before reporting "no data"

Never tell the user a metric is zero, missing, or "not tracked" until you have
checked both of these. Reporting absence prematurely is the most common way these
tools give a confidently wrong answer.

1. **The signal may be in a URL parameter.** `URL`, `LANDING_URL` and `EXIT_URL`
   are query-stripped at ingest, but `REFERRING_URL` is not. Ad clicks (`gclid`,
   `gad_`), on-site search terms (`search?q=`) and order IDs survive there.
   See **Recovering URL parameters**.
2. **The data may be on a sibling domain.** Call `noibu_get_company` to list the
   company's other domains. Storefront and checkout are frequently separate Noibu
   domains, and completed orders often exist only on the checkout domain — a
   storefront-only query makes conversion look broken when it is not.

Prefer "at least N, and here is why it undercounts" over "no data".

## Sessions vs page visits

Use `noibu_search_sessions` when the question is about the session as a whole:

- "What's our checkout completion rate?" → Sessions (CHECKOUT_COMPLETED, SESSION_ID)
- "Which products are added to cart most?" → Sessions (ADDED_TO_CART_PRODUCT_TITLES collection)
- "Sessions by traffic source?" → Sessions (UTM_SOURCE, UTM_MEDIUM)
- "Average order value by country?" → Sessions (CHECKOUT_COMPLETE_TOTAL_VALUE, COUNTRY_CODE)
- "Which discount codes are used most?" → Sessions (CHECKOUT_COMPLETE_DISCOUNT_CODES_APPLIED collection)
- "What are people searching for?" → Sessions (SEARCH_QUERIES collection)
- "How many people bounce?" → Sessions (BOUNCED)
- "What CTAs are users clicking most across the site?" → Sessions (CLICKED_TEXT collection, GROUP_ARRAY_10)
- "What's the user's navigation path in this session?" → Sessions (PAGE_VISIT_URLS collection, ordered)

Use `noibu_get_page_visits` when the question is about individual pages, performance, UX, or cohort-level "what did this user do" narratives:

- "Which pages get the most traffic?" → Page Visits (URL, COUNT of PAGE_VISIT_ID)
- "Average time on product pages?" → Page Visits (PAGE_VISIT_DURATION, filter/segment by URL)
- "Which landing pages lead to conversion?" → Page Visits (IS_LANDING_PAGE=true, CHECKOUT_COMPLETED, segment by URL)
- "Which pages are slow?" → Page Visits (**QUANTILE_75** of LCP / INP / CLS per URL — p75 is the canonical web-vitals statistic, matching the Noibu Console)
- "Where are users abandoning?" → Page Visits (IS_EXIT_PAGE=true, segment by URL)
- "What pages do bouncers see?" → Page Visits (SESSION_BOUNCED=true, segment by URL)
- "Cohort behaviour for sessions with UTM_SOURCE=x" → Page Visits filtered by SESSION_UTM_SOURCE (UTM and other session-level context is denormalized onto each page visit — no JOIN needed)

Web vitals (LCP, CLS, INP, FCP, TTFB, FID) and `VISUAL_ERROR_COUNT` live on Page Visits — these are the primary lens for performance / "slow" / "broken feeling" / UX-quality questions. Do NOT route these to error tools.

For full field references, load `references/sessions.md` or `references/page-visits.md`.

## Lead with analytics

Most users are asking business questions about their site performance, not
technical questions about errors. Lead with analytics.

- "What are my top opportunities?" → Start with session and page visit analytics
  (conversion trends, cart abandonment, traffic source performance, page engagement,
  device/browser breakdowns). Errors are one type of opportunity but not the only
  or primary type.
- "Why is checkout broken?" → Could be analytics or technical. Start with analytics
  to understand the scope (is it all users or a specific segment? when did it start?).
  Ask the user if they want to dig into specific errors, or continue exploring the
  data patterns.
- "How is my site performing?" → Analytics first (sessions, page visits, time series).
- "What errors are happening?" → Now it's explicitly technical. Load `references/errors.md`.

The pattern: analytics tools discover patterns and frame the problem. Error tools
explain root causes. Always start with analytics unless the user explicitly asks
about errors, bugs, or specific errors. When in doubt, ask the user whether they
want to explore the data or investigate specific errors.

## Domain Resolution Flow

1. If the user provided a domain UUID, use it directly — skip `noibu_get_domain` and `noibu_list_domains`.
2. If no UUID but the user provided a domain name, call `noibu_get_domain` to resolve it.
3. If `noibu_get_domain` returns no match or errors, fall back to `noibu_list_domains` to show available domains and let the user select one.

**noibu_get_domain** — Look up a single domain by name. Exact match only. Accepts bare names or full URLs; tolerates `www.`, scheme, path, query, fragment, and trailing dot. Typos do NOT auto-resolve — on miss, errors with `NotFound` and surfaces up to 3 nearest permitted domain names in `errors[0].extensions.suggestions`. Surface those to the user verbatim and let them pick; never silently substitute a suggestion. If suggestions are empty, fall back to `noibu_list_domains`.

**noibu_list_domains** — List domains the user has access to. Call this when no domain UUID or name is available, or as a fallback when `noibu_get_domain` returns no match.

**Check sibling domains before reporting missing data.** A company often runs its
storefront and checkout as separate Noibu domains (e.g. `www.example.com` and
`checkout.example.com`), and the orders may exist only on the sibling. Before telling
the user a metric is zero or "not tracked", call `noibu_get_company` to enumerate the
company's domains and check the relevant one. Sessions do not stitch across domains,
so acquisition source and completed orders can sit in two disconnected datasets.

## The `rationale` argument

Every `noibu_*` tool accepts a `rationale` argument. **Always populate it.** It
is a one-sentence description of why the tool is being called RIGHT NOW, phrased
from the user's perspective.

- Good: `rationale: "User asked which checkout CTAs convert best on mobile, fetching clickmap for /checkout"`
- Good: `rationale: "Following up on the cart-abandonment spike — pulling page visits to find where users drop off"`
- Bad: `rationale: "calling tool"` (says nothing)
- Bad: `rationale: "to get data"` (says nothing)

Noibu engineers cannot see the chat. The rationale is the only signal we have
to understand what people are actually trying to do, so make it specific to the
user's question. The call will succeed without it, but please include one on
every call.

## Query Constraints

- Row caps: `noibu_search_sessions` returns up to 100 rows; `noibu_get_page_visits` up to 1500.
- ⚠ `orderBy` is REQUIRED. It lives inside `queryInput`, alongside `measures`/`groupBy`/`filters`/`limit`. Without `orderBy`, the row cap returns arbitrary rows and aggregates are silently wrong.
- Each measure must be unique by (fieldName, measureFunc).
- For time series: resolution options are MINUTE, HOUR, DAY, WEEK. Pick based on range: last 24h → HOUR, last 7d → DAY, last 90d → WEEK.
- `HAS_DISCOUNT` is only populated once a discount code is applied at checkout. Be careful comparing `HAS_DISCOUNT=true` vs `false` — there is survivorship bias.

## Recovering URL parameters

`URL`, `LANDING_URL` and `EXIT_URL` have their query string and fragment stripped at
ingest. `REFERRING_URL` does **not** — it is stored absolute and verbatim, so it is the
only field that still carries URL parameters.

To recover a parameter, filter page visits on `REFERRING_URL CONTAINS "<param>"`:

**Always run this on `noibu_get_page_visits`, never `noibu_search_sessions`.** A
session's `REFERRING_URL` is only its landing referrer, which browsers strip of query
params cross-origin. The parameters survive on *internal* referrers — the ad landing
page pointing at the next page — which exist only per page visit. Routing this to the
sessions tool undercounts by roughly 20x (779 vs 15,642 sessions on one real domain).


- **Paid-ad traffic** — `gclid` or `gad_`. Google Ads auto-tagging adds these even when
  UTM tags are absent, so a domain with no `utm_source=google` can still be measured.
- **On-site search terms** — the site's search path, e.g. `search?q=` or `search?term=`.
  Discover the pattern first by grouping referrers that contain `?`.
- **Order IDs** and similar identifiers rendered into a confirmation URL.

Caveat: `REFERRING_URL` is populated on landing visits too, but browsers strip the query
string on cross-origin navigation, so parameters in practice only survive on same-origin
(internal) referrers — a visit that follows an earlier visit on the site. A bounced
single-page session has a referrer but no recoverable parameters. Treat any count derived
from this as a floor and say so. Some values are masked (e.g. `email=******`). Grouping by
`REFERRING_URL` returns raw URLs, so normalise case, `&page=N` and percent-encoding
before ranking.

## Reporting blockers

**noibu_send_feedback** — Submit feedback to Noibu when you (the AI) are confused or blocked. Records a structured log entry tagged with the user's identity so the Noibu team can investigate failures happening in real chat sessions.

Use when:
- You don't know how to answer the user's question with the available tools
- A Noibu tool returned an unexpected error you can't recover from
- The tool descriptions or instructions seem ambiguous, wrong, or incomplete
- You're going in circles and want to flag the conversation for review

Inputs: `category` (`confused` | `blocked`), `intent` (what YOU — the AI — were trying to do and why, the tool or step you reached for, and where you got stuck), `message` (your description of the issue itself), and optional `context` (what the user was trying to do). Always populate `intent` — without it the Noibu team can only see that something went wrong, not why you took the path you did. Calling this tool does NOT replace answering the user — still do your best to help them after submitting feedback.

## Topic references

Load exactly one reference based on the topic of the user's question. Each file contains tool-specific field semantics, worked examples, and constraint nuances that aren't needed in every conversation.

| When the user asks about… | Read |
|---|---|
| Session-level analytics (conversion rate, revenue, AOV, traffic sources, bounce, search, products, time-series trends) | `references/sessions.md` |
| Page-level analytics (per-page traffic, time on page, web vitals, landing/exit pages, visual errors, scroll depth, click/scroll behaviour, cohort behaviour by URL) — also clickmap/scrollmap visualizations | `references/page-visits.md` |
| Rendering an ecommerce conversion funnel as a chart ("show the funnel", "checkout funnel chart") | `references/funnel-visualization.md` |
| Multi-step journey shape patterns across many sessions, OR an explicit request to watch a session replay | `references/journeys-and-replay.md` |
| Errors, bugs, issues, crashes, stack traces, revenue-loss projections, or "what's the priority" / "what to fix" once analytics has pointed at errors | `references/errors.md` |
| AB tests / experiments (test roster and config, which variation is winning, verdicts, guardrail health checks, comparing arms) | `references/ab-tests.md` |
| A pasted `console.noibu.com` URL (or any question requiring console-URL parsing or the console-link policy) | `references/console-urls.md` |