feed-mob/feedmob-reporting-skills

FeedMob Reporting Skills

🚨🚨🚨 STOP AND READ THIS FIRST 🚨🚨🚨

Critical Principle: Prevent Hallucinated Numbers

Before performing any spend verification analysis, you MUST follow the anti-hallucination protocol. For detailed rules, see: Anti-Hallucination Protocol

Core Rules Summary:

• ❌ NEVER make up, guess, or calculate numbers in your head
• ✅ MUST display raw data → aggregation table → calculation steps → final report
• ✅ All numbers must be traceable to tool responses
• ✅ Use correct formula: client_paid_action_count × gross_cpi
• ✅ Dynamically check client_paid_action, don't hard-code event fields

Mandatory Workflow:

1. Display raw data rows (from tool responses)
2. Create aggregation table (grouped by date, click_url_id)
3. Display calculation steps (each multiplication)
4. Spot-check 3 data points to verify accuracy
5. Then and only then generate final report

Complete anti-hallucination rules, verification checklist, and examples in references/anti-hallucination-protocol.md

---

Overview

This skill provides structured workflows for FeedMob reporting tasks using feedmob-reporting MCP tools. Includes processes for Possible Finance, Koho Financial spend verification, TextNow Adjust report analysis, AppsFlyer MMP clients, and cross-platform spend reconciliation.

Important: MCP Tool Usage

First check if MCP tools are available:

• If mcp__feedmob-reporting__* tools are available, call them directly
• If tools are unavailable (call fails or doesn't exist), ask user to configure MCP server

When tools are available:

• ✅ Call mcp__feedmob-reporting__get_possible_finance_singular_reports(...) directly
• ✅ No need to check configuration or installation

When tools are unavailable:

• ✅ Inform user they need to configure feedmob-reporting MCP server
• ✅ Provide configuration instructions or guide user to MCP server documentation

🚀 Quick Start: Automation Scripts (Recommended)

Before diving into detailed workflows, understanding available automation scripts can greatly simplify your work.

Available Scripts Overview

| Script | Supported Clients | Speed | Recommended Scenario | |--------|------------------|-------|---------------------| | calculate_gross_spend_datafusion.py ⭐⭐ | All clients | ~0.1s | Calculate comparison (Step 3.5, recommended) | | analyze_gross_spend_datafusion.py ⭐⭐ | All clients | ~0.1s | Generate summary (Step 3.6, mandatory) | | compare_client_report_spend_datafusion.py | All clients | ~0.1s | Client report vs direct spend comparison | | calculate_gross_spend.py | All clients | ~0.5s | Backup/zero-dependency environment |

Important Notes:

• ✅ All scripts are now universal, supporting any client (Possible Finance, TextNow, etc.)
• ✅ Automatically adapt to different report structures (Singular, Adjust, etc.)
• ✅ Dynamic CSV column detection, no code modification needed for new clients
• 📖 Detailed script usage instructions in "Step 3.5" section of each workflow

Recommended Workflow (must execute in order):

1. Use MCP tools to fetch data and download CSV (Steps 1-2)
2. Use calculate_gross_spend_datafusion.py to calculate comparison (Step 3.5)
3. 🚨 Mandatory: Use analyze_gross_spend_datafusion.py to generate summary data (Step 3.6)
4. LLM reads summary CSV and generates final report (Step 4)

⚠️ Warning: Don't skip Step 3.6!

• Summary data generated in Step 3.6 is the foundation for LLM to generate accurate reports
• Skipping this step leads to LLM manual calculation → extremely high hallucination risk
• All numbers must come from DataFusion summary, not LLM memory or manual calculation

---

Core Workflows

1. Gross Spend Verification Workflow (Universal)

Compare attribution reports (Singular/Adjust/etc.) with direct spend data to identify discrepancies.

Applicable Clients:

• ✅ Possible Finance (Singular reports)
• ✅ Koho Financial (Singular reports)
• ✅ TextNow (Adjust reports)
• ✅ Privacy Hawk (Singularreports)
• ✅ Uber Technologies (AgencyConversionRecords)
• ✅ AppsFlyer MMP clients (universal AppsFlyer reports)
• ✅ Any future clients

When to use: When verifying spend accuracy, reconciling reports, or investigating spend mismatches.

Workflow Steps:

Step 1: Fetch Attribution Report

Choose tool based on client:

• Possible Finance → get_possible_finance_singular_reports
• Koho Financial → get_koho_financial_singular_reports
• TextNow → get_textnow_adjust_reports
• Privacy Hawk → get_privacy_hawk_singular_reports
• Uber Technologies → See Uber Workflow
• AppsFlyer MMP clients → See AppsFlyer Workflow

For detailed API calls, data validation, and CSV saving process, see: Data Collection Guide

Step 1.5: Fetch Partner Reports (When vendor_managed Campaigns Exist)

When to use: When click_url_histories contains entries with client_paid_action = "vendor_managed" and margin field.

Why needed: Vendor-managed campaigns (CPM billing) don't have event data in attribution reports. Instead, gross spend is calculated from partner partner_net_spend and margin:

calculated_gross = partner_net_spend × (1 - margin/100)

Choose tool based on partner:

• Jampp → get_jampp_reports (requires client_id)
• Kayzen → get_kayzen_reports
• YouAppi → get_youappi_reports
• Samsung → get_samsung_reports

Example:

// Fetch Jampp partner report (if Jampp vendor_managed campaigns exist)
mcp__feedmob-reporting__get_jampp_reports({
  client_id: 123,
  start_date: "2026-01-15",
  end_date: "2026-01-15"
})

Save the response CSV for use in Step 3.5.

---

Step 2: Fetch Historical Rates and Direct Spend (Parallel)

Call two tools in parallel:

• get_click_url_histories - number array [12345, 12346]
• get_direct_spends - string array ["12345", "12346"]

For detailed type differences, CSV saving, and parallel download process, see: Data Collection Guide

Step 3: Match Event Fields and Calculate Expected Gross Spend

🚨 Mandatory: Use Correct Formula

calculated_gross_spend = client_paid_action_count × gross_cpi

Key Requirements:

• ✅ Dynamically match client_paid_action field (don't hard-code)
• ✅ Aggregate multiple rows for same click_url_id
• ✅ Use gross_cpi (not gross_rate)
• ✅ MUST display verification sections before calculating (raw data, aggregation, calculation steps)

For detailed calculation rules, verification requirements, and examples, see: Calculation Verification Guide

Quick Checklist:

• [ ] Aggregated multiple rows for same click_url_id?
• [ ] Used correct event field?
• [ ] Used gross_cpi instead of gross_rate?
• [ ] Displayed verification sections (A, B, C)?

Step 3.5: Use Automation Scripts (Recommended)

DataFusion Python Version (auto-installs dependencies):

First use Glob to find: **/calculate_gross_spend_datafusion.py

python3 scripts/calculate_gross_spend_datafusion.py \
    <attribution_report.csv> <histories.csv> <direct_spend.csv> <output.csv> \
    [partner_report1.csv partner_report2.csv ...]

Optional partner_report CSVs: When vendor_managed campaigns exist, pass one or more partner report CSVs as additional arguments. The script will:

1. Run the standard query for non-vendor_managed campaigns
2. Run a vendor_managed query calculating partner_net_spend × (1 - margin/100)
3. Merge both results into a single output CSV

For detailed script version comparison, parameter descriptions, and usage examples, see: Scripts Usage Guide

Step 3.6: Generate Multi-Dimensional Analysis Summary (⚠️ Mandatory)

🚨 Important: This is a mandatory step, cannot be skipped!

Why mandatory?

• Prevents LLM hallucinations and calculation errors
• Avoids token limit exceeded
• Lets SQL engine handle data aggregation

python3 scripts/analyze_gross_spend_datafusion.py \
    <comparison_report.csv> \
    <output_directory>

Generates 10 summary dimensions: Global, Vendor, Click URL, trends, etc.

LLM reading order:

1. Read global summary
2. Read key groupings (Vendor, Paid Action)
3. Read Top anomalies
4. Generate business report

For detailed script descriptions, 10 analysis dimensions, and LLM workflow, see: Scripts Usage Guide

---

Step 4: Generate Final Report

Prerequisites: Completed Steps 3.5 and 3.6, read summary CSVs

🚨 MUST reference standard format and section order defined in Report Structure Guide.

🎯 Report Structure

For detailed report structure and formatting guide, see: Report Structure Guide

Core Principles:

• Separate CPM and Non-CPM activities
• Non-CPM: Show Click URL and Vendor level comparison
• CPM: Only show Direct Spend (cannot verify without CPM rates)
• Only include Non-CPM accuracy statistics
• Sort tables by Calculated Gross (descending)
• Use status icons: ✅ (0-1%), ⚠️ (1-2%), 🚨 (≥2%)

Standard Sections:

1. Overall Summary
2. Non-CPM Activity Comparison (Click URL + Vendor tables)
3. CPM Activity Section (separate)
4. Verification Accuracy Statistics
5. Key Findings and Recommendations

---

2. Net Spend Verification Workflow (Partner Reports)

Compare partner reports (Jampp, Kayzen, etc.) with direct spend data to verify net spend accuracy.

Applicable Partners:

• ✅ Jampp
• ✅ Kayzen
• ✅ YouAppi
• ✅ Samsung
• ✅ Smadex
• ✅ InMobi
• ✅ Liftoff

When to use: When verifying net spend from partner platforms against FeedMob direct spend records.

Key Difference from Gross Spend:

• Gross Spend: Requires calculation (client_paid_action_count × gross_cpi)
• Net Spend: Direct comparison (partner_net_spend vs feedmob_net_spend)

Workflow Steps:

Step 1: Fetch Partner Report

Direct Partners (Jampp, Kayzen, YouAppi, Samsung):

// Jampp - requires client_id
mcp__feedmob-reporting__get_jampp_reports({
  client_id: 123,
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

// Kayzen - no client_id required
mcp__feedmob-reporting__get_kayzen_reports({
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

// YouAppi - no client_id required
mcp__feedmob-reporting__get_youappi_reports({
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

// Samsung - no client_id required
mcp__feedmob-reporting__get_samsung_reports({
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

Multi-step Partners (Smadex, InMobi, Liftoff):

Smadex (3-step process):

// Step 1: Get report IDs
mcp__feedmob-reporting__get_smadex_report_ids({
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

// Step 2: Check status (repeat until ready)
mcp__feedmob-reporting__check_smadex_report_status({
  report_id: "abc-123"
})

// Step 3: Get report data when status is "ready"
mcp__feedmob-reporting__get_smadex_reports({
  report_id: "abc-123"
})

InMobi (3-step process):

// Step 1: Get report IDs
mcp__feedmob-reporting__get_inmobi_report_ids({
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

// Step 2: Check status (repeat until ready)
mcp__feedmob-reporting__check_inmobi_report_status({
  report_id: "abc-123",
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

// Step 3: Get report data when status is "ready"
mcp__feedmob-reporting__get_inmobi_reports({
  skan_report_id: "skan-123",
  non_skan_report_id: "non-skan-456",
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

Liftoff (3-step process):

// Step 1: Get report IDs
mcp__feedmob-reporting__get_liftoff_report_ids({
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

// Step 2: Check status (repeat until ready)
mcp__feedmob-reporting__check_liftoff_report_status({
  stash_report_id: "stash-123",
  possible_finance_report_id: "pf-456"
})

// Step 3: Get report data when status is "ready"
mcp__feedmob-reporting__get_liftoff_reports({
  stash_report_id: "stash-123",
  possible_finance_report_id: "pf-456",
  start_date: "2025-01-01",
  end_date: "2025-01-31"
})

Response contains:

• click_url_id: Click URL identifier
• partner_net_spend: Net spend from partner report
• date: Report date
• Other partner-specific fields

Step 2: Extract Click URL IDs and Fetch Direct Spends

From partner report, extract all unique click_url_id values, then fetch direct spends:

mcp__feedmob-reporting__get_direct_spends({
  start_date: "2025-01-01",
  end_date: "2025-01-31",
  click_url_ids: ["12345", "12346", ...]  // string array
})

Step 3: Use Automation Scripts (Recommended)

Step 3.1: Compare Net Spend

First use Glob to find: **/compare_net_spend_datafusion.py

python3 scripts/compare_net_spend_datafusion.py \
    <partner_report.csv> <direct_spend.csv> <output.csv>

Step 3.2: Generate Analysis Summary

python3 scripts/analyze_net_spend_datafusion.py \
    <comparison_report.csv> <output_directory>

For detailed script usage, see: Scripts Usage Guide

Step 4: Generate Final Report

Compare partner_net_spend vs feedmob_net_spend:

| Click URL | Date | Partner Net | FeedMob Net | Difference | Diff % | Status | |-----------|------|-------------|-------------|------------|--------|--------| | 12345 | 2025-01-01 | $1,500.00 | $1,500.00 | $0.00 | 0.00% | ✅ | | 12346 | 2025-01-01 | $2,000.00 | $1,950.00 | $50.00 | 2.56% | 🚨 |

Status Icons:

• ✅ Perfect Match: 0% difference
• ⚠️ Minor Difference: <2% difference
• 🚨 Significant Difference: ≥2% difference

For detailed report structure, see: Report Structure Guide

---

3. AppsFlyer MMP Client Workflow

Use this workflow when client uses AppsFlyer as MMP (instead of Singular or Adjust).

Key Features:

• ✅ First call get_clients to check client's mmp_track_party field
• ✅ Use get_appsflyer_reports to fetch attribution report
• ✅ Subsequent steps identical to other clients (Possible Finance, TextNow)
• ✅ Supports multiple clients, various filter options (client_ids, af_app_ids, campaign_ids)

For detailed workflow, examples, and considerations, see: AppsFlyer MMP Client Workflow Guide

Quick Start:

1. Check client MMP type: get_clients({ client_name: "..." })
2. Fetch AppsFlyer reports: get_appsflyer_reports({ client_ids: [...] })
3. Fetch historical rates and direct spend (parallel)
4. Use DataFusion scripts to calculate comparison and generate summary
5. Read summary CSVs and generate report

---

4. Client Report Spend Comparison Workflow

Compare client-provided gross_spend against feedmob_gross_spend directly — no event calculation needed.

Steps:

1. Fetch client report: get_client_report_spend_report_names() → get_client_report_spends()
2. Fetch direct spends: get_direct_spends()
3. Run: python3 scripts/compare_client_report_spend_datafusion.py <client_report.csv> <direct_spend.csv> <output.csv>

For detailed script usage, comparison modes, and output format, see: Client Report Comparison Guide

---

Reference Documentation

The following reference documents provide detailed workflow guides, best practices, and troubleshooting solutions:

Core Guides

• Anti-Hallucination Protocol - Mandatory rules for ensuring number accuracy
• Data Collection Guide - API calls, data validation, and CSV saving
• Calculation Verification Guide - Event matching and Gross Spend calculation rules
• Scripts Usage Guide - Automation scripts and multi-dimensional analysis
• Report Structure Guide - Standardized report format and best practices

Workflow Guides

• Uber Technologies Workflow - Handling Uber Technologies using agency conversion records
• AppsFlyer MMP Client Workflow - Handling clients using AppsFlyer MMP

Tools and Troubleshooting

• Client Report Comparison Guide - Client report vs direct spend comparison
• MCP Tools Reference - Detailed descriptions of all available MCP tools
• Troubleshooting Guide - Common issue solutions

Quick Find Common Issues:

• Missing click_url_ids or empty results → Troubleshooting
• Type conversion errors → Troubleshooting
• CPM campaigns handling → Troubleshooting
• Inaccurate numbers or hallucinations → Anti-Hallucination Protocol
• Uber Technologies workflow → Uber Workflow
• AppsFlyer client workflow → AppsFlyer MMP Workflow

---