Skip to main content
Glama

@lweight/xbrush-api-mcp

MCP server for the XBrush AI media generation API — images, video, speech, music, sound effects, lip-sync (incl. talking photos), video extend/retake, LLM chat, content moderation, and watermarks, directly from Claude Code.

Quick Start

1. Get an API Key

Get your key at xbrush.run/api-keys.

2. Configure Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "xbrush": {
      "command": "npx",
      "args": ["-y", "@lweight/xbrush-api-mcp"],
      "env": {
        "XBRUSH_API_KEY": "your_api_key_here"
      }
    }
  }
}

3. Use It

"Generate an image of a cat sitting on a desk"
"Remove the background from this image"
"Read this script aloud in Korean"
"Create a 30-second upbeat synth track"
"Extend this video by another 5 seconds"
"Make this portrait photo say the following line"
"Ask GLM 5.2 to summarize this paragraph"

Related MCP server: gemini-nano-banana-mcp

How results work

All generation tools submit asynchronously and return a request_id. Poll it with xbrush_get_request until status is completed, then read the output URL(s). The blocking /sync endpoints are intentionally never called (see CLAUDE.md).

The one exception is xbrush_chat (LLM chat completions): it is synchronous and returns the completion text directly — the API has no async variant for it. Responses must fit the platform's ~30s gateway limit; if a 504 cuts the connection, the request keeps processing server-side and its result can be recovered via xbrush_list_requests + xbrush_get_request.

Available Tools (21)

Image (4)

Tool

Description

xbrush_image_generate

Generate images from text (e.g. seedream-5.0-pro, nano-banana-pro, flux.2-pro, gpt-image-2, z-image-turbo)

xbrush_image_edit

Edit / inpaint (qwen-image-edit, seedream-5.0-pro-edit, flux.2-pro-edit) or outpaint (flux-outpaint, qwen-outpaint)

xbrush_image_upscale

Upscale images (2x / 4x)

xbrush_image_remove_bg

Remove background

Video (5)

Tool

Description

xbrush_video_generate

Image-/text-/reference-to-video (e.g. kling-v3/o3, veo3.1, seedance-2.0, hailuo-02, wan-2.7). seedance-2.0 supports multi-reference via image_urls + @ImageN prompts and model-specific duration (4–15s)

xbrush_video_upscale

Upscale videos (realesrgan, seedvr)

xbrush_video_lip_sync

Lip-sync a face video (pixverse-lipsync, infinite-talk) or animate a still portrait as a talking photo (fabric-1.0) — speech from audio or built-in TTS (text + voice_id)

xbrush_video_extend

Extend an existing video by 1–20 seconds

xbrush_video_retake

Regenerate a video variation up to a timestamp

Audio (3)

Tool

Description

xbrush_tts_generate

Text-to-speech (e.g. speech-2.8-hd, eleven-v3)

xbrush_music_generate

Music generation from text (lyria2, lyria3, lyria3-pro)

xbrush_sound_effect_generate

Generate sound effects for a video — video-driven (pixverse) or prompt-driven (elevenlabs, stable-audio)

Text (1)

Tool

Description

xbrush_chat

LLM chat completions (e.g. GLM 5.2) — synchronous, OpenAI-compatible, billed per token

Utility (8)

Tool

Description

xbrush_content_moderate

NSFW moderation + masking for an image or video

xbrush_watermark_add

Add the XBrush watermark to an image/video

xbrush_list_models

List available AI models with pricing, vendor, and per-model duration constraints

xbrush_list_voices

List TTS voices (use a voice_id with tts_generate)

xbrush_get_request

Check status/result of an async operation

xbrush_list_requests

List recent API requests

xbrush_file_upload

Upload a local file to the XBrush CDN (auto / direct / presign)

xbrush_check_health

Check API server status

Environment Variables

Variable

Required

Description

XBRUSH_API_KEY

Yes

Your XBrush API key

XBRUSH_BASE_URL

No

API base URL. Defaults to https://api.xbrush.run.

XBRUSH_DISABLED_TOOLS

No

Comma-separated tool names to skip. Safety valve for selectively disabling a specific tool without uninstalling. Example: xbrush_music_generate,xbrush_content_moderate

License

MIT

Available Tools

21 tools
xbrush_chatChat (LLM)A

Chat with an XBrush-hosted LLM (OpenAI-compatible chat completions, e.g. GLM 5.2). SYNCHRONOUS — returns the completion text directly; no request_id polling needed. The platform gateway cuts responses at ~30s, so keep outputs short: prefer the default reasoning_effort (none) or 'minimal' and a modest max_tokens. On a 504 gateway timeout the request usually STILL completes and bills server-side — recover the text with xbrush_list_requests + xbrush_get_request (failed requests are auto-refunded).

Args: model (string, required): e.g. z-ai/glm-5.2. See xbrush_list_models(category='text'). messages (array, required): 1-1000 of {role: system|user|assistant, content: string ≤1M chars}. max_tokens (int, optional): 1-65536, includes reasoning tokens. temperature (float, optional): 0-2. top_p (float, optional): 0-1. frequency_penalty / presence_penalty (float, optional): -2 to 2. reasoning_effort (string, optional): none/minimal/high/max. Default: none (fastest).

Billed per token (input/output/cached rates via xbrush_list_models). OpenAI params not listed above (tools, stop, n, seed, response_format, stream) are not supported.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelYesLLM model ID (e.g. z-ai/glm-5.2). Use xbrush_list_models with category='text' to see options and per-token pricing.
top_pNoNucleus sampling probability mass (0-1).
messagesYesConversation so far, oldest first (1-1000 messages). The completion answers the last user message.
max_tokensNoUpper bound on generated tokens (1-65536), reasoning included. Keep modest — the response must finish within the ~30s gateway limit.
temperatureNoSampling temperature (0-2). Higher = more random.
presence_penaltyNoPenalize tokens already present (-2 to 2).
reasoning_effortNoReasoning budget for reasoning-capable models. Server default: none (fastest). Higher efforts can exceed the ~30s gateway limit — prefer none/minimal here.
frequency_penaltyNoPenalize frequent tokens (-2 to 2).

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, etc.), the description discloses critical behavioral traits: synchronous execution, 30s gateway cutoff, 504 timeout behavior where the request still completes and bills, automatic refunds for failed requests, and unsupported OpenAI parameters. This adds significant value and gives the agent a realistic model of the tool's side effects and failure modes.

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 description is front-loaded with purpose and the most critical behavioral caveat (synchronous, 30s limit). The Args section does repeat some schema constraints (types, ranges), but each repetition often carries added context (e.g., 'keep modest' for max_tokens). It is somewhat long but every section serves a purpose; still, a slightly tighter version could omit the redundant parameter constraints.

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 tool with 8 parameters, no output schema, and non-trivial runtime behavior, this description is thorough. It covers invocation, billing, error recovery, unsupported parameters, and practical usage constraints. The agent has enough context to select the tool, set parameters sensibly, and handle timeouts without needing additional lookup.

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 coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema: it notes that max_tokens includes reasoning tokens, that server default reasoning_effort is 'none (fastest)', and explicitly lists unsupported OpenAI parameters (tools, stop, etc.). This enriches parameter understanding beyond raw schema definitions.

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?

The description clearly states the tool's function: 'Chat with an XBrush-hosted LLM (OpenAI-compatible chat completions)'. It uses a specific verb and resource, and the focus on chat completions distinguishes it from the many image/video/audio generation siblings. The 'SYNCHRONOUS' note further differentiates it from request-based tools.

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 provides strong contextual guidance: it explicitly states this is synchronous with no polling needed, warns about the ~30s gateway limit, and advises on reasoning_effort and max_tokens. It also directs users to xbrush_list_models for model selection and mentions using xbrush_list_requests/get_request for timeout recovery. It does not explicitly name alternative chat tools because none exist among siblings, so exclusion guidance is less critical.

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

xbrush_check_healthCheck HealthA
Read-onlyIdempotent

Check XBrush API server health status.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior2/5

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

Annotations already declare read-only, idempotent, and non-destructive hints, and the description adds no further behavioral context. It does not describe what 'health status' means or what the response will look like, but for a simple health check, the transparency is minimal yet not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant words. It precisely conveys the tool's purpose without wasting any space.

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

Completeness4/5

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

For a very simple tool with no parameters and no output schema, the description is mostly complete, but it does not elaborate on what 'health status' includes or how the response is structured. Given the minimal complexity, this is a minor gap.

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?

The tool has zero parameters, and the schema is empty with 100% coverage. The baseline for zero parameters is 4, and the description does not need to add parameter information. It correctly avoids inventing parameters.

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?

The description clearly states the tool checks the XBrush API server health status, using a specific verb and resource. It uniquely identifies the tool among siblings, as no other sibling is concerned with health checks.

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

Usage Guidelines3/5

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

The description implies usage by naming the action, but it does not explicitly state when to use it or mention any alternatives or exclusions. Since there are no sibling tools for health checks, the lack of explicit alternatives is not penalized heavily, but some guidance is absent.

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

xbrush_content_moderateModerate ContentA

Run NSFW moderation on an image or video. The result (poll with xbrush_get_request) includes a flagged verdict, an overall score, and a processed copy with unsafe regions masked. Submits async — poll the returned request_id with xbrush_get_request.

Args: image_url (string, optional): Target image URL. video_url (string, optional): Target video URL (provide exactly one of image_url/video_url).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A5/5.0
Behavior5/5

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

The description discloses async behavior, the nature of the result (flagged verdict, overall score, processed copy with masked unsafe regions), and the requirement to poll with the returned request_id. These go beyond the annotations and give a clear picture of the tool's behavior without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly written, front-loaded with the purpose, and each sentence provides essential information (purpose, output, async note, args). No wasted words, making it highly concise and well-structured.

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 description covers purpose, parameters, async behavior, expected output, and polling mechanism. With no output schema, it adequately explains return values, making it complete for an agent to select and invoke the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the input schema is empty, the description fully documents the two parameters (image_url, video_url) with types and the requirement to provide exactly one. This adds crucial meaning where the schema is silent, earning full credit.

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?

The description clearly states 'Run NSFW moderation on an image or video' with a specific verb and resource, and it distinguishes the tool from siblings by being the only moderation tool. It also explicitly describes the output, making its purpose unambiguous.

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?

The description provides explicit usage context: it notes the asynchronous submission and instructs to poll with `xbrush_get_request`. It also includes the constraint to provide exactly one of image_url or video_url, which is clear guidance on how to invoke the tool.

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

xbrush_file_uploadUpload FileA

Upload a local file to XBrush CDN and get a URL. Use the returned CDN URL as image_url or video_url in other XBrush tools.

Supported formats: PNG, JPG, GIF, WebP, MP4, WebM, MP3, WAV.

Args: file_path (string, required): Absolute path to the local file. strategy (string, optional): 'auto' (default), 'direct', or 'presign'. - auto: small files (< 10MB) go via direct upload, larger via presigned S3. - direct: POST /v1/files/upload (multipart). - presign: presigned URL + S3 upload (handles large files).

ParametersJSON Schema
NameRequiredDescriptionDefault
strategyNoUpload strategy: 'auto' (default) picks by file size; 'direct' uses /v1/files/upload; 'presign' uses /v1/files/presign + S3.
file_pathYesAbsolute path to the local file to upload.

TDQS

A4.7/5.0
Behavior5/5

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

The description enriches beyond annotations by detailing upload strategies (auto/direct/presign), size thresholds (<10MB), endpoints (/v1/files/upload, presigned S3), and supported formats. This provides deep behavioral insight, especially since annotations only indicate basic safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear opening purpose, usage note, supported formats list, and parameter details. Every sentence serves a purpose, and it is concise without unnecessary filler.

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?

Despite no output schema, the description states that the tool returns a URL and how to use it. It covers parameter semantics, format support, internal strategy details, and usage context, making the tool fully understandable without needing to inspect schema or annotations.

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 coverage is 100%, so baseline is 3. The description adds meaningful detail for the strategy parameter by explaining the behavior and trade-offs of each enum value (e.g., 'auto: small files go via direct upload, larger via presigned S3'). This goes beyond the schema's enum list.

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?

The description clearly states the tool uploads a local file to XBrush CDN and returns a URL, with specific verb and resource. It also explains the purpose of the returned URL in other XBrush tools, distinguishing it from sibling tools that generate or process media.

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 indicates when to use the tool ('Upload a local file ... Use the returned CDN URL as image_url or video_url in other XBrush tools'), providing clear context. It does not explicitly mention alternatives or when not to use it, but the context is sufficient for an upload utility.

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

xbrush_get_requestGet RequestA
Read-onlyIdempotent

Get the status and result of an XBrush API request. Use this to check the result of async operations (image edit, video generate, etc.).

Args: request_id (string, required): Request ID starting with 'req'.

ParametersJSON Schema
NameRequiredDescriptionDefault
request_idYesRequest ID (starts with 'req', 24 characters).

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds the async-operation context, which is useful, but it doesn't disclose behaviors like response format, error handling for unknown request IDs, or whether it polls or returns immediately. This goes slightly beyond annotations but not by much.

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 description is brief and front-loaded with the purpose, followed by a clear usage note. The 'Args:' section is redundant with the schema, but it doesn't bloat the description. Overall, it is concise and easy to scan.

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?

With no output schema, the description should clarify what 'status and result' means in terms of return value. It doesn't describe the structure or possible states (e.g., pending, completed, error), which is a gap for an async polling tool. However, the tool is simple and the annotations cover safety, so the description is minimally adequate but not complete.

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%, with the parameter already described as 'Request ID (starts with 'req', 24 characters)'. The description repeats this requirement ('starts with 'req'') without adding new meaning. Baseline 3 is appropriate since the schema handles parameter documentation.

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?

The description uses a specific verb ('Get') and resource ('status and result of an XBrush API request'), making the tool's function clear. It also distinguishes it from sibling tools by noting it checks async operations like image edit and video generate, which differentiates it from list_requests or generation tools.

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 explicitly states to use this tool to check the result of async operations, providing clear context. It doesn't explicitly mention alternatives like list_requests, but the use case is well-defined and implies when this tool is appropriate.

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

xbrush_image_editEdit ImageA

Edit an image with text instructions. For inpainting use an edit model; for outpainting (extending the canvas) use an outpaint model — there is no separate outpaint tool. Submits async — poll the returned request_id with xbrush_get_request.

Args: model (string, required): Inpaint: qwen-image-edit, nano-banana-edit, seedream-4.5-edit. Outpaint: flux-outpaint, qwen-outpaint. See xbrush_list_models(category='image'). prompt (string, required): Text instruction for the edit. image_url (string, required): URL of the primary source image (also the first reference). image_urls (string[], optional): Additional reference image URLs for multi-reference models (gpt-image-2-edit, nano-banana-edit). Model receives [image_url, ...image_urls]. n (int, optional): Number of results (1-8). Default: 1. mask_url (string, optional): Mask image URL (white=edit, black=preserve). mode (string, optional): Hint 'inpaint'/'outpaint'; the chosen model determines the actual operation. width (int, optional): Output width (256-4096). Megapixel/outpaint models use it directly (outpaint: target canvas width). Resolution-based edit models ignore it UNLESS aspect_ratio:"custom" (see aspect_ratio). height (int, optional): Output height (256-4096). Same rules as width (outpaint: target canvas height). resolution (string, optional): Resolution tier for resolution-based edit models (gpt-image-2-edit, seedream-*-edit, nano-banana-pro/2-edit), e.g. "1K"/"2K"/"4K". aspect_ratio (string, optional): Aspect ratio for resolution-based edit models. gpt-image-2-edit: 1:1, 3:2, 2:3, 4:3, 3:4, 4:5, 16:9, 9:16, 21:9, 1.91:1 (1K/2K); only 16:9/9:16/21:9/1.91:1 at 4K. Special value "custom": gpt-image-2-edit outputs the exact width×height you pass (both required; each a multiple of 16, longest edge ≤3840, total pixels 655,360–8,294,400). quality (string, optional): low/medium/high — gpt-image-2-edit only. seed (int, optional): Random seed.

Note: resolution-based edit models (gpt-image-2-edit, seedream-*-edit, nano-banana-pro/2-edit) ignore width/height — passing them returns an error. Exception: aspect_ratio:"custom" with width+height yields an EXACT pixel size on gpt-image-2-edit. Note: to give multiple reference images (e.g. compose two subjects with gpt-image-2-edit), put the primary in image_url and the rest in image_urls.

ParametersJSON Schema
NameRequiredDescriptionDefault
nNoNumber of edited images (1-8). Default: 1.
modeNoOptional hint ('inpaint'/'outpaint'). The selected model ultimately determines the operation — pick an outpaint model to outpaint.
seedNoRandom seed for reproducible results.
modelYesEditing model. Inpaint/instruct-edit: qwen-image-edit, nano-banana-edit, seedream-5.0-pro-edit, flux.2-pro-edit. Outpaint: flux-outpaint, qwen-outpaint. Use xbrush_list_models(category='image').
widthNoOutput width in pixels (256-4096) for megapixel-based models; for outpaint models, the target canvas width. Resolution-based edit models normally ignore it — but with aspect_ratio:"custom", gpt-image-2-edit outputs exactly width×height (both required).
heightNoOutput height in pixels (256-4096) for megapixel-based models; for outpaint models, the target canvas height. Resolution-based edit models ignore it unless aspect_ratio:"custom" (see width).
promptYesText instruction describing the desired edits.
qualityNoOutput quality tier. Applies to byResolutionAndQuality models (gpt-image-2-edit); higher = better and more expensive. Server default is high if omitted.
mask_urlNoMask image URL. White areas = edit, black areas = preserve.
image_urlYesURL of the primary source image to edit (also the first reference).
image_urlsNoAdditional reference image URLs for models that compose from multiple references (e.g. gpt-image-2-edit, nano-banana-edit). Appended after image_url, so the model receives [image_url, ...image_urls]. Omit for single-reference edits.
resolutionNoOutput resolution tier for resolution-based edit models (gpt-image-2-edit, seedream-*-edit, nano-banana-pro/2-edit). Examples: "1K", "2K", "4K".
aspect_ratioNoAspect ratio for resolution-based edit models (e.g. "16:9"). gpt-image-2-edit supports 1:1, 3:2, 2:3, 4:3, 3:4, 4:5, 16:9, 9:16, 21:9, 1.91:1 at 1K/2K — at 4K only 16:9, 9:16, 21:9, 1.91:1. Special value "custom" makes gpt-image-2-edit use width×height as the exact output size (both required, each a multiple of 16, longest edge ≤3840, total pixels 655,360–8,294,400). seedream-*-edit / nano-banana-*-edit accept their own sets; an unsupported value is rejected with the list of allowed ratios.

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the annotations, the description discloses the async submission and polling mechanism: 'Submits async — poll the returned request_id with xbrush_get_request.' It also reveals model-specific behavior such as resolution-based models ignoring width/height and raising errors, the custom aspect_ratio exception, and the exact image_urls ordering passed to the model. No contradiction with 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 description is front-loaded with the core purpose and uses a clear Args list plus notes. It is long, but the tool has 13 parameters and many conditional behaviors; nearly every sentence carries useful information. Minor redundancy with the input schema prevents a perfect score.

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 complex, 13-parameter tool with no output schema, the description is remarkably complete: it covers async behavior, model categories, parameter semantics, model-specific constraints, reference-image ordering, and return value (request_id). An agent could correctly invoke this tool without additional documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 100%, the description adds substantial meaning: it partitions models into inpaint/outpaint categories, explains that mask white=edit and black=preserve, clarifies when width/height are used or ignored, defines the 'custom' aspect-ratio behavior with exact pixel constraints, and scopes quality to gpt-image-2-edit only. This goes far beyond the schema's property descriptions.

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?

The description opens with a specific verb+resource statement: 'Edit an image with text instructions.' It immediately distinguishes inpainting vs outpainting, and explicitly notes there is no separate outpaint tool, clearly differentiating from image generation, upscaling, and background-removal siblings.

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?

The description gives explicit when-to-use guidance: 'For inpainting use an edit model; for outpainting (extending the canvas) use an outpaint model — there is no separate outpaint tool.' It also directs users to xbrush_list_models(category='image') for model selection and explains multi-reference usage, covering both alternatives and prerequisites.

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

xbrush_image_generateGenerate ImageA

Generate images from a text prompt using XBrush AI models. Submits async — poll the returned request_id with xbrush_get_request.

Args: model (string, required): Model ID (e.g. z-image-turbo). Use xbrush_list_models to see options. prompt (string, required): Text description of the image. n (int, optional): Number of images (1-8). Default: 1. negative_prompt (string, optional): Elements to exclude. width (int, optional): Width in pixels (256-4096). Megapixel-based models (flux., z-image-turbo, ...) use it directly (default 1024). Resolution-based models ignore it UNLESS aspect_ratio:"custom" (see aspect_ratio). height (int, optional): Height in pixels (256-4096). Same rules as width. resolution (string, optional): Resolution tier for resolution-based models (gpt-image-2, seedream-, nano-banana-pro/2), e.g. "1K"/"2K"/"4K". aspect_ratio (string, optional): Aspect ratio for resolution-based models. gpt-image-2/-edit: 1:1, 3:2, 2:3, 4:3, 3:4, 4:5, 16:9, 9:16, 21:9, 1.91:1 (1K/2K); only 16:9/9:16/21:9/1.91:1 at 4K. Special value "custom": gpt-image-2/-edit output the exact width×height you pass (both required; each a multiple of 16, longest edge ≤3840, total pixels 655,360–8,294,400) — e.g. width:1024,height:1152,aspect_ratio:"custom" returns 1024×1152. quality (string, optional): low/medium/high — gpt-image-2/-edit only. seed (int, optional): Random seed for reproducibility.

Note: resolution-based models (gpt-image-2, seedream-*, nano-banana-pro/2) ignore width/height — passing them returns an error. Exception: aspect_ratio:"custom" with width+height yields an EXACT pixel size on gpt-image-2/-edit (other resolution models may only keep the ratio or ignore it).

ParametersJSON Schema
NameRequiredDescriptionDefault
nNoNumber of images to generate (1-8). Default: 1.
seedNoRandom seed for reproducible results.
modelYesImage model to use (e.g. z-image-turbo, flux.2-pro, seedream-5.0-pro, nano-banana-pro). Use xbrush_list_models to see available models.
widthNoOutput width in pixels (256-4096) for megapixel-based models (flux.*, z-image-turbo, etc.). Default: 1024. Resolution-based models (gpt-image-2, seedream-*, nano-banana-*) normally ignore it — but with aspect_ratio:"custom", gpt-image-2/-edit output exactly width×height (both required).
heightNoOutput height in pixels (256-4096) for megapixel-based models. Default: 1024. Resolution-based models ignore it unless aspect_ratio:"custom" (see width).
promptYesText description of the image to generate.
qualityNoOutput quality tier. Applies to byResolutionAndQuality models (gpt-image-2/-edit); higher = better and more expensive. Server default is high if omitted.
resolutionNoOutput resolution tier for resolution-based models (gpt-image-2, seedream-*, nano-banana-pro/2). Examples: "1K", "2K", "4K". Ignored by megapixel-based models — use width/height for those.
aspect_ratioNoAspect ratio for resolution-based models (e.g. "16:9"). gpt-image-2/-edit support 1:1, 3:2, 2:3, 4:3, 3:4, 4:5, 16:9, 9:16, 21:9, 1.91:1 at 1K/2K — at 4K only 16:9, 9:16, 21:9, 1.91:1. Special value "custom" makes gpt-image-2/-edit use width×height as the exact output size (both required, each a multiple of 16, longest edge ≤3840, total pixels 655,360–8,294,400; missing dimensions or out-of-range values return 400). seedream-* / nano-banana-* accept their own sets; an unsupported value is rejected with the list of allowed ratios.
negative_promptNoElements to exclude from the generated image.

TDQS

A4.3/5.0
Behavior5/5

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

The description discloses the asynchronous submission behavior, the need to poll the returned request_id, and detailed model-specific behaviors including error conditions ('passing them returns an error') and the exact-size exception for aspect_ratio:'custom'. Annotations provide only basic hints (readOnlyHint=false, etc.), so this context is valuable beyond what annotations offer.

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 description is front-loaded with a clear one-line purpose, followed by an async note and a structured argument list. It is long but every section covers distinct parameter semantics or model-specific interactions; the bullet list improves scannability. Minor redundancy with schema descriptions keeps it from being maximally concise.

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 10-parameter tool with no output schema, the description covers all arguments, model families, default behavior, error conditions, and the follow-up polling mechanism via xbrush_get_request. It also provides concrete examples for the most complex parameter (aspect_ratio), making it exceptionally complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema covers 100% of parameters, the description adds meaningful semantics by grouping models into megapixel-based vs resolution-based, clarifying which parameters apply to which model types, and explaining the special 'custom' aspect_ratio behavior with a concrete example. This substantially aids correct parameter selection beyond the schema.

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 'Generate images from a text prompt using XBrush AI models,' clearly identifying the operation and resource. However, it does not explicitly differentiate from siblings like xbrush_image_edit or xbrush_image_upscale, relying on the tool name and phrase 'from a text prompt' for implicit distinction.

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

Usage Guidelines3/5

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

The description provides context (text-to-image generation, async flow with xbrush_get_request) and points to xbrush_list_models for model selection, but it never states when to prefer this tool over alternatives or when not to use it. Usage is implied rather than explicitly guided.

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

xbrush_image_remove_bgRemove BackgroundA

Remove the background from an image. Submits async — poll the returned request_id with xbrush_get_request.

Args: image_url (string, required): URL of the image.

ParametersJSON Schema
NameRequiredDescriptionDefault
image_urlYesURL of the image to remove background from.

TDQS

A4.2/5.0
Behavior4/5

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

The description discloses the async behavior and the need to poll with xbrush_get_request, adding context beyond the annotations. It does not mention side effects or permissions, but the annotations already indicate non-read-only and non-destructive characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is remarkably concise, with three short sentences covering purpose, async behavior, and parameter. Every sentence earns its place and the structure is front-loaded with the primary action.

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

Completeness4/5

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

For a single-parameter tool with no output schema, the description effectively communicates how to invoke it and what to do with the result (poll with request_id). It could be more complete with an example or edge-case note, but it is sufficient for correct invocation.

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?

The schema already fully describes the only parameter (image_url) with a URI format and clear description. The description repeats this information without adding new meaning, so it meets the baseline for high schema coverage.

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?

The description clearly states 'Remove the background from an image' with a specific verb and resource, distinctly separating it from siblings like xbrush_image_upscale or xbrush_image_edit.

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?

It provides clear context by noting the async submission and polling requirement, which is essential for correct usage. It does not explicitly mention when not to use it or alternatives, but the context is unambiguous.

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

xbrush_image_upscaleUpscale ImageA

Upscale an image to higher resolution. Submits async — poll the returned request_id with xbrush_get_request.

Args: image_url (string, required): URL of the image to upscale. upscale_factor (int, optional): 2x or 4x. Default: 2.

ParametersJSON Schema
NameRequiredDescriptionDefault
image_urlYesURL of the image to upscale.
upscale_factorNoUpscale multiplier: 2 or 4. Default: 2.

TDQS

A4/5.0
Behavior4/5

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

The description reveals the tool's asynchronous nature and the need to poll for the result, information not present in the annotations. This is key behavioral context beyond the readOnly/destructive hints, though it could mention failure or polling specifics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short, high-signal sentences: purpose, async note, and args. No filler or redundancy; all content earns its place.

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

Completeness4/5

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

For a simple async tool, the description covers the essential usage loop: call, receive request_id, poll. It lacks response structure or error details, but that is handled by xbrush_get_request. The description is sufficiently complete given the tool's simplicity and sibling relations.

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?

The input schema already fully describes both parameters with constraints and defaults. The description's Arg list repeats this information without adding new meaning, so it neither improves nor harms parameter understanding.

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?

The description opens with 'Upscale an image to higher resolution,' a clear verb+resource+outcome statement. It also notes async submission, which distinguishes it from synchronous sibling tools like xbrush_image_generate and xbrush_image_edit.

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

Usage Guidelines3/5

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

The description provides explicit workflow guidance ('Submits async — poll the returned request_id with xbrush_get_request'), implying how to use the tool. However, it does not name alternative tools or state when not to use this tool, leaving the usage context partially implied.

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

xbrush_list_modelsList ModelsA
Read-onlyIdempotent

List available XBrush AI models with pricing info. Models span image (generate/edit/upscale/remove-bg/outpaint/moderate), video (i2v/upscale/lipsync/extend/retake/moderate), audio (tts/music/sound-effect), text (chat LLMs for xbrush_chat, priced per 1M tokens), and utility. Video i2v entries include their duration constraints (min-max seconds, step, default). Watermark has no dedicated model list — call it directly.

Args: category (string, optional): 'image', 'video', 'audio', 'text', or 'utility'.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryNoFilter by top-level category: image, video, audio, text (chat LLMs), or utility. Omit to list all.

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior. The description adds useful context about the content: models include pricing, video i2v duration constraints, and the watermark exception. This goes beyond the structured 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 description is well-structured with a clear opening statement, a compact enumeration of model categories, specific notes about video constraint fields and watermark behavior, and a brief arg summary. It is slightly redundant with the schema in the Args section but remains appropriately sized.

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

Completeness4/5

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

Without an output schema, the description compensates by mentioning pricing info, model categories, video duration constraints, and the watermark exclusion. It gives enough context for the agent to understand what will be returned. Minor gap: it doesn't specify exact response structure or pagination, but that's acceptable for a simple list tool.

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?

The input schema already provides a full description of the category parameter, including the valid enum values and the meaning of omission. The description's Args section merely repeats the schema's coverage, adding no new semantic value. Baseline 3 is appropriate since schema coverage is 100%.

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?

The description clearly states the tool lists available XBrush AI models with pricing info, using a specific verb and resource. It distinguishes itself from sibling tools like list_voices and the various generation tools by focusing on model metadata rather than execution.

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?

The description includes explicit guidance: it notes that watermark models have no dedicated list and should be called directly, providing a when-not usage. It also implies the tool is for discovering models before invoking generation/chat calls, and the category filter offers a way to narrow results.

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

xbrush_list_requestsList RequestsA
Read-onlyIdempotent

List recent XBrush API requests with status and results.

Args: limit (int, optional): Number of requests (1-100). Default: 20. cursor (string, optional): Pagination cursor from previous response.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoNumber of requests to return (1-100). Default: 20.
cursorNoPagination cursor from a previous response.

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds behavioral context beyond these annotations: it emphasizes 'recent' (implying temporal ordering) and includes pagination via a cursor, which are useful behavioral traits. It does not detail rate limits or response format, but that is partially mitigated by 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the primary purpose, followed by a clear args list. It contains no redundant or verbose phrases, and every sentence serves a purpose.

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 simple list tool with optional parameters and strong annotations, the description is fully adequate. It explains the returned content (status and results), pagination via cursor, and the default/range for limit. No output schema exists, but the description covers the essential details needed to invoke the tool successfully.

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 schema already fully documents both parameters. The description's parameter section merely repeats the schema's descriptions (limit and cursor) without adding extra meaning, such as how the cursor is obtained or what happens if the limit is exceeded.

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?

The description clearly states the tool lists recent XBrush API requests with status and results. The verb 'list' and resource 'requests' are specific, and it distinguishes itself from sibling xbrush_get_request by focusing on a collection of recent requests.

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

Usage Guidelines3/5

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

The description implies usage for listing recent requests but does not explicitly mention when to use this tool instead of alternatives like xbrush_get_request or how to handle pagination pitfalls. There is no explicit exclusion or comparison with sibling tools, so guidance is only implied.

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

xbrush_list_voicesList VoicesA
Read-onlyIdempotent

List the voices available for text-to-speech, optionally for a specific model/provider. Use a returned voice_id as the voice_id argument to xbrush_tts_generate.

Args: model (string, optional): TTS model ID (e.g. speech-2.8-hd, eleven-v3). Omit for the default provider.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoTTS model ID to list voices for (e.g. speech-2.8-hd, eleven-v3). Omit for the default provider. See xbrush_list_models(category='audio').

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful context: the returned voice_id feeds into xbrush_tts_generate, and omitting model uses the default provider. No contradiction with 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 description is short and front-loaded with the primary purpose. The Args block is somewhat redundant with the schema but keeps information inline for quick reading. Overall it is appropriately sized and well organized.

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

Completeness4/5

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

The tool is simple with one optional parameter and no output schema. The description covers the main usage pattern and integration with xbrush_tts_generate. It does not detail the return format, but that is not critical given the tool's low complexity.

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 model parameter is already well documented with examples and a reference to xbrush_list_models. The description's Args section mostly repeats the schema and adds no new semantic meaning beyond restating optional behavior.

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?

The description clearly states the tool lists voices for text-to-speech, optionally filtered by model/provider. It differentiates from sibling tools by explicitly mentioning TTS and linking to xbrush_tts_generate. The verb 'list' and resource 'voices' are specific.

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 tells the agent when to use the tool (to select a voice_id for xbrush_tts_generate) and how to optionally filter by model. It does not explicitly mention exclusions or when to prefer alternatives like xbrush_list_models, but the context is clear.

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

xbrush_music_generateGenerate MusicA

Generate music from a text prompt using an XBrush music model (e.g. lyria2, lyria3, lyria3-pro). Submits async — generation typically takes tens of seconds to minutes. Poll with xbrush_get_request.

Args: prompt (string, required): Text description of the music. model (string, optional): Music model ID. Server default if omitted. duration (int, optional): Duration in seconds (1-120). negative_prompt (string, optional): Elements to exclude. seed (int, optional): Random seed.

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoRandom seed for reproducibility.
modelNoMusic model ID (e.g. lyria2, lyria3, lyria3-pro). Optional — server picks a default.
promptYesText description of the music to generate.
durationNoDuration in seconds (1-120). Conservative upper bound; may be lifted by server.
negative_promptNoStyles/elements to exclude from the generated music.

TDQS

A4/5.0
Behavior4/5

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description adds critical non-obvious behavioral context: the operation is asynchronous, typically takes tens of seconds to minutes, and must be polled. No contradiction exists.

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 description is concise and well-structured: a clear first line, a short async guidance note, and a neat Args list. It is slightly redundant with the schema, but it remains scannable and front-loaded.

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?

With no output schema, the description should specify what the initial call returns (e.g., a request ID) to enable polling. It only says 'Poll with xbrush_get_request' without stating the response shape, which is a notable gap. All parameters and the async flow are otherwise covered.

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?

The input schema covers all 5 parameters with complete descriptions, so the Args block in the description largely restates what the schema already provides. The description adds no new semantic detail beyond the schema's existing examples and bounds.

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?

The description uses a specific verb 'Generate' and resource 'music' with model examples (lyria2, lyria3, lyria3-pro). This clearly distinguishes it from sibling tools like xbrush_sound_effect_generate, xbrush_image_generate, and xbrush_video_generate.

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 clearly communicates the async workflow and points to xbrush_get_request for polling. It does not explicitly rule out alternatives (e.g., when to use sound effects vs music), but the scope is evident from the purpose line.

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

xbrush_sound_effect_generateGenerate Sound EffectA

Generate foley / ambient sound effects for a given video. Video-driven models (pixverse-sound-effects) design sound from the visuals; text-driven models (elevenlabs-sound-effects, stable-audio-sfx) generate from prompt — but video_url is required for every model. Submits async — poll the returned request_id with xbrush_get_request.

Args: video_url (string, required): Source video URL (required even for text-driven models). prompt (string, optional): Sound description — main input for text-driven models. model (string, optional): Sound-effect model ID. Server default if omitted. duration (number, optional): Seconds (1-30).

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoSound-effect model ID: pixverse-sound-effects (video-driven), elevenlabs-sound-effects / stable-audio-sfx (text-driven — describe the sound in prompt). Server default if omitted.
promptNoText description of the sound (e.g. 'gentle rain on leaves'). Main input for text-driven models; a bias hint for video-driven ones.
durationNoSound duration in seconds (1-30).
video_urlYesURL of the source video. Required for all models (even text-driven ones).

TDQS

A4.5/5.0
Behavior4/5

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

The description discloses the async submission behavior and the need to poll for results, which annotations don't convey. It also clarifies the surprising constraint that video_url is required even for text-driven models. It doesn't mention rate limits or side effects, but given the annotations (readOnlyHint=false, destructiveHint=false), the behavioral disclosure is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized: a one-sentence purpose, followed by key distinctions, async workflow, and a compact Args list. It is front-loaded with the most critical info and every sentence contributes useful guidance without padding.

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 4-parameter async generation tool with no output schema, the description covers the essential operational context: model selection guidance, required video_url constraint, async polling flow, and duration limits. It is complete enough for an agent to invoke and follow up correctly.

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 schema itself includes detailed descriptions for all parameters. The description's Args section largely mirrors the schema, adding only the emphasis that video_url is required for all models. Since the schema already carries the semantic load, the description adds marginal value, warranting the baseline score.

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?

The description opens with a specific verb+resource: 'Generate foley / ambient sound effects for a given video.' This clearly states what the tool does and distinguishes it from sibling tools like image generation, TTS, or music generation. It further clarifies model subtypes (video-driven vs text-driven), making the purpose unambiguous.

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?

Usage guidance is explicit: it explains that video_url is required for every model, describes when to use text-driven vs video-driven models, and instructs the caller to poll xbrush_get_request with the returned request_id. This gives clear when-to-use and next-step context, going beyond simple purpose.

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

xbrush_tts_generateGenerate Speech (TTS)A

Generate speech audio from text using an XBrush TTS model. Minimax models (speech-2.6-hd, speech-2.8-hd, speech-2.8-turbo) REQUIRE a voice_id — get one from xbrush_list_voices. ElevenLabs (eleven-v3) works without a voice_id. Submits async — poll the returned request_id with xbrush_get_request.

Args: text (string, required): Text to speak. model (string, optional): TTS model ID (e.g. eleven-v3, speech-2.8-hd). Default is Minimax (needs voice_id). voice_id (string, required for Minimax): a voice from xbrush_list_voices. language (string, optional): Locale code (e.g. 'ko', 'en'). speed (float, optional): Speech rate (0.5-2.0). Default: 1.0.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesText to synthesize (non-blank).
modelNoTTS model ID (e.g. eleven-v3, speech-2.8-hd). Optional — server default is a Minimax model (which needs voice_id). Use xbrush_list_models with category='audio'.
speedNoSpeech rate multiplier (0.5-2.0). Default: 1.0.
languageNoLanguage/locale code (e.g. 'ko', 'en', 'ko-KR').
voice_idNoVoice identifier. REQUIRED for Minimax models (speech-*); get one from xbrush_list_voices. ElevenLabs (eleven-v3) works without it.

TDQS

A4.5/5.0
Behavior4/5

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

The description discloses a key behavioral trait—'Submits async—poll the returned request_id with xbrush_get_request'—which adds value beyond the annotations. It also notes model-specific requirements. However, it doesn't detail what happens on failure or whether partial output exists, though the annotations already cover readOnly/destructive/idempotent hints. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, well-structured, and front-loaded with the core purpose. It uses a short intro followed by clearly labeled argument bullets. Every sentence adds useful information without redundancy or filler, making it easy to scan.

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 description provides complete context for a tool with no output schema: it names all parameters, explains conditional requirements, and tells the agent how to follow up (xbrush_get_request). The async nature and model-specific voice_id needs are covered. No output schema exists, so the tool adequately guides the agent through the full invocation flow.

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%, and the description largely repeats the same parameter details already present in the input schema (e.g., voice_id requirements, default speed range, model examples). It consolidates the information readable but does not add significant new meaning beyond the structured schema definitions. Baseline 3 is appropriate.

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?

The description clearly states the tool's purpose: 'Generate speech audio from text using an XBrush TTS model.' This is a specific verb+resource combination that also distinguishes this text-to-speech tool from sibling tools like image, video, music, and sound effect generation. The model family details reinforce the tool's unique scope.

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?

Usage guidance is explicit: it distinguishes when a voice_id is required (Minimax models) versus not (ElevenLabs), directs users to xbrush_list_voices for obtaining a voice, and explains the asynchronous workflow with 'poll the returned request_id with xbrush_get_request.' This provides clear when-to-use and prerequisite context beyond mere tool naming.

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

xbrush_video_extendExtend VideoA

Extend an existing video by generating additional seconds of motion. Submits async — poll the returned request_id with xbrush_get_request.

Args: model (string, required): Extend model (e.g. ltx-2.3-extend, pixverse-v6-extend). See xbrush_list_models(category='video'), featureType 'extend'. video_url (string, required): URL of the source video to extend. duration (number, required): Seconds of new video to append (1-20).

ParametersJSON Schema
NameRequiredDescriptionDefault
modelYesVideo-extend model (e.g. ltx-2.3-extend, pixverse-v6-extend). Use xbrush_list_models(category='video') and pick a model whose featureType is 'extend'.
durationYesSeconds of new video to append (1-20).
video_urlYesURL of the source video to extend.

TDQS

A4.3/5.0
Behavior4/5

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

The description adds meaningful behavioral context beyond the annotations: it discloses the asynchronous nature and the polling mechanism, which is critical for the agent. It also states the effect ('generating additional seconds of motion'), consistent with readOnlyHint=false. The description complements the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a one-sentence purpose, a one-sentence async note, and a compact argument list. Every sentence earns its place, with no redundancy or fluff.

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 description is complete for a tool with three required parameters and no output schema. It explains the async workflow and explicitly directs the agent to xbrush_get_request for polling, which is essential. The model-selection hint and duration range cover the key usage details. Given the moderate complexity, nothing critical 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 description coverage is 100%, so the baseline is 3. The description repeats the parameter details but adds marginal value with example model names and a direct pointer to xbrush_list_models. Since the schema already documents ranges and formats, the description does not significantly enhance parameter understanding beyond the schema.

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?

The description clearly states the tool's function: 'Extend an existing video by generating additional seconds of motion.' This uses a specific verb ('extend') and resource ('existing video'), and the scope is well-defined. It naturally distinguishes from siblings like xbrush_video_generate, xbrush_video_upscale, and xbrush_video_retake.

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 provides clear usage context by noting that the tool 'Submits async — poll the returned request_id with xbrush_get_request,' which tells the agent what to do after invocation. It also gives model selection guidance via 'See xbrush_list_models(category='video'), featureType 'extend'.' However, it does not explicitly contrast with alternatives like video_generate or video_upscale, so it lacks explicit when-not-to-use guidance.

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

xbrush_video_generateGenerate VideoA

Generate a video from a start image, a text prompt, and/or reference images (reference-to-video). Submits async — poll the returned request_id with xbrush_get_request (typical wait 2-10 min).

Args: model (string, required): Video model ID (e.g. kling-v3-pro, kling-o3, veo3.1, seedance-2.0, hailuo-02-pro, wan-2.7-video). Use xbrush_list_models(category='video') — entries include per-model duration constraints. image_url (string, optional): Start image (first frame) for image-to-video. Not needed for text-to-video or reference-to-video. image_urls (array, optional): Reference images for reference-to-video models (seedance-2.0/-fast). Each item is a URL string OR an object {url, role} where role is first_frame/last_frame/reference_image — so one call can combine a start frame, an end frame, and subject references. NUMBERING: in prompt/idea, @ImageN = the N-th item here by 1-based ARRAY POSITION, counting first_frame/last_frame too (NOT 'the N-th reference'). E.g. [last_frame, reference_image] → the reference is @Image2. image_url is not required when this is set. prompt (string, optional): ENGLISH motion/action description, sent to the model as-is. Reference an image_urls item as @ImageN (N = its 1-based position in image_urls). Use 'idea' instead for non-English text. Provide prompt or idea for text-to-video. idea (string, optional): NON-English description (e.g. Korean) — the server translates it before generation. Use this instead of prompt when not writing in English. Reference an image_urls item as @ImageN (N = its 1-based position in image_urls). end_image_url (string, optional): End image (last frame), for models that support an end frame. duration (int, optional): Seconds; valid range is model-specific (e.g. seedance-2.0 4–15, kling 5/10, veo3 4–8). resolution (string, optional): Resolution tier for models that support it (seedance-2.0: 480p/720p/1080p/1440p/2160p/4k/512p/768p). Server-validated per model. aspect_ratio (string, optional): Aspect ratio for models that support it (seedance-2.0: auto/adaptive/16:9/9:16/1:1/4:3/3:4/21:9). generate_audio (bool, optional): Generate audio with the video (seedance-2.0/-fast). consistency_mode (string, optional): Reference consistency for reference-to-video (seedance-2.0/-fast): overlay/advanced/auto. prompt_relevance (float, optional): Prompt adherence (0.0-1.0).

ParametersJSON Schema
NameRequiredDescriptionDefault
ideaNoSame purpose as prompt but for NON-English text (e.g. Korean): the server translates it before sending to the model. Use 'idea' for non-English, 'prompt' for English. Reference an image_urls entry as @ImageN, where N is its 1-based position in the image_urls array (first_frame/last_frame count toward the position too). Provide prompt OR idea.
modelYesVideo model to use (e.g. kling-v3-pro, kling-o3, veo3.1, seedance-2.0, hailuo-02-pro, wan-2.7-video). Use xbrush_list_models with category='video' to see options and per-model duration constraints.
promptNoMotion/action description in ENGLISH — sent to the model as-is. Use this when writing directly in English; for any non-English text use 'idea' instead (the server translates it). Reference an image_urls entry as @ImageN, where N is its 1-based position in the image_urls array (first_frame/last_frame count toward the position too). Provide prompt OR idea (required for text-to-video when no image is supplied).
durationNoVideo duration in seconds (integer). Valid range is model-specific — e.g. kling 5 or 10, veo3 4–8, seedance-2.0 4–15 (default 5), wan-2.7 2–15. Default depends on the model; out-of-range values are rejected by the server per model.
image_urlNoURL of the start image (first frame) for image-to-video. Optional — text-to-video (prompt only) and reference-to-video (image_urls) models don't need it. The selected model decides what is required.
image_urlsNoReference images for reference-to-video models (e.g. seedance-2.0 / seedance-2.0-fast). Each element is EITHER a plain URL string OR an object {url, role} where role is 'first_frame' | 'last_frame' | 'reference_image'. The {url, role} form lets a single call combine a start frame, an end frame, and subject/style references in one list (passed through to the model as video_params.image_urls). Standalone: image_url is not required when this is set. NUMBERING (important): in prompt/idea, @Image1, @Image2, … refer to entries of THIS array by 1-based position in array order, counting EVERY entry — first_frame and last_frame included, NOT only reference_image entries. Example: image_urls=[{url, role:'last_frame'}, {url, role:'reference_image'}] → the reference is @Image2, because last_frame occupies position 1. To make a reference @Image1, place it first in the array. Ignored by models without a reference-image input.
resolutionNoOutput resolution tier for video models that support it (seedance-2.0/-fast: "480p", "720p", "1080p", "1440p", "2160p", "4k", "512p", "768p"). Server-validated per model; ignored by models that size differently. Higher tiers cost more.
aspect_ratioNoAspect ratio for video models that support it (seedance-2.0/-fast: "auto", "adaptive", "16:9", "9:16", "1:1", "4:3", "3:4", "21:9"). Server-validated per model.
end_image_urlNoURL of the end image (last frame). Creates a transition from start to end. Supported by select models (e.g. kling); ignored by models without an end-frame input such as seedance-2.0.
generate_audioNoWhether to generate audio together with the video (seedance-2.0/-fast). Default is model-specific.
consistency_modeNoSubject/reference consistency mode for reference-to-video models (seedance-2.0/-fast): "overlay", "advanced", or "auto". Controls how reference images stay consistent across frames. Server-validated; omit for the model default.
prompt_relevanceNoHow closely to follow the prompt (0.0-1.0).

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already indicate a write operation, but the description adds substantial behavioral detail: async execution, typical 2-10 minute wait, server-validated per-model constraints, ignored parameters for unsupported models, and the translation behavior for non-English text. This goes well beyond 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 description is front-loaded with the core purpose and async behavior before the Args block. It is long but justified by 12 parameters and complex reference-image semantics; every sentence contributes, though there is some redundancy with the schema descriptions.

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?

Given the tool's complexity and the absence of an output schema, the description covers all necessary invocation context: return of request_id, polling workflow, model selection, prompt/idea requirements, reference-image numbering, and model-specific parameter validation. It is sufficiently complete for an agent to select and call the tool correctly.

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?

Input schema coverage is 100%, and the description reinforces semantics with clarifying examples like the @ImageN numbering rule and the [last_frame, reference_image] -> @Image2 case. It also explains model-specific duration and resolution ranges. It does not quite reach 5 because much of the parameter text mirrors the schema's own descriptions.

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?

The description opens with a specific verb+resource: 'Generate a video from a start image, a text prompt, and/or reference images (reference-to-video).' It clearly defines the tool's scope and differentiates it from siblings like video_upscale, video_extend, and video_retake by emphasizing generation from inputs rather than post-processing.

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?

Provides clear context for when to use this tool: async submission, polling with xbrush_get_request, model selection via xbrush_list_models, and the distinction between prompt (English) and idea (non-English). It stops short of explicitly naming alternative tools or excluding them, so it misses a 5.

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

xbrush_video_lip_syncLip-sync VideoA

Sync a face to speech: either a face VIDEO (pixverse-lipsync, infinite-talk) or a still portrait PHOTO animated as a talking head (fabric-1.0, fabric-1.0-fast). Speech comes from audio_url, or from built-in TTS via text + voice_id. Submits async — lip-sync generation can take 30s to several minutes. Poll with xbrush_get_request.

Args: video_url (string): Face video URL — video-driven models. Provide this OR image_url. image_url (string): Still portrait URL — talking photo (fabric-1.0/-fast). audio_url (string): Audio URL to drive the mouth movement. Or use text + voice_id. text (string): Text to speak via built-in TTS (with voice_id from xbrush_list_voices). voice_id (string): TTS voice for text. duration (number, optional): Output seconds (1-60). resolution (string, optional): "480p" or "720p" (720p costs more). model (string, optional): Lip-sync model ID; which inputs are required is model-specific.

ParametersJSON Schema
NameRequiredDescriptionDefault
textNoText to speak via built-in TTS instead of audio_url (use with voice_id; see xbrush_list_voices).
modelNoLip-sync model ID: pixverse-lipsync / infinite-talk (video input), fabric-1.0 / fabric-1.0-fast (still-photo input, 'talking photo'). Defaults to the server's default model.
durationNoOutput duration in seconds (1-60). Model default if omitted.
voice_idNoVoice for built-in TTS when using text (from xbrush_list_voices).
audio_urlNoURL of the speech audio to lip-sync. Alternative: text + voice_id (built-in TTS).
image_urlNoURL of a still portrait photo to animate — talking photo (fabric-1.0/-fast). Provide video_url OR image_url.
video_urlNoURL of the source face video (video-driven models). Provide video_url OR image_url.
resolutionNoOutput resolution tier — currently "480p" or "720p" (higher costs more; e.g. fabric-1.0 480p 0.104 vs 720p 0.195 credits/sec). Server-validated.

TDQS

A4/5.0
Behavior4/5

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

The description discloses crucial behavioral traits not captured by the generic annotations: 'Submits async — lip-sync generation can take 30s to several minutes' and directs users to poll with xbrush_get_request. It also surfaces model-specific input requirements and resolution cost implications, adding real operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The introductory paragraph is tightly written and front-loads the core purpose and async behavior. However, the following Args block repeats the input schema's property descriptions almost verbatim for all eight parameters, making the overall description longer than necessary despite being well-organized.

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

Completeness4/5

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

For a tool with eight parameters, multiple input alternatives, and asynchronous behavior, the description covers a great deal: input modes, speech sources, polling, cost tiers, and model-specific caveats. It stops short of stating explicit mutual-exclusion rules (e.g., 'exactly one of video_url/image_url required') and omits any output/return format, though the lack of an output schema lowers that burden.

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%, and the schema already describes each parameter in detail, including the video/image OR constraint and model groupings. The Args section in the description largely duplicates these schema descriptions, contributing little new parameter-level meaning beyond the minor note that required inputs are model-specific.

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?

The description opens with 'Sync a face to speech' and immediately distinguishes the two input modes: face video (pixverse-lipsync, infinite-talk) vs. still portrait (fabric-1.0/-fast). It also names speech sources (audio_url or built-in TTS), making the tool's scope unmistakable and distinct from siblings like xbrush_video_generate or xbrush_tts_generate.

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 clear when-to-use guidance by explaining the video vs. photo branches, the audio vs. TTS branches, and the model-specific input requirements. It also advises polling with xbrush_get_request. However, it does not explicitly mention alternative sibling tools or state when not to use this tool, so it lacks full exclusion guidance.

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

xbrush_video_retakeRetake VideoA

Regenerate (retake) a video up to a given timestamp, producing a new variation. Submits async — poll the returned request_id with xbrush_get_request.

Args: model (string, required): Retake model (e.g. ltx-2.3-retake). See xbrush_list_models(category='video'), featureType 'retake'. video_url (string, required): URL of the source video to retake. end_time (number, required): Timestamp in seconds (>= 0) up to which to regenerate.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelYesVideo-retake model (e.g. ltx-2.3-retake). Use xbrush_list_models(category='video') and pick a model whose featureType is 'retake'.
end_timeYesTimestamp in seconds (>= 0) up to which the video is regenerated into a new variation.
video_urlYesURL of the source video to retake.

TDQS

A4.2/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false and openWorldHint=true, so the mutation is expected. The description adds valuable behavioral context by stating 'Submits async — poll the returned request_id with xbrush_get_request,' which is essential for the agent to know the tool is non-blocking and how to retrieve the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a one-sentence purpose, a brief async note, and a clean Args list. Every sentence earns its place, and the most important operational detail (async + request_id) is front-loaded.

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

Completeness4/5

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

Given there is no output schema, the description does enough by mentioning the returned request_id and how to poll. It covers all three parameters and the async behavior. It could add what the final output will look like, but the pointer to xbrush_get_request sufficiently bridges that gap.

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?

The input schema has 100% description coverage, so the description adds little beyond what the schema already states. It does provide a concrete model example (ltx-2.3-retake) and points to xbrush_list_models, but this is also present in the schema. There is no significant extra meaning added.

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?

The description clearly states the action: 'Regenerate (retake) a video up to a given timestamp, producing a new variation.' It specifies the resource (video) and the operation (retake), and the timestamp constraint distinguishes it from related video tools like generate, extend, or upscale.

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 clear context for use: you retake a video up to a given timestamp, and it explicitly notes the async workflow with xbrush_get_request. It also points to xbrush_list_models for selecting the right model, but it does not explicitly list exclusions or tell when not to use this tool versus alternatives.

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

xbrush_video_upscaleUpscale VideoA

Upscale a video to higher resolution. Submits async — poll the returned request_id with xbrush_get_request.

Args: video_url (string, required): URL of the video to upscale. scale (int, required): Upscale multiplier (2 or 4). model (string, optional): Model ID (e.g. realesrgan, seedvr).

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoUpscale model ID (e.g. realesrgan, seedvr). Server default if omitted.
scaleYesUpscale multiplier (e.g. 2 or 4). Required.
video_urlYesURL of the video to upscale.

TDQS

A4.2/5.0
Behavior4/5

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

The description reveals a key behavioral trait: 'Submits async — poll the returned request_id with xbrush_get_request.' This goes beyond the annotations (which only indicate non-read-only, non-destructive, open-world) by explaining the asynchronous workflow and how to retrieve results. This is meaningful behavioral context not present in 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: one purpose sentence, one async note, and a compact Args list. Every sentence is informative, no filler, and front-loaded with the main purpose. This is an ideal length and structure for agent consumption.

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

Completeness4/5

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

The description covers the main workflow (submit async, poll with xbrush_get_request) and all required parameters are explained. It doesn't mention limitations like supported video formats or file size constraints, but for a simple 3-parameter tool with annotations and a complete schema, it provides enough context for an agent to invoke it correctly.

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 repeats the parameter details (e.g., 'scale (int, required): Upscale multiplier (2 or 4)') but adds no new semantics beyond what the schema already provides. It doesn't clarify format requirements or edge cases that the schema doesn't cover.

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?

The description states 'Upscale a video to higher resolution' with a specific verb and resource. It clearly distinguishes this tool from siblings like xbrush_image_upscale and video generation tools by focusing on video upscaling, and the async mention further clarifies its specific role.

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 a clear usage context: 'Upscale a video to higher resolution' and instructs to 'poll the returned request_id with xbrush_get_request', which is actionable. However, it doesn't explicitly state when not to use this tool versus alternatives like xbrush_video_generate, though the resource (video vs image) and action (upscale vs generate) make it implicit.

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

xbrush_watermark_addAdd WatermarkA

Apply the XBrush watermark to a target image or video. The watermark content is fixed by the server — no customization is accepted. Submits async — poll the returned request_id with xbrush_get_request.

Args: image_url (string, optional): Target image URL. video_url (string, optional): Target video URL (one of image_url/video_url required).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already indicate a non-read, non-destructive operation. The description adds valuable transparency by specifying the async submission behavior, that the watermark content is server-fixed, and that the response yields a request_id for polling. It does not detail side effects (e.g., whether the original is modified) but covers the key operational traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a single purpose statement, two clarifying constraints, and a clean parameter list. Every sentence adds value without redundancy.

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

Completeness4/5

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

For a simple tool with two parameters, the description covers the async workflow, the request_id polling mechanism, and the param requirement. It does not explicitly describe the result format, but given the async pattern and the presence of a polling tool, this is sufficient for an agent to invoke and follow up.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema is empty, so the description is the sole source of parameter information. It clearly defines image_url and video_url with types, optionality, and the critical constraint that exactly one is required. This fully compensates for the schema gap.

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?

The description clearly states the specific operation: 'Apply the XBrush watermark to a target image or video.' This uses a strong verb ('apply') and explicit resources (image/video), making it distinct from sibling tools like generate, upscale, or remove_bg.

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?

Provides usage context by explaining the async workflow ('poll the returned request_id with xbrush_get_request') and the limitation that the watermark is fixed with no customization, implicitly guiding against use for custom watermark needs. However, it does not explicitly contrast with alternatives or state when to prefer this tool over others.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 21 tool updatesv2.8.0
    • First observedxbrush_chat
    • First observedxbrush_check_health
    • First observedxbrush_content_moderate
    • First observedxbrush_file_upload
    • First observedxbrush_get_request
    • First observedxbrush_image_edit
    • First observedxbrush_image_generate
    • First observedxbrush_image_remove_bg
    • First observedxbrush_image_upscale
    • First observedxbrush_list_models
    • First observedxbrush_list_requests
    • First observedxbrush_list_voices
    • First observedxbrush_music_generate
    • First observedxbrush_sound_effect_generate
    • First observedxbrush_tts_generate
    • First observedxbrush_video_extend
    • First observedxbrush_video_generate
    • First observedxbrush_video_lip_sync
    • First observedxbrush_video_retake
    • First observedxbrush_video_upscale
    • First observedxbrush_watermark_add

TDQS

A4.2/5.0
Disambiguation5/5

Each tool targets a distinct resource and action: image generation/edit/upscale/remove-bg, video generation/upscale/extend/retake/lip-sync, TTS/music/sound-effect generation, chat, watermarking, moderation, and request/model/file utilities. There is no significant overlap; even similar operations like video_extend and video_retake are clearly differentiated by their descriptions and parameters.

Naming Consistency4/5

All tool names share the 'xbrush_' prefix and use domain prefixes (image_, video_, tts_, etc.) for most operations, which is predictable. However, verb placement is inconsistent: some are noun_verb (image_generate, video_extend) while others are verb_noun (list_models, get_request, check_health). This minor deviation does not hinder readability but breaks a strict pattern.

Tool Count4/5

With 21 tools, the set is on the heavier side but appropriate for a multi-modal generative AI API spanning image, video, audio, text, file upload, request polling, and model listing. Each tool serves a distinct function, and the breadth justifies the count without redundancy.

Completeness5/5

The tool surface is comprehensive: it covers the full creative lifecycle including model discovery, file upload, image generation/editing/upscaling/background removal, video generation/extension/retaking/lip-sync, audio generation (TTS, music, sound effects), chat, watermarking, moderation, and request status retrieval. Async operations uniformly reference xbrush_get_request, and there are no obvious dead ends or missing critical operations.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lweight/xbrush-api-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server