Skip to main content
Glama
Sign In
Alidade MCP

Alidade MCP

Official
by alidade-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Search ads

search_ads
Read-only

Search paid ads across Google, Meta, and LinkedIn ad libraries by saved search, entities, dates, keywords, or platform; returns copy, links, creatives, run dates, and spend/impression ranges.

Instructions

The paid ads run by the entities in the scope, collected from the Google, Meta, and LinkedIn ad libraries, newest first by default: copy, link, creative URLs, run dates, reported impression and spend ranges, and a link to the ad's public ad-library page. Scope with savedSearchId or entityIds like the other tools; the date range keeps every ad whose run overlaps it, keyword filters match the ad's headline and body, and adPlatforms (google, meta, linkedin) narrows the ad libraries — a saved search's platform filter does not apply to ads. Requires the mentions API tier, and every returned ad counts against the workspace's monthly post quota — keep pageSize small (default 25) and only paginate when needed.

Input Schema

NameRequiredDescriptionDefault
sortNoSort order by when the ad ran: its start date, else its end date, else (for ads the library reports no dates for) when Alidade first collected it. Default newest.
cursorNoOpaque pagination cursor from a previous response's `nextCursor`. Use the same query parameters across paged requests.
dateToNoOnly include ads that started running on or before this date (ISO 8601). A date-only value (`2026-01-31`) includes that whole day, UTC. Overrides the saved search's range end; its range start is kept unless `dateFrom` is also provided.
dateFromNoOnly include ads still running on or after this date (ISO 8601). Ads without run dates match by when Alidade saw them listed (`firstSeenAt`–`lastSeenAt`). A date-only value (`2026-01-31`) means the start of that day, UTC. Overrides the saved search's range start; its range end is kept unless `dateTo` is also provided.
keywordsNoComma-separated keywords to filter ad headline and body text by (e.g. `sustainability,net zero`). Replaces the saved search's keyword filters. Cannot be combined with `booleanQuery`.
pageSizeNoItems per page (max 100, default 25).
entityIdsNoComma-separated entity IDs (max 100) for an ad-hoc scope, treated as a single comparison group. Provide either this or `savedSearchId`.
adPlatformsNoComma-separated ad libraries to include. Valid values: google, meta, linkedin. Omit for all. A saved search's platform filter applies to posts, not ads.
booleanQueryNoBoolean keyword query matching the app's advanced search mode (e.g. `"net zero" AND (solar OR wind)`). Syntax: AND/OR/NOT (upper case), parentheses, quoted phrases with optional proximity ("health care"~3 = up to 3 words between, any phrase length, max 20), NEAR/N (either order) and THEN/N (ordered) between terms or groups, wildcards (elect*, wom?n), fuzzy (medicaid~1, max 2). Always use explicit operators between terms. Mixing AND or NOT with OR at the same depth is an error — parenthesize to make precedence explicit ((a AND b) OR c, (a OR b) NOT c). NEAR/THEN bind tighter than AND/OR — parenthesize a proximity expression that sits next to AND/OR ((a NEAR/5 b) OR c, (a OR b) NEAR/5 c). NOT is not allowed inside NEAR/THEN; exclude outside the proximity expression. Matching is exact-token, case- and accent-insensitive (no stemming) — cover word variants with OR or a wildcard (tariff OR tariffs, tariff*). Korean attaches particles to words, so put a trailing wildcard on each Korean term (검색*). Hindi is written in Devanagari and romanized, so OR both forms ((दोस्त OR dost)); Devanagari and Tamil matching ignores vowel signs, so expect some unrelated matches. Comments are ignored by search: // to the end of the line, <<< >>> inline or across lines. Full syntax: https://docs.alidade-ai.com/search-syntax. Replaces the saved search's keyword filters. Cannot be combined with the keyword parameters.
keywordMatchNoWhether posts must match `any` (default) or `all` of `keywords`.
savedSearchIdNoID of a saved search to scope the request to. Its comparison groups, date range, and keyword filters apply; its platform filter applies to posts, not ads (use `adPlatforms`). Only entities your workspace can access are included; a saved search with none returns 422. Provide either this or `entityIds`.
excludeKeywordsNoComma-separated keywords that matching posts must not contain (exact word/phrase match). Replaces the saved search's keyword filters. Cannot be combined with `booleanQuery`.
keywordMatchTypeNo`exact` (default) matches the exact words or phrases only; `stemmed` also matches English word variants (run/running). Applies to `keywords`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.2

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint, but the description adds the costly details an agent actually needs: requires the mentions API tier, each returned ad consumes monthly post quota, pageSize defaults to 25 and should stay small, and a saved search with no accessible entities returns 422. Date-overlap semantics and default sort order are also disclosed.

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?

Dense but front-loaded: what it returns first, then scoping, then filtering, then the quota warning. The long enumerations of return fields and platform values cost some tightness, but every sentence carries operational information rather than restating the schema.

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?

With 13 parameters, no output schema, and a quota-sensitive backend, this is the amount of coverage needed: quota/tier cost, pagination advice, default sort, scoping options, and the platform-filter gotcha are all present. The only soft spot is not stating whether savedSearchId or entityIds is mandatory, which the schema leaves optional.

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; the description still earns more by synthesizing behavior the schema states piecemeal — the date range keeps any ad whose run overlaps it, keywords match headline and body, and adPlatforms is the correct lever because saved-search platform filters don't apply to ads.

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?

Opens with a specific verb+resource and disambiguates the resource: 'paid ads run by the entities in the scope, collected from the Google, Meta, and LinkedIn ad libraries.' It also names the returned fields (copy, link, creative URLs, run dates, impression/spend ranges) so an agent knows this is not the organic-posts tool.

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?

Gives real usage context: scope via savedSearchId or entityIds, keyword filters hit headline/body, adPlatforms narrows libraries, and the important caveat that a saved search's platform filter applies to posts, not ads. It never explicitly routes to a sibling (e.g. 'for organic mentions use search_mentions'), so a 4 rather than 5.

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