BlockRun MCP

Official

Overview Schema Source Related Servers Discussions Admin

blockrun_video

Generate short AI videos from a text prompt or seed image by submitting a job, polling until the clip is ready, and returning a hosted video URL.

Instructions

Generate short AI videos via BlockRun x402 on the active Base or Solana chain (async, client-polled).

Turns a text prompt (and optional seed image) into a short video clip (MP4, or MOV on Seedance 2.5). The tool submits the job, then polls until the video is ready (typical total wall-time 60-180s; 9 min Base / 15 min Solana hard cap). On the wallet rails payment settles only when upstream returns a finished video — if the job fails you are not charged; if this client gives up while a paid poll is still in flight the gateway may still settle, and the error text says so. On the account rail the job is billed when the gateway accepts it, so a job that fails or outlives the poll budget is still charged — the error names it.

Models. Every rate below is what you are CHARGED (margin and transaction fee included), at the 720p baseline Seedance renders by default with synced audio:

azure/sora-2 (~$0.105/sec, 720p + synced audio, text- or image-to-video) — OpenAI Sora 2 via Azure AI Foundry. duration_seconds must be 4, 8, or 12 (4s default -> ~$0.42/clip). image_url takes a NON-HUMAN reference image (faces are rejected upstream by moderation — use Seedance + RealFace for real people); same price as text-to-video. No RealFace, no last_frame_url. Base only for now: the Solana gateway quotes it as Seedance 2.0 at $1.135 and the tool refuses that quote unsigned.
xai/grok-imagine-video ($0.05/sec at 480p default, $0.07/sec at 720p; 8s default -> $0.401/clip, 1-15s) — stylized, fast. 480p/720p only.
bytedance/seedance-1.5-pro (~$0.071/sec, 4-12s, 5s default -> ~$0.35/clip) — cheapest Seedance, token-priced upstream
bytedance/seedance-2.0-mini (~$0.080/sec, 4-15s, 5s default) — 2.0-generation quality at roughly half the 2.0-fast rate; 720p ceiling; supports RealFace, first/last-frame and the full reference set. The CHEAPEST model that takes reference video/audio — prefer it over 2.0 for reference work unless you need 4K.
bytedance/seedance-2.0-fast (~$0.165/sec, 4-15s, ~60-80s gen) — sweet-spot price/quality; supports RealFace, first/last-frame and the full reference set
bytedance/seedance-2.0 (~$0.227/sec, 4-15s, up to 4K) — highest quality, and the ONLY model that renders true 4K; supports RealFace, first/last-frame and the full reference set. Also the priciest: 2.0-mini takes the same reference inputs at ~1/3 the rate.
bytedance/seedance-2.5 (~$0.315/sec, 4-30s, 5s default) — long-form: double 2.0's length ceiling, multilingual. NOT a strict upgrade — it caps at 720p and takes no RealFace, though it does take first/last-frame, up to 30 reference IMAGES and reference clips. Use 2.0 for 1080p/4K or real-person video.

Image-to-video is NOT cheaper than text-to-video on Seedance — same per-second rate. Higher resolutions ARE more expensive (token-priced: 1080p ~2.25x, 4K ~9x the 720p rate); the 402 quote is authoritative and is what gets charged.

Reference media (reference_image_urls / reference_videos / reference_audios) is served ONLY on the BlockRun account rail (BLOCKRUN_API_KEY) — the Base and Solana gateways refuse it with a 400 before quoting, and this tool refuses it there first. Reference CLIPS are expensive: each one is billed at its model's ceiling (15.2s on the 2.0 family, 30.2s on 2.5) whatever its real length, and that price does NOT shrink with a shorter render or a lower resolution. On seedance-2.0-mini a 5s 720p render goes ~$0.40 -> ~$1.61 with one reference video (~4x), ~$5.10 with three videos plus three audios (~13x), and ~24x at 480p, where the discount reaches the render but not the clip. Reference IMAGES cost nothing extra. The account rail bills at submit with no quote to correct against, so check blockrun_wallet action:"report" before a large reference job.

RealFace: to generate video of a SPECIFIC real person, first enroll them with blockrun_realface (returns a ta_xxxx asset id), then pass real_face_asset_id here with seedance-2.0, seedance-2.0-fast, or seedance-2.0-mini. Mutually exclusive with image_url.

Returns a permanent blockrun-hosted video URL (the gateway mirrors the asset to GCS so URLs don't expire).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`seed`	No	Seedance 1.5-pro only: reproducibility seed. Same seed + same prompt re-renders the same clip.
`model`	No	Video model to use	xai/grok-imagine-video
`prompt`	Yes	Text description of the video to generate. E.g. 'a red apple slowly spinning on a wooden table', 'a hummingbird hovering near a red flower, ultra slow motion'
`agent_id`	No	Agent identifier for budget tracking and enforcement.
`image_url`	No	Optional seed image URL for image-to-video generation
`watermark`	No	Seedance only: burn the provider watermark into the output. Defaults off.
`resolution`	No	Output resolution. Seedance defaults to 720p and is token-priced (~2.25x at 1080p, ~9x at 4K); per-model sets from token360's published schema: seedance-2.0 480p/720p/1080p/4K · 1.5-pro 480p/720p/1080p · 2.0-fast, 2.0-mini and 2.5 480p/720p only. grok-imagine-video honours 480p (default, $0.05/sec) and 720p ($0.07/sec) and rejects anything higher. Ignored by Sora only (dropped from the request).
`aspect_ratio`	No	Output aspect ratio. Seedance honors the full set; Sora uses it only to pick portrait vs landscape (9:16 / 3:4 -> portrait); Grok ignores it (the gateway never forwards it to xAI). Defaults to the model's own default. (9:21 removed 2026-08-07 — no Seedance model offers it; use 9:16 for vertical.)
`bitrate_mode`	No	Seedance 2.x only (2.0, 2.0-fast, 2.0-mini, 2.5): output bitrate. Defaults to standard.
`camera_fixed`	No	Seedance 1.5-pro only: lock the camera so the shot does not drift.
`output_format`	No	Seedance 2.5 only: output container. Every other model returns MP4.
`generate_audio`	No	Seedance only: whether to generate a synced audio track. Defaults ON for text-to-video and OFF for image/RealFace-conditioned. The auto-generated audio is occasionally rejected by upstream moderation ('output audio may contain sensitive information') even for benign prompts — pass false to skip audio and avoid that failure. Ignored by xAI/Sora.
`last_frame_url`	No	Seedance 1.5-pro / 2.0 / 2.0-fast / 2.0-mini / 2.5 (2.5 not on the Solana wallet rail): first-and-last-frame interpolation. A second image URL that seeds the FINAL frame so the model tweens from image_url (first frame) → last_frame_url (last frame). Requires image_url; mutually exclusive with real_face_asset_id.
`duration_seconds`	No	Duration to bill for. Defaults to the model's own default (8s xAI, 5s Seedance, 4s Sora). Per-model range: seedance-1.5-pro 4-12s · seedance-2.0 / 2.0-fast / 2.0-mini 4-15s · seedance-2.5 4-30s · sora-2 exactly 4, 8 or 12 · grok-imagine-video 1-15s.
`reference_audios`	No	ACCOUNT RAIL ONLY. Audio reference clips (1-3), same models. Requires a reference image or video alongside. Billed at 0.3x the video-clip ceiling (15.2s on the 2.0 family, 30.2s on 2.5).
`reference_videos`	No	ACCOUNT RAIL ONLY. Motion reference clips (1-3) on the seedance-2.0 family and 2.5. Each clip is BILLED AT ITS MODEL'S CEILING (15.2s on the 2.0 family, 30.2s on 2.5) whatever its real length, so one clip makes a 5s 720p render cost about 4x (seedance-2.0-mini ~$0.40 -> ~$1.61), ~7x on 2.5, more at 480p.
`return_last_frame`	No	Seedance only: also return the final frame as an image URL, to seed the next clip in a chain.
`safety_identifier`	No	Seedance only: an opaque, stable end-user id forwarded upstream for abuse attribution. Not a content filter — do NOT put personal data in it.
`real_face_asset_id`	No	BytePlus RealFace asset id (from blockrun_realface enroll/list) to generate video of a specific real person. Seedance 2.0 / 2.0-fast / 2.0-mini only (NOT 2.5). Mutually exclusive with image_url.
`reference_image_urls`	No	ACCOUNT RAIL ONLY (BLOCKRUN_API_KEY) — the Base and Solana gateways refuse reference media with a 400. Character/style reference images, cited as 'image 1', 'image 2' in the prompt: up to 9 on seedance-2.0 / 2.0-fast / 2.0-mini, 30 on 2.5. Mutually exclusive with image_url / last_frame_url / real_face_asset_id.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.54.1Oct 7, 2026

changedInput schema / properties / reference_audios / description

Previous value: -"ACCOUNT RAIL ONLY. Audio reference clips (1-3) on seedance-2.0 / 2.0-fast / 2.0-mini — NOT 2.5. Requires a reference image or video alongside. Billed at 0.3x the 15.2s video-clip rate."New value: +"ACCOUNT RAIL ONLY. Audio reference clips (1-3), same models. Requires a reference image or video alongside. Billed at 0.3x the video-clip ceiling (15.2s on the 2.0 family, 30.2s on 2.5)."

changedInput schema / properties / reference_videos / description

Previous value: -"ACCOUNT RAIL ONLY. Motion reference clips (1-3) on seedance-2.0 / 2.0-fast / 2.0-mini — NOT 2.5. Each clip is BILLED AT THE 15.2s CEILING whatever its real length, so one clip makes a 5s 720p render cost about 4x (seedance-2.0-mini ~$0.40 -> ~$1.61), and more at 480p."New value: +"ACCOUNT RAIL ONLY. Motion reference clips (1-3) on the seedance-2.0 family and 2.5. Each clip is BILLED AT ITS MODEL'S CEILING (15.2s on the 2.0 family, 30.2s on 2.5) whatever its real length, so one clip makes a 5s 720p render cost about 4x (seedance-2.0-mini ~$0.40 -> ~$1.61), ~7x on 2.5, more at 480p."

Changed11 schema fields changedv0.53.1Sep 30, 2026

addedInput schema / properties / bitrate_mode

Added value: +{
+  "description": "Seedance 2.x only (2.0, 2.0-fast, 2.0-mini, 2.5): output bitrate. Defaults to standard.",
+  "enum": [
+    "standard",
+    "high"
+  ],
+  "type": "string"
+}

addedInput schema / properties / camera_fixed

Added value: +{
+  "description": "Seedance 1.5-pro only: lock the camera so the shot does not drift.",
+  "type": "boolean"
+}

changedInput schema / properties / last_frame_url / description

Previous value: -"Seedance 1.5-pro / 2.0 / 2.0-fast / 2.0-mini only (NOT 2.5): first-and-last-frame interpolation. A second image URL that seeds the FINAL frame so the model tweens from image_url (first frame) → last_frame_url (last frame). Requires image_url; mutually exclusive with real_face_asset_id."New value: +"Seedance 1.5-pro / 2.0 / 2.0-fast / 2.0-mini / 2.5 (2.5 not on the Solana wallet rail): first-and-last-frame interpolation. A second image URL that seeds the FINAL frame so the model tweens from image_url (first frame) → last_frame_url (last frame). Requires image_url; mutually exclusive with real_face_asset_id."

addedInput schema / properties / output_format

Added value: +{
+  "description": "Seedance 2.5 only: output container. Every other model returns MP4.",
+  "enum": [
+    "mp4",
+    "mov"
+  ],
+  "type": "string"
+}

addedInput schema / properties / reference_audios

Added value: +{
+  "description": "ACCOUNT RAIL ONLY. Audio reference clips (1-3) on seedance-2.0 / 2.0-fast / 2.0-mini — NOT 2.5. Requires a reference image or video alongside. Billed at 0.3x the 15.2s video-clip rate.",
+  "items": {
+    "properties": {
+      "url": {
+        "format": "uri",
+        "maxLength": 2048,
+        "type": "string"
+      }
+    },
+    "required": [
+      "url"
+    ],
+    "type": "object"
+  },
+  "maxItems": 3,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / reference_image_urls

Added value: +{
+  "description": "ACCOUNT RAIL ONLY (BLOCKRUN_API_KEY) — the Base and Solana gateways refuse reference media with a 400. Character/style reference images, cited as 'image 1', 'image 2' in the prompt: up to 9 on seedance-2.0 / 2.0-fast / 2.0-mini, 30 on 2.5. Mutually exclusive with image_url / last_frame_url / real_face_asset_id.",
+  "items": {
+    "format": "uri",
+    "maxLength": 2048,
+    "type": "string"
+  },
+  "maxItems": 30,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / reference_videos

Added value: +{
+  "description": "ACCOUNT RAIL ONLY. Motion reference clips (1-3) on seedance-2.0 / 2.0-fast / 2.0-mini — NOT 2.5. Each clip is BILLED AT THE 15.2s CEILING whatever its real length, so one clip makes a 5s 720p render cost about 4x (seedance-2.0-mini ~$0.40 -> ~$1.61), and more at 480p.",
+  "items": {
+    "properties": {
+      "url": {
+        "format": "uri",
+        "maxLength": 2048,
+        "type": "string"
+      }
+    },
+    "required": [
+      "url"
+    ],
+    "type": "object"
+  },
+  "maxItems": 3,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / return_last_frame

Added value: +{
+  "description": "Seedance only: also return the final frame as an image URL, to seed the next clip in a chain.",
+  "type": "boolean"
+}

addedInput schema / properties / safety_identifier

Added value: +{
+  "description": "Seedance only: an opaque, stable end-user id forwarded upstream for abuse attribution. Not a content filter — do NOT put personal data in it.",
+  "maxLength": 128,
+  "type": "string"
+}

addedInput schema / properties / seed

Added value: +{
+  "description": "Seedance 1.5-pro only: reproducibility seed. Same seed + same prompt re-renders the same clip.",
+  "maximum": 2147483647,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / watermark

Added value: +{
+  "description": "Seedance only: burn the provider watermark into the output. Defaults off.",
+  "type": "boolean"
+}

Changed1 schema field changedv0.45.1Sep 2, 2026
- removedInput schema / $schema
```
Removed value: -"http://json-schema.org/draft-07/schema#"
```

Changed5 schema fields changedv0.40.1Aug 14, 2026

changedInput schema / properties / duration_seconds / description

Previous value: -"Duration to bill for. Defaults to the model's own default (8s xAI, 5s Seedance, 4s Sora). Per-model range: seedance-1.5-pro 4-12s · seedance-2.0 / 2.0-fast 4-15s · seedance-2.5 4-30s · sora-2 exactly 4, 8 or 12 · grok-imagine-video 1-15s."New value: +"Duration to bill for. Defaults to the model's own default (8s xAI, 5s Seedance, 4s Sora). Per-model range: seedance-1.5-pro 4-12s · seedance-2.0 / 2.0-fast / 2.0-mini 4-15s · seedance-2.5 4-30s · sora-2 exactly 4, 8 or 12 · grok-imagine-video 1-15s."

changedInput schema / properties / last_frame_url / description

Previous value: -"Seedance 1.5-pro / 2.0 / 2.0-fast only (NOT 2.5): first-and-last-frame interpolation. A second image URL that seeds the FINAL frame so the model tweens from image_url (first frame) → last_frame_url (last frame). Requires image_url; mutually exclusive with real_face_asset_id."New value: +"Seedance 1.5-pro / 2.0 / 2.0-fast / 2.0-mini only (NOT 2.5): first-and-last-frame interpolation. A second image URL that seeds the FINAL frame so the model tweens from image_url (first frame) → last_frame_url (last frame). Requires image_url; mutually exclusive with real_face_asset_id."

changedInput schema / properties / model / enum

Previous value: -[
-  "azure/sora-2",
-  "xai/grok-imagine-video",
-  "bytedance/seedance-1.5-pro",
-  "bytedance/seedance-2.0-fast",
-  "bytedance/seedance-2.0",
-  "bytedance/seedance-2.5"
-]New value: +[
+  "azure/sora-2",
+  "xai/grok-imagine-video",
+  "bytedance/seedance-1.5-pro",
+  "bytedance/seedance-2.0-mini",
+  "bytedance/seedance-2.0-fast",
+  "bytedance/seedance-2.0",
+  "bytedance/seedance-2.5"
+]

changedInput schema / properties / real_face_asset_id / description

Previous value: -"BytePlus RealFace asset id (from blockrun_realface enroll/list) to generate video of a specific real person. Seedance 2.0 / 2.0-fast only (NOT 2.5). Mutually exclusive with image_url."New value: +"BytePlus RealFace asset id (from blockrun_realface enroll/list) to generate video of a specific real person. Seedance 2.0 / 2.0-fast / 2.0-mini only (NOT 2.5). Mutually exclusive with image_url."

changedInput schema / properties / resolution / description

Previous value: -"Seedance only: output resolution. Defaults to 720p. Higher resolutions cost more (token-priced upstream, ~2.25x at 1080p and ~9x at 4K). Per-model sets from token360's published schema: seedance-2.0 480p/720p/1080p/4K · 1.5-pro 480p/720p/1080p · 2.0-fast and 2.5 480p/720p only. Ignored by xAI/Sora (dropped from the request)."New value: +"Output resolution. Seedance defaults to 720p and is token-priced (~2.25x at 1080p, ~9x at 4K); per-model sets from token360's published schema: seedance-2.0 480p/720p/1080p/4K · 1.5-pro 480p/720p/1080p · 2.0-fast, 2.0-mini and 2.5 480p/720p only. grok-imagine-video honours 480p (default, $0.05/sec) and 720p ($0.07/sec) and rejects anything higher. Ignored by Sora only (dropped from the request)."

Changed8 schema fields changedv0.39.0Aug 8, 2026

changedInput schema / properties / aspect_ratio / description

Previous value: -"Seedance only: output aspect ratio, e.g. '9:16' for vertical/mobile, '16:9' for landscape. Defaults to the model's own default. Ignored by xAI/Sora."New value: +"Output aspect ratio. Seedance honors the full set; Sora uses it only to pick portrait vs landscape (9:16 / 3:4 -> portrait); Grok ignores it (the gateway never forwards it to xAI). Defaults to the model's own default. (9:21 removed 2026-08-07 — no Seedance model offers it; use 9:16 for vertical.)"

changedInput schema / properties / aspect_ratio / enum

Previous value: -[
-  "adaptive",
-  "16:9",
-  "9:16",
-  "1:1",
-  "4:3",
-  "3:4",
-  "21:9",
-  "9:21"
-]New value: +[
+  "adaptive",
+  "16:9",
+  "9:16",
+  "1:1",
+  "4:3",
+  "3:4",
+  "21:9"
+]

changedInput schema / properties / duration_seconds / description

Previous value: -"Duration to bill for (defaults to the model's default — 8s for xAI, 5s for Seedance; Seedance supports up to 10s)."New value: +"Duration to bill for. Defaults to the model's own default (8s xAI, 5s Seedance, 4s Sora). Per-model range: seedance-1.5-pro 4-12s · seedance-2.0 / 2.0-fast 4-15s · seedance-2.5 4-30s · sora-2 exactly 4, 8 or 12 · grok-imagine-video 1-15s."

changedInput schema / properties / last_frame_url / description

Previous value: -"Seedance only: first-and-last-frame interpolation. A second image URL that seeds the FINAL frame so the model tweens from image_url (first frame) → last_frame_url (last frame). Requires image_url; mutually exclusive with real_face_asset_id. Priced as image-to-video."New value: +"Seedance 1.5-pro / 2.0 / 2.0-fast only (NOT 2.5): first-and-last-frame interpolation. A second image URL that seeds the FINAL frame so the model tweens from image_url (first frame) → last_frame_url (last frame). Requires image_url; mutually exclusive with real_face_asset_id."

changedInput schema / properties / model / enum

Previous value: -[
-  "azure/sora-2",
-  "xai/grok-imagine-video",
-  "bytedance/seedance-1.5-pro",
-  "bytedance/seedance-2.0-fast",
-  "bytedance/seedance-2.0"
-]New value: +[
+  "azure/sora-2",
+  "xai/grok-imagine-video",
+  "bytedance/seedance-1.5-pro",
+  "bytedance/seedance-2.0-fast",
+  "bytedance/seedance-2.0",
+  "bytedance/seedance-2.5"
+]

changedInput schema / properties / real_face_asset_id / description

Previous value: -"BytePlus RealFace asset id (from blockrun_realface enroll/list) to generate video of a specific real person. Seedance 2.0 / 2.0-fast only. Mutually exclusive with image_url."New value: +"BytePlus RealFace asset id (from blockrun_realface enroll/list) to generate video of a specific real person. Seedance 2.0 / 2.0-fast only (NOT 2.5). Mutually exclusive with image_url."

changedInput schema / properties / resolution / description

Previous value: -"Seedance only: output resolution. Defaults to 720p. Higher resolutions cost more (token-priced upstream) — the final price is set by the 402 challenge, so the up-front estimate may understate 1080p/4K. Ignored by xAI/Sora."New value: +"Seedance only: output resolution. Defaults to 720p. Higher resolutions cost more (token-priced upstream, ~2.25x at 1080p and ~9x at 4K). Per-model sets from token360's published schema: seedance-2.0 480p/720p/1080p/4K · 1.5-pro 480p/720p/1080p · 2.0-fast and 2.5 480p/720p only. Ignored by xAI/Sora (dropped from the request)."

changedInput schema / properties / resolution / enum

Previous value: -[
-  "360p",
-  "480p",
-  "540p",
-  "720p",
-  "1080p",
-  "1K",
-  "2K",
-  "4K"
-]New value: +[
+  "480p",
+  "720p",
+  "1080p",
+  "4K"
+]

Changed4 schema fields changedv0.25.2Jun 29, 2026

addedInput schema / properties / aspect_ratio

Added value: +{
+  "description": "Seedance only: output aspect ratio, e.g. '9:16' for vertical/mobile, '16:9' for landscape. Defaults to the model's own default. Ignored by xAI/Sora.",
+  "enum": [
+    "adaptive",
+    "16:9",
+    "9:16",
+    "1:1",
+    "4:3",
+    "3:4",
+    "21:9",
+    "9:21"
+  ],
+  "type": "string"
+}

addedInput schema / properties / generate_audio

Added value: +{
+  "description": "Seedance only: whether to generate a synced audio track. Defaults ON for text-to-video and OFF for image/RealFace-conditioned. The auto-generated audio is occasionally rejected by upstream moderation ('output audio may contain sensitive information') even for benign prompts — pass false to skip audio and avoid that failure. Ignored by xAI/Sora.",
+  "type": "boolean"
+}

addedInput schema / properties / last_frame_url

Added value: +{
+  "description": "Seedance only: first-and-last-frame interpolation. A second image URL that seeds the FINAL frame so the model tweens from image_url (first frame) → last_frame_url (last frame). Requires image_url; mutually exclusive with real_face_asset_id. Priced as image-to-video.",
+  "format": "uri",
+  "type": "string"
+}

addedInput schema / properties / resolution

Added value: +{
+  "description": "Seedance only: output resolution. Defaults to 720p. Higher resolutions cost more (token-priced upstream) — the final price is set by the 402 challenge, so the up-front estimate may understate 1080p/4K. Ignored by xAI/Sora.",
+  "enum": [
+    "360p",
+    "480p",
+    "540p",
+    "720p",
+    "1080p",
+    "1K",
+    "2K",
+    "4K"
+  ],
+  "type": "string"
+}

First observedv0.16.2May 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false); the description carries the real behavioral burden and adds substantial context beyond them: async polling with typical 60-180s wall time and 9 min Base / 15 min Solana caps, and asymmetric billing on failure ('settles only when upstream returns a finished video ... on the account rail the job is billed when the gateway accepts it'). These are latent traits an agent could not infer from the schema or 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?

Purpose and the submit-then-poll flow are front-loaded in the first two sentences, and the model bullet list is genuinely decision-relevant (cost, resolution ceiling, reference support) rather than filler. It is long and a few clauses overlap with schema text (reference-clip ceiling pricing appears in both places), which keeps it off a 5, but nearly every sentence earns its place for a 7-model, 20-param, multi-rail, paid tool.

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?

With no output schema, the description still closes the loop: it states the return value ('a permanent blockrun-hosted video URL ... mirrored to GCS so URLs don't expire'), the polling/latency envelope, hard caps per rail, and what failures cost. Given the tool's complexity (payment rails, model matrix, mutual exclusions), nothing an agent needs to invoke it correctly 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 100%, so the baseline is 3, but the prose adds meaning the schema cannot: per-model capability and pricing matrices (which models take RealFace, 4K, reference clips, 4-30s ceilings, sora-2's exact 4/8/12s) and the cost multiplier for reference clips at 480p. It stops short of 5 because much of the per-parameter detail is restated from the schema rather than extended.

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?

Opens with a specific verb+resource+scope: 'Generate short AI videos via BlockRun x402 on the active Base or Solana chain (async, client-polled)', then restates the transformation ('text prompt (and optional seed image) into a short video clip'). It differentiates itself from siblings by naming blockrun_realface as the prerequisite enroll step and contrasting with the image tool's model set, so an agent can route without opening another schema.

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 explicit selection rules: 'prefer it over 2.0 for reference work unless you need 4K', 'Use 2.0 for 1080p/4K or real-person video', 'RealFace ... first enroll them with blockrun_realface', and 'check blockrun_wallet action:"report" before a large reference job'. It also states the condition that unlocks a whole feature set (reference media is account-rail only; gateways 400 first), which is exactly when/when-not guidance.

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

blockrun_video

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools