StealAds

Scan a tracked competitor

scan_competitor

Idempotent

Requests one immediate check for new ads from a competitor that is already tracked; get_tracking_status shows when it finishes. Two steps: without confirm it returns a preview with idempotency_key; the same call with confirm: true, that key and max_credits: 0 starts the scan. It runs under the existing tracking month and does not start or renew tracking. Refused when tracking is off or paused, when a scan is already queued or running, and within one hour of the last manual scan.

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": {
      "competitor_id": "<competitor_id>"
    },
    "name": "scan_competitor"
  }
}

Input Schema

Name	Required	Description
`confirm`	No	true starts the scan described by the preview. Absent or false returns the preview and changes nothing.
`max_credits`	No	0 with confirm: true: a scan carries no new charge and cannot approve a renewal.
`competitor_id`	Yes	Competitor id from list_competitors.
`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.

Output Schema

Name	Required	Description
`next`	No	next value in this response.
`status`	No	Current progress or delivery state.
`replayed`	No	replayed 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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 10, 2026

changedInput schema / properties / competitor_id / description

Previous value: -"Competitor reference from list_competitors (e.g. the returned competitor id)."New value: +"Competitor id from list_competitors."

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 scan described by the preview. Absent or false returns the preview and changes nothing."

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: +"0 with confirm: true: a scan carries no new charge and cannot approve a renewal."

First observedNov 9, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description discloses that the scan runs under the existing tracking month without starting or renewing tracking, that it carries no new charge, and that the idempotency key is valid for 15 minutes and replays the first result. That is substantial behavioral context a schema alone would not convey. The only gap is that it doesn't describe latency or what the preview object contains beyond the key.

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 action, then the procedure, then the refusal conditions in a single dense but purposeful paragraph. Every clause carries information, though the run-on sentence structure around the confirm/idempotency_key/max_credits triple takes a second read to parse.

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?

An output schema exists and get_tracking_status is named for completion checking, so return values need not be spelled out. Given the mutation-adjacent two-step flow, the description covers cost, idempotency, tracking-month scope, and every refusal state - nothing an agent needs before calling is missing.

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 already 100%, so the baseline is 3. The description still adds cross-parameter meaning the schema cannot express on its own: confirm and idempotency_key must be used together with max_credits: 0 in the second step, and an absent confirm returns a preview and changes nothing. That sequencing logic earns an increment above baseline.

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 ('Requests one immediate check for new ads') and immediately narrows scope to a competitor that is 'already tracked', which separates it from add_competitor and from passive listing tools. It also points at get_tracking_status for the outcome, so the agent knows exactly what this call does and does not do.

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

Usage Guidelines5/5

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

Gives an explicit two-step procedure: first call without confirm yields a preview plus idempotency_key, then the same call with confirm: true, that key and max_credits: 0 starts the scan. It also enumerates the precise conditions under which the call is refused (tracking off or paused, scan already queued or running, within one hour of the last manual scan), which is exactly the when-not guidance an agent needs.

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.