StealAds

List tracked rival ads

list_tracked_rival_ads

Read-onlyIdempotent

Pages through the stored ads of the competitors (rivals) a brand tracks, running and stopped, up to 50 per page: caption, opening hook, format, dates and delivery evidence for each ad. The tool for a full walk of tracked competitors, and the only ad list with table (CSV) output. Ads and counts describe only this account’s tracked set, not complete advertiser or library coverage. Order recent (default) mixes all tracked competitors; rival walks one at a time and reports totals.tracked_rivals once the walk completes. Missing hook evidence and unanalyzed why are null. Each ad returned draws on the daily workspace reading allowance. A page can be short or empty while has_more is true; page_note says why.

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_tracked_rival_ads"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Ads per page, 1 to 50 (default 20).
`order`	No	recent (default) mixes every tracked competitor of the brand, most recently updated first; rival walks one competitor at a time. With competitor_id the order is rival.
`cursor`	No	next_cursor from the previous page for this brand with the same filters; absent for the first page. A page can be empty while has_more is true.
`format`	No	Media filter: static = image ads (image is an alias), video = video ads. Absent means both.
`status`	No	Delivery filter: live = still running, stopped = no longer running, all = both. Absent means all.
`compact`	No	Defaults to true: body_text is capped at 280 characters with an ellipsis and body_text_truncated. False includes the full caption and legacy primary_text.
`brand_id`	Yes	Brand id from list_brands.
`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 tracked for this brand instead of all of them.
`response_format`	No	Output format: text (default), json for versioned research rows, or table for this page as CSV.

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.
`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.
`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.
`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 / competitor_id / description

Previous value: -"One rival actively tracked for this brand."New value: +"Optional competitor id from list_competitors: reads one competitor tracked for this brand instead of all of them."

changedInput schema / properties / cursor / description

Previous value: -"next_cursor from this brand and the same filters. Empty pages may have more results."New value: +"next_cursor from the previous page for this brand with the same filters; absent for the first page. A page can be empty while has_more is true."

changedInput schema / properties / format / description

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

changedInput schema / properties / limit / description

Previous value: -"Rows per page, default 20, at most 50."New value: +"Ads per page, 1 to 50 (default 20)."

changedInput schema / properties / min_run_days / description

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

changedInput schema / properties / order / description

Previous value: -"recent pages the whole authorized brand by stored update time across rivals; rival walks one rival at a time."New value: +"recent (default) mixes every tracked competitor of the brand, most recently updated first; rival walks one competitor at a time. With competitor_id the order is rival."

changedInput schema / properties / response_format / description

Previous value: -"Defaults to text; json returns versioned research rows; table returns CSV for this page only."New value: +"Output format: text (default), json for versioned research rows, or table for this page as CSV."

changedInput schema / properties / status / description

Previous value: -"Delivery status filter: live, stopped or all."New value: +"Delivery filter: live = still running, stopped = no longer running, all = both. Absent means all."

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

A3.8/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: each ad draws on the daily workspace reading allowance, coverage is limited to the account's tracked set, pages can be empty while has_more is true with page_note explaining why, and rival order reports totals.tracked_rivals only on completion.

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?

Purpose and scope are front-loaded in the first sentence, and the coverage caveat and allowance cost follow in a logical order. A few phrases, such as the enumeration of returned fields, partly duplicate what the output schema covers, but nothing is padding.

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

Completeness3/5

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

Output schema exists, so return values needn't be explained, and the description covers coverage limits, cost, and pagination edge cases well. What is missing is a clearer statement of when to prefer a sibling list tool over this one, which matters for a 10-parameter tool with several related ad-list alternatives.

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 the baseline is 3. The description adds some meaning beyond the schema, notably how order=recent mixes tracked competitors versus rival walking one at a time, the 50-per-page ceiling, and null semantics for missing hook evidence and unanalyzed why.

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 (pages through stored ads of tracked competitors) plus concrete scope: running and stopped, up to 50 per page, with the fields returned. It also differentiates itself from other ad lists by calling itself 'the tool for a full walk of tracked competitors' and 'the only ad list with table (CSV) output.'

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?

Makes the selecting condition clear ('the tool for a full walk of tracked competitors') and flags the unique CSV output path, which is enough to steer an agent away from single-competitor or search-style lists. It does not explicitly name a sibling to use instead or state when not to use it.

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.