Navin
All documentation

Ads module - Overview

The Ads module (sidebar → Other modules → Ads, route #/ads) is a senior paid-media desk: Google Ads, Microsoft Ads, Meta Ads, TikTok Ads, Reddit Ads, and LinkedIn Ads. Every number comes from the built-in ads engine (your Ads Manager exports or MCP report rows), never from the model. Creative production (videos, social visuals, brand kits) stays in the Marketing studio (#/marketing).

How it works

  1. Open Ads under Other modules.
  2. Click a card: Audit from exports (attach your CSV/XLSX), Wasted spend & negatives, Approve & apply changes, or a platform card for Google / Microsoft / Meta / TikTok / Reddit / LinkedIn (overview, structure, or optimization) - see Actions and Skills.
  3. The chat opens with /ads and the card prompt. Fill account / KPI, then send.
  4. The agent runs the ads engine (and connected MCP tools when available), saves under ads/ + ads-report-*.html, and queues changes in ads/changes.jsonl until you approve them.

Direct usage:

/ads Google Ads overview for customer 1234567890
/ads Meta weekly optimization - ad account act_…

The /ads command

Command/ads [platform|account|brief]
LifecycleAgent workflow
Skills preloadedstudio-expert-contract, critic-reviewer, paid-ads-manager, marketing-analytics, conversion-rate-optimization, copywriting-agent, ad-creative-generator
BoardTracked run
OutputFiles under ads/ + ads-report-*.html + expert gate

The ads engine (real analysis)

The ads tool is deterministic and only available in this module:

ActionWhat it does
ingestReads Google, Microsoft, Meta, LinkedIn, TikTok or Reddit exports (CSV / TSV / XLSX, UTF-16 Google downloads, French number formats, report preambles) and MCP JSON rows; detects the platform and maps the columns.
analyze / pipelineCTR, CPC, CPM, CPA, CVR, ROAS and spend share per campaign, ad group, ad, keyword and search term; period and monthly projection.
findingszero_conversion_spend, high_cpa, search_term_waste, low_ctr, low_quality_score, creative_fatigue, budget_pacing (with monthly_budget), impression_share_limited, spend_concentration, scale_winner, tracking_missing. Each one carries the exported numbers as evidence.
scoreHealth score 0-100: severity penalties plus one point per percent of spend without conversions.
reportDeterministic JSON / Markdown / HTML report (KPIs, campaigns, findings, proposed changes, data gaps).
changesApproval queue: list, status=approved, rejected, applied. Approved changes come with an MCP execution plan (operation + read-back check).
export_changescsv (all actions), google_editor (negatives + pauses for Google Ads Editor), microsoft_bulk (Microsoft Advertising bulk sheet).

Rules the desk follows: numbers only from exports or MCP rows; missing columns are reported as data_gaps; nothing is paused, re-budgeted or negated without an approved change id. Thresholds live under tools.ads.thresholds in the config.

Connect platform MCPs

Open Settings → MCP, then install the presets you need (category ads):

Google Ads (google-ads)

Microsoft Ads (microsoft-ads)

Meta Ads (meta-ads)

  • Remote hosted MCP: https://mcp.facebook.com/ads
  • Field: Authorization header as Bearer <user access token> (scopes include ads_read / ads_management)
  • Docs: Meta Ads MCP get started
  • Note: some accounts are still on Meta's phased MCP rollout.

TikTok Ads (tiktok-ads)

  • Community PyPI server via uvx tiktok-ads-mcp (official TikTok Agentic Hub / MCP is announced; public paste-URL not self-serve yet)
  • Env: TIKTOK_APP_ID, TIKTOK_SECRET, TIKTOK_ACCESS_TOKEN

Reddit Ads (reddit-ads)

LinkedIn Ads (linkedin-ads)

Cron/loop jobs reuse the same gateway env when configured.

Tips

  • Start with Audit from exports when you have no MCP: the engine reads what Ads Manager exports.
  • Connect MCP before asking for live metrics.
  • Prefer read-only; never approve spend mutations casually.
  • Chain with Marketing for creatives, then Ads for structure and optimization.