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?

Goes well beyond the annotations: exact credit costs (10 cr), latency (~15-30s, returns within ~45s), per-image billing for variations, the polling contract (get_job every ~10s with taskId+kind), and the 60s client-timeout caveat for wait:true. Also discloses a real failure mode (source URLs with spaces/parentheses may fail upstream).

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 front-loaded: the core action, then the default, then a scannable model-selection block, then the polling contract. Slightly long, with the model list appearing both in prose and in the schema's model description, but no sentence is wasted on 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?

For a non-idempotent, billed, long-running generation tool with no output schema, the description covers what comes back (edited image URL(s) or a taskId), how to resume the job, cost, and timing — everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds meaningful selection semantics on top — which models accept maxImages/resolution, which are slow (~5 min), and cost tiers per model — that the schema's flat enum list doesn't convey. The wait/async distinction is reinforced rather than merely restated.

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 ('Edits an existing image guided by a text prompt') and gives concrete prompt examples that pin down the operation. The 'I2I' framing and the imageUrl requirement make it clearly distinct from the text-to-image generate_image sibling without the agent needing to open 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?

A full model-selection rubric is provided with an explicit default-and-fallback rule ('If the user simply says "edit this image"... default to grok-imagine-i2i'), and alternatives like list_image_models are named. What's missing is when NOT to use this tool at all — e.g. versus upscale_image, reframe_image, or generate_image — which 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?

Goes well beyond the annotations, which only declare openWorld=true and non-idempotent/non-destructive: it discloses credit costs per model, ~45s typical latency vs a 6-15 minute wait budget, the 60s MCP client hazard that can lose the taskId, the 20-credit confirmation threshold, 18+ auto-tagging and adult-gallery routing, and that aspectRatio is required by some upstream providers. Behavior is consistent with the annotations (a paid, non-idempotent, non-destructive generation job).

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 behavior, then clearly sectioned headings for character handling and model selection. It is long, and there is redundancy — gpt-image-2-t2i's 9-credit single-output pitch appears both in the bolded recommendation and again in several signal bullets, which could be collapsed.

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?

There is no output schema, yet the description covers the return contract anyway: final image URLs, a `state` of 'running', the returned taskId/kind, and the exact polling recipe with interval and the aetherwave_get_job handoff. For a 12-parameter, 20+ model tool this leaves nothing an agent needs unstated.

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 on top: it explains which models honor maxImages (vs. ignoring it), how `character` attaches a reference pack and overrides the default model, that referenceImages accepts a bare string, and that aspectRatio must be passed explicitly. The main gap is that `seed`, `resolution`, and `negative_prompt` are only defined as 'some models' without saying which.

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 ('Generates one or more images from a text prompt (T2I) or ... + reference image(s) (I2I)') and describes the full lifecycle (submit, poll, return URLs). It also names the sibling that handles the overlapping case ('prefer the dedicated aetherwave_edit_image tool for "change something in this image" intent'), so an agent can separate the two without opening a 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 an explicit model-selection decision table keyed to prompt signals, a stated default, a fallback to aetherwave_list_image_models, exclusions for I2I ('only when you specifically want style transfer, premium quality, or adult content'), and rules for when to ask the user first. This is about as complete as when-to-use guidance 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 openWorldHint=true, non-idempotent, non-destructive; the description adds the operational traits annotations cannot express — 30–90 s generation time, ~45 s return window, a 6-minute polling budget, and common transient failures. It does not spell out that repeated submissions create separate jobs and spend credits each time, which matters for a non-idempotent 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 purpose and output count, then timing, then failure handling, then the wait/async contract. Slight redundancy with the schema's wait/async/instrumental descriptions and a dense middle sentence about title behavior, but nothing is wasted.

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 12-parameter async generation tool with no output schema, the description covers latency, polling target, failure recovery, defaults and the wait/async choice — enough to call it correctly. It stops short of describing the returned track objects or credit spend per submission, which would complete the picture.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning — default model and equal 20-credit pricing across versions, when a title is honored (lyrics, or instrumental within a 200/1000-char style cap) versus named by Suno, and how the style/title/lyrics combination gates other 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 ("Generates AI music via Suno") plus a concrete output expectation ("Returns two tracks per submission"), which clearly separates it from siblings like aetherwave_generate_speech, aetherwave_generate_image and aetherwave_master_audio. The default model note (V6, same as website) further pins down what the agent gets.

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 on when to use wait vs async, when to poll aetherwave_get_job (and how often), and a concrete recovery path for GENERATE_AUDIO_FAILED (retry once, then degrade model). It also names the condition for setting instrumental and the client-side 60 s constraint that selects the default path.

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 annotations only declare that this writes, is open-world and non-idempotent; the description goes far beyond them with the price discovery order (platform reads the price before spending, returns estimatedCredits), the charge/refund lifecycle, and the three terminal states including the dangerous "unknown" case where the connection dropped and a charge may have occurred. The no-job-id caveat and the double-charge warning on resubmission are exactly the behavioral facts an agent cannot get from 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?

It is front-loaded with purpose, then cost, then failure modes, then the resubmission warning, which is the right order for an agent scanning for go/no-go signals. The pricing parenthetical and refund detail are dense but each clause carries an operational consequence; the single longest sentence could be split for readability.

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?

There is no output schema, and the description compensates by naming the returned fields (estimatedCredits, state with its "failed"/"unknown"/"running" values, refunded) and where artifacts land (the gallery as audio). For a charged, non-idempotent generation call, an agent has everything needed to estimate cost, avoid duplicate charges, and recover from an ambiguous 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 coverage is 100%, so baseline is 3, but the description adds real meaning the schema lacks: the byte-based billing that makes accented and non-Latin text cost up to 3x, worked cost examples (200 chars = 2 credits, 1,000 = 5), and the default voice. The only unstressed parameter is `wait`, whose 3-minute versus ~45 s tradeoff is 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?

"Turns text into a spoken voiceover MP3" states a specific verb, resource and output format, then enumerates concrete use cases (narration, ad read, podcast intro, character line). It also names the sibling that resolves voice questions (aetherwave_list_voices), so the agent can separate this from generate_music and the voice-listing tool without opening a 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 routing rules for the non-obvious cases: scripts over 1000 characters must be split at sentence ends into one call per part, voice lookup goes to aetherwave_list_voices, and a result with state "running" must be retrieved via aetherwave_list_my_creations type "audio" rather than resubmitted. It also names a guard parameter ("pass maxCredits to refuse anything dearer"), leaving little to inference.

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 declare it is a non-idempotent, non-destructive open-world write; the description goes far beyond that with latency ('1-8 minutes'), the near-certain 'running' return state and the ~10s polling cadence, the 60s client-timeout trap behind wait:true, credit cost per second per model, audio surcharge behavior for Kling vs Grok/Seedance/VEO, and the silent-failure warning that a take can return wrong words and still report success. That is exactly the kind of operational hazard an agent cannot infer from 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?

Well front-loaded and organized under headings, with the routing table earning its space. However it is very long and partially redundant: the wait/async mechanics are restated almost verbatim from the schema descriptions, and the cost-framing and dialogue-writing sections drift toward documentation rather than tool selection.

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 13-parameter, no-output-schema, multi-minute asynchronous job, the description covers everything an agent needs: default model, cost drivers, polling protocol, mode-specific requirements, and the failure mode that most needs pre-empting (silent audio, mangled compounds, dropped lines). Nothing material is left to inference.

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 already 100%, so 3 is the baseline, but the description adds real semantics the schema does not: duration is authoritative and the engine fits dialogue by changing pace (~2 words/second), character vs imageUrl mutual exclusivity is explained by mechanism (a first frame drops referenceImages), and generateAudio is tied to a concrete rule (pass true whenever the prompt contains dialogue). The first+last-frame combination of imageUrl + endImageUrl is also stated.

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?

Opens with a specific verb and resource ('Generates a short-form video') and immediately distinguishes the two modes (T2V from a prompt vs I2V from prompt + starting image). It also states the lifecycle ('Submits, polls, and returns the final video URL'), which separates it from the read-only siblings like aetherwave_list_video_models or aetherwave_get_job.

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 an explicit signal-to-model routing table ('highest quality' -> veo3-quality, 'talking head' -> kling-avatar-pro, etc.), names the alternative tool for the full lineup (list_video_models), and spells out escalation conditions ('Ask the user only when: single generation would cost more than 100 credits'). When-not guidance is present too (do NOT use imageUrl for a consistent character).

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 readOnlyHint/openWorldHint it discloses that jobs keep running server-side after a client failure and are saved to the gallery regardless, so a taskId is sufficient to recover a paid render — important operational context for a polling tool. It also maps each kind to the tools that emit it and notes taskId aliases (taskKey for merch_mockup, exportId for comic_export), which 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?

Purpose and polling guidance are front-loaded before the kind reference table, and the bullets are scannable. It is dense and the closing note about audio fallbacks is slightly tangential, but nearly every line carries routing information 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?

There is no output schema, so the description carries the return contract itself — current state plus output URLs once finished — and it also resolves the tool's biggest ambiguity by pinning down taskId aliases and per-kind routing. Nothing required to call it correctly or interpret the response 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: the kind→tool mapping table tells the agent exactly which value to pass for each producer, and it flags projectId as required only for kind 'comic-export'. It largely restates the schema's taskId/projectId wording, which keeps it short of 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?

States a concrete verb+resource (returns current state, then output URLs), scopes it to jobs returned as "running" or submitted with async:true, and explicitly carves out the cases handled by aetherwave_comic_status and aetherwave_list_my_creations. An agent can separate this from aetherwave_merch_mockup_status and the comic tools without opening a 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-to-use (after any async submission, after a client timeout) and when-not-to-use (comic script/draw/assemble goes to aetherwave_comic_status; master_audio and generate_speech have no job id), plus a concrete polling cadence of ~10 s. Alternatives and the conditions selecting them are named outright.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds genuinely non-derivable context instead of restating it. "Free" is a cost disclosure the agent otherwise could not infer, and the per-call limit plus price per 1,000 characters tell the agent this list is also the pricing reference. It stops short of describing ordering or how the default is flagged, which keeps 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?

Three sentences, each earning its place: the free-cost note is front-loaded, the payload contents follow, and the invocation cue comes last. No repetition of the title or the annotations.

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 input parameters and no output schema, the description carries the burden of describing returns, and it does so by listing the fields an agent will receive. The only gap is that it doesn't say how the response is framed (ordering, whether price is per-model or per-voice), but that is a small omission for a simple enumeration tool.

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

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

There are zero parameters, so the baseline is 4 per the rubric. The description correctly implies an unfiltered full dump rather than a paged or queryable listing, which is the only parameter-adjacent meaning left to 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?

The description names a specific verb and a specific resource (every voice aetherwave_generate_speech accepts) and even enumerates what each entry contains (gender, age, accent, manner, default, price, limit). An agent can distinguish this from sibling list tools such as aetherwave_list_image_models or aetherwave_list_characters purely from the relation it draws to generate_speech.

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 it when the user asks which voices exist or which suits a script." That covers the realistic invocation contexts. It does not name an alternative or an exclusion, but for a zero-parameter enumeration tool there is no meaningful competing call to route against, so the omission 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?

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.