Querying Noibu Data

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:

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.