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, top products, most-accessed sales pages, and recent workspace activity.

Not this skill

• payment dashboard browsing, headline KPIs, my-sales, or loss/recovery cohorts (failed, canceled, refunded, chargedBack, dispute, pending) -> clickmax-payments-dashboard-analysis
• 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 (analyticssalesmetrics, analyticsleadsmetrics, analyticsmessagesmetrics) 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: analyticstotalsales 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 analyticssalesmetrics) can be negative but means decline vs the prior window, not lost money.
• analyticstopproducts limit defaults 5 (max 100); analyticssalespages limit defaults 5 (max 20).

Thought process

1. Map the question to the narrowest tool:

- "quanto faturei" / "how much did I make" -> analyticstotalsales for the range (headline revenue: internal + external + total), or analyticssalesmetrics when they also want conversion, top product, or growth vs a prior period. - "quantos leads" / lead conversion / lead price -> analyticsleadsmetrics; lead-engagement overview across lists -> analyticsleadsoverview. - "top produtos" / best sellers -> analyticstopproducts. - "desempenho do funil" -> analyticsfunnel (step + aggregate stats + sales history). - messaging engagement -> analyticsmessagesmetrics; automation reach/executions -> analyticsflowsoverview. - page traffic -> analyticssalespages; latest workspace movement -> analyticsrecent_activities.

1. For "quanto estou perdendo" / lost money: this skill has no direct loss field. Decide what the user means and be explicit:

- money not converted (failed/canceled/refunded/chargeback/pending) -> hand off to clickmax-payments-dashboard-analysis (dashboardmysales with non-paid statuses); that is where loss cohorts live. - within this skill you can only approximate the gap: low salesConversionPercentage and totalViews vs totalProductsSold (from analyticssalesmetrics) show demand that did not convert, and negative previousPeriodGrowth shows revenue decline. Frame these as leakage signals, not a refund/loss total, and say so.

1. For period-over-period questions, always pass an explicit previous window so growth is meaningful.

Execute guide

• Headline revenue for a window: use analyticstotalsales with startDate and endDate covering the window, optionally scoped by projectSlugs; read totalRevenue plus the totalInSales / totalExternalSales split.
• Sales performance with comparison: use analyticssalesmetrics 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 analyticsleadsmetrics with the same window/previous-window pattern plus optional funnelIds / pageIds; read totalLeads, leadConversionPercentage, leadAveragePrice, and leadsPerMonth.
• Lead-engagement overview: use analyticsleadsoverview with startDate/endDate for engaged contacts, active flows, and per-list engagement.
• Top products: use analyticstopproducts 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 analyticsmessagesmetrics with window + previous window; read totalMessagesSent and per-channel (mail, whatsApp, telegram) engaged percentages.
• Automation reach: use analyticsflowsoverview with projectSlugs and the window for activeFlows, totalExecutions, and topFlows.
• Sales-page traffic: use analyticssalespages with optional projectSlugs / funnelIds and limit.
• Recent activity: use analyticsrecentactivities with startDate/endDate and optional projectIds, funnelIds, categories.
• Showcase prompt "quanto faturei nos últimos 15 dias e quanto estou perdendo":

1. Compute the 15-day window (endDate = today, startDate = today − 15d) and the immediately prior 15-day window for previousStartDate / previousEndDate. 2. Call analyticstotalsales for headline revenue and analyticssalesmetrics for conversion, top product, and previousPeriodGrowth over the same 15 days. 3. There is no lost-revenue cut here: report the demand-vs-conversion gap (views vs products sold, low salesConversionPercentage, negative growth) as leakage signals, and hand off to clickmax-payments-dashboard-analysis for the actual failed/refunded/abandoned amount. State that the "loss" figure is partial unless that skill is used.

• Keep the same date window and filters across tools in one answer so numbers stay comparable.

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.
• Cap ranked lists and summarize the tail as +N more.
• When "loss" was requested, be explicit that this skill covers revenue/conversion and that failed/refunded/abandoned amounts require the payments dashboard skill; give the partial signal you do have rather than inventing 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 — those fields are not in these tools.
• Backend clamps dates to the last two years; flag it if the user asked for older data.

Anti-patterns

• Answering "quanto estou perdendo" with a fabricated loss number instead of routing to the payments dashboard skill.
• 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.