StealAds

New ads from tracked rivals

list_new_competitor_ads

Read-onlyIdempotent

Lists the ads StealAds first observed from a brand’s tracked competitors since a date, newest first, up to 50 per page: the tool for what rivals launched this week. since defaults to seven days ago and reaches back at most 30 days. first_observed_at is when StealAds first saw the ad, not its launch date; first_import marks ads from a competitor’s initial import. The final page returns resume_since for the next periodic check. Ads and counts describe only this account’s tracked set, not complete advertiser or library coverage. Each ad returned draws on the daily workspace reading allowance.

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": {
      "brand_id": "<brand_id>"
    },
    "name": "list_new_competitor_ads"
  }
}

Input Schema

Name	Required	Description
`since`	No	Start of the window: an ISO date or date-time within the last 30 days, the resume_since of an earlier walk, or next_cursor from the previous page with the same filters. Defaults to seven days ago.
`cursor`	No	next_cursor from the previous page with the same filters. An alternative to since; sending both is refused.
`format`	No	Media filter: static = image ads (image is an alias), video = video ads. Absent means both.
`brand_id`	Yes	Brand id from list_brands.
`max_results`	No	Ads per page, 1 to 50 (default 20).
`min_run_days`	No	Only ads observed running for at least this many days (0 to 36500).
`competitor_id`	No	Optional competitor id from list_competitors: reads one competitor of this brand instead of all tracked ones.
`response_format`	No	Output format: text (default) or json for versioned research rows.

Output Schema

Name	Required	Description
`ads`	No	Bounded sample of accessible ads with delivery evidence; not a complete library inventory.
`as_of`	No	as of value in this response.
`order`	No	order value in this response.
`scope`	No	Which accessible ad examples this search covered.
`since`	No	Exclusive lower time bound for first-observed ads in this walk.
`totals`	No	Counts for your tracked set only; excludes library inventory totals.
`brand_id`	No	Reference for the selected brand.
`has_more`	No	Whether another bounded page is available with next_cursor.
`allowance`	No	Free daily ad-return allowance for this workspace, resetting at midnight UTC.
`page_note`	No	Plain-language explanation of a short page and how to continue.
`date_caveat`	No	Limitations distinguishing first observation, initial import and provider launch dates.
`description`	No	description value in this response.
`next_cursor`	No	Continuation handle for the same filters; null when no further page is offered.
`reading_use`	No	reading use value in this response.
`search_note`	No	Limitations or suggestions for interpreting this bounded search.
`cost_credits`	No	Credits quoted or charged by this operation.
`resume_since`	No	Settled polling watermark, available only on the final page.
`tracking_note`	No	tracking note value in this response.
`returned_count`	No	Number of ads returned in this response.
`page_stop_reason`	No	Machine-readable reason a short page stopped before the requested limit.
`tracking_enabled`	No	tracking enabled value in this response.
`page_status_counts`	No	Live, stopped and unknown delivery counts within this returned page.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedNov 10, 2026

changedInput schema / properties / brand_id / description

Previous value: -"Accessible brand reference from list_brands."New value: +"Brand id from list_brands."

changedInput schema / properties / competitor_id / description

Previous value: -"Optional rival reference under this brand; selected paused rivals include history."New value: +"Optional competitor id from list_competitors: reads one competitor of this brand instead of all tracked ones."

changedInput schema / properties / cursor / description

Previous value: -"Continuation alias for since; mutually exclusive with since."New value: +"next_cursor from the previous page with the same filters. An alternative to since; sending both is refused."

changedInput schema / properties / format / description

Previous value: -"Media filter; image is an alias for static."New value: +"Media filter: static = image ads (image is an alias), video = video ads. Absent means both."

changedInput schema / properties / max_results / description

Previous value: -"Page size, default 20, maximum 50."New value: +"Ads per page, 1 to 50 (default 20)."

changedInput schema / properties / min_run_days / description

Previous value: -"Minimum observed run duration, bounded from 0 to 36500 days."New value: +"Only ads observed running for at least this many days (0 to 36500)."

changedInput schema / properties / response_format / description

Previous value: -"Response presentation; defaults to text, with json for versioned research rows."New value: +"Output format: text (default) or json for versioned research rows."

changedInput schema / properties / since / description

Previous value: -"ISO date within 30 days, or next_cursor from this tool with the same filters. Defaults to seven days ago."New value: +"Start of the window: an ISO date or date-time within the last 30 days, the resume_since of an earlier walk, or next_cursor from the previous page with the same filters. Defaults to seven days ago."

Changed2 schema fields changedNov 10, 2026

addedOutput schema / properties / page_note

Added value: +{
+  "anyOf": [
+    {
+      "description": "Plain-language explanation of a short page and how to continue.",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Plain-language explanation of a short page and how to continue."
+}

addedOutput schema / properties / page_stop_reason

Added value: +{
+  "anyOf": [
+    {
+      "description": "Machine-readable reason a short page stopped before the requested limit.",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Machine-readable reason a short page stopped before the requested limit."
+}

Changed3 schema fields changedNov 9, 2026

changedOutput schema / properties / allowance / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "Daily scanned-row allowance for this workspace, resetting at midnight UTC.",
-    "properties": {
-      "daily_limit": {
-        "description": "Maximum scanned rows allowed per UTC day.",
-        "type": "number"
-      },
-      "remaining": {
-        "description": "Scanned rows still available today.",
-        "type": "number"
-      },
-      "resets_at": {
-        "description": "ISO timestamp when the allowance or credits reset.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "daily_limit",
-      "remaining",
-      "resets_at"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "description": "Free daily ad-return allowance for this workspace, resetting at midnight UTC.",
+    "properties": {
+      "daily_limit": {
+        "description": "Maximum free ad examples returned per UTC day.",
+        "type": "number"
+      },
+      "remaining": {
+        "description": "Free ad examples still available today.",
+        "type": "number"
+      },
+      "resets_at": {
+        "description": "ISO timestamp when the allowance or credits reset.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "daily_limit",
+      "remaining",
+      "resets_at"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / allowance / description

Previous value: -"Daily scanned-row allowance for this workspace, resetting at midnight UTC."New value: +"Free daily ad-return allowance for this workspace, resetting at midnight UTC."

addedOutput schema / properties / reading_use

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "description": "reading use value in this response.",
+      "properties": {
+        "ads_returned": {
+          "anyOf": [
+            {
+              "description": "ads returned value in this response.",
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "ads returned value in this response."
+        },
+        "message": {
+          "anyOf": [
+            {
+              "description": "message value in this response.",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "message value in this response."
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "reading use value in this response."
+}

First observedNov 9, 2026

TDQS

A4/5.0

Behavior5/5

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

Annotations only cover the read-only/idempotent safety profile; the description adds substantive behavior on top: 50-per-page pagination, a 7-day default with a hard 30-day lookback, resume_since returned on the final page for periodic walks, and explicit quota consumption ('draws on the daily workspace reading allowance'). It also pre-empts the most likely misreading by stating first_observed_at is observation time, not launch date, and that first_import marks initial-import ads.

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 verb, resource and ordering, then layered with caveats and quota notes; nearly every sentence carries distinct information. It runs long and dense in the middle (first_observed_at / first_import / coverage caveat packed together), which slightly hurts scannability but not substance.

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 paginated read tool with an output schema, the description covers the window rules, pagination and resume mechanics, the observation-vs-launch semantic trap, the coverage caveat, and the quota cost. An agent has everything needed to call it and interpret results without surprises.

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%, so every parameter is already documented, and the description largely restates the since default and 30-day bound that the schema carries. The added value is the resume_since-for-next-check framing, but format, max_results, min_run_days and competitor_id get no semantic elaboration 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.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: ads first observed from a brand's tracked competitors, newest first, paginated. The phrase 'the tool for what rivals launched this week' sharpens intent. However, it never distinguishes itself from the near-identically named sibling list_tracked_rival_ads, so an agent comparing the two gets no disambiguation.

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

Usage Guidelines3/5

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

'The tool for what rivals launched this week' implies a usage context (recent competitor launches) and the 7-day default / 30-day cap implicitly bound when it applies. But there is no explicit when-not guidance and no named alternative for the adjacent case, which is a real gap given a sibling with an almost interchangeable name.

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

All StealAds 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.