Ad Radar

Search the Ad Radar board: competitor ads from the Meta Ad Library, with the same filters as the board. By default only ACTIVE ads, sorted by score. Returns compact rows with an adKey: call get_ad for the full record and get_swipe_prompt for a ready-to-run prompt. Call list_taxonomy first for valid tag values. headline and body can be null when the ad's text isn't available: use the tags to understand it; in the rows they are cut at 140 and 280 characters (get_ad has them whole). Every other value in a row is the same get_ad returns for that ad. spendEstimate is an ESTIMATE based on engagement, not real spend; spendLowerBound = it is a minimum ("at least").

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 300,
      "description": "Free text over headline, body, advertiser name and transcript"
    },
    "tier": {
      "type": "string",
      "enum": [
        "winner",
        "rising"
      ],
      "description": "winner = top 10% by score and running 21+ days; rising = growing. Every ad on the radar has at least $50k estimated spend"
    },
    "media": {
      "type": "string",
      "enum": [
        "video",
        "image",
        "all"
      ],
      "default": "all"
    },
    "includePastWinners": {
      "type": "boolean",
      "default": false,
      "description": "Also include winners that are no longer running (archive)"
    },
    "advertiserId": {
      "type": "integer"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Advertiser vertical, e.g. health, pet"
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "description": "Taxonomy filters: { \"<dimension>\": [\"slug\", ...] }. Different dimensions are ANDed, slugs within one are ORed"
    },
    "minDays": {
      "type": "integer",
      "minimum": 0,
      "description": "Minimum days running"
    },
    "sort": {
      "type": "string",
      "enum": [
        "score",
        "reactions",
        "rpd",
        "days",
        "recent"
      ],
      "default": "score"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 15
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 1
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full record of one ad: headline, body, CTA, full transcript, metrics, spendEstimate (an ESTIMATE based on engagement, not real spend; spendLowerBound = it is a minimum, "at least"), delivery status, winnerObservation (when we first observed it above $50k), media (public URLs), links (post, Ad Library, landing page, board), tags (the same dimension and slug search_ads shows), publisher platforms and landing domain. The transcript is in English: when the ad runs in another language (e.g. Spanish), transcript is the English translation, translatedFrom names the language and transcriptOriginal holds the original script. Text fields are null when they aren't available for that ad; the links always point to the original.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "maxLength": 80,
      "description": "adKey (\"meta:<id>\"), a bare id or a Meta Ad Library id"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A ready-to-run prompt for one ad. kind='swipe' = rebuild the ad for your product: map its beats, check the fit, write a full version with the same structure, plus alternative hooks. kind='analysis' = why the ad works (audience, funnel, psychology, weak spots) and how to apply it to your business. Pass product to fill it in, then follow the returned prompt.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "maxLength": 80,
      "description": "adKey (\"meta:<id>\"), a bare id or a Meta Ad Library id"
    },
    "kind": {
      "type": "string",
      "enum": [
        "swipe",
        "analysis"
      ],
      "default": "swipe"
    },
    "product": {
      "type": "string",
      "maxLength": 500,
      "description": "Your product, the one the prompt is for"
    },
    "niche": {
      "type": "string",
      "maxLength": 300,
      "description": "Angle or audience to lean into (swipe only)"
    },
    "annotate": {
      "type": "boolean",
      "default": true,
      "description": "Mark the copy blocks inside the script when available (swipe only)"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The board's taxonomy dimensions (awareness, angle, hook_pattern, vformat, pformat, landing...) with their valid values: the slugs to use in the tags filter of search_ads.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The hooks, hook mechanisms and angles an advertiser uses most, aggregated over all of its ads: the pattern worth swiping, not a single ad. advertiserId comes from search_ads.

{
  "type": "object",
  "properties": {
    "advertiserId": {
      "type": "integer"
    }
  },
  "required": [
    "advertiserId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The 'What to do now' block of the analytics page: for each taxonomy value, how many times more often it produces winners than average (lift), with adoption (ads, advertisers) and example ads. doThis = above average, lower = below. exampleAdKeys are adKeys: pass them to get_ad.

{
  "type": "object",
  "properties": {
    "format": {
      "type": "string",
      "enum": [
        "all",
        "video",
        "image"
      ],
      "default": "all"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}