Skip to main content
Glama
Sign In

ShortsIntel

by com.shortsintel
OverviewDiscussionsAdmin

Search ad libraries

search_ads

Use when you need Meta, TikTok or Google Ads by query or advertiser (one). Not for one Ad or an Advertiser's profile: use get_ad. To watch an Advertiser: track. Price: Meta 1 credit per Ad delivered; TikTok 3 credits per page; Google 3 credits per Ad; +20 credits per Ad analysed. Meta: status, kind, media_type, placements, started_after/before, limit; order_by winner. analyze: first 50. TikTok: EU/EEA, CH, UK and Turkey only; advertiser: id, library URL or name (advertiser_ambiguous: candidates, free).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "library": "<library>"
    },
    "name": "search_ads"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoMeta only. Default commercial.
limitNoMax: Meta 500 (default 50), TikTok 30, Google 200 (default 40).
queryNoNot Google.
cursorNo
statusNoMeta only. Default active.
analyzeNoNot TikTok: first 50 Ads, per Ad, computed or stored; refused Ads free (Google: delivery alone).
countryNoISO-2, not TikTok. Google default: worldwide, US on fallback.
libraryYes
estimateNoQuote the price in Credits: no Run, no charge
order_byNoMeta only. relevance (default, the library's order), winner (winner Score), days_running or start_date (newest); sorts the returned page.
advertiserNoIts id (Meta Page, TikTok, Google AR), library URL or name; Google also a domain.
media_typeNocarousel: Meta; text: Google.
placementsNoMeta; one for Google.
max_creditsNo
started_afterNoISO date, inclusive.
started_beforeNoISO date, exclusive.
idempotency_keyNoReuse on a retry: replays the original Run, not charged again

Output Schema

NameRequiredDescriptionDefault
runNo
cachedNo
resultNo
max_adsNo
poll_urlNo
priced_perNo
per_ad_creditsNo
estimate_creditsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changed
    • changedInput schema / properties / advertiser / description
      Previous value: -"Meta: Page id, Page URL or name. TikTok: advertiser id, library.tiktok.com URL or name."New value: +"Its id (Meta Page, TikTok, Google AR), library URL or name; Google also a domain."
    • changedInput schema / properties / analyze / description
      Previous value: -"Meta only. Ad analysis on the first 50 Ads, charged per Ad, whether computed or already stored."New value: +"Not TikTok: first 50 Ads, per Ad, computed or stored; refused Ads free (Google: delivery alone)."
    • changedInput schema / properties / country / description
      Previous value: -"ISO-2; Meta only. Omit for every country."New value: +"ISO-2, not TikTok. Google default: worldwide, US on fallback."
    • changedInput schema / properties / library / enum
      Previous value: -[
-  "meta",
-  "tiktok"
-]New value: +[
+  "meta",
+  "tiktok",
+  "google"
+]
    • changedInput schema / properties / limit / description
      Previous value: -"Meta up to 500 (default 50); TikTok up to 30."New value: +"Max: Meta 500 (default 50), TikTok 30, Google 200 (default 40)."
    • changedInput schema / properties / media_type / description
      Previous value: -"Meta only."New value: +"carousel: Meta; text: Google."
    • changedInput schema / properties / media_type / enum
      Previous value: -[
-  "video",
-  "image",
-  "carousel"
-]New value: +[
+  "video",
+  "image",
+  "carousel",
+  "text"
+]
    • changedInput schema / properties / placements / description
      Previous value: -"Meta only."New value: +"Meta; one for Google."
    • changedInput schema / properties / placements / items / enum
      Previous value: -[
-  "facebook",
-  "instagram",
-  "messenger",
-  "audience_network"
-]New value: +[
+  "facebook",
+  "instagram",
+  "messenger",
+  "audience_network",
+  "youtube",
+  "google_search",
+  "google_shopping",
+  "google_maps",
+  "google_play"
+]
    • addedInput schema / properties / query / description
      Added value: +"Not Google."
    • changedInput schema / properties / started_after / description
      Previous value: -"Meta only. ISO date; Ads that started on or after it."New value: +"ISO date, inclusive."
    • changedInput schema / properties / started_before / description
      Previous value: -"Meta only. ISO date; Ads that started before it."New value: +"ISO date, exclusive."
  2. Changed4 schema fields changed
    • changedInput schema / properties / estimate / description
      Previous value: -"Return the price, in Credits, without running the operation or creating a Run"New value: +"Quote the price in Credits: no Run, no charge"
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Reuse the same key when retrying: a repeat returns the original Run and is not charged again"New value: +"Reuse on a retry: replays the original Run, not charged again"
    • changedOutput schema / properties / run / additionalProperties
      Previous value: -trueNew value: +{}
    • removedOutput schema / properties / run / properties
      Removed value: -{}
  3. Changed1 schema field changed
    • addedInput schema / properties / max_credits
      Added value: +{
+  "minimum": 0,
+  "type": "integer"
+}
  4. Changed1 schema field changed
    • addedOutput schema / properties / poll_url
      Added value: +{
+  "format": "uri",
+  "type": "string"
+}
  5. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "cached": {
+      "type": "boolean"
+    },
+    "estimate_credits": {
+      "type": "integer"
+    },
+    "max_ads": {
+      "type": "number"
+    },
+    "per_ad_credits": {
+      "type": "number"
+    },
+    "priced_per": {
+      "type": "string"
+    },
+    "result": {
+      "$ref": "#/properties/run"
+    },
+    "run": {
+      "additionalProperties": true,
+      "properties": {},
+      "type": "object"
+    }
+  },
+  "type": "object"
+}
  6. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false; the description goes well beyond them with per-library credit pricing, the +20 credit analysis surcharge, the first-50-ads analysis cap, the TikTok geo restriction, and the fact that ambiguous advertiser lookups return free candidates. It also clarifies the estimate path creates no Run and incurs no charge, which resolves the apparent tension with idempotentHint=false.

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 most important content (what it does, what it is not, cost) is front-loaded and nothing is obviously padded. However, the telegraphic fragment style ('order_by winner', 'analyze: first 50') forces re-reading and some phrases like 'Price: Meta 1 credit per Ad delivered' are compressed to the point of ambiguity.

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

Completeness3/5

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

For a 17-parameter, three-library tool the description covers pricing, geo limits, analysis caps and sibling routing, and an output schema exists so return values need not be explained. What is missing is per-library coverage of the leftover parameters (country, media_type, placements, cursor/pagination behavior) which differ notably between Google and the other two.

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?

With 82% schema coverage the baseline is 3, and the description raises it by mapping parameter applicability per library beyond what individual schema fields say ('Meta: status, kind, media_type, placements, started_after/before, limit', 'advertiser: id, library URL or name'). The advertiser_ambiguous free-candidate behavior is meaning the schema does not carry, though Google- and TikTok-specific parameter guidance remains thinner.

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 first sentence names the verb (search) and the resource (Meta, TikTok or Google Ads) and states the two selection modes (by query or by advertiser). It also explicitly negates the two nearest siblings, get_ad and track, so an agent can route correctly without opening any schema.

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?

It states when to use it ('Use when you need ... Ads by query or advertiser'), when not to ('Not for one Ad or an Advertiser's profile: use get_ad'), and names the alternative for a related need ('To watch an Advertiser: track'). It adds hard eligibility constraints (TikTok limited to EU/EEA, CH, UK and Turkey), which is stronger guidance than most definitions provide.

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

All ShortsIntel toolsInspect
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.

Resources