Meta Ad Library Spend MCP by AdSpendSpy

List new ads of tracked brands

list_new_ads

Read-onlyIdempotent

List ads that newly appeared for advertisers you actively track, newest first (event ad.new). An ad counts as new when it started at most 7 days before it was first seen, so the back catalog of a freshly tracked advertiser is excluded. Without since_id or cursor the last 30 days are returned. since_id returns only items with a higher internal_ad_id. Spend is a latest cumulative estimate in EUR; null means unknown. Use page_id or project, not both.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_new_ads"
  }
}

Input Schema

Name	Required	Description
`limit`	No
`cursor`	No	Opaque pagination.next_cursor returned by the previous page with the same filters.
`page_id`	No	Meta advertiser page ID, kept as a string.
`project`	No	Public_id of one of your projects. Cannot be combined with page_id.
`since_id`	No	Return only items with a higher id (internal_ad_id for new ads, alert_id for alerts).

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world. The description adds genuinely behavioral detail beyond them: newest-first ordering, the 7-day newness rule, the 30-day default window, since_id's higher-internal_ad_id semantics, and the meaning of null spend as unknown in EUR.

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 core purpose, then the newness definition, then defaults, then parameter rules — each sentence carries load. It is dense (five clauses across five sentences) and the spend sentence sits slightly awkwardly at the end, but nothing is redundant.

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 does the work of defining ordering, the newness window, pagination defaults, and the spend field's estimate/null semantics. The remaining gap is that the rest of the returned item shape (beyond internal_ad_id and spend) is never sketched.

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 80% so the baseline is 3, but the description adds real meaning: since_id's comparison semantics and default lookback behavior, cursor's interaction with the default window, and the page_id/project mutual exclusion that the schema only hints at. Only limit's bounds are left to the schema.

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 ('List ads that newly appeared') plus scope ('for advertisers you actively track') and ordering ('newest first'), tied to the ad.new event. This clearly separates it from siblings like list_brand_ads, get_advertiser_ads, or list_alerts.

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?

Explains the core usage rule — an ad counts as new only when it started at most 7 days before first seen, so a freshly tracked advertiser's back catalog is excluded — and states the default window (last 30 days) when since_id/cursor are omitted. It also gives an explicit exclusivity rule ('Use page_id or project, not both'), though it never names a sibling alternative for non-new listings.

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

All Meta Ad Library Spend MCP by AdSpendSpy tools Inspect

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

Need Help?