Skip to main content
Glama
hermoso-ai

Hermoso

Official
by hermoso-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Pull competitor ads

pull_competitor_ads

Fetch a named brand's live Meta ads from the Ad Library to see what it is running. Returns deduplicated, sorted results for one company; Meta only.

Instructions

Pull one named brand’s live ads from the Meta (Facebook and Instagram) Ad Library: deduplicated, sorted, with the brand’s own page resolved. One call, back in a few seconds. Use it when the user names a brand and asks what ads it is running ("show me the ads is running"). Covers the Meta Ad Library only; for a broader search across brands or platforms use research_ads. Spends credits.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNosame as domain
nameNosame as companyName
sortNo'longest_running' (default) etc.
brandNosame as companyName
limitNomax ads per platform (default 30)
domainNothe advertiser domain, e.g. liquiddeath.com — a full website URL works (url / website are read as this too). Pass companyName OR domain
companyNosame as companyName
countryNo2-letter, default 'US'
websiteNosame as domain
companyNameNothe advertiser name, e.g. "Liquid Death" (company / brand / name are read as this too)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.1.320
    • addedInput schema / properties / brand
      Added value: +{
+  "description": "same as companyName",
+  "type": "string"
+}
    • addedInput schema / properties / company
      Added value: +{
+  "description": "same as companyName",
+  "type": "string"
+}
    • changedInput schema / properties / companyName / description
      Previous value: -"the advertiser name"New value: +"the advertiser name, e.g. \"Liquid Death\" (company / brand / name are read as this too)"
    • changedInput schema / properties / domain / description
      Previous value: -"the advertiser domain"New value: +"the advertiser domain, e.g. liquiddeath.com — a full website URL works (url / website are read as this too). Pass companyName OR domain"
    • addedInput schema / properties / name
      Added value: +{
+  "description": "same as companyName",
+  "type": "string"
+}
    • addedInput schema / properties / url
      Added value: +{
+  "description": "same as domain",
+  "type": "string"
+}
    • addedInput schema / properties / website
      Added value: +{
+  "description": "same as domain",
+  "type": "string"
+}
  2. Changed2 schema fields changedv0.1.161
    • removedInput schema / properties / platforms
      Removed value: -{
-  "description": "default ['facebook']; add 'google','linkedin'",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}
    • changedOutput schema / (root)
      Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "properties": {
-    "facebook": {
-      "description": "Meta results ({ads[], matched} or {error}; null when not requested)"
-    },
-    "google": {
-      "description": "Google results ({ads[], cursor} or {error}; null when not requested)"
-    },
-    "linkedin": {
-      "description": "LinkedIn results ({ads[], cursor} or {error}; null when not requested)"
-    }
-  },
-  "type": "object"
-}New value: +null
  3. Addedv0.1.0

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds credit consumption and latency ('back in a few seconds'), which explains why the tool is not read-only. But it omits how many credits, whether repeated calls are charged again (idempotency implications), and failure/auth behavior.

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?

Front-loaded with the capability, then the trigger, then the boundary/alternative, then the cost warning. No wasted clauses, though 'One call, back in a few seconds' is mildly promotional filler.

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

Completeness4/5

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

With no output schema, the description usefully characterizes the result ('deduplicated, sorted, with the brand's own page resolved'), so an agent knows what comes back. Missing credit amount and pagination/limits detail keeps it short of a 5.

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

Parameters3/5

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

Schema description coverage is 100% across 10 params, so the schema carries parameter meaning (including aliases like 'company / brand / name'). The description adds no parameter-level guidance such as default limit behavior or sort semantics beyond the schema. Baseline 3 is appropriate.

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?

Specific verb+resource ('Pull one named brand's live ads from the Meta Ad Library') with scope, and it names a sibling ('research_ads') for the broader case. An agent can distinguish it from search_meta_ads and research_ads without opening a 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 triggering condition with a quoted user phrasing ('show me the ads <brand> is running'), an explicit boundary ('Covers the Meta Ad Library only'), and a named alternative ('for a broader search across brands or platforms use research_ads'). Also warns about cost ('Spends credits').

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