An MCP server for AetherWave Studio that lets an LLM generate, edit, upscale, reframe, and background-strip images and video, create music, master audio, and browse your credit balance and gallery — all via one API key and credit pool.
Check credit balance (aetherwave_balance) before spending
Generate images (T2I/I2I) with selectable models like Grok Imagine, GPT Image 2, Ideogram V3, Z-Image Turbo, Seedream V4
Edit images with a prompt (I2I)
Upscale images with Topaz at 1x/2x/4x/8x
Remove image backgrounds (Recraft, with fal.ai BiRefNet v2 fallback)
Reframe images to a new aspect ratio (Ideogram V3, turbo/balanced/quality)
Generate video (T2V/I2V) with Grok Imagine, Wan 2.7, Veo 3.1, Kling, Seedance, Hailuo, etc.
Upscale video to 1080p or 2K (Atlas)
Remove video backgrounds frame-by-frame → transparent WebM or solid color
Reframe video to a new aspect ratio (Luma Ray 2 Flash)
Generate music with Suno (two tracks per call, optional lyrics/instrumental)
Master audio using any of 12 genre/style presets
List models/presets: image models, video models, mastering presets
List gallery creations: paginated images, videos, and audio, filterable by type or favorites
Allows generating music using Suno AI models (V3.5 to V5.5) with support for lyrics, instrumental mode, and multiple tracks per submission.
Model Context Protocol server for AetherWave Studio. Drop it into any MCP-compatible client (Claude Code, Cursor, Continue, Claude Desktop, custom agents) and your LLM can generate, edit, upscale, reframe, and master across every flagship creative AI provider through one API key, one credit pool.
One install. One token. Thirty-one default tools covering:
Music - Suno V3.5 / V4 / V4.5 / V5 / V5.5
Image gen - Grok Imagine, GPT Image 2, Seedream V4, Wan 2.7, Imagen 4, Nano Banana, Ideogram V3, Z-Image Turbo
Image edit - Grok Imagine I2I, Seedream V4 Edit, Flux Kontext, Wan 2.5 Spicy, Qwen Edit, Midjourney I2I, GPT Image 1.5
Image utility - Topaz upscale, Recraft background removal (with fal BiRefNet v2 fallback), Ideogram V3 Reframe
Video - Grok Imagine (KIE+fal fallback), Wan 2.7, Hailuo 02, Seedance Pro/Lite, Kling 2.6 (audio), VEO 3.1, Happy Horse
Video utility - Atlas upscaler (1080p/2K), rembg u2netp background removal, Luma Ray 2 Flash reframe
Audio mastering - 12 genre/style presets via the AetherWave Python service
Gallery read - paginated list of your saved creations
Comic books - 9 tools driving the AetherWave Graphic Novel Engine end to end: cast, character references, script, panels, lettered pages, and a PDF / EPUB / CBZ download link
Merch - 4 tools: garment catalog, design-to-mockup, and (with PRINTFUL_API_TOKEN) 2 more that create and list products in your own Printful store, plus 1 admin shop-listing tool
Every generation tool submits the job and waits up to a soft 45 s deadline for the result. Fast jobs come back with the final URL in one round-trip; anything longer returns state: "running" with a taskId, and aetherwave_get_job covers every pipeline (image, video, music, mastering, comics, merch) for polling. Pass async: true on any tool to return immediately. Results auto-save to your Cloudflare R2 gallery so URLs don't expire.
The comic tools are built around this from the start: a book takes about an hour to draw, so each slow step starts and returns at once, and aetherwave_comic_status is how the agent checks back. See Make a comic book with the MCP.
# 1. Get a key at https://aetherwavestudio.com/profile (Developer tab)
# 2. Add to your MCP client config (see below)
# 3. Restart the client
# 4. Ask your agent to "generate a synthwave album cover, then animate it"claude mcp add aetherwave \
-e AETHERWAVE_API_KEY=aw_live_your_key_here \
-- npx -y @aetherwave-studio/mcpEdit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"aetherwave": {
"command": "npx",
"args": ["-y", "@aetherwave-studio/mcp"],
"env": {
"AETHERWAVE_API_KEY": "aw_live_..."
}
}
}
}Restart Claude Desktop.
In Cursor Settings -> MCP -> Add new server:
{
"aetherwave": {
"command": "npx",
"args": ["-y", "@aetherwave-studio/mcp"],
"env": { "AETHERWAVE_API_KEY": "aw_live_..." }
}
}In your ~/.continue/config.yaml:
mcpServers:
- name: aetherwave
command: npx
args: ["-y", "@aetherwave-studio/mcp"]
env:
AETHERWAVE_API_KEY: aw_live_...Standard stdio MCP server. Any client that speaks JSON-RPC 2.0 over stdio per the MCP spec can connect:
AETHERWAVE_API_KEY=aw_live_... npx -y @aetherwave-studio/mcpRelated MCP server: Google Veo 3.1 MCP Server
Tool | Purpose |
| Your saved UGC characters with identity block, reference pack, voice and personality |
| Poll any job a tool handed back as |
| Current credit balance + plan |
| Enumerate every image model with cost, speed, I2I support |
| Enumerate every video model with cost-per-second, durations, resolutions |
| Enumerate the 12 mastering presets with target LUFS, tags, descriptions |
| T2I or I2I across 8+ models. Default |
| T2V or I2V across 7+ model families. Native audio, reference-image identity lock, async submit |
| Suno V5.5 by default. Two tracks per submission, lyrics + instrumental |
| I2I editing. Default |
| Topaz upscale 1x / 2x / 4x / 8x |
| Ideogram V3 Reframe to a new aspect ratio (outpaints edges) |
| Recraft primary + fal BiRefNet v2 fallback (auto failover). Output auto-saved to gallery |
| Atlas Video Upscaler, 1080p or 2K |
| Frame-by-frame bg removal via rembg u2netp. Transparent WebM or solid color output. 2 cr/sec |
| Luma Ray 2 Flash reframe to new aspect ratio |
| AI mastering across 12 genre/style presets. 20 cr/track, free on Producer / Mogul / Ultimate plans |
| Paginated gallery read for chained workflows |
| Free quote for a comic: script + panel credits for a page count |
| Create a comic project (title, premise, cast, art style). Free |
| Generate (6 cr each) or approve a character's reference image |
| Start writing the script (2-3 min, charged on use, about 40 cr for 12 pages) |
| Start drawing every undrawn panel (9 cr a panel, charged on success). Safe to call again |
| Progress, stalled runs, failed panels with reasons, page URLs, next step. Free |
| Redraw one panel, optionally with a reworded scene (9 cr on success) |
| Lay out and letter the pages (about 4 s a page). Free |
| PDF, EPUB, CBZ or bundle as a download link that lasts about a day. Free |
Every generation tool includes a model-selection rubric in its description. Your agent can pick the right model from prompt intent without round-tripping list_image_models or list_video_models.
Nine tools drive the AetherWave Graphic Novel Engine from start to finish, so an agent can turn one sentence into a finished, lettered comic. You say something like:
Make me a 12-page Franco-Belgian adventure comic about a 14-year-old courier and her grumbling mechanic uncle who fly the village's last airmail balloon over the Alps at night to deliver a letter that stops a dam from flooding their home. All ages. Keep it under 350 credits.
and the agent runs this sequence:
Step | Tool | What happens | Time | Credits |
1 |
| Confirms which account pays and that it can afford the book | instant | 0 |
2 |
| Quotes an upper bound (it assumes 4 panels a page) | instant | 0 |
3 |
| Creates the project and the cast; returns | seconds | 0 |
4 |
| Draws a full-body reference for each character, in the book's style | up to about a minute | 6 each |
5 |
| Locks the chosen image; every panel uses it to keep the face the same | seconds | 0 |
6 |
| Starts the script: chapters, pages, panels, dialogue, captions | 2-3 min | charged on use |
7 |
| Polls until | instant | 0 |
8 |
| Starts drawing every panel, one at a time; | 1.5-6 min a panel | 9 a panel, on success |
9 |
| Polls every few minutes. | instant | 0 |
10 |
| For a panel that keeps failing on a content refusal: reword its scene and redraw | 1.5-6 min | 9, on success |
11 |
| Lays out and letters every page | about 4 s a page | 0 |
12 |
| Returns a PDF (or EPUB / CBZ / bundle) download link | about 15-30 s | 0 |
"The Last Balloon Post" (2026-09-25) was made exactly this way, through the same API these tools call:
12 pages, 27 panels, 301 credits: 27 panels x 9 = 243, script 40, three character references 18. The estimate had quoted 462, because it assumes 48 panels for 12 pages. Re-quote from creditsToFinishDrawing once the script exists.
About 65 minutes of drawing, 1.5 to 6 minutes a panel, strictly one after another. About 80 minutes end to end.
9 panel failures along the way, none charged: 3 content-filter refusals, 4 upstream "Internal Error" flakes, 2 panels cut off when the server restarted. Every one was drawn on a later run.
Assembly took about 45 seconds for 12 pages. The PDF was 130 MB, which is why export returns a link rather than the file.
Approve references before writing the script. Approving re-describes the character from the picture, and the script writer reads that description. A character with no approved reference is drawn from text alone and their face drifts between panels.
Never treat a stopped run as finished. A server restart ends a drawing run silently. aetherwave_comic_status reports drawing: "stalled" whenever panels are pending or failed and no run is active. aetherwave_comic_draw is safe to call again: it draws only what is missing and never double-starts (a second start reports alreadyDrawing).
Reword, do not retry, a refused panel. failedPanels[].errorMessage in the status carries the reason. A content refusal repeats on a plain retry; aetherwave_comic_redraw_panel with a new prompt replaces the scene description for that drawing. Scenes of physical contact between an adult and a child are refused by the image filter.
Rewriting the script deletes every panel. aetherwave_comic_write_script refuses on a project that has panels unless replaceExisting: true.
Re-assemble after a redraw on a page that was already assembled; aetherwave_comic_status lists those pages under pages.staleSinceAssembly.
Only permanent images can be references. approve refuses temporary links (for example a raw provider result URL), because the book would break when the link expires.
Every comic tool result carries account: the AetherWave username that is paying. Check it if you run more than one MCP connection.
The tools above compose into something the API could not do before: hand an agent a description and get back a finished multi-shot film, starring a character you already created, with one consistent face and voice throughout.
A UGC character is a recurring on-screen person you have saved in AetherWave - their locked appearance, an approved pack of reference images, a voice and a personality. aetherwave_list_characters is how an agent discovers they exist. Without it, an agent told "shoot this with my Amy character" has no way to learn who Amy is, and invents a different face for every clip.
// 1. Discover the character. There is no other way to find them.
const { characters } = await listCharacters({ name: "amy" });
const amy = characters[0];
// 2. Build every prompt from her stored identity - VERBATIM, never paraphrased.
// Identical text is identical conditioning; that IS the consistency mechanism.
const prompt = [
shotDescription,
amy.identityBlock, // "CORE IDENTITY: same woman, Nordic, ..."
`Her speaking voice: ${amy.voiceSpec ?? amy.voiceDescriptor}`,
`She says exactly this and nothing else: "${line}"`,
].join("\n\n");
// 3. Submit async, anchored to her approved pack, with audio on.
const { taskId } = await generateVideo({
prompt,
model: "seedance-2-mini",
duration: 12,
resolution: "480p",
aspectRatio: "16:9",
generateAudio: true, // without this the clip is SILENT
referenceImages: amy.referenceImages, // NOT imageUrl - that drops the anchors
async: true, // returns in ~2s, survives the client timeout
});
// 4. Poll until the render lands.
let job;
do { await sleep(15000); job = await getJob({ taskId, kind: "video" }); }
while (!job.done && !job.error);
// 5. Repeat per shot, then assemble the clips in order.Append identityBlock verbatim to every prompt. Rewriting it in your own words breaks the lock - identical text is the whole mechanism.
Pass referenceImages, never imageUrl. A first frame switches the engine to first-frame mode and discards the anchors. When a character has an approved pack, that pack replaces the hero image rather than riding alongside it; mixing them pulls the face two ways.
Keep the voice text byte-identical across clips, for the same reason as the identity block.
Set generateAudio: true on anything with dialogue. It is off by default and free on Seedance 2.x, so a silent clip is never the cheaper choice - just a worse one.
duration is authoritative. The engine honours the seconds you ask for to within ~0.1s and then fits the line to that length by changing pace, rather than finishing early. So write the line to the clip, not the clip to the line - roughly 2 words per second is the measured working figure. A words-per-minute number in a voice description describes the character, not the engine; budgeting by it overran a 22-clip production by 35%.
Spell hard words the way they should be spoken: "super intelligence" renders more reliably than "superintelligence".
A take can come back saying the wrong words and still report success with a URL. Re-rendering an identical prompt has produced one clean take and one that dropped an entire sentence - it is per-take randomness, and nothing in the response distinguishes them. On a 22-clip production, four clips were mis-spoken and none was detectable without listening.
For anything assembled unattended, transcribe each clip and score it against the line you asked for before using it, and re-shoot the ones that fail. Checking costs nothing; the clip already cost credits. Score against the script, not against whatever the previous step handed you.
Turn any design into a print-on-demand product by asking for it:
"Make a tee that says NIGHT SHIFT in chrome letters, put it on a black Bella+Canvas 3001, show me mockups, then add it to my Printful store at $29.99."
Tool | Cost | What it does |
| free | Tees, tanks, hoodies, hats: colours, US in-stock sizes, print areas in inches, embroidery thread colours |
| 1 credit | Any image (AetherWave URL, data URL, or a local file path) becomes a transparent, trimmed print PNG. |
| 3 credits | Builds the print file at the garment's real print area and DPI, then renders Printful mockups. Refunded if the render fails; bad garment, colour or placement is never charged. 20 an hour |
| free | Checks a render that outlived the 90-second wait |
| free | Creates the product in your own Printful store |
| free | Lists your store's products |
Add your Printful token to the server's env. It is used only between your machine and api.printful.com; it never goes to AetherWave.
{
"mcpServers": {
"aetherwave": {
"command": "npx",
"args": ["-y", "@aetherwave-studio/mcp"],
"env": {
"AETHERWAVE_API_KEY": "aw_live_...",
"PRINTFUL_API_TOKEN": "your Printful private token",
"PRINTFUL_STORE_ID": "only needed for account-level tokens"
}
}
}
}Create the token in Printful under Settings > API (a private token scoped to one store is simplest). The two aetherwave_printful_* tools appear only when PRINTFUL_API_TOKEN is set, and only on the local npx server: the remote connector never asks for your store key. Products land in Printful; publishing to Shopify, Etsy and other connected channels happens there as usual.
Before you promote a product: Printful charges per order (garment, shipping, and in the US often sales tax). Check that your retail price covers it. You are the seller: only print artwork and wording you have the rights to.
Printify: coming next. Its catalog works differently (the same garment from several print providers, with their own prices and stock), so it gets its own tools rather than a half-working flag.
aetherwave_balanceReturns current credit balance. No inputs.
Returns: { credits, plan, ... }
aetherwave_list_image_modelsReturns every image model with credit cost, supported inputs, resolution/aspect options. No inputs.
Returns: { models: [...] }
aetherwave_list_video_modelsReturns every video model with per-second credit cost, durations, resolutions, aspect ratios. No inputs.
Returns: { models: [...] }
aetherwave_list_master_presetsReturns every mastering preset with target LUFS, tags, descriptions, difficulty. No inputs. Call this before master_audio when you don't know which preset fits the track.
Returns: { presets: [...] } (each: { id, name, description, target_lufs, tags, difficulty, icon })
aetherwave_generate_imageT2I or I2I. Submits, polls, returns final URLs.
Param | Type | Required | Default | Notes |
| string | yes | - | Text description of the image |
| string | no |
| Model ID. Use |
| string | no | model default | e.g. |
| string | no | model default |
|
| string[] | no | - | URLs for I2I; required if model is I2I |
| int (1-8) | no | model default | For multi-output models |
| string | no | - | Supported by some models |
| int | no | - | Deterministic generation, supported by some |
Selection signals (built into the tool description): photoreal → z-image-turbo or imagen-4. Text-in-image → ideogram-v3-t2i. NSFW → wan-2.5-spicy-t2i. Premium → grok-imagine-quality-t2i or imagen-4-ultra. Cheapest → z-image-turbo (3 cr).
Returns: { taskId, state, images, autoSaved, creationIds }
aetherwave_list_charactersYour saved UGC characters - the recurring, named people you shoot with - with everything needed to hold one consistent across a production. Call this first whenever a request names a person the user already has.
Param | Type | Required | Notes |
| string | no | Case-insensitive substring filter on name or handle. Omit to list all |
Returns: { count, characters[], usage }, each character carrying:
Field | Why it matters |
| The locked CORE IDENTITY string. Append verbatim to every prompt |
| The approved pack. Pass as |
| True when a pack exists - prefer it over |
| Single fallback anchor for characters with no pack |
| Voice conditioning text; keep byte-identical across clips |
| Tones, quirks, speechStyle - the tonal direction the user wrote |
| The character's negative prompt |
| Per-mode reference strengths |
MCP clients (claude.ai, Claude Desktop, Cursor) abandon a tool call at about 60 seconds. Before 0.3.0 every long tool blocked for 6 to 15 minutes, so a 90-second image render "failed" on the client while the job finished and was charged, and the taskId died with the abandoned call.
Now every tool that submits a job (generate_image, edit_image, upscale_image, reframe_image, remove_background, generate_video, upscale_video, reframe_video, remove_background_video, generate_music, merch_mockup, comic_export) polls for at most ~45 seconds and then returns:
{ "state": "running", "taskId": "…", "kind": "image", "checkWith": "aetherwave_get_job", "pollEverySeconds": 10, "next": "…" }Poll aetherwave_get_job with that taskId and kind until done. Two explicit escapes on each of those tools:
Arg | Effect |
| Submit and return the taskId immediately, no polling |
| The old long block (6-15 min budget). Only if your client permits calls over 60 s |
master_audio has no job id (the request itself is the job): it also returns within ~45 s, and a master that outlives the call is saved to the gallery - find it with aetherwave_list_my_creations type audio rather than resubmitting.
aetherwave_get_jobCheck a job by taskId. Use it for any state: "running" result, after an async: true submit, or to recover any generation whose call timed out, since the job keeps running server-side and saves to your gallery regardless of what happened to the client.
Param | Type | Required | Notes |
| string | yes | The taskId (or taskKey / exportId) a tool returned |
| enum | yes |
|
| string | for | The comic project the export belongs to |
Returns: { taskId, kind, state, done, failed, videoUrl, imageUrls, tracks, mockups, downloadUrl, autoSaved, creationIds, error, next, raw }
aetherwave_generate_videoT2V or I2V. Submits, polls for up to ~45 s, and returns the URL if the render finished - otherwise state: "running" with the taskId (video takes 1-8 min, so that is the usual case).
Param | Type | Required | Default | Notes |
| string | yes | - | Text description of the scene |
| string | no |
| Model ID. Use |
| int (2-30) | no | model default | Seconds. Grok accepts 6-15 |
| enum | no | model default |
|
| string | no | model default | e.g. |
| string | no | - | Required for I2V models |
| string | no | - | Some I2V models support first+last frame |
| enum | no |
| Grok Imagine: |
| bool | no |
| Render speech/sound with the video. Clips are SILENT without it. Free on Seedance 2.x at every resolution |
| string[] (max 9) | no | - | Identity anchors held consistent across the clip. Mutually exclusive with |
| bool | no |
| Return a |
| bool | no |
| Block up to 8 min. Only if your client permits calls over 60 s |
Returns (finished): { taskId, state, videoUrl, fallbackProvider, autoSaved, creationId, kieTaskId }
Returns (still rendering, or async): { state: "running", taskId, kind: "video", checkWith, pollEverySeconds, next }
A render takes 1-8 minutes and most MCP clients abandon a call at 60 seconds (
MCP error -32001), so this tool returnsstate: "running"within ~45 s and you pollaetherwave_get_job. The job itself is submitted, billed and saved to your gallery regardless of what the client does.
⚠️
imageUrlandreferenceImagesare not additive. A supplied first frame switches the engine to first-frame mode exclusively and drops the reference images - which silently disables the only no-drift mechanism available. Passing both is rejected with an explicit error rather than quietly honouring one.
aetherwave_generate_musicSuno music generation. Two tracks per submission.
Param | Type | Required | Default | Notes |
| string | yes | - | Style/mood/topic description |
| boolean | no |
| If true, no vocals |
| enum | no |
|
|
| string | no | - | Optional title for the tracks |
| string | no | - | Custom lyrics, omit to let Suno write them |
Returns: { taskId, status, tracks }
aetherwave_edit_imageI2I editing guided by a text prompt.
Param | Type | Required | Default | Notes |
| string | yes | - | Text description of the edit |
| string | yes | - | Public URL of source image |
| string | no |
| 3 cr/image effective, 2 outputs |
| string | no | source ratio | e.g. |
| string | no | model default | Some models: |
| enum | no | model default |
|
| int (1-8) | no | - | For multi-output models |
| enum | no | model default |
|
| string | no | - | Supported by some models |
Selection signals: subtle edits / character consistency → flux-kontext-pro. NSFW → wan-2.5-spicy-i2i. Highest quality → gpt-image-1.5-i2i or grok-imagine-quality-i2i. Stylized → midjourney-i2i. Single-output / 4K → seedream-v4-edit.
URL gotcha: source URLs with spaces or parentheses may fail upstream. Prefer clean URLs without special characters.
Returns: { taskId, state, images, autoSaved, creationIds }
aetherwave_upscale_imageTopaz upscaler.
Param | Type | Required | Default | Notes |
| string | yes | - | Public URL of source image |
| enum | no |
|
|
Credit cost scales with source resolution × factor.
Returns: { taskId, state, images, autoSaved, creationIds }
aetherwave_reframe_imageIdeogram V3 Reframe. Outpaints edges to fit a new aspect ratio.
Param | Type | Required | Default | Notes |
| string | yes | - | Public URL of source image |
| string | yes | - | Target ratio: |
| enum | no |
|
|
Returns: { taskId, state, images, autoSaved, creationIds }
aetherwave_remove_backgroundRecraft primary + fal.ai BiRefNet v2 fallback. ~5 cr per image.
Param | Type | Required | Default | Notes |
| string | yes | - | Public URL of source image |
Returns: { taskId, state, images } (PNG with transparent alpha)
aetherwave_upscale_videoAtlas Video Upscaler. Targets 1080p or 2K.
Param | Type | Required | Default | Notes |
| string | yes | - | Public URL of source video (MP4) |
| enum | no |
|
|
Returns: { taskId, status, videoUrl, autoSaved, creationId }
aetherwave_remove_background_videoFrame-by-frame background removal via rembg u2netp on AetherWave's Python service. 2 cr/sec.
Param | Type | Required | Default | Notes |
| string | yes | - | Public URL of source video (MP4) |
| enum | no |
|
|
| string | no |
| Hex color for solid replacement when |
Returns: { taskId, status, videoUrl, autoSaved, creationId }
aetherwave_reframe_videoLuma Ray 2 Flash reframe to a new aspect ratio. 17 cr/sec.
Param | Type | Required | Default | Notes |
| string | yes | - | Public URL of source video (MP4) |
| enum | yes | - |
|
| string | no | - | Optional steering prompt for new edge content (e.g. "extend the sky with sunset clouds") |
Returns: { taskId, status, videoUrl, autoSaved, creationId }
aetherwave_master_audioAI mastering via the AetherWave Python service. Synchronous response (route polls internally, expect 30s-5min). 20 credits per track. Free for Producer, Mogul, and Ultimate plans. Output is WAV (~50MB per 3-min track) and auto-rehosted to Cloudflare R2.
Param | Type | Required | Default | Notes |
| string | yes | - | Public URL to MP3 or WAV |
| string | yes | - | One of 12 (see below) |
| string | no | - | Optional title for gallery row |
Preset list (12, retrieved live from /api/master-presets):
Preset | Name | Target LUFS | Use for |
| Streaming Ready | -14 | Spotify, Apple Music, YouTube |
| Loud & Punchy | -9 | Competitive loudness |
| Gentle Touch | -16 | Acoustic, classical, jazz |
| Hip Hop / Trap | -11 | Heavy low + crisp highs + 808s |
| EDM / Electronic | -10 | House, techno, dubstep, drops |
| Pop / Top 40 | -12 | Radio-ready polish |
| Rock / Alternative | -12 | Punchy mids, gritty edge |
| Lo-Fi / Chill | -14 | Warm, relaxed |
| R&B / Soul | -13 | |
| Acoustic / Folk | -16 | Preserves dynamics |
| Cinematic / Orchestral | -18 | Wide dynamics |
| Podcast / Voice | -16 | Voice-forward |
Returns: { success, masteredUrl, preset, trackTitle, creditsCharged, isFree }
aetherwave_list_my_creationsPaginated gallery read. Useful for chaining ("reframe my last 5 images to 9:16").
Param | Type | Required | Default | Notes |
| enum | no | all |
|
| int (1-500) | no | 100 | Max items |
| int | no | 0 | Pagination offset |
| boolean | no |
| Filter to favorites |
Returns: { items, total, offset, limit, hasMore }. Each item: { id, type, title, prompt, model, createdAt, isFavorite, contentUrl, thumbnailUrl, visibility, rating, duration?, width?, height?, likeCount, totalPlays, metadata }.
All nine wrap the /api/graphic-novel/* routes the Graphic Novel Studio web app uses, so a book made through the MCP opens in the studio and the reverse. Every result includes account, the username that is billed.
aetherwave_comic_estimateFree upper-bound quote. Assumes 4 panels a page, so short books usually cost less (12 pages: quoted 462, cost 301).
Param | Type | Required | Default | Notes |
| int (4-64) | yes | - | The studio offers 12, 16, 24, 32, 48, 64 |
| enum | no |
|
|
Returns: { account, scriptCredits, panelCredits, assumedPanels, creditsPerPanel, totalCredits, imageModel, note }
aetherwave_comic_createCreates the project and its cast. Free. Nothing is generated yet.
Param | Type | Required | Default | Notes |
| string | yes | - | Painted into the cover panel |
| string | yes | - | The situation, goal and stakes |
| array (1-12) | yes | - | Each |
| enum | no |
|
|
| enum | no |
|
|
| enum | no |
|
|
| int (4-64) | no | 24 | Target pages |
| enum | no |
| As above. Locked once created |
| string | no | - | Places, era, landmarks. Every panel prompt includes it |
| string | no | - | Steer the script writer |
| string[] | no | - | Comics or films to evoke |
| enum | no |
|
|
| enum | no |
| Balloon style: |
Returns: { account, projectId, status, characters: [{ characterId, name, role }], estimate, nextStep }
aetherwave_comic_character_referenceaction: "generate" draws count (1-4) full-body references in the book's style, 6 credits each, and adds them to the character's options. editPrompt alone steers a fresh drawing; editPrompt with baseUrl (one of the character's images) edits that image and keeps the same person. If the call runs past about 50 seconds the images still land server-side and show up in aetherwave_comic_status.
action: "approve" (free) sets imageUrl as the reference. Only the character's own images or permanent AetherWave storage (media.aetherwavestudio.com) are accepted.
Param | Type | Required | Default | Notes |
| string | yes | - | |
| enum | yes | - |
|
| string | one of | - | Name is matched without case |
| int (1-4) | no | 1 | generate |
| string (max 500) | no | - | generate |
| URL | no | - | generate; needs |
| URL | approve | - |
Returns (generate): { account, characterId, characterName, newImages, creditsCharged, stillGenerating, errors, referenceOptions, nextStep }. Returns (approve): { account, approved, characterId, characterName, referenceImageUrl }
aetherwave_comic_write_scriptStarts the script and returns. About 2 to 3 minutes; charged on actual use when it finishes (40 credits for the 12-page book). Refuses on a project that already has panels unless replaceExisting: true, because a new script deletes them all.
Param | Type | Required | Default | Notes |
| string | yes | - | |
| boolean | no |
| Required to rewrite a script that already has panels |
Returns: { account, started, status, message, warning?, nextStep }. warning names characters with no approved reference.
aetherwave_comic_drawaction: "start" (default) starts drawing every pending or failed panel, one at a time, and returns. 9 credits a panel, charged only on success; the balance must cover the whole run to start. Calling it while a run is active starts nothing and reports alreadyDrawing. action: "stop" asks the active run to stop after its current panel.
Param | Type | Required | Default | Notes |
| string | yes | - | |
| enum | no |
|
|
| int | no | - | start: refuse if the remaining panels would cost more |
Returns: { account, started, panelsQueued, creditsPerPanel, upToCredits, message, expectedMinutes, nextStep }, or { started: false, alreadyDrawing: true }
aetherwave_comic_statusFree. The one tool to poll. With no projectId it lists your recent comic projects.
Param | Type | Required | Default | Notes |
| string | no | - | Omit to list projects |
| enum | no |
|
|
Returns: { account, projectId, title, projectStatus, projectError, drawing, drawingDetail, panels: { total, completed, failed, pending, generating, batchRunning }, creditsToFinishDrawing, failedPanels: [{ panelId, page, panelIndex, errorMessage, scene }], pages: { total, assembled, missing, staleSinceAssembly, urls }, characters: [{ characterId, name, role, approvedReference, referenceOptions }], nextStep }
drawing is one of no_script, not_started, drawing, redrawing, stalled, done. stalled means panels are pending or failed and no run is active; call aetherwave_comic_draw again.
aetherwave_comic_redraw_panelRedraws one panel. 9 credits on success, nothing on failure. prompt replaces the panel's scene description for this drawing (dialogue and captions are kept), which is how to get past a content refusal. Refused while a full run is active. If the redraw outlasts about 50 seconds the tool returns stillDrawing: true and the result appears in aetherwave_comic_status.
Param | Type | Required | Default | Notes |
| string | yes | - | |
| string | yes | - | From |
| string (max 4000) | no | - | New scene description |
Returns: { account, redrawn, panelId, status, imageUrl }, { redrawn: false, stillDrawing: true }, or a refusal carrying the panel's errorMessage
aetherwave_comic_assembleFree. Lays out and letters every page, about 4 seconds a page, and returns at once. Refuses while panels are drawing, and refuses while any panel is undrawn unless allowPartial: true (pages with an undrawn panel are skipped and the book is marked pages-partial).
Param | Type | Required | Default | Notes |
| string | yes | - | |
| boolean | no |
| Assemble the complete pages anyway |
Returns: { account, started, pages, message, nextStep }
aetherwave_comic_exportFree. Builds the assembled book and returns a download link on AetherWave storage that lasts about a day. Usually finishes within the call (a 12-page PDF took about 15 seconds to build and upload in testing); otherwise it returns an exportId to check with a second call. One export builds per account at a time: if one is already building, the tool reports that one (alreadyExporting: true, with its projectId) instead of starting another. When the service is busy it refuses with retryAfterSeconds.
Param | Type | Required | Default | Notes |
| string | yes | - | |
| enum | no |
|
|
| boolean | no |
| Append the project's promotional back pages if turned on |
| string | no | - | Check an export started earlier |
Returns: { account, exportId, format, status, url, megabytes, note }. status is building, complete or error.
AetherWave uses a single credit pool. Buy bundles starting at $4.99 / 500 credits (bundle credits never expire) or subscribe to Studio ($9.99/mo, 1,700 credits, 3-day free trial). Both work for API calls.
Typical costs:
Image gen - 3 cr (Z-Image Turbo) to 22 cr (Grok Imagine Quality at 2K)
Image edit - 3 cr/image (Grok Imagine I2I) to 22 cr (Grok Imagine Quality I2I at 2K)
Image utility - 5 cr (background removal, reframe at turbo speed), 5-25+ cr (Topaz upscale, resolution-dependent)
Video - 4-6 cr/sec (Grok Imagine) up to ~80 cr/sec (VEO 3.1)
Music - 12 cr per generation (2 tracks)
Mastering - 20 cr/track (free on Producer / Mogul / Ultimate)
Comic books - 9 cr a panel (charged on success), 6 cr a character reference, script charged on use (about 40 cr for 12 pages). A 12-page, 27-panel book cost 301 cr
See live pricing at https://aetherwavestudio.com/buy-credits or via aetherwave_list_*_models.
Variable | Required | Default | Description |
| yes | - | Your API key. Get one at /profile -> Developer tab. Must start with |
| no |
| Override the API base URL (useful for staging or self-hosted). |
"AETHERWAVE_API_KEY environment variable is required"
Your MCP client isn't passing the env var. Make sure the env block in your client config has AETHERWAVE_API_KEY set. After editing config, fully restart the client.
"AetherWave API ... failed: 401 - Invalid API key" The key has been revoked or regenerated. Visit https://aetherwavestudio.com/profile -> Developer tab and copy a fresh key.
"AetherWave API ... failed: 402 - Insufficient credits"
Your balance is too low for the requested operation. Call aetherwave_balance to confirm, then top up at https://aetherwavestudio.com/buy-credits.
"AetherWave generation timed out after Xs"
The provider is queueing. The job may still complete server-side - check the AetherWave gallery at https://aetherwavestudio.com/gallery.html. If timeouts persist for a particular model, try a different one (e.g. switch from grok-imagine-t2v to wan-2-7-t2v, or gpt-image-1.5-i2i to grok-imagine-i2i).
"Unprocessable Entity" on reframe Ideogram's URL fetcher chokes on source URLs containing spaces, parentheses, or other special characters. Use clean URLs (try downloading and re-uploading to a clean R2 path if needed).
"internal error, please try again later" on remove_background KIE Recraft transient outage. The tool will auto-fall-back to fal.ai BiRefNet v2 on retry, but a single call returning this error means both providers refused. Wait a minute and retry.
Comic status says drawing: "stalled"
The drawing run ended with panels left: a server restart, the balance ran out, or it was stopped. Call aetherwave_comic_draw again; it draws only the missing panels and charges only for panels that succeed.
A comic panel keeps failing with "may violate our content policies"
Retrying the same scene gets the same refusal. Reword it with aetherwave_comic_redraw_panel and a new prompt. Physical contact between an adult and a child is refused even in an all-ages book.
aetherwave_comic_export says the server "does not support export links yet"
The AetherWave server you are pointed at predates export links. Download the book from the Graphic Novel Studio in the web app.
Soul Forge band generation Not exposed via MCP. Soul Forge remains a consumer feature on the web at https://aetherwavestudio.com/soul-forge.
This package follows semver. Tools that change behavior in a breaking way will bump the major version. New tools and additive parameters bump the minor version. Bug fixes bump the patch version.
0.3.0 (2026-09-30): soft 45 s deadline on every long tool (returns state: "running" + taskId instead of timing out the client), async: true on every tool, aetherwave_get_job covers all pipelines, 9 comic tools, 4 merch tools (+2 Printful tools with PRINTFUL_API_TOKEN, +1 admin), 31 default tools.
The MCP protocol version itself (currently 2024-11-05) is negotiated at handshake time by the SDK; no client config needed.
AetherWave Studio: https://aetherwavestudio.com
Developer docs: https://aetherwavestudio.com/developers
Get an API key: https://aetherwavestudio.com/profile (Developer tab)
Buy credits: https://aetherwavestudio.com/buy-credits
MIT. See LICENSE.
Returns the current AetherWave credit balance for the API key. Use this BEFORE a generation to confirm sufficient credits, especially for video which can cost 30-300+ credits depending on model/duration/resolution.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safe-read nature is covered. The description adds useful context about video generation costs (30-300+ credits) which helps the agent anticipate financial checks. It does not describe return format, but that is less critical given the simple resource.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The main purpose is front-loaded, and the second sentence adds actionable usage guidance. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only balance tool with no output schema, the description fully covers what it does and when to use it. The cost guidance for video fills the only needed contextual gap. No missing behavior is apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline of 4 applies. The description needs to explain no parameter semantics; it correctly focuses on the return value and usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Returns the current AetherWave credit balance for the API key' with a specific verb and resource. It distinguishes from sibling generation/editing tools by focusing on a read-only balance check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Use this BEFORE a generation to confirm sufficient credits', providing a clear when-to-use context. The video cost range (30-300+ credits) further guides priority usage without needing to name alternatives, as no sibling tool offers balance checking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edits an existing image guided by a text prompt. Pass a public imageUrl plus a prompt describing the change ("add a moon to the sky", "swap the background for a neon city", "make it look like a comic panel"). Submits, polls, and returns the edited image URL(s). Default model is 'grok-imagine-i2i' (6 cr per call, returns 2 variations, ~30s, best cost-to-quality on standard edits). Other I2I-capable models: 'seedream-v4-edit', 'wan-2.5-spicy-i2i', 'flux-kontext-pro', 'qwen-image-edit', 'gpt-image-1.5-i2i' (slow, ~5min). Use list_image_models for full lineup. Note: source URLs with spaces or parentheses may fail upstream; prefer clean URLs.
Default: grok-imagine-i2i (6 cr per call, returns 2 variations = 3 cr/image effective, fast ~30s, strong general-purpose edit quality).
Pick a different model when:
Need a single deterministic output, or 4K resolution -> seedream-v4-edit (7 cr per image, supports 1K/2K/4K, multi-image up to 6)
Subtle edits / preserve composition / character consistency -> flux-kontext-pro or flux-kontext-max
NSFW edits -> wan-2.5-spicy-i2i
Highest quality, time is not a concern (~5 min OK) -> gpt-image-1.5-i2i or grok-imagine-quality-i2i (16 cr @ 1K, 22 cr @ 2K)
Stylized / artistic transformation -> midjourney-i2i
If the user simply says "edit this image" with no other signal, default to grok-imagine-i2i.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Text description of the edit (e.g. 'replace the sky with sunset clouds'). | |
| imageUrl | Yes | Public URL of the source image to edit. Must be a real, fetchable URL. | |
| model | No | Model ID. Defaults to 'grok-imagine-i2i' (3 cr/image effective, 2 outputs). Other options: 'seedream-v4-edit', 'wan-2.5-spicy-i2i', 'flux-kontext-pro', 'qwen-image-edit', 'gpt-image-1.5-i2i', 'grok-imagine-quality-i2i'. Use list_image_models for the full list. | |
| aspectRatio | No | Output aspect ratio (e.g. '1:1', '16:9'). Defaults to the source ratio for most models. | |
| resolution | No | Output resolution. Tiered-pricing models accept '1K' / '2K'. | |
| quality | No | Quality preset for models that support it (e.g. GPT Image 2). | |
| maxImages | No | Number of variations to return for multi-output models. | |
| renderingSpeed | No | Rendering speed preset for models that support it. | |
| negative_prompt | No | What to avoid in the output (supported by some models). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral details beyond annotations: 'Submits, polls, and returns the edited image URL(s)', cost (6 cr per call), number of variations (2), expected latency (~30s), and the upstream URL-spaces/parentheses failure caveat. These are not captured by the annotations, which only state readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the description adds substantial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening paragraph is front-loaded and direct, with useful examples. The model selection guide is lengthy but well-organized and earns its place given the number of model choices; a small redundancy (default model restated) prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no output schema, and a complex multi-model decision, the description is remarkably complete: it covers return values (edited image URLs), polling behavior, costs, timing, source URL constraints, and model-specific guidance. It is sufficient for an agent to select and invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds extra meaning by explaining model trade-offs (cost, speed, quality), noting that `imageUrl` must be a 'clean URL', and describing default model behavior. It doesn't deeply elaborate every parameter (e.g., `quality`, `renderingSpeed`), but it compensates beyond the schema for the most important ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Edits an existing image guided by a text prompt.' It then gives concrete examples ('add a moon to the sky', 'swap the background for a neon city') and clarifies required inputs (`imageUrl` plus `prompt`), which clearly distinguishes it from siblings like `aetherwave_generate_image` or `aetherwave_remove_background`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit model selection guide with when-to-use rules ('Need a single deterministic output... -> seedream-v4-edit', 'NSFW edits -> wan-2.5-spicy-i2i') and a default fallback ('If the user simply says "edit this image"... default to grok-imagine-i2i'). It also directs users to `list_image_models` for the full lineup, offering clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generates one or more images from a text prompt (T2I) or a text prompt + reference image(s) (I2I). Submits the job, polls until terminal, and returns the final image URLs. Default model is 'grok-imagine-t2i' (fast, 6 images per generation, 5 credits). Use list_image_models to see the full lineup with pricing. For I2I, pass referenceImages as an array of public image URLs and pick a model with I2I support (e.g. 'grok-imagine-i2i', 'wan-2.5-spicy-i2i').
Default: grok-imagine-t2i (5 cr, 6 outputs per call, fast, general purpose).
Strong recommendation: when a single high-quality output is what's wanted (most agent / one-shot workflows), prefer gpt-image-2-t2i (9 cr @ 1K / higher @ 2K, single deterministic image, best general quality across realism, illustration, typography, and composition; supports up to 2K resolution and most aspect ratios including auto). This is the front-runner for serious creative output where you don't need to pick from 6 variations.
Pick a different model when the prompt has these signals:
"single best result" / "one image" / production / no time to pick from variations -> gpt-image-2-t2i (9 cr, 1 output, top general quality)
"photoreal" / "photo of" / "realistic" -> gpt-image-2-t2i (9 cr, best general realism) or imagen-4 (12 cr, very high quality) or z-image-turbo (3 cr, fastest)
"highest quality" / "premium" / no budget -> gpt-image-2-t2i at 2K, or grok-imagine-quality-t2i (16 cr @ 1K, 22 cr @ 2K), or imagen-4-ultra
Text inside the image (signs, posters, typography) -> ideogram-v3-t2i (best in class) or gpt-image-2-t2i (also strong)
Artistic / painterly / stylized -> midjourney-t2i
Album art / cover art -> gpt-image-2-t2i for one strong image; grok-imagine-t2i for 6 variations to choose from; seedream-v4-t2i if 4K wanted
Logo or design with embedded text -> ideogram-v3-t2i
NSFW / adult / explicit -> wan-2.5-spicy-t2i (auto-tags creation as 18+; routes to adult gallery)
Cheapest possible / quick test -> z-image-turbo (3 cr)
Multiple variations to compare -> keep grok-imagine-t2i (6 outputs default) or use numImages on a multi-output model
For I2I (reference image provided): prefer the dedicated aetherwave_edit_image tool for "change something in this image" intent. Use aetherwave_generate_image with I2I models only when you specifically want style transfer (midjourney-i2i), premium quality (grok-imagine-quality-i2i), or adult content (wan-2.5-spicy-i2i).
Always pass an explicit aspectRatio (e.g. "1:1" for square album art, "16:9" for video thumbnails, "9:16" for shorts/reels). Some upstream providers reject submissions with no aspect ratio.
Ask the user only when:
The prompt contradicts itself (e.g., "highest quality but cheapest")
The user requested "the best model" with no context, surface 2-3 options with tradeoffs
A single generation would cost more than 20 credits and the user has not confirmed
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Text description of the image to generate. | |
| model | No | Model ID. Defaults to 'grok-imagine-t2i'. Use list_image_models for the full list. | |
| aspectRatio | No | Aspect ratio (e.g. '1:1', '16:9', '9:16'). Pass this explicitly when possible; some upstream providers reject submissions without an aspect ratio. Default ratios vary by model. | |
| resolution | No | Output resolution. Most models accept '1K' or '2K'; some accept '480p'/'720p'. | |
| referenceImages | No | Array of public image URLs for image-to-image generation. Required when using an I2I model. A single URL string is also accepted (wrapped as a one-element array). | |
| numImages | No | Number of images for models that support multiple outputs. | |
| negative_prompt | No | What to avoid in the output (supported by some models). | |
| seed | No | Seed for deterministic generation (supported by some models). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by disclosing job submission/polling, credit costs, output counts, adult-content routing, and provider aspect-ratio requirements. The description is consistent with readOnlyHint=false and destructiveHint=false, so there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but appropriately structured: front-loaded purpose, then model selection guide, I2I alternatives, and user-confirmation conditions. Every section earns its place given the tool's complexity and 8 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description explains the return value (final image URLs), job lifecycle, credit costs, and when to ask for user input. This is a complete and actionable description for a complex generative media tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds meaningful context: default model behavior, model selection guide, explicit aspectRatio advice, referenceImages single-URL convenience, and numImages usage. It does not add much for seed or negative_prompt, but those are already well-described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates one or more images from text (T2I) or text plus reference image(s) (I2I), and explains the job lifecycle (submit, poll, return URLs). It distinguishes itself from sibling tools like aetherwave_edit_image and other media generation tools by explicitly covering image generation and model selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance: prefer aetherwave_edit_image for editing, use I2I models only for specific intents, use list_image_models for full lineup, and includes concrete model selection criteria by prompt signals. It also specifies when to ask the user for clarification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generates AI music via Suno. Returns two tracks per submission. Default model is V5.5 (newest, best quality). For instrumental output set instrumental: true. Music gen typically takes 30-90s - this tool polls with up to a 6-minute budget. Note: the title param is advisory for instrumentals - Suno often writes its own title from the prompt content for instrumental generations. Transient GENERATE_AUDIO_FAILED errors are common; retry once before degrading the model version.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Style/mood/topic description. E.g. 'Lo-fi ambient track, rain sounds, warm pads' or 'High-energy synthwave with driving bass'. | |
| instrumental | No | If true, no vocals. Default false. | |
| model | No | Suno model version. Defaults to V5_5 (current best). | |
| title | No | Optional title for the generated tracks. | |
| lyrics | No | Custom lyrics. If omitted, Suno will generate lyrics from the prompt (unless instrumental=true). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: returns two tracks, polling mechanism, common transient errors with retry advice, model version behavior. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense single paragraph with all key information, though could benefit from bullet points for improved scannability. Still efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks return value details despite no output schema. Mentions 'returns two tracks' but doesn't specify format (URLs, IDs). Polling is described but not how results are delivered. Slight gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds crucial context: instrumental activation, title advisory for instrumentals, lyrics generation fallback, model default, and prompt examples. This meaningfully supplements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Generates AI music via Suno' with a specific verb and resource. Distinguished from sibling tools like aetherwave_generate_image and aetherwave_generate_video by focusing on music generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed guidance on when to use: default model, instrumental option, timing and polling budget, error handling. While no explicit alternatives are named, the context of music generation vs other tools is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generates a short-form video from a text prompt (T2V) or a text prompt + starting image (I2V). Submits, polls, and returns the final video URL. Default model is 'grok-imagine-t2v' (fast, 4-6 cr/s, with built-in KIE -> fal.ai fallback). Use list_video_models for the full lineup with credit cost per second. I2V models (e.g. 'grok-imagine-i2v', 'seedance-pro-i2v') require a public imageUrl. Video generation can take 30s to several minutes; this tool polls with up to an 8-minute budget.
Default: grok-imagine-t2v (4-6 cr/s, fast, has KIE -> fal.ai fallback for redundancy. Best general-purpose).
Pick a different model when the prompt has these signals:
"highest quality" / "premium" / broadcast / commercial -> veo3.1-quality or veo3-quality (Google's flagship, fixed 350-560 cr for 8s, 3-5 min)
"fast premium" / quick high-quality -> veo3-fast or veo3.1-fast (84 cr fixed for 8s)
Cinematic camera moves / dolly / pan -> seedance-pro-t2v (3-10 cr/s) or kling-3.0-pro-t2v (26 cr/s)
Realistic human motion / faces -> hailuo-2.3-pro-i2v (I2V, supply imageUrl)
Talking head / lip sync -> kling-avatar-pro (23 cr/s) or infinitalk (5-17 cr/s)
Anime / stylized / fantasy -> wan-2.7-t2v
NSFW / adult -> wan-22-nsfw-i2v (I2V only; auto-tags adult)
Animate this exact image -> any I2V variant (grok-imagine-i2v, seedance-pro-i2v, hailuo-2.3-pro-i2v)
First + last frame interpolation -> seedance-pro-i2v with both imageUrl + endImageUrl
Cheapest test -> hailuo-2.0-standard @ 512p (3 cr/s, ~18 cr for 6s) or grok-imagine-t2v @ 480p (4 cr/s, ~24 cr for 6s)
Clip 12-15s -> grok-imagine-t2v (accepts up to 15s)
True 4K -> kling-3.0-4k-t2v (94 cr/s, expensive but native 4K)
Audio in generated video: grok-imagine-t2v, seedance-pro-t2v, and the VEO 3.x family include audio at base cost (no surcharge). Kling 2.6 and Kling 3.0 are the outliers — they price audio as a +50-100% surcharge (Kling 2.6 doubles the cost, Kling 3.0 Pro adds ~46%). Default to Grok / Seedance / VEO when sound matters and you don't want to think about audio pricing.
Cost framing: resolution and duration drive cost more than model choice. A 6-second 480p Grok generation costs ~24 cr; the same prompt at 1080p Seedance 2 is ~858 cr (35x more). Pick the lowest acceptable resolution + duration first.
For I2V models: imageUrl is required. For first+last-frame models, pass endImageUrl too.
Ask the user only when:
Single generation would cost more than 100 credits and they haven't confirmed
They asked for "the best" with no other signal; surface 2-3 options with cost ranges
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Text description of the video scene. | |
| model | No | Model ID. Defaults to 'grok-imagine-t2v'. Use list_video_models for the full list. | |
| duration | No | Duration in seconds. Grok Imagine accepts 6-15; other models have their own ranges (see list_video_models). | |
| resolution | No | Output resolution. Default depends on model. | |
| aspectRatio | No | Aspect ratio (e.g. '16:9', '9:16', '1:1'). | |
| imageUrl | No | Public URL of starting image. Required for I2V models. | |
| endImageUrl | No | Public URL of ending image. Supported by some I2V models (first+last frame). | |
| mode | No | Moderation mode for Grok Imagine. Defaults to 'normal'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only indicate non-read-only, open-world, non-idempotent, non-destructive), the description discloses critical behavioral traits: it submits and polls with an up-to-8-minute budget, default fallback to fal.ai, cost surcharges for audio on Kling models, and the fact that resolution/duration drive cost more than model choice. It also mentions auto-tagging for NSFW. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every section earns its place: the opening paragraph is a clear summary, and the model selection guide is well-structured with terse bullet lines. It is front-loaded with the core behavior. It could be slightly tightened by moving the cost guide elsewhere, but the structure is logical and scannable, making it more genuinely useful than verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, many model choices, no output schema), the description is remarkably complete. It explains the return value (final video URL), poll timing, model selection criteria, cost pitfalls, and when to ask the user. The absence of an output schema is compensated by the explicit mention of the returned URL and the polling behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it notes imageUrl is required for I2V models, endImageUrl is for first+last-frame models, duration constraints per model (e.g., Grok accepts 6-15s), and cost implications of resolution/duration choices. It does not systematically walk through every parameter but enriches the most decision-critical ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Generates a short-form video from a text prompt (T2V) or a text prompt + starting image (I2V).' It clearly distinguishes itself from sibling tools like aetherwave_generate_image and aetherwave_generate_music by focusing exclusively on video generation, and further clarifies T2V vs I2V modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an extensive, explicit model selection guide with concrete conditions ('highest quality', 'fast premium', 'cinematic camera moves', etc.) and names alternative models like veo3.1-quality, seedance-pro-t2v, and wan-2.7-t2v. It also states when to ask the user (e.g., cost >100 credits) and when to use list_video_models, giving clear decision boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns every image-generation model AetherWave supports, with its credit cost, default aspect ratio, supported inputs (T2I vs I2I), and any model-specific options. Call this before generate_image when you don't know the right model ID. The model key (e.g. 'grok-imagine-t2i') is what you pass as model to generate_image.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds behavioral detail about the returned fields (credit cost, aspect ratio, inputs, options) and how the model key is used downstream. It does not mention rate limits or pagination, but the tool is a simple list with zero parameters, so the added context 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The first sentence front-loads the main purpose and return fields; the second sentence gives actionable usage guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description fully covers what the tool returns, how to use it, and why it matters. It is complete for its purpose and requires no further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. The description adds value by explaining that the returned model key is what you pass to generate_image, which clarifies the connection to another tool's parameter even though this tool itself has no inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns every image-generation model AetherWave supports, listing specific fields (credit cost, aspect ratio, input types, options). It distinguishes itself from sibling tools like aetherwave_list_video_models by explicitly focusing on image models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this before generate_image when you don't know the right model ID', giving a clear when-to-use directive and tying it to a sibling tool. It also implies that generate_image is the consumer of the model key, providing practical context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns every AI mastering preset AetherWave supports, with target LUFS, tags, descriptions, and difficulty level. Call this before master_audio when you don't know which preset fits the track. 12 presets total covering streaming, hip hop, EDM, pop, rock, lo-fi, R&B, acoustic, cinematic, podcast, gentle, and loud-and-punchy mastering styles. Each preset has a target LUFS value (e.g. -14 for streaming, -9 for loud) so you can match the user's distribution target.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context about the return contents (12 presets, style coverage, LUFS examples) that goes beyond the annotations. It does not contradict the read-only nature, though it does not discuss potential rate limits or caching, which are minor for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (four sentences) and front-loaded with the primary action. Every sentence earns its place: returns what, when to use, how many and which styles, and LUFS examples. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains the return values (target LUFS, tags, descriptions, difficulty level) and provides concrete examples. It also covers usage context and breadth of presets, making it fully sufficient for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description correctly says nothing about parameters, and the empty schema needs no further explanation. No additional parameter semantics are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Returns every AI mastering preset AetherWave supports' with specific fields (target LUFS, tags, descriptions, difficulty level). It distinguishes this listing tool from the mastering tool (master_audio) and other sibling list tools by focusing on audio mastering presets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'Call this before master_audio when you don't know which preset fits the track.' This names the alternative tool and specifies the condition for use, which is exactly the level of when-to-use guidance expected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns items from the authenticated user's gallery — images, videos, audio tracks they've generated on AetherWave. Useful for agent workflows like 'find my last 5 images and reframe them all to 9:16' or 'list my recent songs and master each one'. Supports pagination and type filtering. Each item includes id, type, prompt, model, contentUrl, thumbnailUrl, createdAt, isFavorite, visibility, rating, and type-specific fields (duration for audio/video, width/height for images).
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter to a single media type. Omit for all types. | |
| limit | No | Max items to return. Defaults to 100, max 500. | |
| offset | No | Pagination offset. Defaults to 0. | |
| favoritesOnly | No | If true, only return items marked as favorite. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true), the description discloses pagination support, type filtering, and the exact fields returned including type-specific fields. This gives agents a complete picture of the return payload and behavior without an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and includes useful examples. The field list is somewhat lengthy but serves as a substitute for an output schema, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no output schema, the description sufficiently explains the return fields, filtering, and use cases. It is complete enough for an agent to invoke correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each property already documented. The description only restates that pagination and type filtering are supported, adding no extra meaning over the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns gallery items from the authenticated user, listing exact media types (images, videos, audio). It distinguishes itself from sibling generation/edit tools by being the listing tool for user creations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit example workflows ('find my last 5 images and reframe them', 'list my recent songs and master each one'), indicating when to use this tool before editing. It lacks an explicit 'when not to use' but there are no sibling listing tools, so context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns every video-generation model AetherWave supports (Grok Imagine, Wan 2.7, Hailuo 02, Seedance Pro/Lite, Kling 2.6 with audio, VEO 3.1, Happy Horse, etc.) with per-second credit cost, supported durations, resolutions, aspect ratios, and whether the model needs an input image (I2V). Call this before generate_video when you don't know the right model ID.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context by listing the exact data fields returned (credit cost, durations, resolutions, aspect ratios, I2V requirement). This goes beyond the safety hint and helps the agent anticipate the response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first sentence packs the output details and examples; the second sentence provides usage context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and no output schema, the description fully compensates by detailing both purpose and return content. It also gives usage context, making the tool self-sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has 0 parameters, so baseline is 4. The description doesn't need to explain parameters; it instead focuses on output, which is appropriate for a zero-argument tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: returning every video-generation model with specific attributes. It distinguishes itself from sibling tools like list_image_models by explicitly focusing on video models and mentioning generate_video in usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: 'Call this before generate_video when you don't know the right model ID.' This tells the agent exactly when to use the tool and implies the alternative (skip if model ID is already known).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submits an audio file for AI mastering and returns the mastered URL synchronously (route polls the Python service internally; expect 30s-5min). Useful as a final polish step after music generation. Cost: 20 credits per track. Producer, Mogul, and Ultimate plans get mastering free. Output is WAV (~50MB per 3-minute track, lossless for redistribution). Pick a preset to steer the mastering style; call aetherwave_list_master_presets for the full live list (12 presets including streaming, loud, gentle, hip_hop, edm, pop, rock, lofi, rnb, acoustic, cinematic, podcast). Each preset has a target LUFS value so you can match the distribution target.
| Name | Required | Description | Default |
|---|---|---|---|
| audioUrl | Yes | Public URL to the source audio file (MP3 or WAV). | |
| preset | Yes | Mastering preset name. Must be one of: 'streaming', 'loud', 'gentle', 'hip_hop', 'edm', 'pop', 'rock', 'lofi', 'rnb', 'acoustic', 'cinematic', 'podcast'. Call aetherwave_list_master_presets for full metadata (target LUFS, description, tags). | |
| trackTitle | No | Optional title for the mastered output (used in gallery row label). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond annotations: synchronous polling ('route polls the Python service internally; expect 30s-5min'), cost ('20 credits per track'), free plan tiers, and output specifics ('WAV (~50MB per 3-minute track, lossless for redistribution)'). These are critical operational facts not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then packs in relevant operational details (timing, cost, output, presets). While it is long, every sentence carries useful information, though it could be tightened slightly without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and 3 parameters, the description is remarkably complete: it covers synchronous behavior, latency, cost, free plans, output format and size, lossless quality, and preset guidance with a pointer to a sibling tool for the live list. The agent has enough context to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 meaning by explaining that the preset 'steer[s] the mastering style' and that each preset's target LUFS lets you 'match the distribution target,' which goes beyond the schema's mere enumeration. However, much of the parameter detail is redundant with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the action and resource: 'Submits an audio file for AI mastering and returns the mastered URL synchronously.' It distinguishes the tool from siblings by positioning it as a 'final polish step after music generation' and by referencing aetherwave_list_master_presets for preset selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context by stating it is 'Useful as a final polish step after music generation,' which implies when to use. It also gives practical constraints like audio URL requirements, expected wait time, and cost, but does not explicitly name alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reframes an image to a new aspect ratio by intelligently outpainting the edges. Pass a public imageUrl and the target aspectRatio ('16:9', '9:16', '1:1', '4:3', '3:4', etc.). Three speed tiers: 'turbo' (5 cr, fast), 'balanced' (10 cr, default), 'quality' (14 cr, slowest, best edges). Returns the reframed image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrl | Yes | Public URL of the source image. | |
| aspectRatio | Yes | Target aspect ratio (e.g. '16:9', '9:16', '1:1', '4:3', '3:4', '21:9'). | |
| speed | No | Rendering speed. 'turbo'=5cr, 'balanced'=10cr (default), 'quality'=14cr. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral details beyond annotations: it performs outpainting, has three speed tiers with specific credit costs, and returns a new image URL. It does not contradict annotations (readOnlyHint=false, etc.) and adds useful cost/performance trade-off information. Minor gaps remain about side effects or rate limits, but for a creative tool this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core purpose and then providing the essential parameter and return information. Every sentence earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 3 parameters and no output schema, the description covers the main functionality, inputs, speed/cost options, and return value. It does not mention limitations like max file size or file format restrictions, but given the openWorldHint and simple nature, the description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all three parameters with 100% description coverage, including the enum values and credit costs. The description reinforces the aspect ratio examples and speed tiers but adds no new parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Reframes') and a specific resource ('image') with a clear goal ('to a new aspect ratio'). It distinguishes itself from siblings like reframe_video and edit_image by focusing on image reframing via outpainting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (when needing to reframe an image to a new aspect ratio) and explicitly lists the required inputs and speed options. It does not explicitly name alternatives or state when not to use it, but the sibling list and specific language make the usage context obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reframes a video to a new aspect ratio by intelligently outpainting/cropping the edges. Pass a public videoUrl and target reframeAspectRatio. 17 credits per second. Optional reframePrompt lets you steer the new edge content (e.g. 'extend the sky with sunset clouds'). Returns the reframed video URL (R2-hosted).
| Name | Required | Description | Default |
|---|---|---|---|
| videoUrl | Yes | Public URL of the source video (MP4). | |
| reframeAspectRatio | Yes | Target aspect ratio. | |
| reframePrompt | No | Optional prompt to steer the new edge content. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context: cost (17 credits per second), output format (R2-hosted URL), and the outpainting/cropping mechanism. It also clarifies that the source must be a public URL. No contradiction with annotations; this is a solid disclosure of operation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary action, and every sentence adds meaningful info: operation, required inputs, optional prompt with example, cost, and return format. There is no fluff or redundancy, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description's mention of 'Returns the reframed video URL (R2-hosted)' fills that gap. It covers purpose, inputs, optional parameter, cost, and output. It could additionally note potential processing time or failure modes, but the provided information is sufficient for an agent to decide to invoke the tool. Sibling tools are similar but not referenced, yet the context is complete for a typical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds marginal value by giving an example for reframePrompt and emphasizing videoUrl must be public, but this is largely redundant. Baseline 3 applies because the schema does the heavy lifting; the description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Reframes a video to a new aspect ratio by intelligently outpainting/cropping the edges.' It uses a specific verb ('reframes') and resource ('video'), and the mention of 'video' distinguishes it from the sibling reframe_image tool. The title also adds model context (Luma Ray 2 Flash), reinforcing the specific operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to change a video's aspect ratio via outpainting/cropping. It specifies required inputs (public videoUrl and reframeAspectRatio) and optional reframePrompt. However, it does not explicitly compare to alternatives or state exclusions (e.g., 'use reframe_image for images'), though sibling tooling implies this. This is a minor gap, so 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Strips the background from an image, returning a PNG with transparent alpha. Pass a public imageUrl. Useful for product shots, character cutouts, logo isolation, or compositing onto a new background. ~5 credits per image. Recraft is the primary provider; on outage the tool auto-falls back to fal.ai BiRefNet v2 so single-image calls never silently fail. Works best on photographic subjects (people, products, animals); transparent-PNG inputs have no foreground to segment.
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrl | Yes | Public URL of the source image. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses costs (~5 credits per image), provider fallback behavior (Recraft to fal.ai BiRefNet v2), and failure semantics ('single-image calls never silently fail'). It also addresses edge cases like transparent-PNG inputs, all beyond the sparse annotations. No contradictions 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the primary action, followed by key context (cost, fallback, limitations). Every sentence provides value without redundancy or verbose explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description specifies the return format (PNG with transparent alpha). It covers costs, provider fallback, ideal use cases, and a limitation, making it complete for a single-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the only parameter with 'Public URL of the source image' and format uri. The description repeats 'Pass a public `imageUrl`' without adding new semantic detail, so it meets the baseline for high schema coverage but does not improve on it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Strips the background from an image, returning a PNG with transparent alpha,' clearly stating the verb, resource, and outcome. It distinguishes itself from siblings like aetherwave_remove_background_video by explicitly targeting images and noting the fallback to BiRefNet v2.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit use cases ('product shots, character cutouts, logo isolation...') and a clear when-not-to-use ('transparent-PNG inputs have no foreground to segment'). However, it does not explicitly name an alternative tool for video or editing, relying on sibling names rather than direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Strips the background from a video frame-by-frame using rembg (u2netp) on AetherWave's Python service. Pass a public videoUrl. Choose bgType: "transparent" for an alpha-channel WebM output (compositing) or bgType: "color" with a customColor hex for a solid replacement. 2 credits per second. Slowest tool in the surface (per-frame processing); a 6s clip takes ~4 min, a 30s clip ~15-20 min. Works best on subjects with clear edges (people, products). Returns the processed video URL (R2-hosted).
| Name | Required | Description | Default |
|---|---|---|---|
| videoUrl | Yes | Public URL of the source video (MP4). | |
| bgType | No | 'transparent' = alpha WebM output (default). 'color' = solid replacement using customColor. | |
| customColor | No | Hex color for solid background when bgType='color' (e.g. '#00ff00'). Default green. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description adds cost (2 credits/second), performance expectations (6s clip ~4 min), limitations (clear edges), and return format (R2-hosted URL). This significantly enriches the behavior profile without contradicting any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense paragraph with no filler. It front-loads the purpose and progressively provides options, cost, performance, and output. Each clause adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the full lifecycle: input requirements, processing method, output format, cost, and performance caveats. Even without an output schema, it tells the agent what to expect (R2 URL). Given the tool's complexity, this is remarkably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already defines all three parameters with descriptions (100% coverage), but the description adds relational meaning: it explains how bgType and customColor interact (transparent vs color replacement) and specifies the output format (alpha WebM). This goes beyond the schema's individual descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Strips') and resource ('the background from a video'), clarifying the frame-by-frame methodology using rembg. This clearly distinguishes it from siblings like aetherwave_remove_background (image-focused) and other video tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use it ('Works best on subjects with clear edges') and warns about performance ('Slowest tool in the surface') with concrete timing examples. It does not explicitly name alternatives or exclusion scenarios, but the context is strong enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upscales a source image using Topaz's high-fidelity upscaler. Pass a public imageUrl and an upscaleFactor. Credit cost depends on the source resolution × factor; small images cost less than large ones at the same factor. Returns the upscaled image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrl | Yes | Public URL of the source image. | |
| upscaleFactor | No | Upscale multiplier. Defaults to '2x'. '8x' is heavy; use only on small sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavior beyond the annotations: credit cost depends on source resolution × factor, and it returns the upscaled image URL. Annotations already indicate non-readonly, non-idempotent, non-destructive, and open-world, and the description does not contradict them. It could mention side effects or limitations, but the cost model is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences: purpose, usage, and cost/return. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only 2 simple parameters and no output schema, the description fully covers inputs, output, and cost behavior. It is complete for the tool's complexity and provides enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 by explaining that credit cost is a function of resolution and factor, which helps choose parameters. It also reiterates the need for a public URL, aligning with the schema's format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb 'Upscales' and a clear resource 'source image', also naming the technology 'Topaz's high-fidelity upscaler'. This clearly distinguishes it from sibling tools like aetherwave_upscale_video or aetherwave_edit_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear instruction to pass a public imageUrl and upscaleFactor, and provides cost guidance based on resolution and factor. It doesn't explicitly mention alternatives or exclusions, but the image-specific language and sibling tool names make the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upscales a source video to 1080p or 2K using Atlas. Pass a public videoUrl and the target resolution. Cost is per-second (7 cr/s @ 1080p, 9 cr/s @ 2K). Atlas-side limits: clips up to 53s at 1080p, 23s at 2K, source must be <=30fps. Returns the upscaled video URL (R2-hosted).
| Name | Required | Description | Default |
|---|---|---|---|
| videoUrl | Yes | Public URL of the source video (MP4). | |
| targetResolution | No | Target output resolution. Defaults to '1080p'. '2k' is more expensive and limited to ~23s clips. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the basic annotations, it discloses per-second costs, Atlas-side limits (clip length, frame rate), and that the result is an R2-hosted URL. This adds meaningful behavioral context about what the tool does and its constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four focused sentences cover function, usage, cost/limits, and return value. No redundancy or irrelevant details. The structure is front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers input, constraints, cost, and output URL, which is sufficient given no output schema. It could mention failure behavior but that's not essential. The limits and cost give good operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameter descriptions, so the description doesn't need to add much. It restates videoUrl and targetResolution without adding new semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool upscales videos to 1080p or 2K using Atlas, with a specific verb (upscales), resource (video), and target resolutions. It distinguishes itself from sibling tools like aetherwave_upscale_image and aetherwave_generate_video.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use: upscaling a video with a public URL, with specified resolutions, limits, and costs. It doesn't explicitly name alternatives but the context is sufficient for most AI agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.6aetherwave_balanceaetherwave_edit_imageaetherwave_generate_imageaetherwave_generate_musicaetherwave_generate_videoaetherwave_list_image_modelsaetherwave_list_master_presetsaetherwave_list_my_creationsaetherwave_list_video_modelsaetherwave_master_audioaetherwave_reframe_imageaetherwave_reframe_videoaetherwave_remove_backgroundaetherwave_remove_background_videoaetherwave_upscale_imageaetherwave_upscale_videoScored across 16 tools
Each tool targets a distinct media type and action (generate, edit, reframe, remove background, upscale, master, list models/presets/creations). No two tools overlap in purpose, and descriptions clearly differentiate them.
All tools follow a consistent 'aetherwave_verb_noun' pattern in snake_case, with clear verbs like generate, edit, list, master, reframe, remove, upscale. Even 'aetherwave_balance' is a concise outlier that still fits the convention.
With 16 tools covering image, video, and audio generation/editing, plus utility tools for models, presets, and user creations, the count is well-scoped for a comprehensive media generation server. No tool feels redundant or missing.
Core workflows (generate, edit, reframe, upscale, background removal, audio mastering) are well covered. However, there is no tool for deleting or managing user creations, which is a minor gap for a complete lifecycle.
MCP server for Google Veo AI video generation
AI image, video, voice and music generation over MCP, routed to Veo 3.1, Seedance 2.5 and more.
Generate images, video, audio and short films with 140+ AI models from any MCP client.
MCP server for Kling AI video generation
