StealAds

Check on an ad being made

get_ad_status

Read-onlyIdempotent

Returns the progress of an ad being made: state, stage (writing, designing, rendering, checking), whether it is terminal, the finished image and download once ready, or a failure message with any refunded credits. Meant to be read again after poll_after_seconds, until terminal is true; an ad usually takes a few minutes.

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": {
      "job_id": "<job_id>"
    },
    "name": "get_ad_status"
  }
}

Input Schema

Name	Required	Description	Default
`job_id`	Yes	Job reference returned when the ad was started (_references.job_id); list_generation_jobs returns it too. A generation_job_id is a different value and is not accepted.
`response_format`	No	Output format: text (default) or json. table is not available for this tool.

Output Schema

Name	Required	Description
`stage`	No	stage value in this response.
`state`	No	state value in this response.
`status`	No	Current progress or delivery state.
`message`	No	message value in this response.
`results`	No	Completed outputs currently available for this job or campaign.
`brand_id`	No	Reference for the selected brand.
`terminal`	No	True when polling should stop: ready, ended without a preview, failed, cancelled, or awaiting human attention.
`created_at`	No	created at value in this response.
`updated_at`	No	updated at value in this response.
`_references`	No	Opaque action references accepted by subsequent tool calls.
`next_action`	No	Suggested next operation for the current job state.
`refund_credits`	No	refund credits value in this response.
`failure_message`	No	failure message value in this response.
`needs_attention`	No	True when the ad is waiting on support before it can continue.
`credits_reserved`	No	credits reserved value in this response.
`estimated_seconds`	No	estimated seconds value in this response.
`poll_after_seconds`	No	Seconds between status checks; zero when finished.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 10, 2026

changedInput schema / properties / job_id / description

Previous value: -"Job reference from the make result (the returned job reference)."New value: +"Job reference returned when the ad was started (_references.job_id); list_generation_jobs returns it too. A generation_job_id is a different value and is not accepted."

changedInput schema / properties / response_format / description

Previous value: -"Output format: text or json for capped research examples; table is available only for tracked rival rows."New value: +"Output format: text (default) or json. table is not available for this tool."

Changed4 schema fields changedNov 9, 2026

addedOutput schema / properties / needs_attention

Added value: +{
+  "anyOf": [
+    {
+      "description": "True when the ad is waiting on support before it can continue.",
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "True when the ad is waiting on support before it can continue."
+}

addedOutput schema / properties / state

Added value: +{
+  "anyOf": [
+    {
+      "description": "state value in this response.",
+      "enum": [
+        "queued",
+        "running",
+        "capacity_deferred",
+        "needs_attention",
+        "ready",
+        "no_preview",
+        "loading_result",
+        "failed",
+        "cancelled",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "state value in this response."
+}

changedOutput schema / properties / terminal / anyOf

Previous value: -[
-  {
-    "description": "True only when the image is ready or the ad failed or was cancelled.",
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "description": "True when polling should stop: ready, ended without a preview, failed, cancelled, or awaiting human attention.",
+    "type": "boolean"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / terminal / description

Previous value: -"True only when the image is ready or the ad failed or was cancelled."New value: +"True when polling should stop: ready, ended without a preview, failed, cancelled, or awaiting human attention."

First observedNov 9, 2026

TDQS

A4/5.0

Behavior4/5

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

The annotations already declare read-only, idempotent, non-destructive, and closed-world, and the description adds real behavior beyond them: the four-stage progress model, the meaning of the terminal flag, the polling cadence, the typical multi-minute duration, and the refunded-credits failure path. This is close to complete, with no statement of rate limits or what happens if you poll too early.

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?

Two sentences, front-loaded with the return payload and followed by the polling loop and timing expectation, with essentially no filler. The first sentence is a long colon-delimited list, but every item is a distinct field the agent needs in order to interpret the response.

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?

The tool is a simple two-parameter status poller, and the description covers the entire lifecycle: the progress stages, the terminal condition, the success and failure outcomes, the refund behavior, and the duration expectation. The output schema carries the return shape and the annotations carry the safety profile, so nothing an agent needs in order to call this repeatedly and correctly is missing.

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 coverage is 100%, and the job_id description already covers the value's origin and the trap of passing a generation_job_id instead, so the schema does the heavy lifting and 3 is the baseline. The description adds no meaning to response_format. Worse, it names poll_after_seconds as if it were an input, but no such parameter exists in the schema and the schema never says what to do with it, which muddies rather than clarifies the parameters.

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?

The description opens with a concrete verb-plus-resource phrase, 'Returns the progress of an ad being made,' and lists exactly what comes back (state, stage, terminal flag, image, failure message with refunded credits). However, it never names sibling get_ad, even though get_ad is exactly what the agent will use after terminal is true, so what separates the two tools has to be inferred from the phrase 'being made'.

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 an explicit polling loop: call it again after poll_after_seconds until terminal is true, and expect a few minutes. That makes the usage context concrete. It does not say what to do instead (for example get_ad after completion) or warn against hammering the endpoint, so it stops short of full when-to-use/when-not guidance.

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.