clickmax-analytics

As tools abaixo aparecem com os nomes que o MCP da Clickmax registra. Se o seu cliente de IA prefixar nomes de tool (mcp__<servidor>__, mcp_<servidor>_, ou outro), use o nome já prefixado que aparecer na sua lista de tools.

When this applies

Use this skill for business/KPI questions answered by specific analytics cuts over a date range: revenue totals, period-over-period sales, lead/conversion metrics, funnel step performance, messaging engagement, campaign (broadcast) and per-channel message performance, top products, most-accessed sales pages, and recent workspace activity.

Not this skill

• payment dashboard browsing, my-sales rows, or drilling into one loss/recovery cohort (failed, canceled, refunded, chargedBack, dispute, pending) -> clickmax-payments-dashboard-analysis (the sales-overview bundle below stays here)
• refund/chargeback operations on a transaction -> clickmax-transaction-operations
• raw per-lead timelines or owner activity aggregates -> clickmax-leads-activity-analysis
• finding/filtering individual leads -> clickmax-leads
• building or reading a saved Insights dashboard of opportunities BI -> clickmax-insights-dashboards

Key assumptions

• these are workspace-scoped read-only cuts; do not ask for workspace/owner ids.
• date filters are startDate / endDate (ISO date strings); backend clamps start to two-years-ago and end to today/tomorrow, so out-of-range dates are silently trimmed.
• comparison tools (analytics_sales_metrics, analytics_leads_metrics, analytics_messages_metrics) take a current window plus a previousStartDate / previousEndDate window; set both windows explicitly for honest growth reads.
• projectSlugs, funnelIds, pageIds are optional array filters; empty means whole workspace.
• percentage fields are 0..1 fractions (multiply by 100 for display); money fields are already amounts, not cents-strings.
• revenue splits: analytics_total_sales returns totalInSales (internal/native), totalExternalSales (imported platforms, with externalBreakdown per platform), and totalRevenue (sum). State which one you mean.
• there is no direct "lost/refused revenue" cut in this skill; previousPeriodGrowth (in analytics_sales_metrics) can be negative but means decline vs the prior window, not lost money.
• analytics_top_products limit defaults 5 (max 100); analytics_sales_pages limit defaults 5 (max 20).

Sales overview bundle (MANDATORY)

Sales-overview question ("como estão minhas vendas", "quanto faturei", "quanto vendi hoje", "quantas vendas", "quanto estou perdendo", "resumo das vendas", "how are my sales") = ONE complete answer, never only the literal number. Sellers expect faturado + a recuperar + why sales fail + what to do, without asking one by one.

Run in the SAME Code Mode script, same window + filters:

Call	Gives
analytics_total_sales	faturado (totalRevenue + internal/external split)
recovery_recoverable_revenue	total a recuperar (deduplicated buckets: failed, canceled, refunded, pixPending, boletoPending, cartAbandonment)
transactions_failure_breakdown	failures by stable code + value

• Map from/to (failure breakdown) and transactionPeriod (recovery) to the same startDate/endDate window.
• Translate failure code → label + next action via the clickmax-failure-diagnosis map (activate_skill it); never print raw gateway reasons or raw code.
• Headline "a recuperar" = recovery total (deduplicated). Failure-breakdown count/value are per ATTEMPT (same buyer retrying counts N times) → label them "tentativas", never "pessoas", never sum them into the recoverable headline.
• NEVER page dashboard_my_sales rows to hand-count failures or buyers for this answer.
• One tool failing → still answer with the others and say which part is missing.
• Skip the bundle only when the user asks for ONE specific cut ("só o faturamento", "top produtos", "quantos leads").

Thought process

1. Sales-overview question → run the bundle above. Otherwise map the question to the narrowest tool:
   • revenue-only cut ("só o faturamento") -> analytics_total_sales for the range (headline revenue: internal + external + total), or analytics_sales_metrics when they also want conversion, top product, or growth vs a prior period.
   • "quantos leads" / lead conversion / lead price -> analytics_leads_metrics; lead-engagement overview across lists -> analytics_leads_overview.
   • "top produtos" / best sellers -> analytics_top_products.
   • "desempenho do funil" -> analytics_funnel (step + aggregate stats + sales history).
   • messaging engagement -> analytics_messages_metrics; automation reach/executions -> analytics_flows_overview.
   • campaign open/click rate, per-channel delivery/open/bounce, WhatsApp template reads -> see ### Campaign and message performance.
   • page traffic -> analytics_sales_pages; latest workspace movement -> analytics_recent_activities.
2. "quanto estou perdendo" / lost money → the bundle's recovery total + failure ranking IS the answer (recoverable money, not consummated loss). Extra leakage signals, labeled as such, never as a loss total: low salesConversionPercentage, totalViews vs totalProductsSold, negative previousPeriodGrowth (all from analytics_sales_metrics).
3. For period-over-period questions, always pass an explicit previous window so growth is meaningful.

Execute guide

• Headline revenue for a window: use analytics_total_sales with startDate and endDate covering the window, optionally scoped by projectSlugs; read totalRevenue plus the totalInSales / totalExternalSales split.
• Sales performance with comparison: use analytics_sales_metrics with startDate/endDate for the current window and previousStartDate/previousEndDate for the prior window; read totalAmount, salesConversionPercentage, totalProductsSold, products, topConversionProduct, and previousPeriodGrowth.
• Lead metrics: use analytics_leads_metrics with the same window/previous-window pattern plus optional funnelIds / pageIds; read totalLeads, leadConversionPercentage, leadAveragePrice, and leadsPerMonth.
• Lead-engagement overview: use analytics_leads_overview with startDate/endDate for engaged contacts, active flows, and per-list engagement.
• Top products: use analytics_top_products with startDate/endDate, optional funnelIds or productId, and limit for how many to rank.
• Funnel performance: use analytics_funnel with funnelIds and/or projectSlugs plus the date window; read steps, stats, and salesHistory.
• Messaging engagement: use analytics_messages_metrics with window + previous window; read totalMessagesSent and per-channel (mail, whatsApp, telegram) engaged percentages.
• Automation reach: use analytics_flows_overview with projectSlugs and the window for activeFlows, totalExecutions, and topFlows.
• Sales-page traffic: use analytics_sales_pages with optional projectSlugs / funnelIds and limit.
• Recent activity: use analytics_recent_activities with startDate/endDate and optional projectIds, funnelIds, categories.
• Showcase prompt "quanto faturei nos últimos 15 dias e quanto estou perdendo":
  1. Window: endDate = today, startDate = today − 15d; prior 15 days → previousStartDate / previousEndDate.
  2. Run the bundle + analytics_sales_metrics (conversion, top product, previousPeriodGrowth) over the same 15 days.
• Keep the same date window and filters across tools in one answer so numbers stay comparable.

Campaign and message performance

Question	Tool + input	Read
"how did my campaigns do" / "what is my open rate"	broadcasts_list with channel = email, perPage = 20 (50 for a baseline)	each campaign's rates (open/click/bounce over sent) + volume-weighted average across sent campaigns; campaign sends only
"how is email/WhatsApp performing overall in a period" (campaigns + automations)	messages_metrics for the window, again for the previous window of the same length; optional platform (WhatsApp = gupshup)	per-platform total, reached, opened, failed, bounced, spamComplaints, openRate / failureRate / bounceRate, trend vs previous window
"why did this campaign do well/badly" / "when do people open"	broadcasts_insights with broadcastId from broadcasts_list	opensByHour, topLinks, devices, clients, geo, engagement (open/click rate + delta vs previous campaign), creditCost
WhatsApp template reads/clicks	gupshup_template_analytics with the template externalId from gupshup_templates_list (only templates submitted to Meta have one)	sent, delivered, read, clicked, readRate / clickRate over delivered

• messages_metrics openRate = opened / reached, first opens only; no clicks there → click rates come from broadcasts_list.
• automation (flow) emails are not in broadcasts_list → messages_metrics covers campaigns + automations combined.
• rates here are 0..1 fractions or null when the denominator is 0; show null as "no data", not 0%.

Report

• Open with the period assumed and the workspace scope (all projects unless the user narrowed it).
• Answer in plain business language with formatted currency and percentages (fractions ×100); never surface UUIDs, slugs, or raw payloads.
• Lead with the headline number the user asked for, then the strongest supporting cut (growth vs prior period, top product, conversion).
• The runtime renders presentation cards: emit a cx-metric for each headline KPI (revenue, conversion, leads) and a cx-ranking for top-products / top-flows lists instead of long inline tables.
• Bundle answer order: cx-hero faturado (value-tone="positive") → cx-hero a recuperar (icon="database-sync", warning) → cx-ranking of failure reasons by value, every row tone="warning", hint = next action (clickmax-failure-diagnosis rules) → close with ONE opt-in next step (e.g. recovery automation for the top reason) via the question tool. No markdown tables for this data. Empty recovery → "Nada a recuperar no período 🎉".
• Cap ranked lists and summarize the tail as +N more.
• When "loss" was requested, report the recoverable total from the bundle (recoverable, not lost); never invent a loss total.
• Treat follow-up actions as opt-in only.

Warnings

• Do not present previousPeriodGrowth or a negative trend as "money lost"; it is a period-over-period delta.
• Do not merge totalExternalSales into native-sales conclusions without labeling it; external is imported-platform revenue.
• Comparison tools need both windows; a missing previous window makes growth meaningless.
• Do not invent refund, chargeback, or abandoned-cart totals — take them only from recovery_recoverable_revenue.
• Backend clamps dates to the last two years; flag it if the user asked for older data.
• Never compare a campaign open rate (broadcasts_list, over sent) with a messages_metrics open rate (over reached, campaigns + automations) as if they were the same number: different denominators and scopes.

Anti-patterns

• Answering a sales-overview question with only the revenue number and making the user ask for recoverable value, failures, and next action one by one.
• Answering "quanto estou perdendo" with a fabricated loss number instead of the bundle's recoverable total.
• Dumping every product/page/activity row instead of a ranked, capped summary.
• Reporting fractions as if they were already percentages.
• Reusing this skill for per-lead timelines or transaction refund operations.
• Asking the user for workspace or owner ids.

---

Clickmax skill revision: e3851ddecfda