Fospha (North & South America)

Answer questions about Fospha products, features, and platform setup. Use this tool whenever the user asks about: - How any Fospha product works (Core, Halo, Beam, Prism, Spark AI) - Attribution methodology, reconciliation, model accuracy, or validation - Platform setup: sign-up, UTM parameters, dashboard configuration - Metrics: ROAS, CAC, CPP, leading indicators, outlier capping - Dashboards: KPI Health Check, Channel Health Check, Optimization, Reporting - Exports, targets, saved views, annotations, custom metrics, custom channel groups - Amazon and TikTok Shop commerce measurement - Benchmarking, year-over-year analysis, cross-channel optimisation - MCP setup, Spark ROAS Agent, Ask Fospha AI - Integrations: Fospha API, TikTok Shop authorization - Competitor comparisons - Why Fospha numbers differ from Meta, Google, GA4, or Shopify HOW TO RESPOND: 1. Read the `results` array — each entry has a `snippet` (relevant content) and a `source` URL 2. Answer the user's question directly and naturally in your own words, using the snippet content as your source of truth 3. Do NOT say "according to the help center" or "the article says" — just answer as if you know the answer 4. At the bottom, add a "Read more:" section with clickable links using the `source` URLs and `title` values from the results

search_help_center

Returns information about the Fospha MCP Server, including what it is, what you can ask, available tools, parameters, and recommended workflows. Use when the user asks what Fospha can do, what tools are available, how to use them, or wants to test the connection.

fospha_intro

Returns performance data broken down by geographic market (e.g. UK, US, DE). Each row is one market with revenue, spend, ROAS, conversions, and all core metrics. Use when the user asks: - "How is the UK performing vs US?" - "Which market has the best ROAS?" - "Show me performance by country" - "Break down revenue by market" - "Weekly UK revenue trend by market"

get_markets

Fetches KPI targets for a Fospha client from the Targets API. IMPORTANT: You MUST set the media, dimension, and kpi parameters correctly based on what the user asks for. Do NOT use defaults blindly.

get_targets

Returns time-series performance data for trending any KPI over time. Each row has a granular_date plus all core metrics (ROAS, revenue, spend, conversions, etc.) and any custom metrics requested. Supports period-over-period comparison: when using preset periods or comparison dates, returns both this_period and previous_period time-series for overlay charts. Use when the user asks: - "Show me ROAS trend over the last 90 days" - "How has revenue trended weekly?" - "Plot spend over time for Paid Social" - "Daily conversion trend for the UK market" - "Compare this month's trend to last year" Engagement metrics (impressions, clicks, CPM, CTR) are supported as time-series. For per-source detail, prefer get_channels or get_markets — they return per-row data instead of blended trends. If time-series aggregation of a media metric fails for a client, the tool degrades gracefully and returns surviving metrics with a partial_response block listing which fields were dropped.

get_trends

Returns overall performance totals for a client — revenue, spend, ROAS, conversions, CPP, CAC, and more. Includes period-over-period comparison (percentage and absolute change) when a preset period or comparison dates are used. Use when the user asks: - "How is my business doing?" - "What's my ROAS / revenue / spend?" - "Show me overall performance for last 30 days" - "Compare this month to last month" For breakdowns by market, channel, or campaign, use the dedicated tools instead. Engagement metrics (impressions, clicks, CPM, CTR) are supported and round-trip correctly. For per-source detail, prefer get_channels or get_markets — they return per-row data instead of blended totals. If summary-level aggregation of a media metric fails for a client, the tool degrades gracefully and returns the surviving metrics with a partial_response block listing which fields were dropped.

get_summary

Peer benchmark data — median SoW (Share of Spend) and SoR (Share of Revenue) across Fospha's client base, broken down by channel group and source. Use when the user asks: - "How does my channel spend compare to peers?" - "Am I over- or under-indexed vs competitors on Paid Social spend?" - "What share of spend do peers put into Google vs Meta?" - "Show me peer benchmarks for all channels" Returns sowBenchmark and sorBenchmark per channel — matching the Fospha webapp benchmark panel. Does NOT return ROAS, CAC, CPP, or CTR benchmarks. Do NOT use this tool to retrieve the client's own performance data — use get_channels, get_summary, or get_markets for that. Combine with get_channels for a side-by-side comparison: get_benchmarks returns peer SoW/SoR; get_channels returns the client's own spend share so they can be compared directly. Benchmarks represent median values across all contributing Fospha clients (minimum 10 clients per data point for privacy). The "window" in the response reflects the latest pipeline aggregation window — use it to show data freshness. Granularity is auto-selected to match webapp behaviour: - channel_group filter set → "group_source_within_group" (source share within that group) - source filter set → "group_source_within_source" (channel share within that source) - no filter → "group_source" (absolute share per channel + source) Pass granularity explicitly to override. Granularity options: - "group_source" — channel group + source breakdown (e.g. Paid Social / Meta) - "channel_group" — channel group only - "campaign_objective" — by campaign objective - "group_source_within_group" — source share within its channel group - "group_source_within_objective" — source share within a campaign objective - "group_source_within_source" — channel group share within a source - "group_within_group" — channel group's own share (always ~100%; scoped to the channel group's own total, for comparing "you" against a benchmark filtered to the same channel group) - "group_within_objective" — channel group share within a campaign objective (across all channel groups) - "group_source_within_group_and_objective" — source share within a channel group AND a campaign objective, both at once - "group_source_within_group_and_source" — channel group's own share within a channel group AND source filter combined (always ~100%) - "group_source_within_source_and_objective" — channel share within a source AND a campaign objective, both at once - "*_excl_amazon_tiktok" variants of group_source, channel_group, campaign_objective, group_within_objective, group_source_within_objective, group_source_within_source, and group_source_within_source_and_objective — same as their base granularity, but the denominator also excludes Amazon and TikTok Shop channel-group spend. Auto-selected whenever excluded_sales_platforms resolves to exactly ["amazon", "TikTok Shop"] (the default) and the active granularity has a variant. Pass non-default excluded_sales_platforms to retain the base granularity. An explicit base granularity is still upgraded when a variant exists. Channels with share of wallet below 5% are suppressed (dashboard parity).

get_benchmarks