Skip to main content
Glama
Sign In
Hermoso

Hermoso

Official
by hermoso-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Search Meta ads

search_meta_ads

Fetch structured Meta Ad Library data for a keyword or specific advertiser, returning compact JSON per ad with page name, body, CTA, link, dates, and media.

Instructions

Structured Meta (Facebook/Instagram) Ad Library pull — use when you know exactly WHAT to fetch: a keyword (query) OR one advertiser (companyName / pageId). Returns compact JSON {page_name, body, cta, link, dates, media} per ad. For open-ended research that needs judgment across platforms, use research_ads instead. Spends credits on each ad-library read it makes: one for a keyword; for a brand name, the page lookup and its ads (plus a keyword search when that page has none).

Input Schema

NameRequiredDescriptionDefault
limitNomax ads returned (1–25, default 8)
queryNokeyword search across ALL advertisers (use INSTEAD of companyName/pageId)
domainNothe advertiser’s website, e.g. buffer.com — with companyName, used to confirm which Meta page is really theirs
pageIdNoone advertiser’s ads by Facebook page id (most precise)
statusNoACTIVE = currently running; default ALL (includes proven past winners)
countryNo2-letter code or 'ALL' (default ALL)
mediaTypeNofilter by creative type (default ALL)
companyNameNoone advertiser’s ads by brand name — resolved to the brand’s own page only on evidence (its Instagram, its domain, or ads that land on its domain); pass domain too for the best match

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.1.435
    • changedInput schema / properties / companyName / description
      Previous value: -"one advertiser’s ads by brand name"New value: +"one advertiser’s ads by brand name — resolved to the brand’s own page only on evidence (its Instagram, its domain, or ads that land on its domain); pass domain too for the best match"
    • addedInput schema / properties / domain
      Added value: +{
+  "description": "the advertiser’s website, e.g. buffer.com — with companyName, used to confirm which Meta page is really theirs",
+  "type": "string"
+}
  2. Changed1 schema field changedv0.1.161
    • changedOutput schema / (root)
      Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "properties": {
-    "ads": {
-      "description": "the compact ad objects ({page_name, body, cta, link, dates, media})",
-      "items": {},
-      "type": "array"
-    },
-    "found": {
-      "description": "total ads found upstream",
-      "type": "number"
-    }
-  },
-  "type": "object"
-}New value: +null
  3. Addedv0.1.0

TDQS

A4.7/5.0
Behavior4/5

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

Adds context beyond annotations: it discloses credit-spend behavior per read, including the surprising cost model for brand lookups (page lookup + ads + fallback keyword search), and gives the return shape. Annotations flag readOnlyHint=false and openWorldHint=true but say nothing about cost or fallback behavior, so these disclosures are genuinely additive; pagination/rate limits are not covered, keeping it from a 5.

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

Conciseness5/5

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

Front-loads the identity of the tool, then the when-to-use condition, return shape, alternative, and cost model — every sentence carries distinct information with no filler.

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?

For an 8-parameter tool with no output schema, the description supplies the return shape ({page_name, body, cta, link, dates, media}), the routing rule versus research_ads, and the credit cost, which is enough for an agent to call it correctly.

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, but the description adds the key semantic point that query and companyName/pageId are mutually exclusive modes of fetch. It reinforces rather than merely repeats the schema text, and frames limit implicitly via the credit model.

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?

States a specific verb and resource ('Structured Meta (Facebook/Instagram) Ad Library pull') and immediately scopes it to the case where you know WHAT to fetch. It names the sibling it is not (research_ads), so an agent can distinguish it without opening the 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?

Explicit when-to-use ('use when you know exactly WHAT to fetch: a keyword OR one advertiser'), explicit exclusion with a named alternative ('For open-ended research that needs judgment across platforms, use research_ads instead'), and it clarifies the keyword-vs-advertiser selection.

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

Deploy Server

Other Tools