Fospha (EMEA & APAC)

Returns the possible values for a specific filter dimension. IMPORTANT: Call this tool to discover valid values for dynamic filters (markets, channels, sources, currencies) before passing them to other tools. Each client has different available values. Returns a list of {key, value, default_selection, ranking, additional_data} objects. Items with default_selection=true are the client's defaults.

get_filter_options

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

Forecasts the incremental impact of paid media spend changes across channels. Uses saturation curve modelling to predict KPI outcomes at a specified daily spend level. Each channel is assessed for headroom (saturation_point - average_spend) and assigned a scaling status. Headroom predicts how much spend can scale before diminishing returns. Positive = room to scale, zero/negative = at or above saturation, "—" = Beyond Predictable Range. Use for budget allocation, channel efficiency, scaling decisions, and spend optimisation. IMPORTANT: Beam uses a fixed ML modelling window (typically quarterly). The period is NOT user-selectable. Within that window, the summary provides lookback metrics at 7, 14, 30, and 90 day intervals. DISPLAY DEFAULT: When presenting data, default to the last 7 day values (e.g. average_last_7_day_spend, average_last_7_day_target, last_7_day_kpi, share_of_wallet_7d). Only use other lookback windows (14d/30d/90d) if the user explicitly asks for them. Headroom statuses (based on spend/saturation ratio): Efficient Scaling (spend < 80% of saturation), Cautious Scaling (80-100%), Inefficient Scaling (>=100%), Exploratory (saturation unknown). The lead KPI determines what metrics mean: - CPP (Cost Per Purchase): target = daily conversions - CAC (Customer Acquisition Cost): target = daily new customer acquisitions - ROAS (Return on Ad Spend): target = daily revenue Use when the user asks: - "Where should I put more budget?" - "Which channels are over-saturated?" - "What CAC/CPP/ROAS can I expect if I scale TikTok?" - "If I increase my daily spend on X, what incremental return will I get?" - "What channels have the most headroom?" - "Which channels are in Cautious Scaling?" - "Black Friday spotlight" or "BF performance"

forecast_beam

Fetches Beam (spend optimisation) data — channel headroom, scaling status, saturation curves, and campaign efficiency. IMPORTANT: Beam uses a fixed ML modelling window (typically quarterly). The period is NOT user-selectable — it always uses the latest available modelling window. Within that window, the summary provides lookback metrics at 7, 14, 30, and 90 day intervals. DISPLAY DEFAULT: When presenting data, default to the last 7 day values (e.g. average_last_7_day_spend, average_last_7_day_target, last_7_day_kpi, share_of_wallet_7d). Only use other lookback windows (14d/30d/90d) if the user explicitly asks for them. Saturation Point is a monetary value showing the predicted daily spend at which returns start diminishing. Displayed as "Beyond Predictable Range" when the model cannot reliably predict it. Headroom is the monetary difference between the Saturation Point and average daily spend for each lookback window: headroom_7d, headroom_14d, headroom_30d, headroom_90d. Default "headroom" uses the lookback parameter (default 7d). Positive = room to scale, zero/negative = at or above saturation, "—" = Beyond Predictable Range. Headroom Status is based on the ratio of average daily spend to saturation point (matching webapp logic): - Efficient Scaling: spend < 80% of saturation - Cautious Scaling: spend 80-100% of saturation - Inefficient Scaling: spend >= 100% of saturation - Exploratory: saturation point unknown Each lookback window has its own status (headroom_status_7d/14d/30d/90d). The default "headroom_status" matches the lookback parameter. The lead KPI determines what metrics mean: - CPP (Cost Per Purchase): target = daily conversions - CAC (Customer Acquisition Cost): target = daily new customer acquisitions - ROAS (Return on Ad Spend): target = daily revenue Use when the user asks about: - "How much headroom does Meta have?" - "Which channels are saturated / have room to scale?" - "What's the scaling status for each channel?" - "Campaign efficiency in Paid Social" - "Saturation curve for Paid Search" - "Where should I increase/decrease spend?" - "Black Friday spotlight" or "BF performance"

get_beam_data