clickmax-failure-diagnosis

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 when the seller wants to understand WHY transactions fail and what to do about it: failures grouped by reason, recoverable value per reason, and the recommended next action.

Not this skill:

• headline KPIs / paginated dashboard browsing / generic loss cohorts -> clickmax-payments-dashboard-analysis
• inspecting or refunding a specific transaction -> clickmax-transaction-operations
• accrued platform-fee debt -> transactions_debt (this is money the seller owes the platform, NOT a failed sale; never use it for failure diagnosis)

Key assumptions

• transactions_failure_breakdown already aggregates FAILED transactions into stable code buckets with count, recoverable value, and isPlatformFault, sorted by value.
• code is a stable category derived from the gateway's free-text reason; rawReasons holds the original strings that fell into each bucket.
• unknown means the gateway reason did not match a known pattern — lean on rawReasons to describe it.
• value mirrors the dashboard's failed-value semantics; render it as currency, do not re-scale it against other tools.
• count/value are per ATTEMPT: one buyer retrying N times counts N → say "tentativas", never "pessoas"; the deduplicated recoverable total is recovery_recoverable_revenue, not the sum of this breakdown.

Thought process

1. If the seller asks "why are my sales failing?" (or similar), call transactions_failure_breakdown. It defaults to the last 30 days; pass from/to only when the seller names a different window, and state the assumed period in the answer.
2. Translate each code into user-facing text and a next action (map below); never surface the raw code.
3. Rank by recoverable value, lead with the biggest lever, and separate "act differently" faults from legitimate bank declines.

Execute guide

• For the failure diagnosis, use transactions_failure_breakdown. Pass from/to (ISO date-time) only when the seller named a window; pass projectIds/productIds/offerIds only when they narrowed scope.
• To drill into a single failing sale the seller points at, use sales_get_details or transactions_get; do NOT paginate dashboard_my_sales just to re-count failures the breakdown already aggregated. When you do need the failing ROWS, pass includeAggregations: false.
• Never call transactions_debt here — it returns platform-fee debt, not failures.

Failure code → user text + next action

Translate the tool's code into the seller's language (PT example / EN example) and pair it with the action. isPlatformFault: true marks a bug on our side (only integration_error today).

code	Label (PT / EN)	Next action
card_declined	Cartão recusado pelo banco / Card declined by bank	Ofereça Pix ou boleto; peça outro cartão
insufficient_funds	Saldo insuficiente / Insufficient funds	Ofereça Pix/boleto ou parcelamento
invalid_cvv	CVV inválido / Invalid security code	Peça para revisar o código de segurança
expired_card	Cartão expirado / Expired card	Peça um cartão válido
card_data_error	Dados do cartão incorretos / Invalid card data	Peça para reconferir número/dados do cartão
auth_3ds	Falha na autenticação 3DS / 3DS authentication failed	Oriente concluir a verificação do banco (3DS)
fraud_suspected	Bloqueio antifraude / Blocked by fraud check	Revise o pedido; se legítimo, oriente contato com o banco
integration_error	Erro de integração / Integration error	É bug nosso — encaminhe ao suporte
unknown	Motivo não classificado / Unclassified reason	Descreva a partir de rawReasons

Report

• Open with the period assumed and the total failed count + recoverable value.
• Result is a diagnostic ranking. The runtime renders presentation cards: emit a cx-ranking (boxed) with one row per failure reason, ordered by recoverable value, each row's hint set to the recommended next action.
• Money color rule (see presentation contract): a failed sale is recoverable money (retryable / winnable back), not a consummated loss, so every reason row is tone="warning" (yellow) — the chart is yellow end to end, never red. Differentiate the platform-fault case (isPlatformFault) via the hint/action text ("é bug, encaminhe ao suporte"), NOT by changing the tone.
• Translate every code to user text (map above); never print the raw code. Format value as currency.
• If the breakdown was computed over a limited window, add a cx-note (variant="info") stating the period premise.
• Cap long lists with +N more. Treat any recovery follow-up (campaign, message) as opt-in only.

Warnings

• transactions_debt is platform-fee debt, not failed sales — do not mix it in.
• value is recoverable money (winnable back via action, but not in the pocket) — so it reads yellow (warning) per the money-color rule, not red (that is for consummated losses like refunds/chargebacks); describe it as "recuperável".
• Never expose the raw failure code, UUIDs, or raw tool payloads.

Anti-patterns

• Paginating dashboard_my_sales to hand-count failures the breakdown already aggregated (dashboard_my_sales_aggregations returns the same counts in one call).
• Coloring failure rows negative (red) or leaving them neutral — failures are recoverable, so all rows are warning (yellow); red is only for consummated losses.
• Dumping rawReasons verbatim instead of synthesizing a labeled reason.

---

Clickmax skill revision: e3851ddecfda