Skip to main content
Glama

Search advertisers

search_advertisers
Read-only

Search advertisers by NAME, numeric Facebook page id, or a pasted facebook.com page link (typeahead; query ≥2 chars). A link in any form (vanity name, profile 100…-id, profile.php, Ads Library view_all_page_id) and either id namespace resolve to the canonical fanpage with the exact match first. Returns advertisers with external_id (the Facebook page id), advertiser_id (the INTERNAL advertiser UUID; advertiser_ids lists every internal record when a page has several) and ad_count. To fetch ONE advertiser's full card by id use get_advertiser; to see an advertiser's ads, call search_ads with page_id=<external_id> (covers every internal record of the page) or advertiser_id=<advertiser_id>. For advertiser RANKINGS, ordering and filters (category/country/followers/founded-date/life_status/hubs), use get_trends with dimension=advertisers. With search_arbitrage=true or any sa_* filter it lists the advertisers whose ads are search arbitrage (ads leading to pages that earn from search-ads clicks), most ads first. FREE PLAN COUNTS: when the plan's archive window narrows a request, pagination.total_status is "restricted" and meta.plan_window_cutoff names the boundary — the count then describes the window actually searched, NOT the one requested, so a zero means "nothing in the archive window" and never "nothing exists". QUOTA: 1 MCP credit per DELIVERED result from your plan balance (free starter: 500 MCP credits lifetime; paid plans: 40,000/month; short pages auto-refund — you pay only for results you receive). Default page is 20 results = 20 MCP credits; pass limit (1–200) to size it. get_usage is free. Autonomous agents must be linked to a spytrend account to access data — an unlinked agent gets an actionable connect-your-account refusal (create agent credentials at spytrend.com/settings?tab=ai, or a human claims it by client_id), NOT a server error. Calls are rate-limited per authenticated user (deployment defaults: 60/minute and 1000/hour); a rate-limit refusal is an MCP tool error with structured error.code=rate_limit_exceeded, scope, window and retry_after_seconds. CONCURRENCY: heavy analytical calls (get_trends, search_ads, search_creatives) are admitted ONE AT A TIME per account — fanning out 5-10 of them in parallel does not go faster, it returns admission refusals for all but one. Issue heavy calls sequentially; light lookups (get_ad, get_advertiser, get_usage) are not gated. PRICING: price × number of filters set (min 1), on paid plans ×1 after 500 MCP credits/month; one-time consent via accept_pricing_terms; before calling, get the maximum debit from estimate_cost (free) and tell the user.

Input Schema

NameRequiredDescriptionDefault
limitNomax results, 1-50 (default 20 — this typeahead is capped at 50 upstream; a larger value is clamped, not rejected). Each delivered result costs 1 MCP credit.
queryNoadvertiser name (at least 2 characters), a numeric Facebook page id (either the Ads Library page id or the direct-page profile 100…-id), OR a pasted facebook.com page link in any form (vanity, profile.php, Ads Library) — links and ids resolve to the canonical fanpage with the exact match first. With search_arbitrage / sa_* the query is optional and matches a name substring or one exact numeric page id; pasted links are NOT resolved there.

Output Schema

NameRequiredDescriptionDefault
metaNo
errorNoPresent only when isError is true: machine-readable failure. The human explanation stays in content.
itemsNo
totalNo
paramsNoRequest parameter echo: applied = parameters that shaped this result; normalized = parameters rewritten before applying (alias, type coercion, resolved id); ignored = parameters that were accepted but NOT applied, with the reason.
addon_hintsNoAdd-on modules that have additional data for objects of this result (no prices, no paid values). subscription_status=active: the account has the module — use its normal path. Do not push a purchase the user did not ask about.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"max results, 1-50 (default 20 — this typeahead is capped at 50 upstream; a larger value is clamped, not rejected). Each delivered result costs 1 token."New value: +"max results, 1-50 (default 20 — this typeahead is capped at 50 upstream; a larger value is clamped, not rejected). Each delivered result costs 1 MCP credit."
    • removedInput schema / properties / sa_country
      Removed value: -{
      -  "description": "ISO-2 codes of the countries the ads are shown in (OR), e.g. US, GB, DE — NOT the visitor country of the site. Implies search_arbitrage.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": [
      -    "null",
      -    "array"
      -  ]
      -}
    • removedInput schema / properties / sa_lang
      Removed value: -{
      -  "description": "ISO 639-1 language codes of the search phrases (OR), e.g. en, de, es. Implies search_arbitrage.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": [
      -    "null",
      -    "array"
      -  ]
      -}
    • removedInput schema / properties / sa_network
      Removed value: -{
      -  "description": "search-arbitrage network slugs (OR): the search-ads network the site monetises through, e.g. tonic, visymo, medianet, cortex, predicto, codefuel, brandclick, system1. Live list with counts: search_arbitrage_facets. Implies search_arbitrage.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": [
      -    "null",
      -    "array"
      -  ]
      -}
    • removedInput schema / properties / sa_phrase
      Removed value: -{
      -  "description": "exact search phrases (OR), lower-case, as returned by search_arbitrage_phrases; a phrase containing a comma cannot be used here. Implies search_arbitrage.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": [
      -    "null",
      -    "array"
      -  ]
      -}
    • removedInput schema / properties / sa_pub
      Removed value: -{
      -  "description": "Google publisher account ids (OR), e.g. pub-1902826156353358: the AdSense/AFS account the site earns under — one account usually means one operator. A bare number or ca-pub-… is accepted. Implies search_arbitrage.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": [
      -    "null",
      -    "array"
      -  ]
      -}
    • removedInput schema / properties / sa_source
      Removed value: -{
      -  "description": "how the site earns from search (OR): rsoc (Google related-search ads through a partner), afs (Google AdSense for Search), yahoo_feed, bing_feed or other. Implies search_arbitrage.",
      -  "items": {
      -    "enum": [
      -      "rsoc",
      -      "afs",
      -      "yahoo_feed",
      -      "bing_feed",
      -      "other"
      -    ],
      -    "type": "string"
      -  },
      -  "type": [
      -    "null",
      -    "array"
      -  ]
      -}
    • removedInput schema / properties / sa_topic
      Removed value: -{
      -  "description": "topic slugs of the search phrases the sites push (OR); live list with counts: search_arbitrage_facets. Implies search_arbitrage.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": [
      -    "null",
      -    "array"
      -  ]
      -}
    • removedInput schema / properties / search_arbitrage
      Removed value: -{
      -  "description": "SEARCH ARBITRAGE filter (confirmed search-arbitrage sites only): true = list only advertisers whose ads lead to search-arbitrage pages — pages that earn from search-ads clicks (Google RSOC/AFS through networks such as Tonic or Visymo, Yahoo/Bing feeds) instead of selling a product — ordered by total ads. Every sa_* filter implies it. Omit or false = the plain name/page-id typeahead. Valid sa_* values and counts: search_arbitrage_facets; the phrases behind them: search_arbitrage_phrases.",
      -  "type": "boolean"
      -}
    • addedOutput schema / properties / addon_hints
      Added value: +{
      +  "description": "Add-on modules that have additional data for objects of this result (no prices, no paid values). subscription_status=active: the account has the module — use its normal path. Do not push a purchase the user did not ask about.",
      +  "items": {
      +    "properties": {
      +      "available_data_types": {
      +        "description": "kinds of data the module confirmedly has for the object",
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "info_url": {
      +        "description": "the object (or its limited breakdown) inside the module on spytrend.com",
      +        "type": "string"
      +      },
      +      "module": {
      +        "description": "nutra | crypto | web2app | search_arb | startups",
      +        "type": "string"
      +      },
      +      "object_id": {
      +        "description": "the ad id, or the site domain for site rows",
      +        "type": "string"
      +      },
      +      "preland_downloadable": {
      +        "description": "Nutra / Crypto: the saved pre-lander can be downloaded in the module",
      +        "type": "boolean"
      +      },
      +      "subscription_status": {
      +        "description": "active | not_connected",
      +        "type": "string"
      +      }
      +    },
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  2. Changed4 schema fields changed
    • removedInput schema / properties / sa_evidence_min
      Removed value: -{
      -  "description": "minimum evidence share of the site, 0 to 1 (e.g. 0.8): the fraction of the site's checked pages that showed the network's markers; higher means a more certain verdict. Implies search_arbitrage.",
      -  "maximum": 1,
      -  "minimum": 0,
      -  "type": "number"
      -}
    • removedInput schema / properties / sa_link
      Removed value: -{
      -  "description": "how the ad reaches the site: tracker (a network tracking/redirect link that carries the phrase) or direct (the ad points straight at the monetised site). Omit for both. Implies search_arbitrage.",
      -  "enum": [
      -    "tracker",
      -    "direct"
      -  ],
      -  "type": "string"
      -}
    • removedInput schema / properties / sa_verdict
      Removed value: -{
      -  "description": "detection confidence (OR): confirmed (network markers found on the site) or probable. Omit for both. Implies search_arbitrage.",
      -  "items": {
      -    "enum": [
      -      "confirmed",
      -      "probable"
      -    ],
      -    "type": "string"
      -  },
      -  "type": [
      -    "null",
      -    "array"
      -  ]
      -}
    • changedInput schema / properties / search_arbitrage / description
      Previous value: -"SEARCH ARBITRAGE filter: true = list only advertisers whose ads lead to search-arbitrage pages — pages that earn from search-ads clicks (Google RSOC/AFS through networks such as Tonic or Visymo, Yahoo/Bing feeds) instead of selling a product — ordered by total ads. Every sa_* filter implies it. Omit or false = the plain name/page-id typeahead. Valid sa_* values and counts: search_arbitrage_facets; the phrases behind them: search_arbitrage_phrases."New value: +"SEARCH ARBITRAGE filter (confirmed search-arbitrage sites only): true = list only advertisers whose ads lead to search-arbitrage pages — pages that earn from search-ads clicks (Google RSOC/AFS through networks such as Tonic or Visymo, Yahoo/Bing feeds) instead of selling a product — ordered by total ads. Every sa_* filter implies it. Omit or false = the plain name/page-id typeahead. Valid sa_* values and counts: search_arbitrage_facets; the phrases behind them: search_arbitrage_phrases."
  3. Changed12 schema fields changed
    • changedInput schema / properties / query / description
      Previous value: -"advertiser name (at least 2 characters), a numeric Facebook page id (either the Ads Library page id or the direct-page profile 100…-id), OR a pasted facebook.com page link in any form (vanity, profile.php, Ads Library) — links and ids resolve to the canonical fanpage with the exact match first"New value: +"advertiser name (at least 2 characters), a numeric Facebook page id (either the Ads Library page id or the direct-page profile 100…-id), OR a pasted facebook.com page link in any form (vanity, profile.php, Ads Library) — links and ids resolve to the canonical fanpage with the exact match first. With search_arbitrage / sa_* the query is optional and matches a name substring or one exact numeric page id; pasted links are NOT resolved there."
    • addedInput schema / properties / sa_country
      Added value: +{
      +  "description": "ISO-2 codes of the countries the ads are shown in (OR), e.g. US, GB, DE — NOT the visitor country of the site. Implies search_arbitrage.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedInput schema / properties / sa_evidence_min
      Added value: +{
      +  "description": "minimum evidence share of the site, 0 to 1 (e.g. 0.8): the fraction of the site's checked pages that showed the network's markers; higher means a more certain verdict. Implies search_arbitrage.",
      +  "maximum": 1,
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / sa_lang
      Added value: +{
      +  "description": "ISO 639-1 language codes of the search phrases (OR), e.g. en, de, es. Implies search_arbitrage.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedInput schema / properties / sa_link
      Added value: +{
      +  "description": "how the ad reaches the site: tracker (a network tracking/redirect link that carries the phrase) or direct (the ad points straight at the monetised site). Omit for both. Implies search_arbitrage.",
      +  "enum": [
      +    "tracker",
      +    "direct"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / sa_network
      Added value: +{
      +  "description": "search-arbitrage network slugs (OR): the search-ads network the site monetises through, e.g. tonic, visymo, medianet, cortex, predicto, codefuel, brandclick, system1. Live list with counts: search_arbitrage_facets. Implies search_arbitrage.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedInput schema / properties / sa_phrase
      Added value: +{
      +  "description": "exact search phrases (OR), lower-case, as returned by search_arbitrage_phrases; a phrase containing a comma cannot be used here. Implies search_arbitrage.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedInput schema / properties / sa_pub
      Added value: +{
      +  "description": "Google publisher account ids (OR), e.g. pub-1902826156353358: the AdSense/AFS account the site earns under — one account usually means one operator. A bare number or ca-pub-… is accepted. Implies search_arbitrage.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedInput schema / properties / sa_source
      Added value: +{
      +  "description": "how the site earns from search (OR): rsoc (Google related-search ads through a partner), afs (Google AdSense for Search), yahoo_feed, bing_feed or other. Implies search_arbitrage.",
      +  "items": {
      +    "enum": [
      +      "rsoc",
      +      "afs",
      +      "yahoo_feed",
      +      "bing_feed",
      +      "other"
      +    ],
      +    "type": "string"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedInput schema / properties / sa_topic
      Added value: +{
      +  "description": "topic slugs of the search phrases the sites push (OR); live list with counts: search_arbitrage_facets. Implies search_arbitrage.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedInput schema / properties / sa_verdict
      Added value: +{
      +  "description": "detection confidence (OR): confirmed (network markers found on the site) or probable. Omit for both. Implies search_arbitrage.",
      +  "items": {
      +    "enum": [
      +      "confirmed",
      +      "probable"
      +    ],
      +    "type": "string"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedInput schema / properties / search_arbitrage
      Added value: +{
      +  "description": "SEARCH ARBITRAGE filter: true = list only advertisers whose ads lead to search-arbitrage pages — pages that earn from search-ads clicks (Google RSOC/AFS through networks such as Tonic or Visymo, Yahoo/Bing feeds) instead of selling a product — ordered by total ads. Every sa_* filter implies it. Omit or false = the plain name/page-id typeahead. Valid sa_* values and counts: search_arbitrage_facets; the phrases behind them: search_arbitrage_phrases.",
      +  "type": "boolean"
      +}
  4. Changed5 schema fields changed
    • addedOutput schema / properties / error
      Added value: +{
      +  "description": "Present only when isError is true: machine-readable failure. The human explanation stays in content.",
      +  "properties": {
      +    "code": {
      +      "description": "fine-grained, stable failure code (e.g. invalid_arguments, backend_busy)",
      +      "type": "string"
      +    },
      +    "kind": {
      +      "description": "failure class: invalid_argument, not_found, permission_denied, unauthenticated, quota_exceeded, rate_limited, temporarily_unavailable, unavailable_until_ready, unsupported, internal",
      +      "type": "string"
      +    },
      +    "message": {
      +      "description": "the same human text as content[0]",
      +      "type": "string"
      +    },
      +    "outcome": {
      +      "description": "activity-feed outcome class",
      +      "type": "string"
      +    },
      +    "param": {
      +      "description": "the request parameter the failure is about, when known",
      +      "type": "string"
      +    },
      +    "retry_after_seconds": {
      +      "description": "wait this long before retrying",
      +      "type": "integer"
      +    },
      +    "retryable": {
      +      "description": "true when repeating the SAME call can succeed (after retry_after_seconds when present)",
      +      "type": "boolean"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / items / items / properties / advertiser_id
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / items / items / properties / advertiser_ids
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "null",
      +    "array"
      +  ]
      +}
    • addedOutput schema / properties / params
      Added value: +{
      +  "description": "Request parameter echo: applied = parameters that shaped this result; normalized = parameters rewritten before applying (alias, type coercion, resolved id); ignored = parameters that were accepted but NOT applied, with the reason.",
      +  "properties": {
      +    "applied": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "ignored": {
      +      "items": {
      +        "properties": {
      +          "param": {
      +            "type": "string"
      +          },
      +          "reason": {
      +            "type": "string"
      +          },
      +          "to": {
      +            "description": "the parameter it was applied as, when renamed",
      +            "type": "string"
      +          },
      +          "value": {
      +            "description": "the value actually applied, when rewritten",
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "normalized": {
      +      "items": {
      +        "properties": {
      +          "param": {
      +            "type": "string"
      +          },
      +          "reason": {
      +            "type": "string"
      +          },
      +          "to": {
      +            "description": "the parameter it was applied as, when renamed",
      +            "type": "string"
      +          },
      +          "value": {
      +            "description": "the value actually applied, when rewritten",
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "items"
      -]
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/openWorld annotations, it discloses the credit cost model (1 MCP credit per delivered result, 20 by default, refunds on short pages), plan balance limits, auth-linking requirement with the failure mode (actionable refusal, not a server error), per-user rate limits with structured error.code=rate_limit_exceeded, and one-at-a-time admission for heavy calls. It even explains the restricted-archive-window behavior so a zero count isn't misread as 'no such advertiser'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and routing are front-loaded, which is good, but the paragraph is very long for a two-parameter tool and carries a large block of cross-cutting operational policy (quota, auth, rate limits, concurrency, pricing) that reads like boilerplate repeated across the server. Every sentence is informative, yet the density makes the tool-specific signal harder to extract.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shapes needn't be explained, yet the description still names the key fields (external_id, advertiser_id, advertiser_ids, ad_count) that drive the follow-up calls it recommends. Combined with cost, auth, and failure-mode disclosure, nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning — that links in any form resolve to the canonical fanpage with the exact match first, that either id namespace works, and that under search_arbitrage/sa_* the query becomes optional and pasted links are not resolved. One defect: the description says 'pass `limit` (1–200)' while the schema caps it at 1–50, a range inconsistency an agent could trip over.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names the verb and resource and enumerates the three accepted query forms (name, numeric page id, pasted facebook.com link). It explicitly separates this tool from get_advertiser (single card by id) and search_ads (an advertiser's ads), so an agent can route without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Alternatives are named with the exact condition that selects each: get_advertiser for one advertiser's full card, search_ads with page_id/advertiser_id for ads, get_trends with dimension=advertisers for rankings and filters. It also flags the arbitrage-only mode (search_arbitrage=true or sa_* filters) as a distinct usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.