AetherWave Studio

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.

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

The description richly discloses behavior beyond annotations: it returns immediately (async), provides timing estimates, explains the 'pages-partial' state, the skip behavior, and the safe re-run property. This aligns with annotations (idempotentHint, non-destructive) and adds critical operational context the annotations don't convey.

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 slightly verbose but every sentence carries useful information (cost, core action, timing, partial handling, re-run guidance, next step). It is front-loaded with 'Free' and the primary purpose, and maintains a logical flow.

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 two parameters and no output schema, the description is thorough: it covers what happens (state changes), when to use (after drawing, before export), performance expectations, edge cases (undrawn panels), and re-run safety. No missing information that an agent would need 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 description coverage is 50% (only allowPartial has a description). The description explains the behavior influenced by allowPartial (default refusal vs. allowing partial assembly) but does not explicitly name the parameter. projectId is self-evident and needs no extra explanation, so the description adds moderate value over 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 the specific action: laying out pages from drawn panels, lettering balloons/captions, and marking the book complete. It distinguishes itself from sibling tools like aetherwave_comic_draw (drawing) and aetherwave_comic_export (exporting) by naming the next step and emphasizing the assembly state change.

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 explicitly states when to re-run (after redrawing a panel) and points to the next step (export). The default behavior with undrawn panels and the allowPartial override are explained, though it doesn't explicitly name alternative tools as 'instead of X' – but the sibling context makes this clear enough. Slight gap: it doesn't say when not to use it beyond the partial-page refusal.

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

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

Beyond annotations, the description discloses important behaviors: generated images are added rather than replacing existing ones, images persist in AetherWave storage, edits preserve the same person, approve re-describes the character from the image, and timed-out calls still save images retrievable via status. This is rich behavioral disclosure with no contradiction to the annotations.

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

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

The description is long but dense and well-organized, front-loaded with the core purpose and then structured by action. Every sentence contributes operational guidance, including edge cases like timeout behavior and URL expiration. No filler or redundancy appears.

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 two-action complexity and no output schema, the description covers invocation, credit cost, parameter relationships, approval timing, storage durability, and failure fallback. It is slightly incomplete because projectId is required but never explained, and the tool's direct return value is not described; however, both are inferable from the workflow 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?

With schema description coverage at 63%, the description adds substantial meaning: count credit costs, baseUrl requiring editPrompt, approve's imageUrl, and characterId/characterName identification. The main gap is projectId, a required parameter with no description in either the schema or the tool description, though its meaning is likely inherited from the surrounding workflow.

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 states a specific verb and resource: it gives a comic character a reference image, with two explicit actions (generate and approve). It clearly distinguishes this tool from generic image-generation siblings by emphasizing that this reference is what every panel uses to keep the character consistent, and it names related tools for context.

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 both actions: generate costs credits and adds options; approve is free and must happen before aetherwave_comic_write_script. It also constrains acceptable image URLs. It does not explicitly contrast this with aetherwave_generate_image or aetherwave_edit_image, but the unique character-consistency purpose is clear enough.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds meaningful behavioral context beyond these: it states that the tool is free, that it returns projectId and characterIds, that nothing is generated yet, and that certain parameters (imageModel, aspectRatio, stylePreset) are 'Locked once created.' It also discloses cost/charging behavior for downstream steps. The only minor gap is that it doesn't explicitly describe failure modes or what happens if required fields are invalid, but the description goes well beyond the annotations.

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

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

The description is long but earns its length: it front-loads the core purpose in the first sentence, then provides a numbered pipeline that is directly actionable. The pipeline list is dense but well-structured. It could be slightly tighter (e.g., the cost details for downstream tools are useful but somewhat tangential to this tool's own invocation), but every section serves a purpose for an agent navigating the workflow.

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 complex 16-parameter tool with no output schema, the description is remarkably complete. It explains the return value (projectId, characterIds), the workflow position, the sequencing constraint with character_reference, the meaning of key parameters, and the locked-parameter behavior. An agent has everything it needs to call this tool correctly and to know what happens next. The absence of an output schema is compensated by the explicit statement of what is returned.

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 16 parameters. The description adds value by explaining the semantic role of key parameters: 'Characters: give each a concrete visualDescription (age, hair, face, clothes, one signature item). The script writer and every panel read it.' It also clarifies that 'custom' artStyle means describing the look in toneNotes, and that the cover is drawn around the protagonist. This is meaningful semantic guidance beyond the schema's field 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 clear verb and resource: 'Creates a comic book project (the AetherWave Graphic Novel Engine) and returns its projectId and each character's characterId.' It also explicitly states what it does NOT do ('Nothing is generated yet'), which distinguishes it from later pipeline tools like aetherwave_comic_draw and aetherwave_comic_write_script. This is a specific, non-tautological statement that an agent can act on.

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 explicit numbered pipeline of all sibling tools, stating the order of operations and when to use each one. It also gives a critical usage rule: 'Do this BEFORE the script: approving rewrites the character's description from the picture, and every panel uses the approved image to keep the face consistent.' This is exactly the kind of when-to-use and sequencing guidance an agent needs.

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

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

Annotations already indicate idempotentHint=true and readOnly=false, but the description adds rich behavioral detail: asynchronous return, 1.5–6 minute per-panel timing, 9 credits charged only on success, alreadyDrawing behavior, silent run death on server restart with resume, and maxCredits refusal. This goes well beyond the structured annotations and does not contradict them.

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 dense but every sentence earns its place, covering async behavior, cost, idempotency, failure recovery, and stop semantics. It is front-loaded with the default action and immediate return, making the most important information available first.

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 complex, long-running, cost-bearing tool with no output schema, the description covers the essential operational details: start/stop behavior, credit charging, idempotent re-invocation, server-restart recovery, and progress monitoring via a sibling tool. An agent has enough context to invoke it correctly and know what to expect.

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 only 33%, so the description must compensate. It explains the meaning of action='start' and action='stop', and ties maxCredits to refusing expensive runs. projectId is left to inference, but its role as the comic project identifier is reasonably clear from the parameter name and required status.

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 uses a specific verb ('draw') and resource ('comic's panels'), and clearly explains both the 'start' and 'stop' actions. It also distinguishes itself from aetherwave_comic_status by directing progress tracking to that sibling tool. The behavior of drawing pending or failed panels one at a time is unambiguous.

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 call it: start draws missing panels, stop halts after the current panel, and it is safe to re-call at any time. It also points to aetherwave_comic_status for progress. It does not explicitly contrast with redraw_panel or state when not to use it, so it stops short of a 5.

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

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

While annotations already mark this as readOnly and openWorld, the description adds valuable behavioral nuance: it is free, it assumes 4 panels per page, it can run high for short books, and character references add 6 credits each. This gives an agent an accurate model of how the estimate behaves beyond the annotation hints.

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, opening with 'Free' and a clear definition before diving into caveats. Every sentence earns its place: the first defines scope, the second explains estimation behavior with a concrete example, and the third directs the agent to the next steps and cost adjustments.

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 small parameter surface, rich schema descriptions, and annotations, the description provides everything an agent needs to call this tool correctly and interpret the estimate's limitations. Even without an output schema, the description makes the returned quote's meaning clear, and it covers supplementary costs like character references.

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 meaningful semantic context by explaining the 4-panels-per-page assumption behind the pageCount parameter and clarifying that the estimate includes both script and panel credits. This goes beyond the schema's basic field definitions.

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 states a specific action with a resource: 'Quotes a comic before anything is made' and breaks down the quote into script and panel credits. It clearly differentiates this estimation tool from related actions like aetherwave_comic_draw and aetherwave_comic_status by positioning it as a pre-production estimate.

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 states when to use the tool ('before anything is made') and points to alternatives after the script exists: aetherwave_comic_status for the real creditsToFinishDrawing and aetherwave_comic_draw for maxCredits. It also explains the over-estimation caveat for short books, giving an agent concrete guidance on when the quoted number is less reliable.

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

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

Goes well beyond annotations, disclosing concrete behavioral traits: ~45s build window, 'building' status fallback, exportId polling, the one-export-per-account limit with alreadyExporting/projectId reporting, retryAfterSeconds on busy, and ~1 day link expiry with 130 MB file sizes. This is rich, decision-relevant context that annotations don't capture.

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 but front-loaded — formats and return value come first, then timeout/polling and concurrency edge cases. The 'Free.' prefix is minor noise, and the long run-on sentences pack a lot in, but virtually every clause carries operational 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, it fully covers return shape (download URL, status 'building', exportId, alreadyExporting, retryAfterSeconds), timing, and error/edge behavior. An agent has everything needed to call it, poll it, and handle contention.

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 75% and the description adds real meaning: it defines what 'bundle' contains (ZIP of all three plus page PNGs), clarifies epub is fixed-layout/Kindle ready, and explains the exportId check-on-earlier-export semantics. It does not explain includeBackMatter, which the schema handles with a default.

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?

States a specific verb and resource ('Builds the assembled book...returns a download URL') and enumerates the exact output formats (pdf, epub, cbz, bundle) with their distinguishing traits. Clearly distinguishes itself from aetherwave_comic_assemble by its final instruction 'Assemble first.'

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 names the prerequisite ('Assemble first.'), the alternative/exhaust path via aetherwave_get_job with exact kind/taskId/projectId arguments, and the condition for re-calling with exportId. It also states the concurrency behavior — one export per account — which is the key usage constraint.

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

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

Annotations already mark this as destructive, non-idempotent, and read-only=false, so the bar for additional value is higher. The description still adds substantial context: 9 credits charged only on success, 1.5–6 minute asynchronous duration with a stillDrawing return path, retention of dialogue/captions, refusal during active runs, and the need to reassemble afterward. This fully enriches the annotation profile without contradicting it.

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?

Every sentence carries actionable information: cost, substitution behavior, retention policy, timing, failure mode, concurrency restriction, and post-condition. The core operation is front-loaded, and there is no redundant restatement of the schema or title.

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?

This is a high-complexity tool with no output schema, yet the description covers the essential behavioral surface: asynchronous completion, credit charging, content-filter handling, concurrency constraints, cross-tool dependency on status, and follow-up assembly. An agent has what it needs to call the tool correctly and interpret the stillDrawing outcome.

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 67%, with prompt and panelId already documented, but the description adds meaning beyond the schema: prompt is explicitly tied to replacing the scene description and to the content-filter rewording strategy, and panelId is tied to failedPanels from aetherwave_comic_status. projectId lacks a schema description, but the tool-level context makes its role clear enough.

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 and resource: 'Redraws a single panel, replacing its current image.' It clearly distinguishes this from the sibling aetherwave_comic_draw by anchoring on a single panel and contrasting with a 'full drawing run,' so an agent can tell them apart without opening either schema.

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 concrete when-to-use guidance: use it for single-panel redraws, avoid it while a full drawing run is active, and re-run aetherwave_comic_assemble if the page was already assembled. It also advises rewording the prompt rather than retrying when a content-filter refusal is encountered, which is explicit operational guidance beyond what the schema provides.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds significant behavioral details: the meaning of 'stalled', the fact that no run is active in that state, that server restarts or failures can end runs, and the explicit warning never to treat a stopped run as finished. This is critical for an agent to avoid misinterpreting stale status.

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, front-loaded with the core value ('Where a comic is and what to do next'), and every sentence adds necessary information. The enum explanation and the stalled-run caveat are placed efficiently and do not waste space.

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 output schema, the description sufficiently enumerates the returned data: project status, drawing state, failed panels with reasons, assembled page URLs, character reference images, and nextStep. It also handles the optional projectId behavior and the critical stalled-state scenario, making the tool fully usable without further documentation.

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 description does not need to duplicate parameter details. It does reinforce that omitting projectId lists recent projects and references the panels detail option, but most parameter meaning is already well documented 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 states the tool's specific purpose: check a comic's progress, report status, drawing state, failed panels, URLs, character references, and nextStep. It clearly distinguishes this status-checking tool from the sibling tools like aetherwave_comic_draw and aetherwave_comic_redraw_panel.

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 clearly explains when to use the tool and even provides conditional guidance: if drawing is 'stalled', aetherwave_comic_draw must be called again, and a stopped run must never be treated as finished. It lacks explicit exclusions for sibling tools, but the context makes 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.

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

The description goes well beyond the annotations by disclosing asynchronous completion (2-3 minutes), cost-on-finish with a concrete credit example, the prerequisite of approving character references, and the destructive consequence of deleting every existing page/panel including drawn panels. This is rich, specific behavioral disclosure with 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?

Every sentence adds necessary operational or cautionary information. The description is front-loaded with the primary action and asynchronous behavior, followed by cost, prerequisite, and destructive warning. There is 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 an asynchronous, destructive, paid operation with no output schema, the description covers all critical operational aspects: what starts, when results appear, cost behavior, required preconditions, and the destructive parameter condition. An agent has enough information to invoke it correctly and avoid data loss.

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 only 50%, so the description must compensate. It strongly clarifies replaceExisting semantics by linking it to destructive deletion of existing panels and drawn art. projectId is not described, but its role is self-evident from the tool name and the required-field context, so the gap is minor.

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 states a specific verb and resource: it 'starts writing the script' and enumerates the content produced (chapters, pages, panels, dialogue, captions). It also distinguishes its asynchronous nature from the status-tracking sibling tool, making its purpose unambiguous.

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

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

It gives clear context: returns immediately, results appear via aetherwave_comic_status, character references must be approved first, and rewriting requires replaceExisting: true when panels exist. It does not explicitly name alternatives to exclude, but the guidance is sufficient for correct use.

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

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

Annotations declare openWorldHint=true, readOnlyHint=false, idempotentHint=false, but the description adds the operational facts an agent actually needs: per-model credit cost, ~15-30s and ~45s latency, the 6-15 minute blocking budget, the recommendation to poll aetherwave_get_job every ~10s on state 'running', and the caveat that source URLs with spaces or parentheses may fail upstream. That is well beyond what the annotations convey.

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?

Well organized with a front-loaded summary followed by a headed 'Model selection guide for edits' section, and the polling/wait advice comes last. It loses a point for duplication: the model lineup and the wait/async semantics are already spelled out in the schema parameter descriptions, so the description repeats them.

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 complex 11-parameter, multi-model image-edit tool with no output schema, the description covers submission, latency expectations, polling handoff to aetherwave_get_job, wait vs async tradeoffs, model/cost selection, and upstream URL constraints. An agent has everything needed to invoke it correctly and recover from a long-running job.

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, but the description adds genuine meaning over the schema: it maps model IDs to cost/quality/latency tradeoffs, reiterates the clean-URL constraint on imageUrl, and explains the practical failure of wait:true in typical MCP clients. The remaining parameters (quality, resolution, aspectRatio, maxImages, negative_prompt, renderingSpeed) are left entirely to 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?

Specific verb+resource ('Edits an existing image') with the mechanism named ('guided by a text prompt') and concrete examples of prompts. It is clearly separable from siblings like aetherwave_generate_image (creation), aetherwave_reframe_image, and aetherwave_upscale_image because it operates on a supplied source 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?

Explicitly states the default model and then gives a condition->model routing table (deterministic/4K -> seedream-v4-edit, subtle edits -> flux-kontext, NSFW -> wan-2.5-spicy-i2i, highest quality -> gpt-image-1.5-i2i). It even handles the ambiguous case ('if the user simply says edit this image, default to grok-imagine-i2i') and names list_image_models as the discovery fallback.

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

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

Annotations only say it is non-readonly and open-world; the description goes much further, disclosing cost per model, ~45s return window, the 'running' state and 10s polling cadence via aetherwave_get_job, and the client-timeout caveat on wait:true. These are operational traits the agent cannot derive from the annotations.

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

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

Core purpose and job lifecycle are front-loaded before the long model-selection block, and the length is largely earned by a 10-parameter, many-model tool. However, the wait/async/timeout guidance in the prose closely repeats the schema descriptions, which is mild 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?

For a 10-parameter tool with no output schema, the description still covers the return contract (final image URLs), the non-terminal case (state 'running' + taskId + polling tool), cost thresholds, defaults, and per-scenario model routing. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds real meaning: which models to pass, that aspectRatio should always be set explicitly (some providers reject submissions without it), and that referenceImages is required for I2I models. Some overlap with the schema text on wait/async keeps it short of 5.

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 names a specific verb and resource and splits the two modes (T2I vs I2I) explicitly, then states the full lifecycle: submit, poll, return image URLs. It also differentiates itself from the sibling aetherwave_edit_image and points to list_image_models. An agent can select this tool without opening any schema.

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 a detailed model-selection guide mapping prompt signals ('photoreal', 'single best result', NSFW, cheapest) to concrete model IDs with credit costs, states the alternative (aetherwave_edit_image) for edit intent, and defines exactly when to stop and ask the user. This is about as explicit as when/when-not/alternatives gets.

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

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

Annotations declare a non-readonly, non-idempotent, open-world operation, and the description goes further: it discloses the 30-90s typical duration, the 6-minute polling budget, ~45s default return time, returning two tracks per submission, the default model V5.5, the advisory nature of the title param for instrumentals, and the retry directive for transient GENERATE_AUDIO_FAILED errors. This is exactly the behavioral context annotations cannot convey.

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?

Front-loads the core (what it does, track count, default model) then layers operational guidance. Slightly dense with wait/async details that duplicate the schema, but every sentence earns its place for an agent deciding how to call it.

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 an agent needs for a long-running, non-idempotent generation call: default polling, wait/async escape hatches, the aetherwave_get_job polling loop, and retry guidance. No output schema, so return-shape info (taskId, kind, state) is carried by the description, which it does. Minor gap: two tracks per submission could be stated alongside the running-state handoff.

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 12 params. The description reinforces a few (instrumental, title, wait, async) but adds no syntax or format info beyond the schema. Baseline 3 is correct when the schema carries semantics.

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?

States a specific verb (generates), resource (AI music via Suno), and vendor. Named sibling aetherwave_master_audio handles audio mastering, so the agent can distinguish generation from post-processing. Purpose is unmistakable.

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 covers when to wait vs. async, when to use the instrumental flag, and when to retry on GENERATE_AUDIO_FAILED. It also points the agent to aetherwave_get_job for polling ongoing jobs. Clear conditional routing for the agent.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false, idempotentHint=false), the description discloses asynchronous timing (1-8 min, ~45 s return, 'running' state + taskId), fallback behavior (KIE -> fal.ai), audio billing quirks, and a real failure mode (takes returning wrong words despite success). This is unusually rich operational context.

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

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

The purpose is front-loaded and the sectioned layout helps, but the description is very large — a full multi-line model-selection matrix is inlined into the tool description despite the referenced aetherwave_list_video_models existing for exactly that. Much of it earns its place, but the sheer volume is a clear gap against 'appropriately sized'.

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 output schema, the description carries the return contract (final video URL, or 'running' + taskId) and the polling recipe, plus cost, audio, and character-consistency guidance. For a 12-parameter, 20-plus-model tool, nothing an agent needs to call it correctly is missing.

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, but the description adds genuine meaning: it explains which models need imageUrl, that endImageUrl extends I2V, that referenceImages (not imageUrl) is the consistent-character mechanism and is mutually exclusive with imageUrl, and that resolution/duration drive cost. Some content (generateAudio, wait/async) merely restates the schema, keeping this off a 5.

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 opening states a specific verb and resource ('Generates a short-form video') and immediately distinguishes the two modes (T2V vs I2V), plus the async submit/poll/return mechanics. An agent can tell this apart from aetherwave_generate_image or aetherwave_generate_music without opening either schema.

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 an explicit model-selection guide keyed to prompt signals, names alternatives for every case, and states when to ask the user (single generation >100 cr, ambiguous 'best' requests). It also routes to siblings aetherwave_list_video_models and aetherwave_get_job with concrete conditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds important behavior beyond them: the job keeps running server-side and is saved to the gallery regardless of client outcome, so a taskId is enough to recover a paid render. It also states the polling cadence of ~10 seconds.

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 behavior and return value, then moves to polling, recovery semantics, and a compact kind-mapping list. Despite its length, every section carries actionable information for a multi-pipeline job-status tool.

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 absence of an output schema and the tool's cross-pipeline complexity, the description fully covers what the tool returns, how to poll it, which kinds it supports, and when to use sibling tools instead. The agent has everything needed to invoke it correctly and route edge cases.

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 schema already documents kind, taskId, and projectId. The description adds value by mapping each kind value to the sibling tools that produce it (image, video, video-edit, music, merch-mockup, comic-export) and clarifying that merch_mockup uses taskKey while comic_export uses exportId. This goes beyond the schema but still largely reinforces structured content.

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 uses a precise verb and resource: it returns the current state and, once finished, output URL(s) for a generation job. It explicitly distinguishes itself from siblings like aetherwave_comic_status and aetherwave_merch_mockup_status, so an agent can tell exactly what this tool does without opening the schema.

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 explicit when-to-use guidance: poll every ~10 seconds for any job returned as state "running" or submitted with async:true, and use it even after a timeout. It also names alternatives and exceptions: comic script/draw/assemble uses aetherwave_comic_status, master_audio has no job id, and mastered audio appears in aetherwave_list_my_creations.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the tool returns a link rather than a file, and the call is 'Free' — meaningful context given most sibling tools consume balance. It stops short of stating link expiry or auth requirements, so not a 5.

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?

Front-loads the return value in the first sentence, then lists the variants compactly, then closes with the routing trigger. Every clause carries information; nothing is padding.

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 output schema, the description covers the return value (a download link) and the full parameter domain. Annotations cover the safety profile. Nothing an agent needs to call this correctly is missing.

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% and the enum plus default are already documented in the schema. The description goes beyond that by explaining what each enum value actually contains (e.g. 'mcp' covers every tool, prices, long jobs, characters, comics, merch, troubleshooting), which helps the agent choose the right manual rather than just picking a valid string.

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?

States a specific verb and resource ('Returns the download link for an AetherWave user manual PDF') and enumerates the four manual variants with their scope, which no sibling tool overlaps with. An agent can distinguish this from the generation/comic/merch tools immediately.

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?

Gives explicit trigger conditions: 'Use it when the user asks for the manual, documentation, a guide or help with how AetherWave or these tools work.' That covers the main routing decision. It does not name a when-not case or an alternative, but no sibling competes for this intent, so the gap is minor.

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

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

Annotations already mark the tool as read-only and open-world, and the description adds useful behavioral context without contradicting them: it warns that referenceImages replaces rather than augments the hero image, and that paraphrasing identityBlock breaks consistency. This gives the agent operational knowledge beyond the structured annotation hints.

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 longer than average, but it is organized with a clear opening directive and bulleted output explanations, and every section provides operational value. The only slight deduction is that several downstream-use instructions could be consolidated, but the structure makes the length acceptable.

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 output schema, the description carries the burden of explaining every meaningful returned field, and it does so thoroughly: identityBlock, referenceImages, heroImageUrl, voiceId/voiceSpec, personality, negativeLock, and hasApprovedPack all receive concrete guidance. It is sufficient for an agent to call the tool and correctly use its result.

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 single optional name parameter is fully documented in the schema (case-insensitive substring filter, omit to list all), and the description does not need to add much. It does not repeat or expand the schema, so baseline 3 is appropriate for high schema coverage.

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 and resource: returning the caller's saved UGC characters, and immediately names the core purpose: keeping recurring characters consistent across a production. It also distinguishes itself from any sibling lookup by stating there is no other way to discover whether a character exists, so agents can route correctly.

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 an explicit trigger: 'CALL THIS FIRST whenever the request names a person the user already has', with concrete example phrases. It also tells the agent how to use the returned fields downstream, including passing referenceImages to aetherwave_generate_video and appending identityBlock/voiceSpec verbatim, leaving no ambiguity about when and how to invoke it.

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

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.

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.

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful behavior beyond that: pagination and type-filter support, plus a full account of returned fields (including type-specific ones). Auth requirement is only implied by 'authenticated user's', and no ordering guarantee is stated.

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?

Purpose is front-loaded, and each subsequent sentence earns its place by covering usage examples, filtering capability, and return fields. The field enumeration is long but justified because no output schema exists, though it slightly dilutes focus.

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 output schema, the description compensates well by enumerating returned fields and type-specific extras. Filtering and pagination behavior are noted. Minor gaps remain around ordering/default behavior and explicit authentication requirements, but the core is 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?

Schema description coverage is 100%, so the schema already documents type, limit, offset, and favoritesOnly in detail. The description's mention of 'pagination and type filtering' largely restates the schema without adding format or default detail, so baseline 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?

States a specific verb and resource: returns gallery items (images, videos, audio) for the authenticated user's AetherWave creations. This cleanly distinguishes it from the many generation/editing siblings like aetherwave_generate_image and aetherwave_reframe_image, which produce or modify rather than list.

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 concrete when-to-use context via example workflows ('find my last 5 images and reframe them all to 9:16', 'list my recent songs and master each one'), which signals it's a discovery step feeding other tools. It lacks explicit exclusions or naming of an alternative list/filter tool, so it stops short of a 5.

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

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.

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

Goes well beyond the annotations with credit cost (20 credits, free on Producer/Mogul/Ultimate), latency (30-90 s, up to 5 min), output format and size (WAV, ~50MB per 3 min), and the polling/no-job-id behavior. The only blemish is an internal inconsistency: the description says 'this pipeline has NO job id' while the schema says the call 'hand[s] back a taskId if still running' — an agent could be confused about how to recover a running result.

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?

Front-loaded with the core action and return value, then cost, latency, and recovery guidance. It is information-dense rather than padded, though the 12-preset list duplicates the schema enum and the two latency figures ('~45 s' vs '30-90 s') slightly muddy the message.

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 output schema, the description carries the full burden and does so: it describes the returned mastered URL, the 'running' state, where the finished file lands (gallery), and the cost model. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it enumerates the 12 live presets, notes each carries a target LUFS so the agent can match a distribution target, and explains the wait:true trade-off in prose. Marginal value above the schema, but genuine.

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?

States a specific verb and resource ('submits an audio file for AI mastering') and names the artifact returned ('returns the mastered URL'). This is clearly distinguishable from siblings like aetherwave_generate_music (creation) and aetherwave_get_job (polling).

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 positions the tool ('useful as a final polish step after music generation') and routes the agent to alternatives: aetherwave_list_master_presets for preset metadata and aetherwave_list_my_creations for retrieving a still-running result instead of resubmitting. It also states a when-not condition ('do not resubmit, which would master and charge it again').

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real value beyond that: it flags the call as free, discloses that the id space is the entire Printful catalog (including hats, contradicting the 'curated' framing when an id is given), and enumerates the per-mode payloads (US in-stock sizes, placements in inches, embroidery thread colours).

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?

Front-loaded with the cost signal ('Free.'), then the two modes, then the routing purpose. Every clause adds decision-relevant information; no filler or repeated name/title.

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 output schema, the description must cover returns, and it does so for both modes with concrete fields. It is complete enough to call correctly; only minor gaps remain (no mention of response size or whether the curated list is paginated).

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 earns above baseline by interpreting the parameter's two regimes (absent = curated list, present = any Printful catalog id including hats) and the shape of what each mode yields, which the schema's one-line description does not convey.

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?

States the resource (print-on-demand garments, colours, print areas) and precisely distinguishes its two operating modes: without garmentId returns the curated list, with garmentId returns colours/sizes/placements. The agent can identify what it returns without opening anything else.

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 routes the agent: 'Use it to pick garmentId, color and placement for aetherwave_merch_mockup.' It names the downstream sibling and the exact function this call serves, so when-to-use versus aetherwave_merch_mockup is unambiguous.

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

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

With annotations covering the safety profile, the description still adds substantial behavioral context: 3 credits with a refund policy on failure, ~45s return window, running-state/taskId semantics, 20 mockups/hour rate limit, and that mockup URLs are temporary Printful links that must be saved.

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?

Front-loads the cost/refund and the core build+render action, then sequencing, then return-value caveats. It is dense and covers a lot, but a few clauses (e.g. the repeated wait/async guidance spanning description and schema) are slightly redundant rather than wasteful.

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?

No output schema and 8 parameters, so the description carries the burden well: it names the returned fields (printfileUrl, mockup URLs), the async state/taskId contract, the polling tools, and the URL expiry caveat. An agent has everything needed to invoke and follow up.

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 goes further by tying wait/async to client timeout behavior and explaining that the returned taskId is the taskKey used for polling. It adds operational meaning beyond the schema's literal parameter docs.

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?

States a concrete verb+resource chain: builds the print file at the garment's print area/resolution and renders Printful product mockups. It clearly distinguishes itself from siblings like aetherwave_merch_prepare_design (upstream) and aetherwave_printful_create_product (downstream consumer).

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 names the alternatives and conditions: poll aetherwave_get_job with kind 'merch-mockup' or aetherwave_merch_mockup_status, use wait:true ONLY if the client permits >60s calls, async:true returns taskKey at once. It also states the downstream step (aetherwave_printful_create_product with printfileUrl).

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely new behavioral facts: results are retained only 6 hours and are visible only to the paying account. It does not explain failure states or what a missing/expired taskKey yields, keeping it from a 5.

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?

A single tightly written sentence with the cost signal ('Free.') front-loaded and the scope details parenthesized. No wasted words, though the parenthetical packs two distinct facts together and could be split for scanability.

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 output schema, the description carries the return-value burden and does state that status and mockup URLs are returned. Retention window and per-account visibility are covered. What is missing is only edge-case behavior (expired tasks, still-rendering state).

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?

One required parameter (taskKey) with 0% schema description coverage, so the description must compensate but only partially does: it implies the key comes from a render started by aetherwave_merch_mockup, but never names taskKey or states its format/source explicitly. Better than nothing, below the 4 baseline for undocumented params.

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?

States a specific verb+resource: retrieving status and mockup URLs for a render. It explicitly ties the artifact to the sibling that created it (aetherwave_merch_mockup), which helps disambiguate among 30 siblings. Slightly terse about what 'status' values mean, so not a full 5.

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 phrase 'of a render started by aetherwave_merch_mockup' implies this is a follow-up poll to that tool, which is useful context. However, there is no explicit when-to-use/when-not guidance, no polling cadence, and no comparison to the generic aetherwave_get_job sibling that might also retrieve job status.

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

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

Adds substantial context beyond the annotations: a 1-credit cost, the exact output transformation (transparent PNG trimmed to artwork), and the nuanced knockout behavior (only edge-connected background is removed so interior white lettering survives). It also states the primary return field, which annotations alone would not convey.

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 dense sentences with the cost and core transformation front-loaded, followed by input forms, the knockout nuance, and the downstream handoff. No filler or repetition of schema content.

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 3-parameter tool with no output schema, the description covers cost, input sources, transformation semantics, and the key return field for chaining. Minor gaps remain (no mention of other return fields or of tolerance interaction), but nothing an agent needs to call it is missing.

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 schema already documents all three parameters (baseline 3). The description still adds value for 'image' by enumerating accepted source types and for 'knockout' by explaining the edge-connectivity rule, though it says nothing about 'tolerance' beyond what the schema provides.

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?

States a precise verb and output: 'Turns an image into a print-ready transparent PNG trimmed to the artwork.' The merch-prep framing and the designUrl -> mockup chain make the intent clear. It does not, however, explicitly distinguish itself from the near-neighbor aetherwave_remove_background, which an agent could plausibly pick for the same input.

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?

Gives concrete usage context: accepted input forms (AetherWave media URL, data URL, local file path), when to set knockout=true, and the downstream tool (aetherwave_merch_mockup). No explicit when-not guidance or contrast against the background-removal siblings.

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

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

Annotations cover only the safety profile (readOnly false, destructive false, idempotent false, openWorld true); the description carries the real behavioral load by disclosing per-tier credit costs (5/10/14 cr), relative latency, the ~45 s return window, the 'running' state and polling cadence, and the trade-off between wait and async. This is exactly the context annotations cannot express.

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?

Front-loaded with what the tool does and the required inputs, then the tier table and async guidance. Two dense paragraphs with little waste, though the wait/async callsite caveat is repeated in both description and schema.

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?

No output schema exists, so the description must cover returns, and it does: the reframed image URL, plus taskId and state for the polling path. Combined with per-tier cost and timing, an agent has everything needed to invoke and handle the result.

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%, and the schema itself already documents wait, async, speed costs, and imageUrl/aspectRatio. The description largely restates those (tier costs, example ratios) with only marginal added meaning, so the baseline 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?

States a specific verb and resource ('reframes an image to a new aspect ratio') and names the mechanism ('intelligently outpainting the edges'), which distinguishes it from sibling aetherwave_reframe_video and from edit/upscale tools. An agent can select this without opening the schema.

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?

Gives clear operational context: default returns in ~45 s, poll aetherwave_get_job every ~10 s when state is 'running', and explicitly warns that wait:true should be used only if the client allows >60 s calls. It does not explicitly contrast with edit_image or upscale_image, but the async/polling routing guidance is strong.

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

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

Adds substantial context beyond the annotations: cost (17 credits per second), expected latency (~45 s), the meaning of the 'running' state, which tool to poll and at what interval, and the client-timeout hazard of wait:true. Annotations only cover the safety profile (openWorld, non-idempotent, non-destructive), so this operational detail is genuinely additive.

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?

Front-loads what the tool does and its cost before the polling mechanics; every sentence carries either a constraint or a recovery instruction. The wait/async material is slightly redundant with the schema descriptions, but it is not wasted length.

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 output schema, the description still covers the return value (R2-hosted reframed video URL), the fallback taskId, the 'running' state, and the exact recovery path. Nothing an agent needs to invoke and follow through on the job is missing.

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 nevertheless adds value by naming videoUrl, reframeAspectRatio and reframePrompt and giving a concrete steering example ('extend the sky with sunset clouds'), plus restating the wait/async contract with the failure mode it avoids.

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?

States a specific verb+resource ('Reframes a video to a new aspect ratio') and explains the mechanism ('intelligently outpainting/cropping the edges'), which distinguishes it from the sibling aetherwave_reframe_image and from aetherwave_generate_video. An agent can route to it without opening the schema.

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?

Gives explicit operational guidance: poll aetherwave_get_job every ~10 s when state is 'running', use wait:true only if the client supports >60 s calls, use async:true otherwise. It does not contrast itself with the sibling reframe/generate tools, so sibling-level when-to-use is left implicit.

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

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

Far exceeds the annotations (readOnlyHint=false, openWorldHint=true): discloses cost (~5 credits/image), provider fallback behavior on outage, expected runtime (~45 s), the 'running' state and taskId handoff, and client-timeout risk for wait:true. These are exactly the operational traits an agent needs and none are in the structured fields.

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?

Front-loads purpose, then usage, then behavior in a tight two-paragraph structure with no filler. Slightly dense in the second paragraph, but every sentence carries actionable information.

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 no output schema, the description explains the return shape (PNG on success; taskId + 'running' state on incomplete jobs), the polling contract, and the timeout constraint. An agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: it stresses that most clients cannot tolerate >60 s calls, names the ~10 s polling interval, and references the 'kind' argument for aetherwave_get_job, which the schema only mentions in passing.

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?

States a specific verb and resource ('strips the background from an image'), names the output format ('PNG with transparent alpha'), and lists concrete use cases. It is clearly distinguishable from the sibling aetherwave_remove_background_video and from editing/upscaling 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?

Gives explicit use cases (product shots, cutouts, logo isolation), an explicit when-not ('transparent-PNG inputs have no foreground to segment'), and routes the agent to aetherwave_get_job for polling with a concrete interval. The wait:true vs async:true tradeoff is spelled out with the condition that selects each.

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

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

Goes well beyond the annotations by disclosing cost (2 credits/second), runtime expectations (6s ~4 min, 30s ~15-20 min), that it is the slowest tool in the surface, return format (R2-hosted URL), subject-matter limits (clear edges), and the exact polling fallback with kind/taskId. The openWorld/non-idempotent hints are supplemented, not repeated.

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 and front-loaded: capability, then modes, then cost/runtime, then return/polling mechanics. Slight redundancy where the wait/async behavior is restated relative to the schema descriptions, but every sentence carries actionable information.

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 output schema, the description fully covers the return contract (processed video URL, taskId + kind, running state) and the async/polling workflow, so an agent has everything needed to invoke and follow up correctly.

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

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 every parameter; nevertheless the description adds interpretive value (public videoUrl, transparent vs color semantics, customColor hex default green) beyond the raw field docs.

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?

States a specific verb+resource ('strips the background from a video frame-by-frame'), names the underlying model (rembg u2netp) and the service, and is clearly distinguishable from the sibling aetherwave_remove_background (image variant) by the video scope. An agent can select it without opening any schema.

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?

Gives concrete when-to-use guidance for the two bgType modes (transparent for compositing, color with customColor for solid replacement) and for the wait/async/poll decision, including the 60s client-timeout caveat. It does not explicitly compare itself against the sibling image-removal tool, so it falls just short of 5.

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

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

Goes well beyond annotations by disclosing the cost model (free, no credits, but counts against storage), a size ceiling (95 MB), the environment caveat for filePath, and supported formats. These are operational facts an agent cannot derive from the schema or the safety hints alone.

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?

Front-loaded with the core action and return value, then constraints. The trailing format list (png/jpg/.../mov) is dense but earns its place since the schema does not enumerate accepted types; still, it reads as a compressed checklist.

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 essentials for a 6-param write tool with no output schema: it states the return value (permanent URL), the size limit, the source exclusivity rule, cost, and environment caveats. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the mutual-exclusivity rule ('give exactly one source') and the environment restriction on filePath. It omits guidance on tags/title/description defaults, which the schema already covers.

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?

States a specific verb and resource (saves/upload a user-provided file into the AetherWave gallery) and its output (permanent URL). Clearly distinguishes itself from sibling generators like generate_image/generate_video by emphasizing files the user *already has*, and enumerates downstream consumers (edit, animate, master, merch).

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?

Gives concrete conditions: exactly one source, which sources are valid, that filePath only works on the npx server, and that >95 MB must go through the website uploader. It routes to an alternative for oversized files, but doesn't explicitly say when to prefer this over a sibling generation tool beyond the implied 'existing file' case.

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

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

Annotations cover the safety profile (readOnlyHint false, idempotentHint false, destructiveHint false, openWorldHint true), and the description adds substantial context beyond them: flat 4-credit cost, ~45 s return window, 6-15 minute full budget, the 'running' state and polling cadence, and the 60 s client-abandonment risk that loses the taskId.

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?

Front-loads what it does and the cost, then layers the polling/latency guidance. No sentence is filler; each one carries an operational fact an agent needs.

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 output schema, the description still covers the return value (upscaled image URL, or a taskId when running), the failure/latency mode, and the follow-up tool. Nothing needed to invoke and follow through on this job is missing.

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 schema already documents all four parameters and the enum; the baseline would be 3. The description adds value the schema lacks — the ~10 s polling interval and the exact get_job(taskId, kind) call to make — justifying a step above baseline.

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?

States a specific verb and resource ('Upscales a source image 2x or 4x') and the required inputs, cleanly distinguishing it from siblings like aetherwave_upscale_video, aetherwave_edit_image, and aetherwave_reframe_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?

Gives explicit operational routing: default behavior returns within ~45 s, poll aetherwave_get_job with the returned taskId/kind every ~10 s while state is 'running', use wait:true only if the client tolerates >60 s calls, and async:true to skip polling entirely. When-to-use conditions are spelled out rather than implied.

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

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

Annotations declare this is a non-readOnly, open-world, non-idempotent, non-destructive mutation, and the description adds real behavioral context beyond that: ~45 s return window, 'running' state polling cadence, R2-hosted output, per-tier credit costs, and automatic engine routing for 4k/8k. This is rich disclosure for a job-submitting tool.

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?

Front-loaded with the core action and required inputs, and every sentence carries actionable content (costs, timing, the box-fit gotcha). It is dense and long, with some repetition of the schema's 4k/8k routing rule and wait-flag guidance, which keeps it short of a 5.

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 output schema, the description correctly explains return values (upscaled video URL, R2-hosted, taskId and state) and the async/polling protocol. Nothing an agent needs to invoke and follow up on this tool is missing.

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, but the description adds meaning the schema does not: measured examples (a 3:4 source at Atlas '2k' returned 1664x2216), the ffmpeg resize workaround, and the concrete credit costs per tier. It reinforces the 'tier is not a dimension' semantics that the schema states more briefly.

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?

States a specific verb and resource ('Upscales a source video'), names the two engines (Atlas/BytePlus) and their tier coverage, and is inherently distinguishable from the sibling aetherwave_upscale_image and aetherwave_reframe_video. An agent can identify the tool without opening the schema.

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?

Gives explicit when/when-not guidance: 'pick the highest sensible tier, then resize to exact dimensions in ffmpeg', 'Do NOT escalate to 8k to compensate', 'Pass wait:true ONLY if your MCP client permits tool calls longer than 60 s', and 'Pass async:true to get the taskId back immediately'. It also names the polling alternative (aetherwave_get_job) and the condition that selects it.

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