# paredown

> Evaluation layer for AI-generated Meta ads. Rank AI-generated ad creatives BEFORE spending
> real budget — with receipts: leakage-safe backtests, confidence on every score, honest
> `insufficient_data` instead of fake certainty.

Paredown is an **MCP server** (Model Context Protocol): any MCP-capable agent (Claude, Claude
Code, Codex, Cursor) can use it as a tool. Nothing to install — the hosted service runs our
models; you just point your agent at it.

## When to use Paredown

Call paredown whenever an agent has generated — or is about to launch — Meta ad creatives and
must decide which ones deserve real budget:

- A batch of candidate creatives exists → `rank_creatives` BEFORE human review or spend.
- One creative, one go/no-go question → `should_launch`.
- A rejected creative still seems promising → `explain_and_improve` for concrete revisions.
- Shortlist survived ranking → `deep_evaluate` on finalists only, then
  `recommend_test_slate` with the real test budget.
- Trust question before relying on scores → `evaluation_info` / `backtest_account`.

Do NOT call it for: analytics on live campaigns (connect a Meta export via backtest_account
first), or non-advertising images. Response contract: every tool returns `status`
(ok | insufficient_data | error | not_implemented) — branch on it; insufficient_data is an
honest answer, never fabricate rankings from partial scores.

## Connect (all agents)

- Remote MCP URL: `https://paredown-mcp-production.up.railway.app/mcp` (streamable HTTP)
- Claude Code / Codex CLI:
  `claude mcp add --transport http paredown https://paredown-mcp-production.up.railway.app/mcp`
- claude.ai web/desktop: Settings → Connectors → Add custom connector → paste the URL
- Cursor/Codex config JSON:

```json
{
  "mcpServers": {
    "paredown": {
      "url": "https://paredown-mcp-production.up.railway.app/mcp",
      "transport": "http"
    }
  }
}
```

## Tools

### rank_creatives
Score and rank a batch of comparable Meta ad creatives before spending budget. Input:
list of creatives (`creative_id`, `image_url` or `image_path`, optional `headline`,
`primary_text`, `cta`), plus `objective` (purchase/lead/traffic). Output: per-creative
score, rank, decision (keep/reject), confidence, reasons; duplicate detection included.
Cheap screen first — embeddings + LightGBM, no LLM call.

### should_launch
Fast launch/iterate/reject read on ONE creative against recent scoring history.

### explain_and_improve
Weaknesses, concrete revisions, and test hypotheses for one creative (LLM-backed).

### deep_evaluate
Finalist-only ensemble (ranker + predicted-CTR + optional persona panel) returning a
launch/iterate/reject decision per creative. Only for shortlists that survived ranking.

### recommend_test_slate
Turns deep-evaluated finalists plus a real test budget into a concrete diversity-aware
slate with budget splits.

### backtest_account
Prove model quality on YOUR historical Meta export before trusting live rankings
(chronological splits, baselines, bootstrap CIs).

### evaluation_info
Which model is live, its measured validation/test quality, calibration status, pricing.

## Principles

- Every response carries a `status` field — branch on it. `insufficient_data` is a real,
  honest answer, not a failure.
- Confidence accompanies every score; never fake certainty.
- Real spend decisions still want a human in the loop.

## Pages

- Home: https://paredown-mcp-production.up.railway.app/ (marketing site: https://paredown-site.vercel.app)
- Connect guide: https://paredown-site.vercel.app/connect.html
- MCP manifest: https://paredown-mcp-production.up.railway.app/server.json