LeaderboardBack to leaderboard — loading return destination
Opening report…
Loading report overview
M
MCP server
server.example.com/mcp
Tools and resources for your MCP client, with a public quality report and detailed checks.
Protocol
MCP 2025-11-25
Server version
1.0.0
Website
server.example.com
Supports
Tools · Resources
Overall score
90 /100
How is this score calculated?
Server metadata
Loading server metadata
Reviewed90/100
Discoverability
Loading discoverability
Reviewed90/100
Protocol
Loading protocol
Reviewed90/100
Tools
Loading tools
Reviewed90/100
MCP Apps
Loading mcp apps
Reviewed90/100
Tool documentation quality
Loading tool documentation quality
Reviewed90/100
LeaderboardBack to leaderboard — loading return destination
H
HYPD AI for Ad Explorer
adexplorer.hypd.ai/mcp
HYPD's competitor ad research on public ad library data: the ads an advertiser runs on Facebook and Instagram, on Google (Search, YouTube, Shopping, Maps, Play) and on LinkedIn
HYPD's competitor ad research on public ad library data: the ads an advertiser runs on Facebook and Instagram, on Google (Search, YouTube, Shopping, Maps, Play) and on LinkedIn
HYPD Ad Explorer: research the ads competitors run, from the public ad libraries — Meta's (Facebook and Instagram), Google's Ads Transparency Center (Search, YouTube, Shopping, Maps, Play) and LinkedIn's. Meta and Google need no connection; LinkedIn's library is read through the user's own LinkedIn Ads connection. Call `init` at the start of a new conversation and follow the guide it returns. Resolve a brand to its advertiser first (ax_meta_find_advertisers, ax_google_find_advertisers), then list its ads. Pass countries, location and language from what the user said or ask them; never assume worldwide. Call ax_linkedin_search one at a time, never in parallel. Spend and impressions are not published for commercial ads: never estimate them as if they were. Each Meta or Google lookup uses the user's plan allowance; paging a stored result with result_id is free. Report tool errors as errors — never invent ads a tool did not return.
Discoverability
2 pass · 1 partial2 passed · 1 partial42/100
Client listings and public setup information.
mcp.json or server-card.json
Either mcp.json or an MCP Server Card declaring this endpoint passes.
The MCP Server Card declares this server's exact endpoint.
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Returns the Ad Explorer guide — call it first in a new conversation. It explains which ax_* tool answers which question across Meta, Google and LinkedIn, a workflow from a brand name to its ads, the country and market conventions, what the libraries publish and what they don't (no spend for commercial ads), how lookups use the plan allowance, and starter prompts.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
No input fields.
Annotations100/100
All four behavior hints are declared.
{
"title": "Load the Ad Explorer guide",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
Output schema79/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"skill"
],
"properties": {
"skill": {
"type": "object",
"required": [
"name",
"title",
"description",
"updatedAt",
"content"
],
"properties": {
"name": {
"type": "string",
"description": "The guide's id."
},
"title": {
"type": "string",
"description": "The guide's title."
},
"content": {
"type": "string",
"description": "The guide itself, in Markdown."
},
"updatedAt": {
"type": [
"string",
"null"
],
"description": "When the guide last changed (ISO 8601), if known."
},
"description": {
"type": "string",
"description": "What the guide covers."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "init",
"title": "Load the Ad Explorer guide",
"description": "Returns the Ad Explorer guide — call it first in a new conversation. It explains which ax_* tool answers which question across Meta, Google and LinkedIn, a workflow from a brand name to its ads, the country and market conventions, what the libraries publish and what they don't (no spend for commercial ads), how lookups use the plan allowance, and starter prompts.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"skill"
],
"properties": {
"skill": {
"type": "object",
"required": [
"name",
"title",
"description",
"updatedAt",
"content"
],
"properties": {
"name": {
"type": "string",
"description": "The guide's id."
},
"title": {
"type": "string",
"description": "The guide's title."
},
"content": {
"type": "string",
"description": "The guide itself, in Markdown."
},
"updatedAt": {
"type": [
"string",
"null"
],
"description": "When the guide last changed (ISO 8601), if known."
},
"description": {
"type": "string",
"description": "What the guide covers."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Load the Ad Explorer guide",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Searches Meta's public Ad Library for Facebook and Instagram ads that mention a keyword or phrase, from any advertiser: how a whole market advertises, and the competitors the user didn't name. Give query (matched as a phrase, or every word anywhere with match "all_words"), and narrow with countries (two-letter codes), ad_active_status (active, inactive or all) and media_type (image, video, meme, none or all). A row is one ad: its text, headline, call to action and media, the advertiser's page_name and page_id, its platforms and run dates; up to 12 thumbnails show inline. Text past 2,000 characters is cut and marked body_truncated, and ax_meta_ad_detail has all of it. With every country in the EU, EEA or UK, rows add Meta's reach, targeting and payer (data_source "official"). Meta publishes no spend or impressions for commercial ads, and media links expire within hours. Pass next_page_token back as page_token for more.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
The keyword or phrase to find in the ads' text; match decides whether it must appear as written or word by word.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
match
phrase (default): the words together, in this order. all_words: every word somewhere in the ad, in any order.
Clear enough to supply this argument.
countries
The countries the ads were shown in, as ISO codes such as ["US","GB"]. Omit for every country. When every code is in the EU, EEA or UK, rows add Meta's official reach, targeting and payer.
Clear enough to supply this argument.
ad_active_status
Which ads by delivery: active (running now), inactive (stopped) or all. Omitted, both running and stopped ads are returned.
Clear enough to supply this argument.
media_type
Which creatives: image (still images), video, meme (what Meta's own Memes filter returns: images Meta classes as memes), none (ads with no image or video) or all. Omitted, all.
Clear enough to supply this argument.
include_thumbnail_data
Omitted, the ads' thumbnails, where they have one, come back as inline images beside the result, at most 12. True puts each in the result as a data: URI (thumbnail_data_uri) instead, for an artifact that can't load outside images; roughly 10-20 KB more per ad.
Clear enough to supply this argument.
page_size
How many rows one page holds. Defaults to 25.
Clear enough to supply this argument.
page_token
The next_page_token a previous call returned, to read the page after it. Omit for the first page.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Search Meta ads by keyword",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema90/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"next_page_token"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"video_url": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"poster_url": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnail_data_uri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with include_thumbnail_data."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"page_id": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what ax_meta_advertiser_ads takes."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"cta_type": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"link_url": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"body_truncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; ax_meta_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"end_date": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"is_active": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"page_name": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"start_date": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"data_source": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"target_ages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"ad_archive_id": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what ax_meta_ad_detail takes."
},
"target_gender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"eu_total_reach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"page_categories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"target_locations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiary_payers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisher_platforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"age_country_gender_reach_breakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
"description": "This page of ads."
},
"next_page_token": {
"type": [
"string",
"null"
],
"description": "Pass as page_token for the next page; null on the last page."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ax_meta_search",
"title": "Search Meta ads by keyword",
"description": "Searches Meta's public Ad Library for Facebook and Instagram ads that mention a keyword or phrase, from any advertiser: how a whole market advertises, and the competitors the user didn't name. Give query (matched as a phrase, or every word anywhere with match \"all_words\"), and narrow with countries (two-letter codes), ad_active_status (active, inactive or all) and media_type (image, video, meme, none or all). A row is one ad: its text, headline, call to action and media, the advertiser's page_name and page_id, its platforms and run dates; up to 12 thumbnails show inline. Text past 2,000 characters is cut and marked body_truncated, and ax_meta_ad_detail has all of it. With every country in the EU, EEA or UK, rows add Meta's reach, targeting and payer (data_source \"official\"). Meta publishes no spend or impressions for commercial ads, and media links expire within hours. Pass next_page_token back as page_token for more.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"match": {
"enum": [
"phrase",
"all_words"
],
"type": "string",
"description": "phrase (default): the words together, in this order. all_words: every word somewhere in the ad, in any order."
},
"query": {
"type": "string",
"minLength": 1,
"description": "The keyword or phrase to find in the ads' text; match decides whether it must appear as written or word by word."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"minItems": 1,
"description": "The countries the ads were shown in, as ISO codes such as [\"US\",\"GB\"]. Omit for every country. When every code is in the EU, EEA or UK, rows add Meta's official reach, targeting and payer."
},
"page_size": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "How many rows one page holds. Defaults to 25."
},
"media_type": {
"enum": [
"all",
"image",
"video",
"meme",
"none"
],
"type": "string",
"description": "Which creatives: image (still images), video, meme (what Meta's own Memes filter returns: images Meta classes as memes), none (ads with no image or video) or all. Omitted, all."
},
"page_token": {
"type": "string",
"minLength": 1,
"description": "The next_page_token a previous call returned, to read the page after it. Omit for the first page."
},
"ad_active_status": {
"enum": [
"active",
"inactive",
"all"
],
"type": "string",
"description": "Which ads by delivery: active (running now), inactive (stopped) or all. Omitted, both running and stopped ads are returned."
},
"include_thumbnail_data": {
"type": "boolean",
"description": "Omitted, the ads' thumbnails, where they have one, come back as inline images beside the result, at most 12. True puts each in the result as a data: URI (thumbnail_data_uri) instead, for an artifact that can't load outside images; roughly 10-20 KB more per ad."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"next_page_token"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"video_url": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"poster_url": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnail_data_uri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with include_thumbnail_data."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"page_id": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what ax_meta_advertiser_ads takes."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"cta_type": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"link_url": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"body_truncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; ax_meta_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"end_date": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"is_active": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"page_name": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"start_date": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"data_source": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"target_ages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"ad_archive_id": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what ax_meta_ad_detail takes."
},
"target_gender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"eu_total_reach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"page_categories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"target_locations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiary_payers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisher_platforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"age_country_gender_reach_breakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
"description": "This page of ads."
},
"next_page_token": {
"type": [
"string",
"null"
],
"description": "Pass as page_token for the next page; null on the last page."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Search Meta ads by keyword",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Finds the Facebook Page that runs a brand's Meta ads, from its name: each row's page_id is what ax_meta_advertiser_ads needs, with the page_name, categories, verification and follower count to tell the real brand from look-alikes. Give query and, when the market is known, countries. Best effort: for a niche or ambiguous name that finds nothing, run ax_meta_search in the brand's country and take page_id from its rows, or use a Facebook Page id the user has. Pass next_page_token back as page_token for more.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
Brand or company name to look up its advertiser page id(s).
Clear enough to supply this argument.
countries
The market to look for the brand in, as ISO country codes such as ["US","GB"]. Omit for every country.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
page_size
How many rows one page holds. Defaults to 25.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
page_token
The next_page_token a previous call returned, to read the page after it. Omit for the first page.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"next_page_token"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"likes": {
"type": [
"number",
"null"
],
"description": "The Page's likes."
},
"page_id": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what ax_meta_advertiser_ads takes."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Meta verified the Page."
},
"page_name": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"ig_username": {
"type": [
"string",
"null"
],
"description": "The linked Instagram account."
},
"ig_followers": {
"type": [
"number",
"null"
],
"description": "Followers of that Instagram account."
},
"page_categories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
}
},
"additionalProperties": {}
},
"description": "This page of advertisers, closest name match first."
},
"next_page_token": {
"type": [
"string",
"null"
],
"description": "Pass as page_token for the next page; null on the last page."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ax_meta_find_advertisers",
"title": "Find a brand's Facebook Page",
"description": "Finds the Facebook Page that runs a brand's Meta ads, from its name: each row's page_id is what ax_meta_advertiser_ads needs, with the page_name, categories, verification and follower count to tell the real brand from look-alikes. Give query and, when the market is known, countries. Best effort: for a niche or ambiguous name that finds nothing, run ax_meta_search in the brand's country and take page_id from its rows, or use a Facebook Page id the user has. Pass next_page_token back as page_token for more.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"minLength": 1,
"description": "Brand or company name to look up its advertiser page id(s)."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"minItems": 1,
"description": "The market to look for the brand in, as ISO country codes such as [\"US\",\"GB\"]. Omit for every country."
},
"page_size": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "How many rows one page holds. Defaults to 25."
},
"page_token": {
"type": "string",
"minLength": 1,
"description": "The next_page_token a previous call returned, to read the page after it. Omit for the first page."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"next_page_token"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"likes": {
"type": [
"number",
"null"
],
"description": "The Page's likes."
},
"page_id": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what ax_meta_advertiser_ads takes."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Meta verified the Page."
},
"page_name": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"ig_username": {
"type": [
"string",
"null"
],
"description": "The linked Instagram account."
},
"ig_followers": {
"type": [
"number",
"null"
],
"description": "Followers of that Instagram account."
},
"page_categories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
}
},
"additionalProperties": {}
},
"description": "This page of advertisers, closest name match first."
},
"next_page_token": {
"type": [
"string",
"null"
],
"description": "Pass as page_token for the next page; null on the last page."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Find a brand's Facebook Page",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description97/100
Lists the Facebook and Instagram ads one advertiser runs or has run, from Meta's public Ad Library: the heart of a competitor creative review. Give page_id from ax_meta_find_advertisers, from an ax_meta_search row or from the user, and narrow with countries and ad_active_status (active, inactive or all). Each row has the ad text (cut at 2,000 characters and marked body_truncated; ax_meta_ad_detail has all of it), headline, call to action, media, platforms and run dates, with up to 12 thumbnails inline; an ad that has run for months is likely one that works. With EU, EEA or UK countries, rows add Meta's reach, targeting and payer (data_source "official"). No spend or impressions are published for commercial ads, and media links expire within hours. Pass next_page_token back as page_token for more.
The description explains the capability, when to use it, and what to expect.
Inputs97/100
Input documentation gives an agent enough context to populate the arguments.
page_id
The advertiser's Facebook Page id: from ax_meta_find_advertisers, the page_id on an ax_meta_search row, or one the user gives.
Clear enough to supply this argument.
countries
The countries the ads were shown in, as ISO codes such as ["US","GB"]. Omit for every country. When every code is in the EU, EEA or UK, rows add Meta's official reach, targeting and payer.
Clear enough to supply this argument.
ad_active_status
Which ads by delivery: active (running now), inactive (stopped) or all. Omitted, both running and stopped ads are returned.
Clear enough to supply this argument.
include_thumbnail_data
Omitted, the ads' thumbnails, where they have one, come back as inline images beside the result, at most 12. True puts each in the result as a data: URI (thumbnail_data_uri) instead, for an artifact that can't load outside images; roughly 10-20 KB more per ad.
Clear enough to supply this argument.
page_size
How many rows one page holds. Defaults to 25.
Clear enough to supply this argument.
page_token
The next_page_token a previous call returned, to read the page after it. Omit for the first page.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "List a brand's Meta ads",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema89/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"next_page_token"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"video_url": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"poster_url": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnail_data_uri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with include_thumbnail_data."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"page_id": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what ax_meta_advertiser_ads takes."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"cta_type": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"link_url": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"body_truncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; ax_meta_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"end_date": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"is_active": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"page_name": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"start_date": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"data_source": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"target_ages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"ad_archive_id": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what ax_meta_ad_detail takes."
},
"target_gender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"eu_total_reach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"page_categories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"target_locations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiary_payers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisher_platforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"age_country_gender_reach_breakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
"description": "This page of ads."
},
"next_page_token": {
"type": [
"string",
"null"
],
"description": "Pass as page_token for the next page; null on the last page."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ax_meta_advertiser_ads",
"title": "List a brand's Meta ads",
"description": "Lists the Facebook and Instagram ads one advertiser runs or has run, from Meta's public Ad Library: the heart of a competitor creative review. Give page_id from ax_meta_find_advertisers, from an ax_meta_search row or from the user, and narrow with countries and ad_active_status (active, inactive or all). Each row has the ad text (cut at 2,000 characters and marked body_truncated; ax_meta_ad_detail has all of it), headline, call to action, media, platforms and run dates, with up to 12 thumbnails inline; an ad that has run for months is likely one that works. With EU, EEA or UK countries, rows add Meta's reach, targeting and payer (data_source \"official\"). No spend or impressions are published for commercial ads, and media links expire within hours. Pass next_page_token back as page_token for more.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"page_id"
],
"properties": {
"page_id": {
"type": "string",
"minLength": 1,
"description": "The advertiser's Facebook Page id: from ax_meta_find_advertisers, the page_id on an ax_meta_search row, or one the user gives."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"minItems": 1,
"description": "The countries the ads were shown in, as ISO codes such as [\"US\",\"GB\"]. Omit for every country. When every code is in the EU, EEA or UK, rows add Meta's official reach, targeting and payer."
},
"page_size": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "How many rows one page holds. Defaults to 25."
},
"page_token": {
"type": "string",
"minLength": 1,
"description": "The next_page_token a previous call returned, to read the page after it. Omit for the first page."
},
"ad_active_status": {
"enum": [
"active",
"inactive",
"all"
],
"type": "string",
"description": "Which ads by delivery: active (running now), inactive (stopped) or all. Omitted, both running and stopped ads are returned."
},
"include_thumbnail_data": {
"type": "boolean",
"description": "Omitted, the ads' thumbnails, where they have one, come back as inline images beside the result, at most 12. True puts each in the result as a data: URI (thumbnail_data_uri) instead, for an artifact that can't load outside images; roughly 10-20 KB more per ad."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"next_page_token"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"video_url": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"poster_url": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnail_data_uri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with include_thumbnail_data."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"page_id": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what ax_meta_advertiser_ads takes."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"cta_type": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"link_url": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"body_truncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; ax_meta_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"end_date": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"is_active": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"page_name": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"start_date": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"data_source": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"target_ages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"ad_archive_id": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what ax_meta_ad_detail takes."
},
"target_gender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"eu_total_reach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"page_categories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"target_locations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiary_payers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisher_platforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"age_country_gender_reach_breakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
"description": "This page of ads."
},
"next_page_token": {
"type": [
"string",
"null"
],
"description": "Pass as page_token for the next page; null on the last page."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List a brand's Meta ads",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description92/100
Opens one Meta ad in full by the ad_archive_id from ax_meta_search or ax_meta_advertiser_ads: text, headline, call to action, media, the advertiser's page, platforms, run dates and countries, with the image inline. It is how to see an ad whose list row came from the official EU path, which has reach and targeting but no media. Null when no ad has that id. Its data comes from the web (data_source "web"), without reach or targeting. Media links expire within hours.
The description explains the capability, when to use it, and what to expect.
Inputs96/100
Input documentation gives an agent enough context to populate the arguments.
ad_archive_id
Which ad to open: Meta's Ad Library id for it, the ad_archive_id on an ax_meta_search or ax_meta_advertiser_ads row.
Clear enough to supply this argument.
include_thumbnail_data
Omitted, the ads' thumbnails, where they have one, come back as inline images beside the result, at most 12. True puts each in the result as a data: URI (thumbnail_data_uri) instead, for an artifact that can't load outside images; roughly 10-20 KB more per ad.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Open one Meta ad",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema81/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object"
],
"properties": {
"object": {
"anyOf": [
{
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"video_url": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"poster_url": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnail_data_uri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with include_thumbnail_data."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"page_id": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what ax_meta_advertiser_ads takes."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"cta_type": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"link_url": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"body_truncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; ax_meta_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"end_date": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"is_active": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"page_name": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"start_date": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"data_source": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"target_ages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"ad_archive_id": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what ax_meta_ad_detail takes."
},
"target_gender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"eu_total_reach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"page_categories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"target_locations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiary_payers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisher_platforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"age_country_gender_reach_breakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad, or null when no ad has this id."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ax_meta_ad_detail",
"title": "Open one Meta ad",
"description": "Opens one Meta ad in full by the ad_archive_id from ax_meta_search or ax_meta_advertiser_ads: text, headline, call to action, media, the advertiser's page, platforms, run dates and countries, with the image inline. It is how to see an ad whose list row came from the official EU path, which has reach and targeting but no media. Null when no ad has that id. Its data comes from the web (data_source \"web\"), without reach or targeting. Media links expire within hours.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ad_archive_id"
],
"properties": {
"ad_archive_id": {
"type": "string",
"minLength": 1,
"description": "Which ad to open: Meta's Ad Library id for it, the ad_archive_id on an ax_meta_search or ax_meta_advertiser_ads row."
},
"include_thumbnail_data": {
"type": "boolean",
"description": "Omitted, the ads' thumbnails, where they have one, come back as inline images beside the result, at most 12. True puts each in the result as a data: URI (thumbnail_data_uri) instead, for an artifact that can't load outside images; roughly 10-20 KB more per ad."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"object"
],
"properties": {
"object": {
"anyOf": [
{
"type": "object",
"properties": {
"media": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "image or video."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "The full-size image."
},
"video_url": {
"type": [
"string",
"null"
],
"description": "The video file."
},
"poster_url": {
"type": [
"string",
"null"
],
"description": "The video's cover image."
},
"thumbnail_data_uri": {
"type": [
"string",
"null"
],
"description": "The thumbnail as a data: URI, only with include_thumbnail_data."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The ad's images and videos."
},
"reach": {
"type": [
"number",
"null"
],
"description": "People reached, where Meta publishes it."
},
"spend": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Spend as a range, only for ads Meta publishes it for (political and issue ads). Commercial ads have none."
},
"page_id": {
"type": [
"string",
"null"
],
"description": "The advertiser's Facebook Page id, what ax_meta_advertiser_ads takes."
},
"creative": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's primary text."
},
"cta_type": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. SHOP_NOW."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"link_url": {
"type": [
"string",
"null"
],
"description": "Where the ad sends people."
},
"body_truncated": {
"type": [
"boolean",
"null"
],
"description": "true when a list cut the text to its start; ax_meta_ad_detail returns all of it."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's copy and destination."
},
"end_date": {
"type": [
"string",
"null"
],
"description": "The day it stopped, or null while it runs."
},
"countries": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Countries it delivered to, as two-letter codes; null when unknown."
},
"is_active": {
"type": [
"boolean",
"null"
],
"description": "Whether it is running now."
},
"page_name": {
"type": [
"string",
"null"
],
"description": "The Facebook Page's name."
},
"start_date": {
"type": [
"string",
"null"
],
"description": "The day it started running."
},
"data_source": {
"type": [
"string",
"null"
],
"description": "official for Meta's own fields (ads scoped to the EU, EEA or UK), web otherwise."
},
"impressions": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Impressions as a range, only for ads Meta publishes them for (political and issue ads)."
},
"target_ages": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Targeted age range (official ads only)."
},
"ad_archive_id": {
"type": [
"string",
"null"
],
"description": "The ad's id in the Ad Library, what ax_meta_ad_detail takes."
},
"target_gender": {
"type": [
"string",
"null"
],
"description": "Targeted gender (official ads only)."
},
"eu_total_reach": {
"type": [
"number",
"null"
],
"description": "People reached in the EU (official ads only)."
},
"page_categories": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "The Page's categories, e.g. Clothing store."
},
"target_locations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Targeted locations (official ads only)."
},
"beneficiary_payers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Who benefits from and who pays for the ad (official ads only)."
},
"publisher_platforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Where it runs: facebook, instagram, messenger, audience_network."
},
"age_country_gender_reach_breakdown": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Reach by age, country and gender (official ads only)."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad, or null when no ad has this id."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Open one Meta ad",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Finds the advertisers Google's Ads Transparency Center lists for a brand or keyword, each with its advertiser id and domain: the step before ax_google_advertiser_ads shows their ads. Give one keyword, with location and language for the market (ask the user rather than assume worldwide); limit caps the advertisers returned. Paged: result_id with page and page_size reads more of the same result without a new lookup, leaving out keyword, location and language.
The description explains the capability, when to use it, and what to expect.
Inputs93/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
keyword
The brand or term whose advertisers to find, e.g. "acme" or "running shoes". Omit when paging with result_id.
Clear enough to supply this argument.
location
The market's country, by name ("United States", "Germany"): the Ads Transparency Center lists ads per country. Take it from what the user said or ask them; it is not read from a Google Ads Account, and worldwide is never assumed. Omit when paging with result_id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
language
The market's language, by name ("English", "German"). Take it from what the user said or ask them. Omit when paging with result_id.
Clear enough to supply this argument.
limit
Maximum number of results to return. The data source ignores small counts and may return many more, so set this to cap the total (e.g. 20). Defaults to the provider's full set.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
page
Which page of the result to read; the first when omitted. With result_id it reads the stored result without a new lookup.
Clear enough to supply this argument.
page_size
How many rows one page holds. Defaults to 10.
Clear enough to supply this argument.
result_id
Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "Find a brand on Google",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema86/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expires_at",
"page",
"page_size",
"result_id",
"row_count",
"total_pages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "What the row is: ads_advertiser, ads_multi_account_advertiser or ads_domain."
},
"title": {
"type": [
"string",
"null"
],
"description": "The advertiser's name."
},
"domain": {
"type": [
"string",
"null"
],
"description": "For ads_domain rows: the advertised domain."
},
"location": {
"type": [
"string",
"null"
],
"description": "The advertiser's country."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the advertiser."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position among rows of the same type."
},
"advertisers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": [
"string",
"null"
],
"description": "The account's country."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the account."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The account's id."
},
"approx_ads_count": {
"type": [
"number",
"null"
],
"description": "Roughly how many ads the account has run."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "For ads_multi_account_advertiser rows: the accounts behind one name."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The advertiser account's id, what ax_google_advertiser_ads takes in advertiser_ids."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position among all rows."
},
"approx_ads_count": {
"type": [
"number",
"null"
],
"description": "Roughly how many ads it has run on Google."
}
},
"additionalProperties": {}
},
"description": "This page's advertisers, best match first."
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"result_id": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and page_size, reads another page without a new lookup."
},
"row_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then result_id reads its other pages for free."
},
"total_pages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this page_size."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ax_google_find_advertisers",
"title": "Find a brand on Google",
"description": "Finds the advertisers Google's Ads Transparency Center lists for a brand or keyword, each with its advertiser id and domain: the step before ax_google_advertiser_ads shows their ads. Give one keyword, with location and language for the market (ask the user rather than assume worldwide); limit caps the advertisers returned. Paged: result_id with page and page_size reads more of the same result without a new lookup, leaving out keyword, location and language.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Which page of the result to read; the first when omitted. With result_id it reads the stored result without a new lookup."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Maximum number of results to return. The data source ignores small counts and may return many more, so set this to cap the total (e.g. 20). Defaults to the provider's full set."
},
"keyword": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The brand or term whose advertisers to find, e.g. \"acme\" or \"running shoes\". Omit when paging with result_id."
},
"language": {
"type": "string",
"minLength": 1,
"description": "The market's language, by name (\"English\", \"German\"). Take it from what the user said or ask them. Omit when paging with result_id."
},
"location": {
"type": "string",
"minLength": 1,
"description": "The market's country, by name (\"United States\", \"Germany\"): the Ads Transparency Center lists ads per country. Take it from what the user said or ask them; it is not read from a Google Ads Account, and worldwide is never assumed. Omit when paging with result_id."
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "How many rows one page holds. Defaults to 10."
},
"result_id": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expires_at",
"page",
"page_size",
"result_id",
"row_count",
"total_pages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "What the row is: ads_advertiser, ads_multi_account_advertiser or ads_domain."
},
"title": {
"type": [
"string",
"null"
],
"description": "The advertiser's name."
},
"domain": {
"type": [
"string",
"null"
],
"description": "For ads_domain rows: the advertised domain."
},
"location": {
"type": [
"string",
"null"
],
"description": "The advertiser's country."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the advertiser."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position among rows of the same type."
},
"advertisers": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": [
"string",
"null"
],
"description": "The account's country."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the account."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The account's id."
},
"approx_ads_count": {
"type": [
"number",
"null"
],
"description": "Roughly how many ads the account has run."
}
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "For ads_multi_account_advertiser rows: the accounts behind one name."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The advertiser account's id, what ax_google_advertiser_ads takes in advertiser_ids."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position among all rows."
},
"approx_ads_count": {
"type": [
"number",
"null"
],
"description": "Roughly how many ads it has run on Google."
}
},
"additionalProperties": {}
},
"description": "This page's advertisers, best match first."
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"result_id": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and page_size, reads another page without a new lookup."
},
"row_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then result_id reads its other pages for free."
},
"total_pages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this page_size."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Find a brand on Google",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Lists the ads one advertiser runs or has run on Google, newest first, from the Ads Transparency Center: Search, YouTube, Shopping, Maps and Play. Each row has the format, first_shown and last_shown, and a preview_image or a preview_url, without the ad text. Name the advertiser by exactly one of target, their domain ("acme.com"), or advertiser_ids from ax_google_find_advertisers; there is no keyword search here. Narrow with platform (google_search, google_shopping, google_maps, google_play or all) and format (text, image, video or all); YouTube ads are among format video, with no platform of their own. Give location and language for the market. Paged: result_id with page and page_size reads more of the same result without a new lookup.
The description explains the capability, when to use it, and what to expect.
Inputs94/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
target
The advertiser's website domain, bare, like "acme.com". For a new search give target or advertiser_ids, not both; omit both when paging with result_id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
advertiser_ids
The advertiser ids from ax_google_find_advertisers whose ads to list. For a new search give target or advertiser_ids, not both; omit both when paging with result_id.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
platform
The Google service the ads ran on; every service when omitted. YouTube has no value of its own: its ads are among format video.
Clear enough to supply this argument.
format
The kind of creative to keep; every kind when omitted. YouTube ads are video.
Clear enough to supply this argument.
location
The market's country, by name ("United States", "Germany"): the Ads Transparency Center lists ads per country. Take it from what the user said or ask them; it is not read from a Google Ads Account, and worldwide is never assumed. Omit when paging with result_id.
Clear enough to supply this argument.
language
The market's language, by name ("English", "German"). Take it from what the user said or ask them. Omit when paging with result_id.
Clear enough to supply this argument.
page
Which page of the result to read; the first when omitted. With result_id it reads the stored result without a new lookup.
Clear enough to supply this argument.
page_size
How many rows one page holds. Defaults to 10.
Clear enough to supply this argument.
result_id
Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"title": "List a brand's Google ads",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema70/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expires_at",
"page",
"page_size",
"result_id",
"row_count",
"total_pages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The ad's page in the Ads Transparency Center."
},
"type": {
"type": [
"string",
"null"
],
"description": "Always ads_search."
},
"title": {
"type": [
"string",
"null"
],
"description": "The advertiser's name."
},
"format": {
"type": [
"string",
"null"
],
"description": "text, image or video."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the advertiser."
},
"last_shown": {
"type": [
"string",
"null"
],
"description": "When Google last showed it (UTC)."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position in the list."
},
"creative_id": {
"type": [
"string",
"null"
],
"description": "The ad's id."
},
"first_shown": {
"type": [
"string",
"null"
],
"description": "When Google first showed it (UTC)."
},
"preview_url": {
"type": [
"string",
"null"
],
"description": "A page that renders the ad, when there is no image."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The advertiser account that runs it."
},
"preview_image": {
"anyOf": [
{
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The preview image."
},
"width": {
"type": [
"number",
"null"
],
"description": "Its width in pixels."
},
"height": {
"type": [
"number",
"null"
],
"description": "Its height in pixels."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "A picture of the ad, when Google has one."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position in the list."
}
},
"additionalProperties": {}
},
"description": "This page's ads, most recently shown first."
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"result_id": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and page_size, reads another page without a new lookup."
},
"row_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then result_id reads its other pages for free."
},
"total_pages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this page_size."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ax_google_advertiser_ads",
"title": "List a brand's Google ads",
"description": "Lists the ads one advertiser runs or has run on Google, newest first, from the Ads Transparency Center: Search, YouTube, Shopping, Maps and Play. Each row has the format, first_shown and last_shown, and a preview_image or a preview_url, without the ad text. Name the advertiser by exactly one of target, their domain (\"acme.com\"), or advertiser_ids from ax_google_find_advertisers; there is no keyword search here. Narrow with platform (google_search, google_shopping, google_maps, google_play or all) and format (text, image, video or all); YouTube ads are among format video, with no platform of their own. Give location and language for the market. Paged: result_id with page and page_size reads more of the same result without a new lookup.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Which page of the result to read; the first when omitted. With result_id it reads the stored result without a new lookup."
},
"format": {
"enum": [
"all",
"text",
"image",
"video"
],
"type": "string",
"description": "The kind of creative to keep; every kind when omitted. YouTube ads are video."
},
"target": {
"type": "string",
"maxLength": 253,
"minLength": 1,
"description": "The advertiser's website domain, bare, like \"acme.com\". For a new search give target or advertiser_ids, not both; omit both when paging with result_id."
},
"language": {
"type": "string",
"minLength": 1,
"description": "The market's language, by name (\"English\", \"German\"). Take it from what the user said or ask them. Omit when paging with result_id."
},
"location": {
"type": "string",
"minLength": 1,
"description": "The market's country, by name (\"United States\", \"Germany\"): the Ads Transparency Center lists ads per country. Take it from what the user said or ask them; it is not read from a Google Ads Account, and worldwide is never assumed. Omit when paging with result_id."
},
"platform": {
"enum": [
"all",
"google_play",
"google_maps",
"google_search",
"google_shopping"
],
"type": "string",
"description": "The Google service the ads ran on; every service when omitted. YouTube has no value of its own: its ads are among format video."
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "How many rows one page holds. Defaults to 10."
},
"result_id": {
"type": "string",
"minLength": 1,
"description": "Result ID returned by a previous call to this research tool. Valid for 24 hours; use for stored pages without a fresh provider request. After expiry, start a fresh lookup."
},
"advertiser_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 25,
"minItems": 1,
"description": "The advertiser ids from ax_google_find_advertisers whose ads to list. For a new search give target or advertiser_ids, not both; omit both when paging with result_id."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"required": [
"expires_at",
"page",
"page_size",
"result_id",
"row_count",
"total_pages",
"rows"
],
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "This page's number."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The ad's page in the Ads Transparency Center."
},
"type": {
"type": [
"string",
"null"
],
"description": "Always ads_search."
},
"title": {
"type": [
"string",
"null"
],
"description": "The advertiser's name."
},
"format": {
"type": [
"string",
"null"
],
"description": "text, image or video."
},
"verified": {
"type": [
"boolean",
"null"
],
"description": "Whether Google verified the advertiser."
},
"last_shown": {
"type": [
"string",
"null"
],
"description": "When Google last showed it (UTC)."
},
"rank_group": {
"type": [
"number",
"null"
],
"description": "Its position in the list."
},
"creative_id": {
"type": [
"string",
"null"
],
"description": "The ad's id."
},
"first_shown": {
"type": [
"string",
"null"
],
"description": "When Google first showed it (UTC)."
},
"preview_url": {
"type": [
"string",
"null"
],
"description": "A page that renders the ad, when there is no image."
},
"advertiser_id": {
"type": [
"string",
"null"
],
"description": "The advertiser account that runs it."
},
"preview_image": {
"anyOf": [
{
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
],
"description": "The preview image."
},
"width": {
"type": [
"number",
"null"
],
"description": "Its width in pixels."
},
"height": {
"type": [
"number",
"null"
],
"description": "Its height in pixels."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "A picture of the ad, when Google has one."
},
"rank_absolute": {
"type": [
"number",
"null"
],
"description": "Its position in the list."
}
},
"additionalProperties": {}
},
"description": "This page's ads, most recently shown first."
},
"page_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows per page."
},
"result_id": {
"type": "string",
"minLength": 1,
"description": "The stored result. With page and page_size, reads another page without a new lookup."
},
"row_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the whole result, across all pages."
},
"expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "When the stored result expires. Until then result_id reads its other pages for free."
},
"total_pages": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Pages in the whole result at this page_size."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "List a brand's Google ads",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Searches LinkedIn's public Ad Library for B2B ads, from any advertiser: give at least one of keyword (every word must match), advertiser or payer_name, and optionally countries (two-letter codes), dates and targeting categories. It reads through the user's LinkedIn Ads connection: account_id is optional (default: their first LinkedIn ad account); with none connected, the error carries the link to connect LinkedIn, to show the user. Without dates LinkedIn returns only yesterday's ads, so give start_date for anything longer (the library starts on 2023-06-01); end_date is exclusive. Rows have the advertiser and payer, ad_url (the ad's public page), first and last impression, impression ranges per country and the targeting. On paid plans and trials, from the research budget, creative_preview adds the headline, text, call to action and up to 12 thumbnails; the free plan gets none. No exact spend or impressions. Pages of up to 25 with count; pass next_start back as start until it is null. One call at a time.
The description explains the capability, when to use it, and what to expect.
Inputs90/100
Remove repeated schema validation from descriptions; focus on meaning and usage context.
account_id
The numeric id of one of the user's LinkedIn ad accounts. Optional: without it, the user's first connected LinkedIn ad account is used; any one works, it only signs the request in.
Clear enough to supply this argument.
keyword
Keywords to search ad content for. Space-separated words are ANDed by LinkedIn.
Clear enough to supply this argument.
advertiser
Advertiser (company/page) name to search for.
Clear enough to supply this argument.
payer_name
Who PAID for the ad — can differ from the advertiser (DSA transparency).
Clear enough to supply this argument.
countries
The countries the ads were served in, as ISO codes such as ["DE","US"]. Omit for every country.
Clear enough to supply this argument.
start_date
The first serving day to search. The library covers ads created on or after 2023-06-01; with no dates at all, LinkedIn returns only yesterday's ads.
Clear enough to supply this argument.
end_date
The day after the last serving day to search: the end is exclusive, so for one day pass the next day. Omitted with start_date, the search runs to the latest day the library has.
Clear enough to supply this argument.
included_targeting_facet_categories
Only ads that used AT LEAST one of these targeting categories.
Clear enough to supply this argument.
excluded_targeting_facet_categories
Only ads that used NONE of these targeting categories.
Clear enough to supply this argument.
count
How many ads one page holds. Defaults to 25. Pass next_start back as start for the next page.
Clear enough to supply this argument.
include_thumbnail_data
Omitted, the ads' thumbnails, where they have one, come back as inline images beside the result, at most 12. True puts each in the result as a data: URI (thumbnail_data_uri) instead, for an artifact that can't load outside images; roughly 10-20 KB more per ad. LinkedIn thumbnails come with creative_preview, on paid plans and trials only.
Clear enough to supply this argument.
start
Offset for paging. Pass the previous response's next_start.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"total",
"next_start"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ad_url": {
"type": [
"string",
"null"
],
"description": "The ad's public page in LinkedIn's Ad Library; its tail is the ad id."
},
"details": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "The ad format, e.g. SPONSORED_STATUS_UPDATE, SPONSORED_VIDEO, SPOTLIGHT_V2."
},
"advertiser": {
"anyOf": [
{
"type": "object",
"properties": {
"ad_payer": {
"type": [
"string",
"null"
],
"description": "Who paid for the ad, as LinkedIn discloses it."
},
"advertiser_url": {
"type": [
"string",
"null"
],
"description": "The advertiser's LinkedIn page."
},
"advertiser_name": {
"type": [
"string",
"null"
],
"description": "The company that ran the ad."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The advertiser and payer."
},
"ad_targeting": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The targeting LinkedIn discloses, one entry per facet with its included and excluded segments; mostly for ads shown in the EU."
},
"ad_statistics": {
"anyOf": [
{
"type": "object",
"properties": {
"total_impressions": {
"anyOf": [
{
"type": "object",
"properties": {},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The total impressions as a range; LinkedIn publishes no exact count."
},
"first_impression_at": {
"type": [
"string",
"null"
],
"description": "When the ad was first shown, ISO 8601."
},
"latest_impression_at": {
"type": [
"string",
"null"
],
"description": "When the ad was last shown, ISO 8601."
},
"impressions_distribution_by_country": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The share of impressions per country, with two-letter country codes."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "When and how widely the ad ran."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's format, advertiser, targeting and statistics."
},
"is_restricted": {
"type": [
"boolean",
"null"
],
"description": "true when LinkedIn restricts the ad's details."
},
"creative_preview": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's text."
},
"cta_text": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. Learn more."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "The creative image, or a video's cover frame."
},
"media_type": {
"type": [
"string",
"null"
],
"description": "image or video; null for text-only formats."
},
"thumbnail_data_uri": {
"type": [
"string",
"null"
],
"description": "A small JPEG of the creative as a data: URI, when thumbnail data was asked for."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's creative, for up to 12 ads: on paid plans and trials only, and only when the ad's public page could be read."
},
"restriction_details": {
"anyOf": [
{
"type": "object",
"properties": {},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Why LinkedIn restricts the ad, when it does."
}
},
"additionalProperties": {}
},
"description": "The matching ads, as LinkedIn's Ad Library returns them."
},
"total": {
"type": [
"number",
"null"
],
"description": "Total matching ads, when LinkedIn reports it."
},
"next_start": {
"type": [
"number",
"null"
],
"description": "Pass as `start` to read the next page; null when done."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ax_linkedin_search",
"title": "Search LinkedIn ads",
"description": "Searches LinkedIn's public Ad Library for B2B ads, from any advertiser: give at least one of keyword (every word must match), advertiser or payer_name, and optionally countries (two-letter codes), dates and targeting categories. It reads through the user's LinkedIn Ads connection: account_id is optional (default: their first LinkedIn ad account); with none connected, the error carries the link to connect LinkedIn, to show the user. Without dates LinkedIn returns only yesterday's ads, so give start_date for anything longer (the library starts on 2023-06-01); end_date is exclusive. Rows have the advertiser and payer, ad_url (the ad's public page), first and last impression, impression ranges per country and the targeting. On paid plans and trials, from the research budget, creative_preview adds the headline, text, call to action and up to 12 thumbnails; the free plan gets none. No exact spend or impressions. Pages of up to 25 with count; pass next_start back as start until it is null. One call at a time.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"count": {
"type": "integer",
"maximum": 25,
"minimum": 1,
"description": "How many ads one page holds. Defaults to 25. Pass next_start back as start for the next page."
},
"start": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Offset for paging. Pass the previous response's next_start."
},
"keyword": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Keywords to search ad content for. Space-separated words are ANDed by LinkedIn."
},
"end_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "The day after the last serving day to search: the end is exclusive, so for one day pass the next day. Omitted with start_date, the search runs to the latest day the library has."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"maxItems": 20,
"minItems": 1,
"description": "The countries the ads were served in, as ISO codes such as [\"DE\",\"US\"]. Omit for every country."
},
"account_id": {
"type": "string",
"pattern": "^\\d+$",
"description": "The numeric id of one of the user's LinkedIn ad accounts. Optional: without it, the user's first connected LinkedIn ad account is used; any one works, it only signs the request in."
},
"advertiser": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Advertiser (company/page) name to search for."
},
"payer_name": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Who PAID for the ad — can differ from the advertiser (DSA transparency)."
},
"start_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "The first serving day to search. The library covers ads created on or after 2023-06-01; with no dates at all, LinkedIn returns only yesterday's ads."
},
"include_thumbnail_data": {
"type": "boolean",
"description": "Omitted, the ads' thumbnails, where they have one, come back as inline images beside the result, at most 12. True puts each in the result as a data: URI (thumbnail_data_uri) instead, for an artifact that can't load outside images; roughly 10-20 KB more per ad. LinkedIn thumbnails come with creative_preview, on paid plans and trials only."
},
"excluded_targeting_facet_categories": {
"type": "array",
"items": {
"enum": [
"LANGUAGE",
"LOCATION",
"AUDIENCE",
"AGE",
"GENDER",
"COMPANY",
"EDUCATION",
"JOB",
"INTERESTS",
"TRAITS"
],
"type": "string"
},
"minItems": 1,
"description": "Only ads that used NONE of these targeting categories."
},
"included_targeting_facet_categories": {
"type": "array",
"items": {
"enum": [
"LANGUAGE",
"LOCATION",
"AUDIENCE",
"AGE",
"GENDER",
"COMPANY",
"EDUCATION",
"JOB",
"INTERESTS",
"TRAITS"
],
"type": "string"
},
"minItems": 1,
"description": "Only ads that used AT LEAST one of these targeting categories."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rows",
"total",
"next_start"
],
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ad_url": {
"type": [
"string",
"null"
],
"description": "The ad's public page in LinkedIn's Ad Library; its tail is the ad id."
},
"details": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "The ad format, e.g. SPONSORED_STATUS_UPDATE, SPONSORED_VIDEO, SPOTLIGHT_V2."
},
"advertiser": {
"anyOf": [
{
"type": "object",
"properties": {
"ad_payer": {
"type": [
"string",
"null"
],
"description": "Who paid for the ad, as LinkedIn discloses it."
},
"advertiser_url": {
"type": [
"string",
"null"
],
"description": "The advertiser's LinkedIn page."
},
"advertiser_name": {
"type": [
"string",
"null"
],
"description": "The company that ran the ad."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The advertiser and payer."
},
"ad_targeting": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The targeting LinkedIn discloses, one entry per facet with its included and excluded segments; mostly for ads shown in the EU."
},
"ad_statistics": {
"anyOf": [
{
"type": "object",
"properties": {
"total_impressions": {
"anyOf": [
{
"type": "object",
"properties": {},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The total impressions as a range; LinkedIn publishes no exact count."
},
"first_impression_at": {
"type": [
"string",
"null"
],
"description": "When the ad was first shown, ISO 8601."
},
"latest_impression_at": {
"type": [
"string",
"null"
],
"description": "When the ad was last shown, ISO 8601."
},
"impressions_distribution_by_country": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "The share of impressions per country, with two-letter country codes."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "When and how widely the ad ran."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's format, advertiser, targeting and statistics."
},
"is_restricted": {
"type": [
"boolean",
"null"
],
"description": "true when LinkedIn restricts the ad's details."
},
"creative_preview": {
"anyOf": [
{
"type": "object",
"properties": {
"body": {
"type": [
"string",
"null"
],
"description": "The ad's text."
},
"cta_text": {
"type": [
"string",
"null"
],
"description": "The call to action button, e.g. Learn more."
},
"headline": {
"type": [
"string",
"null"
],
"description": "The headline under the media."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "The creative image, or a video's cover frame."
},
"media_type": {
"type": [
"string",
"null"
],
"description": "image or video; null for text-only formats."
},
"thumbnail_data_uri": {
"type": [
"string",
"null"
],
"description": "A small JPEG of the creative as a data: URI, when thumbnail data was asked for."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The ad's creative, for up to 12 ads: on paid plans and trials only, and only when the ad's public page could be read."
},
"restriction_details": {
"anyOf": [
{
"type": "object",
"properties": {},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Why LinkedIn restricts the ad, when it does."
}
},
"additionalProperties": {}
},
"description": "The matching ads, as LinkedIn's Ad Library returns them."
},
"total": {
"type": [
"number",
"null"
],
"description": "Total matching ads, when LinkedIn reports it."
},
"next_start": {
"type": [
"number",
"null"
],
"description": "Pass as `start` to read the next page; null when done."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Search LinkedIn ads",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Opens the HYPD Ad Explorer beside the chat: a grid of a competitor's ads on Meta (Facebook and Instagram), Google or LinkedIn that the user can search, page through, open in the ad library and ask about. Use it when the user wants to see or browse ads rather than read a summary. Give platform and query to open on a search: a brand or keyword on meta (or page_id for one advertiser, with countries), the advertiser's domain on google with location and language (ask the user, never assume), the company on linkedin. Without query it opens empty for the user to search. A search uses the plan allowance like the ax_* lookups. Where the host shows the explorer, the result is one line: do not list the ads, and use the ax_* lookups to read them yourself. Elsewhere it returns the ads as cards.
The description explains the capability, when to use it, and what to expect.
Inputs88/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
platform
Which ad library the explorer opens on: meta (Facebook and Instagram), google (the Ads Transparency Center) or linkedin (LinkedIn's Ad Library). Opens on meta when omitted.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
query
What to search for: a brand or keyword on meta, the advertiser's domain on google ("acme.com"), the company on linkedin. Omitted, the explorer opens empty for the user to search.
Clear enough to supply this argument.
page_id
meta only: one advertiser's Facebook Page id, from ax_meta_find_advertisers, to show its ads instead of a keyword search.
Clear enough to supply this argument.
countries
meta and linkedin: the countries the ads were shown in, as ISO codes such as ["US","DE"]. Omit for every country.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
location
google: the market's country, by name ("United States"). A google query needs it: ask the user, never assume.
Clear enough to supply this argument.
language
google: the market's language, by name ("English"). A google query needs it: ask the user, never assume.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "Open the Ad Explorer",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema79/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"next": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Google: the next page number."
},
"start": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "LinkedIn: the next page's offset."
},
"result_id": {
"type": "string",
"description": "Google: the stored result the next page reads from."
},
"page_token": {
"type": "string",
"description": "Meta: the next page's token."
}
},
"description": "Where the next page starts; absent on the last page.",
"additionalProperties": false
},
"cards": {
"type": "array",
"items": {
"type": "object",
"required": [
"platform",
"id",
"advertiser"
],
"properties": {
"id": {
"type": "string",
"description": "The ad's id in its library: Meta's ad archive id, Google's creative id, or LinkedIn's ad page."
},
"cta": {
"type": "string",
"description": "The call to action button."
},
"body": {
"type": "string",
"description": "The ad's text."
},
"link": {
"type": "string",
"description": "The ad's page in its public library."
},
"format": {
"type": "string",
"description": "The ad format, e.g. image or video."
},
"headline": {
"type": "string",
"description": "The ad's headline."
},
"platform": {
"enum": [
"meta",
"google",
"linkedin"
],
"type": "string",
"description": "The ad library the ad is from."
},
"image_url": {
"type": "string",
"description": "The creative on its CDN."
},
"thumbnail": {
"type": "string",
"description": "A small image of the creative as a data: URI, for the view."
},
"advertiser": {
"type": "string",
"description": "Who ran the ad."
},
"last_shown": {
"type": "string",
"description": "When the ad was last shown."
},
"first_shown": {
"type": "string",
"description": "When the ad was first shown."
}
},
"additionalProperties": false
},
"description": "The ads found, one card each."
},
"search": {
"type": "object",
"required": [
"platform"
],
"properties": {
"query": {
"type": "string",
"description": "The brand or keyword, the advertiser's domain, or the company."
},
"page_id": {
"type": "string",
"description": "Meta: the advertiser's Facebook Page id."
},
"language": {
"type": "string",
"description": "Google: the market's language."
},
"location": {
"type": "string",
"description": "Google: the market's country."
},
"platform": {
"enum": [
"meta",
"google",
"linkedin"
],
"type": "string",
"description": "The library searched."
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Meta and LinkedIn: the countries searched."
}
},
"description": "The search the explorer opened on.",
"additionalProperties": false
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "ax_open_explorer",
"title": "Open the Ad Explorer",
"description": "Opens the HYPD Ad Explorer beside the chat: a grid of a competitor's ads on Meta (Facebook and Instagram), Google or LinkedIn that the user can search, page through, open in the ad library and ask about. Use it when the user wants to see or browse ads rather than read a summary. Give platform and query to open on a search: a brand or keyword on meta (or page_id for one advertiser, with countries), the advertiser's domain on google with location and language (ask the user, never assume), the company on linkedin. Without query it opens empty for the user to search. A search uses the plan allowance like the ax_* lookups. Where the host shows the explorer, the result is one line: do not list the ads, and use the ax_* lookups to read them yourself. Elsewhere it returns the ads as cards.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"query": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "What to search for: a brand or keyword on meta, the advertiser's domain on google (\"acme.com\"), the company on linkedin. Omitted, the explorer opens empty for the user to search."
},
"page_id": {
"type": "string",
"pattern": "^\\d+$",
"description": "meta only: one advertiser's Facebook Page id, from ax_meta_find_advertisers, to show its ads instead of a keyword search."
},
"language": {
"type": "string",
"minLength": 1,
"description": "google: the market's language, by name (\"English\"). A google query needs it: ask the user, never assume."
},
"location": {
"type": "string",
"minLength": 1,
"description": "google: the market's country, by name (\"United States\"). A google query needs it: ask the user, never assume."
},
"platform": {
"enum": [
"meta",
"google",
"linkedin"
],
"type": "string",
"description": "Which ad library the explorer opens on: meta (Facebook and Instagram), google (the Ads Transparency Center) or linkedin (LinkedIn's Ad Library). Opens on meta when omitted."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"maxItems": 20,
"description": "meta and linkedin: the countries the ads were shown in, as ISO codes such as [\"US\",\"DE\"]. Omit for every country."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"next": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Google: the next page number."
},
"start": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "LinkedIn: the next page's offset."
},
"result_id": {
"type": "string",
"description": "Google: the stored result the next page reads from."
},
"page_token": {
"type": "string",
"description": "Meta: the next page's token."
}
},
"description": "Where the next page starts; absent on the last page.",
"additionalProperties": false
},
"cards": {
"type": "array",
"items": {
"type": "object",
"required": [
"platform",
"id",
"advertiser"
],
"properties": {
"id": {
"type": "string",
"description": "The ad's id in its library: Meta's ad archive id, Google's creative id, or LinkedIn's ad page."
},
"cta": {
"type": "string",
"description": "The call to action button."
},
"body": {
"type": "string",
"description": "The ad's text."
},
"link": {
"type": "string",
"description": "The ad's page in its public library."
},
"format": {
"type": "string",
"description": "The ad format, e.g. image or video."
},
"headline": {
"type": "string",
"description": "The ad's headline."
},
"platform": {
"enum": [
"meta",
"google",
"linkedin"
],
"type": "string",
"description": "The ad library the ad is from."
},
"image_url": {
"type": "string",
"description": "The creative on its CDN."
},
"thumbnail": {
"type": "string",
"description": "A small image of the creative as a data: URI, for the view."
},
"advertiser": {
"type": "string",
"description": "Who ran the ad."
},
"last_shown": {
"type": "string",
"description": "When the ad was last shown."
},
"first_shown": {
"type": "string",
"description": "When the ad was first shown."
}
},
"additionalProperties": false
},
"description": "The ads found, one card each."
},
"search": {
"type": "object",
"required": [
"platform"
],
"properties": {
"query": {
"type": "string",
"description": "The brand or keyword, the advertiser's domain, or the company."
},
"page_id": {
"type": "string",
"description": "Meta: the advertiser's Facebook Page id."
},
"language": {
"type": "string",
"description": "Google: the market's language."
},
"location": {
"type": "string",
"description": "Google: the market's country."
},
"platform": {
"enum": [
"meta",
"google",
"linkedin"
],
"type": "string",
"description": "The library searched."
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Meta and LinkedIn: the countries searched."
}
},
"description": "The search the explorer opened on.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"annotations": {
"title": "Open the Ad Explorer",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description89/100
Shows the user's getting started steps for HYPD Ad Explorer: looking up a competitor's ads on Meta, on Google and on LinkedIn. Meta and Google need nothing connected; LinkedIn needs the user's LinkedIn. Use it when init says so, or when the user is new or asks how to get started; a concrete question about a competitor goes straight to the ax_* tools. Clients that render MCP Apps show the steps with a button each: a click sends that step's prompt as the user's next message, or opens the HYPD app. There, say only that the steps are shown above: do not repeat them and do not run a step before the user clicks it. Elsewhere, list the steps with their prompts and links.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
No input fields.
Annotations100/100
All four behavior hints are declared.
{
"title": "Getting started with HYPD Ad Explorer",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
Output schema76/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"done_count",
"step_count"
],
"properties": {
"done_count": {
"type": "number",
"description": "Steps the user has completed."
},
"step_count": {
"type": "number",
"description": "Steps in total."
}
},
"description": "Counts only. The steps, with their prompts and links, go to the widget; the text content lists them for clients that show no widget.",
"additionalProperties": false
}
Original tool metadata
{
"name": "hypd_show_getting_started",
"title": "Getting started with HYPD Ad Explorer",
"description": "Shows the user's getting started steps for HYPD Ad Explorer: looking up a competitor's ads on Meta, on Google and on LinkedIn. Meta and Google need nothing connected; LinkedIn needs the user's LinkedIn. Use it when init says so, or when the user is new or asks how to get started; a concrete question about a competitor goes straight to the ax_* tools. Clients that render MCP Apps show the steps with a button each: a click sends that step's prompt as the user's next message, or opens the HYPD app. There, say only that the steps are shown above: do not repeat them and do not run a step before the user clicks it. Elsewhere, list the steps with their prompts and links.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"done_count",
"step_count"
],
"properties": {
"done_count": {
"type": "number",
"description": "Steps the user has completed."
},
"step_count": {
"type": "number",
"description": "Steps in total."
}
},
"description": "Counts only. The steps, with their prompts and links, go to the widget; the text content lists them for clients that show no widget.",
"additionalProperties": false
},
"annotations": {
"title": "Getting started with HYPD Ad Explorer",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description95/100
Lists the user's messages from the HYPD team, newest first: announcements, plan news and actions needed, each with its text, an optional link, and whether it is unread. Use it when the user asks about messages or news from HYPD, or a tool result mentions unread HYPD inbox messages. Listing does not mark anything read; the user does that by opening inbox_url.
The description explains the capability, when to use it, and what to expect.
Inputs100/100
This tool declares no inputs, so argument descriptions are not needed.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"unread_count",
"inbox_url",
"messages",
"note"
],
"properties": {
"note": {
"type": "string",
"description": "How messages become read."
},
"messages": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"title",
"body",
"published_at",
"read"
],
"properties": {
"body": {
"type": "string",
"description": "The message text."
},
"kind": {
"enum": [
"announcement",
"plan",
"action"
],
"type": "string",
"description": "announcement: news from HYPD. plan: about the user's HYPD plan. action: something the user needs to do."
},
"read": {
"type": "boolean",
"description": "Whether the user has opened it in the Inbox."
},
"title": {
"type": "string",
"description": "The message's headline."
},
"link_url": {
"type": "string",
"description": "Where the message points the user, when it has a link."
},
"link_label": {
"type": "string",
"description": "The link's button text, when the message has one."
},
"published_at": {
"type": "string",
"description": "When HYPD published the message (ISO 8601, UTC)."
}
},
"additionalProperties": false
},
"description": "The newest messages, newest first, at most 20."
},
"inbox_url": {
"type": "string",
"description": "The user's Inbox in the HYPD app; opening it marks messages read."
},
"unread_count": {
"type": "number",
"description": "Unread messages in the whole Inbox, not only those listed."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "hypd_list_inbox_messages",
"title": "List HYPD inbox messages",
"description": "Lists the user's messages from the HYPD team, newest first: announcements, plan news and actions needed, each with its text, an optional link, and whether it is unread. Use it when the user asks about messages or news from HYPD, or a tool result mentions unread HYPD inbox messages. Listing does not mark anything read; the user does that by opening inbox_url.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"unread_count",
"inbox_url",
"messages",
"note"
],
"properties": {
"note": {
"type": "string",
"description": "How messages become read."
},
"messages": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"title",
"body",
"published_at",
"read"
],
"properties": {
"body": {
"type": "string",
"description": "The message text."
},
"kind": {
"enum": [
"announcement",
"plan",
"action"
],
"type": "string",
"description": "announcement: news from HYPD. plan: about the user's HYPD plan. action: something the user needs to do."
},
"read": {
"type": "boolean",
"description": "Whether the user has opened it in the Inbox."
},
"title": {
"type": "string",
"description": "The message's headline."
},
"link_url": {
"type": "string",
"description": "Where the message points the user, when it has a link."
},
"link_label": {
"type": "string",
"description": "The link's button text, when the message has one."
},
"published_at": {
"type": "string",
"description": "When HYPD published the message (ISO 8601, UTC)."
}
},
"additionalProperties": false
},
"description": "The newest messages, newest first, at most 20."
},
"inbox_url": {
"type": "string",
"description": "The user's Inbox in the HYPD app; opening it marks messages read."
},
"unread_count": {
"type": "number",
"description": "Unread messages in the whole Inbox, not only those listed."
}
},
"additionalProperties": false
},
"annotations": {
"title": "List HYPD inbox messages",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}
The title clearly communicates the tool’s action and subject. Keep it concise.
Description94/100
Searches HYPD's help center for articles that answer a question about HYPD itself: connecting or reconnecting ad accounts, plans, billing and credits, privacy and data access, what HYPD can do, and setting HYPD up in Claude, ChatGPT or other AI clients. Returns the matching articles' text and links; answer from them and cite them. Not for advertising advice or the user's account data; use the platform tools for those.
The description explains the capability, when to use it, and what to expect.
Inputs75/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
question
The user's question about HYPD, in their words, e.g. 'How do I connect my Google Ads account?'
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "Search the HYPD help center",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
Output schema74/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"status",
"articles",
"help_center_url",
"note"
],
"properties": {
"note": {
"type": "string",
"description": "How these results relate to the question."
},
"status": {
"enum": [
"ok",
"no_results"
],
"type": "string",
"description": "no_results when no article matched."
},
"articles": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"url",
"description",
"content",
"updated_at"
],
"properties": {
"url": {
"type": "string",
"description": "The article's public link."
},
"title": {
"type": "string",
"description": "The article's title."
},
"content": {
"type": "string",
"description": "The article text to answer from."
},
"updated_at": {
"type": "string",
"description": "When the article last changed."
},
"description": {
"type": "string",
"description": "A one-line summary."
}
},
"additionalProperties": false
},
"description": "The matching articles."
},
"help_center_url": {
"type": "string",
"description": "The help center, for questions no article answers."
}
},
"additionalProperties": false
}
Original tool metadata
{
"name": "hypd_search_help",
"title": "Search the HYPD help center",
"description": "Searches HYPD's help center for articles that answer a question about HYPD itself: connecting or reconnecting ad accounts, plans, billing and credits, privacy and data access, what HYPD can do, and setting HYPD up in Claude, ChatGPT or other AI clients. Returns the matching articles' text and links; answer from them and cite them. Not for advertising advice or the user's account data; use the platform tools for those.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"question"
],
"properties": {
"question": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "The user's question about HYPD, in their words, e.g. 'How do I connect my Google Ads account?'"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"status",
"articles",
"help_center_url",
"note"
],
"properties": {
"note": {
"type": "string",
"description": "How these results relate to the question."
},
"status": {
"enum": [
"ok",
"no_results"
],
"type": "string",
"description": "no_results when no article matched."
},
"articles": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"url",
"description",
"content",
"updated_at"
],
"properties": {
"url": {
"type": "string",
"description": "The article's public link."
},
"title": {
"type": "string",
"description": "The article's title."
},
"content": {
"type": "string",
"description": "The article text to answer from."
},
"updated_at": {
"type": "string",
"description": "When the article last changed."
},
"description": {
"type": "string",
"description": "A one-line summary."
}
},
"additionalProperties": false
},
"description": "The matching articles."
},
"help_center_url": {
"type": "string",
"description": "The help center, for questions no article answers."
}
},
"additionalProperties": false
},
"annotations": {
"title": "Search the HYPD help center",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}
Loading score analytics…
Put your MCP to the test
A few tasks worth trying with this server, chosen from its reviewed tools. These have not been run.
01Search Meta ads by keywordSearches Meta's public Ad Library for Facebook and Instagram ads that mention a keyword or phrase, from any advertiser: how a whole market advertises, and th…
02Search the HYPD help centerSearches HYPD's help center for articles that answer a question about HYPD itself: connecting or reconnecting ad accounts, plans, billing and credits, privac…
03Find a brand's Facebook PageFinds the Facebook Page that runs a brand's Meta ads, from its name: each row's page_id is what ax_meta_advertiser_ads needs, with the page_name, categories,…
04List HYPD inbox messagesLists the user's messages from the HYPD team, newest first: announcements, plan news and actions needed, each with its text, an optional link, and whether it…
05Find a brand on GoogleFinds the advertisers Google's Ads Transparency Center lists for a brand or keyword, each with its advertiser id and domain: the step before ax_google_advert…
Want to run these tasks against your MCP server with us?
HYPD AI for Ad Explorer setup, tools, quality score, publishing readiness, and alternatives.
How do I add HYPD AI for Ad Explorer to Claude, ChatGPT, or Cursor?
Add HYPD AI for Ad Explorer to Claude, ChatGPT, or Cursor by connecting its remote MCP URL in each client's MCP settings. In Claude, add a custom connector. In ChatGPT, add an MCP app. In Cursor, add an MCP server under Settings. The MCP URL is https://adexplorer.hypd.ai/mcp.
Is HYPD AI for Ad Explorer MCP ready for ChatGPT and Claude?
As of November 17, 2026, HYPD AI for Ad Explorer scores 100/100 on Manufact's MCP publishing checklist. The scan meets ChatGPT publishing checks and meets Claude publishing checks. Passing these checks does not guarantee marketplace approval.
How clear is HYPD AI for Ad Explorer's MCP tool documentation?
As of November 17, 2026, HYPD AI for Ad Explorer scores 94/100 in Manufact's review of tool titles, descriptions, input and output schemas, and behavior annotations. The review covers 12 of 12 discovered tools. The quality score measures documentation clarity; runtime behavior and marketplace readiness require separate checks.
What are the best alternatives to HYPD AI for Ad Explorer?
As of November 17, 2026, alternatives to HYPD AI for Ad Explorer in marketing-seo on the Manufact MCP leaderboard include Notra, BulkPublish, Fuxux, HYPD AI for Ad Library, and HYPD AI for App Store Optimization.
Not your MCP?
Review any public or OAuth MCP server for protocol compatibility, tool documentation, and ChatGPT and Claude publishing readiness. No account required.