StealAds

Add a competitor

add_competitor

Saves an advertiser as a competitor under one of the account's brands and returns it with its competitor id; a matching name or Facebook page returns the existing competitor instead of a duplicate. Adding without track spends no credits. With track: true it also starts tracking. When tracking would charge credits, the call without confirm returns a cost preview (idempotency_key, max_credits) and saves nothing, and the same call with confirm: true and those two values saves the competitor and starts tracking. Tracking that costs no credits starts on the first call. search_advertisers finds the facebook_page_id that pins the right page.

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": "<name>"
    },
    "name": "add_competitor"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	The competitor's brand or advertiser name, up to 200 characters.
`track`	No	true also starts tracking this competitor for new ads. A cost preview comes back first when credits would be charged; tracking that costs no credits starts on this call.
`confirm`	No	true starts the paid work shown in the cost preview. Absent or false returns that preview and spends nothing when credits would be charged; an action that costs no credits runs on this call.
`brand_id`	Yes	Brand id from list_brands.
`page_url`	No	Their Facebook page or website URL.
`max_credits`	No	max_credits from the cost preview, sent unchanged with confirm: true as the approved credit ceiling. A higher current price needs a new preview.
`country_code`	No	Two-letter country code for their ads.
`idempotency_key`	No	idempotency_key from the cost preview, needed with confirm: true and valid for 15 minutes. A repeat with the same key returns the first result without a second charge.
`facebook_page_id`	No	Their facebook_page_id from search_advertisers. Optional, but it pins the exact advertiser page.

Output Schema

Name	Required	Description
`status`	No	Current progress or delivery state.
`created`	No	Whether this call created a new rival.
`tracking`	No	Whether tracking is enabled after this operation.
`competitor`	No	competitor value in this response.
`billing_url`	No	billing url value in this response.
`max_credits`	No	Explicit credit ceiling to echo after the user approves this quote.
`cost_credits`	No	Credits quoted or charged by this operation.
`what_happens`	No	Plain explanation of the proposed work, confirmation steps and quote expiry.
`enough_credits`	No	enough credits value in this response.
`balance_credits`	No	balance credits value in this response.
`idempotency_key`	No	Key binding confirmation to this preview and preventing duplicate work.
`confirmation_required`	No	True for a cost preview awaiting explicit approval.
`original_reservation_credits`	No	original reservation credits value in this response.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedNov 10, 2026

changedInput schema / properties / confirm / description

Previous value: -"Set to true to spend the credits shown in the preview. Leave it out to see the cost first."New value: +"true starts the paid work shown in the cost preview. Absent or false returns that preview and spends nothing when credits would be charged; an action that costs no credits runs on this call."

changedInput schema / properties / facebook_page_id / description

Previous value: -"Their Facebook page id, if known."New value: +"Their facebook_page_id from search_advertisers. Optional, but it pins the exact advertiser page."

changedInput schema / properties / idempotency_key / description

Previous value: -"The idempotency_key from the preview. Required with confirm: true. Repeating a confirmed call with the same key returns the first result and does not spend again."New value: +"idempotency_key from the cost preview, needed with confirm: true and valid for 15 minutes. A repeat with the same key returns the first result without a second charge."

changedInput schema / properties / max_credits / description

Previous value: -"The explicit credit ceiling you approve. For paid confirmation, echo max_credits from the preview unchanged. A higher current price requires a new preview and approval."New value: +"max_credits from the cost preview, sent unchanged with confirm: true as the approved credit ceiling. A higher current price needs a new preview."

changedInput schema / properties / name / description

Previous value: -"Competitor name."New value: +"The competitor's brand or advertiser name, up to 200 characters."

changedInput schema / properties / track / description

Previous value: -"Also preview tracking this competitor for new ads."New value: +"true also starts tracking this competitor for new ads. A cost preview comes back first when credits would be charged; tracking that costs no credits starts on this call."

Changed1 schema field changedNov 10, 2026

changedOutput schema / properties / competitor / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "competitor value in this response.",
-    "properties": {
-      "ad_count": {
-        "anyOf": [
-          {
-            "description": "ad count value in this response.",
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "ad count value in this response."
-      },
-      "ads_tracked": {
-        "anyOf": [
-          {
-            "description": "ads tracked value in this response.",
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "ads tracked value in this response."
-      },
-      "ads_tracked_capped": {
-        "anyOf": [
-          {
-            "description": "ads tracked capped value in this response.",
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "ads tracked capped value in this response."
-      },
-      "ads_tracked_label": {
-        "anyOf": [
-          {
-            "description": "ads tracked label value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "ads tracked label value in this response."
-      },
-      "as_of": {
-        "anyOf": [
-          {
-            "description": "as of value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "as of value in this response."
-      },
-      "brand_id": {
-        "anyOf": [
-          {
-            "description": "Reference for the selected brand.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Reference for the selected brand."
-      },
-      "count": {
-        "anyOf": [
-          {
-            "description": "count value in this response.",
-            "type": "number"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "count value in this response."
-      },
-      "count_status": {
-        "anyOf": [
-          {
-            "description": "count status value in this response.",
-            "enum": [
-              "ready",
-              "pending",
-              "unavailable"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "count status value in this response."
-      },
-      "country_code": {
-        "anyOf": [
-          {
-            "description": "country code value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "country code value in this response."
-      },
-      "created_at": {
-        "anyOf": [
-          {
-            "description": "created at value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "created at 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."
-      },
-      "flags": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "description": "flags value in this response.",
-            "properties": {
-              "off_category": {
-                "anyOf": [
-                  {
-                    "description": "off category value in this response.",
-                    "type": "boolean"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "description": "off category value in this response."
-              },
-              "possible_duplicate": {
-                "anyOf": [
-                  {
-                    "description": "possible duplicate value in this response.",
-                    "type": "boolean"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "description": "possible duplicate value in this response."
-              },
-              "possible_duplicate_of": {
-                "anyOf": [
-                  {
-                    "description": "possible duplicate of value in this response.",
-                    "type": "string"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "description": "possible duplicate of value in this response."
-              },
-              "stale": {
-                "anyOf": [
-                  {
-                    "description": "stale value in this response.",
-                    "type": "boolean"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "description": "stale value in this response."
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "flags value in this response."
-      },
-      "id": {
-        "anyOf": [
-          {
-            "description": "id value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "id value in this response."
-      },
-      "is_active": {
-        "anyOf": [
-          {
-            "description": "is active value in this response.",
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "is active value in this response."
-      },
-      "last_checked": {
-        "anyOf": [
-          {
-            "description": "last checked value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "last checked value in this response."
-      },
-      "last_scanned_at": {
-        "anyOf": [
-          {
-            "description": "last scanned at value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "last scanned at 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."
-      },
-      "next_scan_at": {
-        "anyOf": [
-          {
-            "description": "next scan at value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "next scan at value in this response."
-      },
-      "off_category": {
-        "anyOf": [
-          {
-            "description": "off category value in this response.",
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "off category 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."
-      },
-      "tracking_enabled": {
-        "anyOf": [
-          {
-            "description": "tracking enabled value in this response.",
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "tracking enabled value in this response."
-      },
-      "tracking_note": {
-        "anyOf": [
-          {
-            "description": "tracking note value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "tracking note value in this response."
-      },
-      "updated_at": {
-        "anyOf": [
-          {
-            "description": "updated at value in this response.",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "updated at value in this response."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "description": "competitor value in this response.",
+    "properties": {
+      "ad_count": {
+        "anyOf": [
+          {
+            "description": "ad count value in this response.",
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "ad count value in this response."
+      },
+      "ads_tracked": {
+        "anyOf": [
+          {
+            "description": "ads tracked value in this response.",
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "ads tracked value in this response."
+      },
+      "ads_tracked_capped": {
+        "anyOf": [
+          {
+            "description": "ads tracked capped value in this response.",
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "ads tracked capped value in this response."
+      },
+      "ads_tracked_label": {
+        "anyOf": [
+          {
+            "description": "ads tracked label value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "ads tracked label value in this response."
+      },
+      "as_of": {
+        "anyOf": [
+          {
+            "description": "as of value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "as of value in this response."
+      },
+      "brand_id": {
+        "anyOf": [
+          {
+            "description": "Reference for the selected brand.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Reference for the selected brand."
+      },
+      "count": {
+        "anyOf": [
+          {
+            "description": "count value in this response.",
+            "type": "number"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "count value in this response."
+      },
+      "count_reason": {
+        "anyOf": [
+          {
+            "description": "Machine-readable reason a rival count is pending or unavailable.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Machine-readable reason a rival count is pending or unavailable."
+      },
+      "count_retry_at": {
+        "anyOf": [
+          {
+            "description": "ISO timestamp when this rival count becomes eligible for another read.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "ISO timestamp when this rival count becomes eligible for another read."
+      },
+      "count_status": {
+        "anyOf": [
+          {
+            "description": "count status value in this response.",
+            "enum": [
+              "ready",
+              "pending",
+              "unavailable"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "count status value in this response."
+      },
+      "country_code": {
+        "anyOf": [
+          {
+            "description": "country code value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "country code value in this response."
+      },
+      "created_at": {
+        "anyOf": [
+          {
+            "description": "created at value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "created at 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."
+      },
+      "flags": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "description": "flags value in this response.",
+            "properties": {
+              "off_category": {
+                "anyOf": [
+                  {
+                    "description": "off category value in this response.",
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "off category value in this response."
+              },
+              "possible_duplicate": {
+                "anyOf": [
+                  {
+                    "description": "possible duplicate value in this response.",
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "possible duplicate value in this response."
+              },
+              "possible_duplicate_of": {
+                "anyOf": [
+                  {
+                    "description": "possible duplicate of value in this response.",
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "possible duplicate of value in this response."
+              },
+              "stale": {
+                "anyOf": [
+                  {
+                    "description": "stale value in this response.",
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "stale value in this response."
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "flags value in this response."
+      },
+      "id": {
+        "anyOf": [
+          {
+            "description": "id value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "id value in this response."
+      },
+      "is_active": {
+        "anyOf": [
+          {
+            "description": "is active value in this response.",
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "is active value in this response."
+      },
+      "last_checked": {
+        "anyOf": [
+          {
+            "description": "last checked value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "last checked value in this response."
+      },
+      "last_scanned_at": {
+        "anyOf": [
+          {
+            "description": "last scanned at value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "last scanned at 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."
+      },
+      "next_scan_at": {
+        "anyOf": [
+          {
+            "description": "next scan at value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "next scan at value in this response."
+      },
+      "off_category": {
+        "anyOf": [
+          {
+            "description": "off category value in this response.",
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "off category 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."
+      },
+      "tracking_enabled": {
+        "anyOf": [
+          {
+            "description": "tracking enabled value in this response.",
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "tracking enabled value in this response."
+      },
+      "tracking_note": {
+        "anyOf": [
+          {
+            "description": "tracking note value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "tracking note value in this response."
+      },
+      "updated_at": {
+        "anyOf": [
+          {
+            "description": "updated at value in this response.",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "updated at value in this response."
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

First observedNov 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare the generic profile (not read-only, not destructive, not idempotent), while the description discloses the real behavior: deduplication by name/page, that untracked adds spend no credits, a two-phase preview-then-confirm protocol gated by idempotency_key and max_credits, a 15-minute key validity window, and that a price increase invalidates the ceiling. That is substantial context an agent could not derive from the annotations.

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?

The definition is front-loaded with the core action and return value, then the credit/confirm protocol, then the sibling pointer, so an agent can stop reading early. It is dense but slightly redundant with the schema's own parameter descriptions of track, confirm, and max_credits.

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 a 9-parameter mutation with an output schema, the description covers the key gaps: what is returned (competitor id), dedup outcomes, credit-spend semantics, and the confirmation handshake. Nothing essential to calling it correctly is left implicit.

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 description coverage is 100%, so a baseline of 3 is warranted; the description nonetheless adds meaning by explaining how confirm, idempotency_key, and max_credits interlock rather than treating them as independent flags. It also clarifies that track alone may not start tracking when credits are involved.

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?

"Saves an advertiser as a competitor under one of the account's brands and returns it with its competitor id" names a specific verb (save), resource (competitor), scope (under a brand), and return value. It is clearly distinguishable from siblings like list_competitors and search_advertisers without opening the schema.

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?

The description gives concrete routing context: dedup behavior means a matching name or Facebook page returns the existing competitor, and "search_advertisers finds the facebook_page_id that pins the right page" points the agent to a prerequisite sibling. It stops short of stating when not to call this at all (e.g., checking list_competitors first), so it is clear but not exhaustive.

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.