social·scout

Tools for your agent

list_ad_plays

The play book: named advertising tricks behind great ads, what each one is and how to make one.

Returns
Tricks with what they are, how to make one, and how many ads on the wall use them.
Does
Reads
Who
Free on every account
Limits
Up to 100 results per call. Free on every account: 500 tool calls a day (1,500 on the paid plan), shared by all tools.

Try it on your account

Give it to your agent

Prompt for

No key in it: your agent reads it from SOCIALSCOUT_KEY or asks you.

Read the prompt
Set up SocialScout for me and use it: Belgian social-media data (viral brand videos, Flemish creators, Meta ads and what they say, the Belgian marketing calendar, my own numbers and my content calendar), as an MCP server.

## 1. Connect
You are Claude Code. Add SocialScout as an MCP server for my user (not in this project's .mcp.json, so the key never lands in git):

claude mcp add --transport http --scope user socialscout https://socialscout.be/api/mcp --header "Authorization: Bearer $SOCIALSCOUT_KEY"

First check that SOCIALSCOUT_KEY is set (echo ${SOCIALSCOUT_KEY:+set}); the shell fills it in when the command runs.
Then tell me to run /mcp (or restart Claude Code) so the socialscout tools load.

My key: use the environment variable SOCIALSCOUT_KEY. If it is not set, ask me for my key (I find it at https://socialscout.be/me/crew, under "SocialScout inside your AI": the part after ?key=). Treat it as a password: never print it back, never put it in a file that goes into git.

What the key may do: it reads everything my plan includes and may make drafts in my calendar (scopes read + drafts). It cannot schedule, publish or touch ads: schedule_post, reschedule_post, unschedule_post and delete_post answer "needs_confirmation" with a review_url. Give me that link; nothing happens until I confirm there.
Check the connection: call corpus_stats (works without a key), then list_accounts (needs the key), and tell me in one line what you see.

## The tool: list_ad_plays
The play book: named advertising tricks behind great ads, what each one is and how to make one.
Returns: Tricks with what they are, how to make one, and how many ads on the wall use them.
Does: Reads · Free on every account
Limits: Up to 100 results per call. Free on every account: 500 tool calls a day (1,500 on the paid plan), shared by all tools.

Parameters:
- q? (string): words to find a trick by, e.g. 'price', 'nostalgia', 'billboard'
- min_ads? (integer): only tricks used by at least this many ads
- limit? (integer)

Use it well: Pick a trick, then search_inspiration with play=<slug> for the ads that use it.

## Worked example
"Which tricks work for a price message?"
Call list_ad_plays {"q":"price","limit":10} and answer from what it returns, with the links.

## A bigger job with it
"Find the 10 Belgian food brands whose Meta ads changed their hook this week, and what they changed to."
1. rising_brands {"belgian": true, "advertisers": true, "limit": 30}: the Belgian advertisers moving now; keep the food ones (list_sectors has the sector names).
2. brand_moves {"handle": "<each>"}: which of them started new Meta ads this month, by format, and their longest-running ads.
3. ask_scout {"question": "For <brands>: which started Meta ads this week with a different hook than their ads before? Give the hook before and after, with the ad links."}: Scout reads Gemini's read of every ad (hook, angle, offer). It takes up to a minute.
4. Answer as a table: brand (linked), hook before → hook now, the ad link, and one line on what that tells me.

## Rules
- Every claim about a video, creator, brand or ad comes from a tool result. Say so when a tool returned nothing.
- Every result carries a link to its page on socialscout.be: put it next to each name.
- "5x" or "viral" means five times the account's own normal views, not a fixed number.
- Times without an offset are Belgian time (Europe/Brussels).
- A tool that answers with a sentence instead of data is telling you what it needs (a plan, a key): pass that on, do not guess.

What your agent reads

Free with any SocialScout account. The play book behind the Inspired wall: named advertising tricks (e.g. Break The 4th Wall, The Choiceless Choice), each with what it is, how to make one, and how many great ads use it. Use it to pick a proven trick for a brand, then search_inspiration with play=<slug> for examples. Most used first.

ParameterTypeAbout
qstringwords to find a trick by, e.g. 'price', 'nostalgia', 'billboard'
min_adsintegeronly tricks used by at least this many ads
limitinteger

More in meta ads & ad reads

  • get_brand Everything a brand page shows: numbers, rank, format mix, rhythm, creators, Meta ads.
  • rising_brands The brands growing fastest right now, with the evidence: followers, new ads, views.
  • openings Positioning gaps: what Belgians watch in a sector's videos while few competitor ads say it, and what every ad already says.
  • brand_moves What one brand changed month by month: Meta ads started, its posts, and what its website began to say.
  • explore Exactly what an Explore view shows: the cards and the charts with their findings.
  • stats_query Any count across all posts: group by sector, format, weekday, hour and more, with filters.
  • search_inspiration Search the Inspired wall: great ads from everywhere, each with why it works and where it came from.
  • get_inspiration One ad from the Inspired wall: why it works, its angles, its source and the ads like it.

← All 60 tools

list_ad_plays · Tools · SocialScout