Spytrend

Get advertiser by id

get_advertiser

Read-only

Fetch a single advertiser's FULL card by id — the same data as the spytrend.com/advertisers page: name, external_id (FB page id), avatar_url, page_url, total_ads and active_ads (EXACT precomputed counts — THIS is the cheap way to answer 'how many ads / how many are active does this advertiser run', NOT paginating search_ads, whose total is estimated for advertiser_id), launched_14d, top_countries (geo breakdown), platforms, top_landing (destination domains), page_like_count (followers), born (founded date), categories and recent creatives. The card also embeds top_creatives — the advertiser's MOST RE-UPLOADED creatives (a creative's total_ads = how many ads reuse the same material, ordered desc, media stripped/free); present these as the headline at the end and download with get_media (entity_type=creo). The id is an advertiser UUID (from an ad's advertiser_id / get_trends dimension=advertisers) OR a Facebook page id — a fanpage id from get_creative's fanpages, or an ad's page_id: a page id is resolved to its advertiser automatically, so a fanpage you found in a creative resolves straight to its card. A pasted facebook.com page link (any form — vanity name, profile 100…-id, profile.php, Ads Library) is likewise resolved to the page automatically. To list the advertiser's ads, call search_ads with advertiser_id. CATEGORY COUNTERS CONTRACT category_total_ads / subcategory_total_ads and every top_categories[].ads_count / top_subcategories[].ads_count count ONLY the advertiser's AI-LABELED ads - they are a share of the labeled subset, NOT of the page's ad universe. The labeling share is ai_coverage (labeled / total_ads). Read them as: 'N of total_ads ads are labeled (ai_coverage), and X% of THOSE are '. Never compare category_total_ads against total_ads/active_ads directly, and never report a category share as the advertiser's overall vertical mix when ai_coverage is low. QUOTA: 1 token (one entity card). TOP_CREATIVES CONTRACT each top_creatives entry's total_ads counts the creative's FULL family of matching material across the whole serving universe as the market-wide reuse of that creative; note the family may span MORE advertisers than this page — it is the creative's market-wide reuse, not this advertiser's share.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes	the resource id to fetch

Output Schema

TableJSON Schema

Name	Required	Description
`data`	No
`error`	No	Present only when isError is true: machine-readable failure. The human explanation stays in content.
`params`	No	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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 25, 2026

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 / 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"
+}

First observedSep 2, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the readOnlyHint/openWorldHint annotations, the description reveals important behaviors: id resolution from UUID, Facebook page id, or pasted page link, quota cost of 1 token, the fact that search_ads totals are estimated, and the category-counter semantics around ai_coverage. It also explains the top_creatives contract, including the market-wide reuse meaning, which is not derivable from annotations.

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

Conciseness4/5

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

The description is long and dense, but it is front-loaded with the core fetch purpose and the main field list, and the explicit CONTRACT sections are structurally marked. It could be more scannable with bullets, but every sentence earns its place given the number of API-specific caveats.

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?

Given the tool's complexity and the sparse input schema, the description fully covers the return payload, id resolution, quota impact, counter semantics, and relationships to sibling tools. With an output schema present, this is more than enough for an agent to call the tool correctly.

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

Parameters5/5

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

Even though the schema covers the single id parameter (100% coverage), the description adds substantial semantics: id can be an advertiser UUID, a Facebook page id, or a pasted facebook.com link that gets resolved automatically. This transforms a generic 'resource id' into actionable parameter usage information.

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 description opens with a specific verb and resource ('Fetch a single advertiser's FULL card by id') and enumerates the exact fields included, tying it to the spytrend.com/advertisers page. It also distinguishes itself from sibling tools like search_ads and get_creative, so the tool's purpose is unmistakable.

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?

The description gives explicit when-to-use guidance: it is the cheap way to get exact ad counts, explicitly warns against paginating search_ads for that purpose, and tells the user to call search_ads with advertiser_id to list ads. It also names get_media for downloading creatives, providing clear routing.

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

All Spytrend tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.