attribution_compare
ChatGPTCompares conversion / revenue numbers across connected ad platforms (and GA4 / Shopify if available) to surface attribution gaps. Use when the user says 'Meta claims X but GA4 shows Y', or asks why platform totals don't reconcile.
audience_overlap
ChatGPTEstimates which campaigns are bidding into the same audience (device + age + gender similarity proxy). Use when the user asks 'am I cannibalising myself', 'why are CPMs rising', or 'are my retargeting and prospecting fighting'.
blended_spend
ChatGPTReturns total spend and revenue across every connected platform, normalised to USD so multi-currency workspaces produce a single blended ROAS. Use when the user asks for an overall picture, 'what did we spend total', or compares platforms head-to-head.
budget_reallocation_sim
ChatGPTSimulates moving a percentage of budget from low-ROAS to high-ROAS campaigns and projects the blended-ROAS lift. Use when the user asks 'what if I moved 20% from X to Y' or 'where should I shift budget'.
budget_what_if_sim
ChatGPTInitializes an interactive 'What-If' budget simulator. Use when the user asks to simulate budget changes, forecast what happens if they increase/decrease spend, or wants to play with budget scenarios across campaigns.
cohort_comparison
ChatGPTCompares performance across audience cohorts (device, age, gender, or location) and surfaces the best and worst slices. Use when the user asks 'which device/age/gender performs best?', 'should I exclude mobile?', or 'where's the wasted spend by location?'.
compare_periods
ChatGPTCompares a metric between the current page period and the immediately preceding equal-length period. Returns overall change, per-platform deltas, and the top 5 campaigns that contributed most to the change (with their contribution share). Use this whenever the user asks 'why did X change', 'did Y go up/down', or 'what's driving the move'.
connection_context
ChatGPTReturns the Meerkads workspace this connection reads, the ad accounts in it with their platforms and currencies, and which platforms are NOT connected. Call this first when the user asks what you can see, which workspace or account you are reading, or why a platform is missing from a result.
creative_fatigue
ChatGPTDetects fatigued creatives across Meta/TikTok/Google: heuristic combines low CTR, climbing CPA, and high-spend-low-CVR. Use when the user asks which creatives are tired, who should be paused/refreshed, or why a campaign's performance is sliding.
creative_performance
ChatGPTReturns the biggest-spending creatives/assets with CTR / CVR / ROAS, for questions about specific creatives, hooks, assets or PMax visuals. It lists by SPEND and does not rank performance: for 'worst ads', 'best ads', 'en kötü reklamlar' or 'en iyi reklamlar', use get_top_entities with entityKind 'ad' instead (direction 'asc' for worst).
cross_platform_summary
ChatGPTAggregates KPIs across ALL connected ad platforms (Google, Meta, TikTok, Shopify, etc.) into a single comparison. Returns per-platform spend, revenue, ROAS, CPA, and efficiency ranking. Use this when the user is on the overview page or asks 'which platform is best', 'where should we shift budget', 'compare platforms'.
explain_metric
ChatGPTReturns the canonical definition, formula, direction (higher/lower is better), industry benchmark, and related metrics for a metric id. Use when the user asks 'what does X mean?'. Pure metadata, no data fetch — instant.
find_anomalies
ChatGPTDetects unusually high or low performers using z-score outlier analysis. Frontend renders detected outliers as signal cards — explain what each anomaly likely means.
forecast_metric
ChatGPTProjects a metric N days into the future from the current page's daily trend using simple linear regression. Returns an observed+projected series for charting plus a window total. Use when the user asks 'where will X land', 'forecast spend', 'if this continues…'.
get_page_kpis
ChatGPTReturns the headline KPIs (spend, revenue, ROAS, CPA, conversions, CTR, CPC for paid channels, or search clicks, impressions, CTR, average position for Google Search Console/GSC) for the current page context, plus signals when a KPI breaches industry benchmarks. Use first when the user asks anything about current performance — the frontend will render KPIs as cards automatically, so just interpret what they mean.
get_search_terms
ChatGPTReturns search terms with their performance and waste classification (wasted_spend = spend with zero conversions). Google Ads search campaigns only. Use when the user asks about 'wasted spend', 'broad match drift', 'negative keywords' or 'search queries'.
get_top_entities
ChatGPTReturns top (or bottom) campaigns / ad groups / ads / search terms sorted by a metric, plus the total entity count in scope. The frontend renders the rows as a table — interpret the leaders / laggards rather than restating the numbers. Pass excludeNames to drop specific entities and get back remainingRollup (the spend/revenue/ROAS of everything left) — this is how you answer 'exclude X and give me the real ROAS' without ever asking the user to pause or change anything.
keyword_landing_fit
ChatGPTScores how well each high-spend search term matches its landing-page URL. Flags mismatches that usually convert poorly. Use when the user asks about quality score, bounce rate causes, or landing-page relevance.
negative_kw_bulk
ChatGPTSuggests negative keywords from search-term reports: terms that consumed material spend without converting. Use when the user asks 'where's the wasted search spend', 'what should I negate', or 'clean up my search terms'.
placement_perf
ChatGPTBreaks down account-wide spend efficiency by placement (or device proxy/PMax channels when placement is unavailable) across all campaigns for the connected accounts, and flags placements wasting spend at sub-par ROAS. Note: this returns account-level and campaign-specific PMax channel aggregates. Use when the user asks about Facebook Reels vs Feed, GDN vs Search, YouTube vs other PMax networks, etc.
plan_dashboard
ChatGPTPropose a custom-dashboard panel: a title plus the widgets it should contain. Returns a PLAN for the user to approve — it does not create anything. Every widget is validated against the capability catalog; invalid ones are reported as rejected. Use when the user asks for a dashboard or panel to be built for them.
preview_ad_copy
ChatGPTRenders ad copy you have already written into a mobile/desktop mockup of the platform's ad unit. Use after composing headlines, descriptions, primary text or calls to action for Google Ads, Meta Ads (Facebook/Instagram) or TikTok Ads, when the user would benefit from seeing them laid out. This tool does not write copy: pass your variations as the input and it returns them arranged for display, filling in a placeholder image where none is given.
profit_first_ranking
ChatGPTRe-ranks campaigns by NET PROFIT after ad spend (revenue × gross-margin − spend) instead of ROAS, using a gross-margin assumption. Computes each currency's break-even ROAS (= 1/margin) and flags 'profit traps' (positive ROAS but a net loss after margin) and 'hidden winners' (real profit at an unremarkable ROAS a ROAS-first view would overlook). Use when the user asks 'which campaigns actually make money', 'am I profitable', 'profit vs ROAS', or 'what's really losing money'. Margin defaults to 40% — ask for or accept the real margin for an accurate read.
profit_margin
ChatGPTApplies a gross-margin assumption to convert revenue → gross profit and ROAS → POAS (profit-on-ad-spend) per platform. Use when the user asks about profitability rather than top-line ROAS.
summarize_changes
ChatGPTReturns the most notable changes (outliers, trends, benchmark breaches, concentration shifts) inside the current page period. Use when the user asks 'what changed', 'what's new', 'anything I should know'.
waste_ledger
ChatGPTReturns an itemized 'wasted spend' statement for the current scope — every campaign, ad group, ad, search term, device, location, age or gender slice that spent money but drove ZERO conversions in the period, ranked by recoverable amount, with a per-currency recoverable total. Use when the user asks 'where am I wasting money', 'what can I cut', 'wasted spend', 'recoverable budget' or 'where is my budget leaking'. Amounts are in each account's own currency and are never summed across currencies.
