Skip to main content
Glama

Find public advertisers

search_advertisers
Read-onlyIdempotent

Looks up public advertisers by name, domain, Facebook page id or Ad Library URL. Returns confirmed advertisers and unconfirmed suggestions with facebook_page_id. A missing brand returns not_indexed and can_pull; pull access enables quote_pull_brand_ads with the intended page id and page_name, including from suggestions. Starts no fetch. Results are capped with next_cursor.

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": {
      "query": "<query>"
    },
    "name": "search_advertisers"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesBrand name (up to 100 characters), website domain, Facebook page id or Ad Library URL; at least 3 characters.
cursorNonext_cursor from the previous page of the same query; absent for the first page. A page can be empty while has_more is true.
max_resultsNoAdvertisers per page, 1 to 25 (default 10).
response_formatNoOutput format: text (default) is readable text with image previews and links; json returns the structured rows. table is refused by Ad Library tools.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "https://json-schema.org/draft/2020-12/schema",
      -  "additionalProperties": false,
      -  "properties": {
      -    "advertisers": {
      -      "anyOf": [
      -        {
      -          "description": "Advertisers matching the query in this bounded sample.",
      -          "items": {
      -            "additionalProperties": false,
      -            "description": "Advertisers matching the query in this bounded sample.",
      -            "properties": {
      -              "facebookPageId": {
      -                "anyOf": [
      -                  {
      -                    "description": "facebookPageId value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "facebookPageId value in this response."
      -              },
      -              "facebook_page_id": {
      -                "anyOf": [
      -                  {
      -                    "description": "facebook page id value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "facebook page id value in this response."
      -              },
      -              "logoUrl": {
      -                "anyOf": [
      -                  {
      -                    "description": "logoUrl value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "logoUrl value in this response."
      -              },
      -              "logo_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "logo url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "logo url value in this response."
      -              },
      -              "name": {
      -                "anyOf": [
      -                  {
      -                    "description": "name value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "name value in this response."
      -              },
      -              "pageName": {
      -                "anyOf": [
      -                  {
      -                    "description": "pageName value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "pageName value in this response."
      -              },
      -              "pageUrl": {
      -                "anyOf": [
      -                  {
      -                    "description": "pageUrl value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "pageUrl value in this response."
      -              },
      -              "page_name": {
      -                "anyOf": [
      -                  {
      -                    "description": "page name value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "page name value in this response."
      -              },
      -              "page_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "page url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "page url value in this response."
      -              },
      -              "schema_version": {
      -                "anyOf": [
      -                  {
      -                    "const": 1,
      -                    "description": "schema version value in this response.",
      -                    "type": "number"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "schema version value in this response."
      -              },
      -              "suggestion": {
      -                "anyOf": [
      -                  {
      -                    "description": "suggestion value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "suggestion value in this response."
      -              }
      -            },
      -            "type": "object"
      -          },
      -          "type": "array"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Advertisers matching the query in this bounded sample."
      -    },
      -    "can_pull": {
      -      "anyOf": [
      -        {
      -          "const": false,
      -          "description": "can pull value in this response.",
      -          "type": "boolean"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "can pull value in this response."
      -    },
      -    "has_more": {
      -      "anyOf": [
      -        {
      -          "description": "Whether another bounded page is available with next_cursor.",
      -          "type": "boolean"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Whether another bounded page is available with next_cursor."
      -    },
      -    "message": {
      -      "anyOf": [
      -        {
      -          "description": "message value in this response.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "message value in this response."
      -    },
      -    "next_cursor": {
      -      "anyOf": [
      -        {
      -          "description": "Continuation handle for the same filters; null when no further page is offered.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Continuation handle for the same filters; null when no further page is offered."
      -    },
      -    "request_brand_url": {
      -      "anyOf": [
      -        {
      -          "description": "request brand url value in this response.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "request brand url value in this response."
      -    },
      -    "search_note": {
      -      "anyOf": [
      -        {
      -          "description": "Limitations or suggestions for interpreting this bounded search.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Limitations or suggestions for interpreting this bounded search."
      -    },
      -    "source": {
      -      "anyOf": [
      -        {
      -          "const": "ad_library",
      -          "description": "Where the accessible ad or advertiser evidence came from.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Where the accessible ad or advertiser evidence came from."
      -    },
      -    "status": {
      -      "anyOf": [
      -        {
      -          "const": "not_indexed",
      -          "description": "Current progress or delivery state.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Current progress or delivery state."
      -    },
      -    "suggestions": {
      -      "anyOf": [
      -        {
      -          "description": "Suggested advertiser names for a narrower search.",
      -          "items": {
      -            "additionalProperties": false,
      -            "description": "Suggested advertiser names for a narrower search.",
      -            "properties": {
      -              "facebook_page_id": {
      -                "anyOf": [
      -                  {
      -                    "description": "facebook page id value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "facebook page id value in this response."
      -              },
      -              "name": {
      -                "anyOf": [
      -                  {
      -                    "description": "name value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "name value in this response."
      -              },
      -              "schema_version": {
      -                "anyOf": [
      -                  {
      -                    "const": 1,
      -                    "description": "schema version value in this response.",
      -                    "type": "number"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "schema version value in this response."
      -              },
      -              "suggestion": {
      -                "anyOf": [
      -                  {
      -                    "description": "suggestion value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "suggestion value in this response."
      -              }
      -            },
      -            "type": "object"
      -          },
      -          "type": "array"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Suggested advertiser names for a narrower search."
      -    }
      -  },
      -  "type": "object"
      -}New value: +null
  2. Changed4 schema fields changed
    • changedInput schema / properties / cursor / description
      Previous value: -"next_cursor from the previous page with the same query and filters. Empty pages can still have more results."New value: +"next_cursor from the previous page of the same query; absent for the first page. A page can be empty while has_more is true."
    • changedInput schema / properties / max_results / description
      Previous value: -"Maximum number of results in this bounded response; constrained by the field maximum."New value: +"Advertisers per page, 1 to 25 (default 10)."
    • changedInput schema / properties / query / description
      Previous value: -"Brand name (up to 100 characters), domain, Facebook page id or Ad Library URL."New value: +"Brand name (up to 100 characters), website domain, Facebook page id or Ad Library URL; at least 3 characters."
    • changedInput schema / properties / response_format / description
      Previous value: -"Response format. Defaults to readable text; json returns the closed public data contract. Library tools refuse table; use text or json."New value: +"Output format: text (default) is readable text with image previews and links; json returns the structured rows. table is refused by Ad Library tools."
  3. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, yet the description still adds real value: 'Starts no fetch' clarifies no data pull or cost is triggered, and it explains the confirmed-vs-unconfirmed suggestion split plus not_indexed/can_pull on misses. Pagination and result capping via next_cursor are also disclosed. It stops short of stating rate limits or auth requirements.

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?

Four compact sentences, front-loaded with purpose and identifier formats, then the outcome/next-step behavior. Minor telegraphic phrasing ('including from suggestions') slightly reduces readability but nothing is padding.

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 carries the return-value burden and largely does so, covering confirmed advertisers, unconfirmed suggestions with facebook_page_id, the not_indexed/can_pull miss case, and next_cursor paging. It leaves the shape of a confirmed advertiser row (fields returned) unspecified, which is the remaining gap.

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%, and the schema already documents query formats, cursor semantics, max_results bounds, and the response_format enum with the table refusal. The description restates the identifier types for query and echoes the next_cursor cap, adding little beyond the structured fields.

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 ('Looks up public advertisers') and enumerates the accepted identifier types (name, domain, Facebook page id, Ad Library URL). It also separates itself from the sibling it names, quote_pull_brand_ads, by framing this tool as lookup-only ('Starts no fetch').

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

Usage Guidelines4/5

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

Clear usage context: use it to resolve a brand to a facebook_page_id, and the missing-brand path ('returns not_indexed and can_pull') explains what to do next via quote_pull_brand_ads. It does not state exclusions versus other candidates such as list_brands or search_ads, so the routing is implied rather than exhaustive.

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.