Ludo AI Game Assets

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

Annotations only declare the safety quartet (non-read-only, non-destructive, non-idempotent, closed-world); the description adds substantial context beyond that: the call is free/no credits, explicit rate limits (20/5min, 120/hr, 1000/day), the source sheet is left untouched and a new sheet with its own spritesheet_url is produced, and it is an async job returning {id, status} that must be polled via getApiJob. That is the exact information an agent needs before spending a call.

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 correctly: purpose, then source-URL requirement, then the settings rationale, then job/rate-limit mechanics. It is a single dense ~250-word paragraph with no formatting breaks, so the operational details (rate limits, polling contract) are buried mid-block rather than scannable; still, essentially every sentence carries new 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?

Covers everything an agent needs for a nested-payload, no-output-schema async tool: the full result shape (same sprite result as animateSprite — spritesheet_url, video_url, grid fields, optional GIF/frame URLs, audio_url), the async poll contract, credit cost, rate limits, and request_id tagging plus listGenerations retrieval. Nothing material is omitted.

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 and the schema already documents each field thoroughly. The description nevertheless adds usage-level meaning the schema fields don't carry on their own — linking 'frame_size' 0 or a fixed value to recovering content clipped by True Size, and 'use_pixel_grid' false to fixing a wrongly detected grid on a smooth sprite — which is scenario guidance rather than field restatement.

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 resource — re-export a previously generated sprite animation with new sheet settings without regenerating — and explicitly distinguishes itself from editSpritesheet ('cannot change the motion, margins or content - use editSpritesheet for that'), so an agent can route between the two 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?

Gives both when-to-use (fix True Size clipping, change frame count/size, 1.5x upscale, toggle loop trimming, correct a bad pixel grid) and when-not-to-use (motion/margin/content changes go to editSpritesheet). It also states the eligibility precondition for spritesheet_url: must come from animateSprite, animateSpriteKeyframes, transferMotion, editSpritesheet, rotateSpritesheet or a prior adjust, within 7 days; external images rejected.

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

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

Beyond the annotations, it discloses async job behavior, the {id, status} return shape, polling via getApiJob, credit hold/refund rules, a 30MB rejection limit, quality variance, and the exact output artifacts. This adds substantial operational context that annotations alone do not provide.

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 front-loaded: it starts with the core action, then prerequisites, outputs, mode choice, quality expectations, credits, and async polling. Every sentence contributes operational or decision-relevant 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?

For a complex async generation tool with a nested request body and no output schema, the description covers the key prerequisite, input meaning, return shape, polling, credit behavior, and output artifact structure. Remaining parameter details such as loop and augment_prompt are fully documented in the schema.

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 still adds useful meaning by clarifying that model is a rigged GLB asset rather than an AI model name, explaining mode representations, and describing num_variants as candidate animation outputs.

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 gives a specific verb and resource: generating text-driven skeletal animations for an already-rigged 3D model. It distinguishes the tool from rigModel by stating that rigging must happen first, and the 'text-driven' framing separates it from preset-based animation 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?

It clearly states the prerequisite that the model must already have a skeleton and names rigModel as the alternative when it does not. It does not explicitly contrast with animate3DModelPreset or other animation transfer tools, so sibling routing is strong but not complete.

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 is a non-read-only, non-idempotent, non-destructive, closed-world write. The description goes well past that: credits are held on acceptance and refunded on failure/cancellation, the call is async and returns {id, status} that must be polled via getApiJob, and jobs can outright fail when retargeting doesn't take. It also pins the output shape (animation-only GLB in glb_url plus an mp4 preview in the same animations envelope), which the annotations can'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?

It is a single dense block that front-loads the action, then the inputs, then the failure and output behavior, with the credit note last. Every sentence carries information, though the crop_loop/in_place explanations repeat the schema and the paragraph is long enough that the async/polling instruction could get lost.

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 has to carry return values, and it does: {id, status} from the call, glb_url and preview_url in the animations envelope from the finished job. With complexity driven by an async job, credit consumption, and a nested request body, it covers prerequisites, failure handling, polling, and cost — 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 description coverage is 100%, so the schema already documents every field, including the crop_loop and in_place semantics the description largely restates. The one genuinely additive clarification is that model is a 3D asset file rather than an AI model name — a real disambiguation given siblings like create3DModel — plus the note that any preset id is acceptable, but the rest is duplication rather than new meaning.

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: 'Apply a curated animation preset to an already-rigged 3D model (retargeting).' It clearly distinguishes itself from listAnimationPresets (which supplies the preset_id) and from rigModel (a stated prerequisite), but it never explicitly contrasts itself with its closest siblings, animate3DModel and transferMotion, leaving the agent to infer the split.

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?

Prerequisites and sourcing are explicit: the model must be rigged first, via rigModel or create3DModel's rig, and preset_id must come from listAnimationPresets. It also states that any preset id works and that retargeting is not guaranteed, so the agent knows what to do on failure. What's missing is an explicit 'use this instead of X when Y' rule against animate3DModel/transferMotion.

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 establish that this is a non-destructive, non-read-only, non-idempotent job, and the description goes well beyond them: credit hold/refund mechanics, the rule that the loop trim is not deducted, per-model audio behavior (hydra/hydra-plus return audio_url; forge models do not), and the HTTP 400 failure mode for incompatible model/duration pairs. The only reason it is not a 5 is that the credit-rate table largely duplicates the model enum in the schema rather than adding new behavioral insight.

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

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

The purpose and tool-choice guidance are front-loaded, which is good, but the body is a single dense paragraph that mixes output contract, credits, model defaults, sibling routing, and prompt advice. It is informative yet noticeably bloated, with pricing details repeated verbatim from the model enum, so an agent scanning for the key decision points must wade through a wall of text.

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 async generation job with a deeply nested schema and no output schema, the description covers the returned fields (spritesheet_url, video_url, grid layout, optional gif/individual frames/background sheet, per-model audio_url) and the polling contract via getApiJob. Combined with the routing guidance and error behavior, 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 baseline is 3, but the description adds cross-field semantics the per-property schema cannot: incompatible model/duration combinations fail with HTTP 400, and the output's spritesheet is trimmed to its best loop and may run shorter than the video. Most individual parameter hints (prompt style, defaults) restate the schema, which keeps this below a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening states a specific verb and transformation: 'Animate a static sprite into a spritesheet driven by a motion text prompt (image-to-spritesheet)', and immediately names the required inputs (initial_image, motion_prompt) plus the optional final_image interpolation. It explicitly distinguishes itself from animateSpriteKeyframes, transferMotion, and generatePose, so an agent can pick it without opening a sibling 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 'Choosing a tool' section spells out when to use this tool versus transferMotion (reference video or listAnimationPresets preset), generatePose (source not in the starting pose), and animateSpriteKeyframes (up to three keyframes). It also states the default model (hydra), that model/duration must be compatible or the call returns HTTP 400, and that the result should be polled via getApiJob.

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

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

Beyond the annotations (readOnly=false, idempotent=false), the description discloses async job semantics (returns {id, status}, poll getApiJob), the credit hold/refund contract including failure and cancellation refunds, the loop-trim behavior, and the HTTP 400 failure mode for unsupported models. That is substantially more than the annotations convey.

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

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

Purpose is front-loaded and easy to scan, but the trailing credits block restates per-model pricing (Hydra 3/s, Griffin 12 flat, etc.) and LEGACY flags that already appear in the model parameter's schema description. The [LEGACY] pricing detail and the repeated credits/s × seconds explanation add bulk without new decision-relevant 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?

For a complex, multi-parameter async generation tool with no output schema, the description covers the result shape (spritesheet_url, video_url, grid fields, audio_url on hydra/hydra-plus), job polling, credit accounting, and model support. An agent has enough to select the tool, pick a model, and handle the async response 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; the description still adds meaning by stating that initial_image is required as the starting frame, that middle/final are optional additions in order, and that motion_prompt is optional with motion derived from keyframes when omitted. It does not restate the per-parameter enum or margin rules, 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?

The first sentence names the specific verb and resource (animate a sprite through up to three fixed keyframes) and states the output (a spritesheet interpolating the frames in order). It is immediately distinguishable from sibling animateSprite, which the description explicitly contrasts.

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 states when to use this tool versus animateSprite ("For just a start and end frame, animateSprite with `final_image` does the same job", "Use animateSprite instead for the classic single-image + text-prompt animation"). It also constrains model choice (only hydra, hydra-plus, forge, forge-pixel support a middle keyframe; others return HTTP 400) and flags legacy models to avoid.

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 ('Free (no credits)'), execution mode ('synchronous'), retention ('kept 7 days'), and the conditional side effect of persisting items onto a saved 3D model. It also explains conflict resolution (items on a bone a new item takes are dropped) and how keep_saved/save_on_model change the outcome, including the `saved` and `kept` result flags.

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 core action and item limit are front-loaded, and the return-value and persistence rules follow in a logical order. It is a dense single paragraph with parenthetical asides that require a second read, but no sentence is filler.

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

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

With no output schema, the description carries the return contract itself and does so fully: `model_url` as a single GLB, `saved`, and `kept`, plus the 7-day retention window. Combined with the cost, sync behavior, and persistence semantics, an agent has everything needed to call this 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 real meaning: it ties `items` placement to fitDirectionalAccessory output, explains the bone-conflict rule for existing saved items, and clarifies the default behavior of `keep_saved` and `save_on_model` in terms of observable results. It does not cover the model size limit or base64 input form, which remain schema-only.

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 concrete verb+resource ('Put accessories on a rigged 3D model for Directional Sprites') and immediately bounds scope (up to 8 items, placement from fitDirectionalAccessory). It is clearly distinguishable from rigModel, fitDirectionalAccessory, and createDirectionalSprites, which it explicitly names.

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 strong workflow routing: use the `placement` returned by fitDirectionalAccessory, and feed the resulting `model_url` into createDirectionalSprites, createDirectionalStills, or previewDirectionalSprites. It does not state any when-not-to-use case or what to do if no fit has been computed, so it stops just short of full alternative guidance.

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: held credits are refunded, already-running jobs fail with 409, the canceled job is returned, and the call is free. This complements destructiveHint and idempotentHint without contradicting them.

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

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

The key action and refund behavior are front-loaded, followed by the running-job exception, return value, and cost. Every sentence adds useful information with no filler.

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 one-parameter cancellation tool with rich annotations and no output schema, the description covers eligibility, failure behavior, return value, and cost. Nothing essential for correct invocation 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?

The schema already documents the single id parameter clearly at 100% coverage, including that it is the id returned by a generation call. The description does not add further parameter semantics beyond what the schema provides, so the baseline 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: cancel a queued job started through the API or MCP. It also distinguishes cancellable queued jobs from already-running jobs, which an agent needs in order to select it 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?

Clearly says to use this for queued jobs and that running jobs cannot be canceled because they return 409. It does not explicitly name getApiJob as the way to check job status first, so it falls short of full when/when-not/alternatives guidance.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses that the call is free, synchronous with no job to poll, rate-limited (20/5min, 120/hr, 1000/day), capped at 15MB input with HTTP 400 rejection, and that the source image is left untouched while a new image is produced. These are exactly the operational facts annotations cannot convey.

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

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

Purpose and cost model are front-loaded, and nearly every sentence carries new information (defaults, failure modes, limits, return shape). It is a single dense run-on paragraph, though, and a few clauses such as the redundant restatement of the input range could be trimmed 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?

There is no output schema, and the description fully compensates by enumerating the response fields and how to consume them, plus rate limits, size limits, error conditions and request tagging. Nothing an agent needs to invoke 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 already 100%, so the baseline is 3, but the description adds real semantics: `pixel_size` is expressed in input pixels and snaps to whole grid steps, and the no-detect case fails with HTTP 400. It also describes the response fields (`url`, `pixel_size`, `columns`, `rows`) and the nearest-neighbour resize instruction, which the schema does not cover.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('Convert an image to pixel art') and immediately clarifies the accepted input range ('any art, broken AI pixel art or pixel art'), which separates it from generic siblings like editImage or upscaleImage. An agent can tell what this tool does and what it is not without opening the schema.

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

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

It gives concrete conditional guidance: omit `pixel_size` only when the image already has a detectable grid (otherwise HTTP 400), omit `palette_size` to preserve colours, and use `request_id` for later retrieval via listGenerations. It never names a competing sibling tool (editImage, upscaleImage) as an alternative, 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 the write/async profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower, and the description does add real value: credit hold/refund on failure, rig price charged only when the result comes back rigged, and the per-request_id dedupe behavior. What it does not disclose is anything about the polling lifecycle beyond 'poll getApiJob' — no timeout, failure states, or how long credits stay held — and the credit figures are stated twice (inline and in a trailing 'Credits:' line), which muddies rather than clarifies.

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 well — purpose, then return shape, then model choice, then optional controls — but it is a single dense block with genuine redundancy: the credit cost for prop/hero/rig is stated inline mid-paragraph and again in a trailing 'Credits:' sentence, and texture_size/target_num_faces ranges and defaults are repeated verbatim from the schema. The information is valuable but not tight.

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 async, paid, multi-mode generation tool with no output schema, the description covers everything an agent needs to call it correctly: return shape `{id, status}`, the getApiJob polling path (deferring to server instructions for the credit contract), the credit hold/refund model and per-mode pricing, and the interlock between rig and the downstream animate3DModelPreset / createDirectionalSprites tools.

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 earns one step above it by explaining the intent behind parameters rather than restating them — why back_image must be the same subject at the same scale/pose, what joint_naming actually means ('purely a relabel - the skeleton is identical'), and that rig uses the general rigModel rig with no type choice. Several details (ranges, defaults, enum meanings) merely duplicate the schema, which caps it below 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource — 'Convert a source image into a textured 3D model (image-to-3D)' — and immediately declares the output artifacts (GLB model_url plus snapshot image URLs). It also names the sibling it is not (create3DModelImage) and explains what that sibling does instead, so an agent can discriminate 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?

Explicit selection guidance for the model parameter (prop = cheap everyday props, hero = detailed close-up assets but slower/more expensive), plus a hard exclusion: hero 'takes the front image only and rejects a back_image with HTTP 400.' It also routes the agent to create3DModelImage when the source image itself needs to be generated, giving a when-to-use-this vs when-to-use-sibling decision 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?

Goes well beyond the annotations: rejects calls with neither prompt nor image (HTTP 400) and images over 15MB, holds credits on acceptance and refunds on failure/cancellation, costs 0.5 credits, and explicitly declares the async contract (returns {id, status}, poll getApiJob). The request_id dedup note is not a contradiction of idempotentHint=false — the default call is non-idempotent and only request_id opts into reuse — but the description makes that distinction clear.

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 then usage, and nearly every sentence carries operational value (the 15MB/400 limits, the credit hold, the async return shape). It is dense and reads as one long run-on block, so a small amount of structural splitting would help, but there is no filler to cut.

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, yet the description still states the return contract ({id, status}, single image result with a url, not an array) and the polling path. For a one-parameter nested async job tool, an agent has everything needed to call it, poll it, and chain 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 coverage is 100%, so the baseline would be 3, but the description adds semantics the schema does not: the prompt's meaning flips depending on whether an image is supplied, and leaving it out preserves the character as-is. The credit/request_id retrieval behavior is reinforced rather than newly explained.

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 ("make a character image ready to turn into a 3D model") and positions it as the first step of Directional Sprites, distinguishing it from createImage/editImage and from the downstream create3DModel. An agent can tell what it produces and where it sits in the pipeline 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?

Explicit branch logic: prompt only (describes a new character), image only (redraw) or both (prompt becomes edits); omitting the prompt keeps the character unchanged. It also names the downstream consumer (pass the returned url to create3DModel), the retry path (call again for another try), and the retrieval path (listGenerations type image via request_id).

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 the generic non-readonly/non-destructive profile; the description adds the real operational context: async job returning {id, status}, polling via getApiJob, credit hold-and-refund semantics, 2-credit cost, and the 10-second duration cap. The request_id dedup behavior ('re-sending returns the existing job') is disclosed as a conditional, which does not contradict idempotentHint=false since that applies to calls without a request_id.

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 the sibling-routing sentence, and nearly every sentence carries distinct information. The duration cap and the 10-second limit appear twice (description and schema), a minor redundancy in an otherwise tight block.

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 async generation job with no output schema, the description supplies everything needed: return shape, polling path, output file type detection via URL extension, credit contract, and cancellation/refund behavior. Nothing an agent must know to call and follow up 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; the description goes slightly beyond by explaining duration=0 as auto-pick and the request_id tagging/lookup pattern. Most parameter detail (loop, augment_prompt) is left to the schema, which is acceptable but not additive.

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 (produce) and resource (looping background ambiance soundscape) with example inputs, and explicitly distinguishes itself from createSoundEffect, createMusic, and createAudioTransform. An agent can route correctly without opening any sibling 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 an explicit when-to-use rule ('continuous, atmospheric background loops') and names the three alternatives with the condition that selects each. It also tells the agent how to relocate results via listGenerations (type audio), which is a usage pattern, not just behavior.

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: discloses the 15MB cap and the HTTP 400 failure mode, the credit cost (3 credits), that credits are held on acceptance and refunded on failure/cancel, that the result is a single audio asset whose URL extension indicates MP3 vs WAV, and that the call is async and must be polled via getApiJob. The request_id dedup behavior is also spelled out, which is important given idempotentHint=false.

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 the use/create routing decision, and every sentence carries real operational content. It loses a little efficiency by re-enumerating the duration values and the 0-1 strength range that the schema already states verbatim.

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 nested, async, credit-consuming mutation with no output schema, the description covers everything an agent needs: required inputs, size and duration constraints, cost and refund semantics, the shape of the immediate response, the polling tool, and the eventual return format. Nothing material is left implicit.

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 nested requestBody documents every field, including modification_strength's 0-1 range and default, loop, and the full duration enum. The description mostly restates those same facts; the only genuinely additive parameter-adjacent detail is that the result URL's extension signals the output format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Remix an existing audio sample ... into a variation guided by a text prompt') and names the exact kind of input it operates on (sound effect, ambiance, music clip). It explicitly distinguishes itself from the create* audio siblings, so an agent can route 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 an explicit routing rule: 'Use this to transform existing audio you already have; use createSoundEffect, createAmbiance, or createMusic to generate audio from scratch.' It also states the async contract (returns {id, status}, poll getApiJob) and the request_id/listGenerations workflow, so the agent knows both when and how to use 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 only cover the read/write/destructive profile, so the description carries the rest, and it does: async job contract returning {id, status} with polling via getApiJob, credits held per direction on acceptance and refunded on failure or cancellation, and an explicit error case when a preset cannot be retargeted. It does not describe the sheet's grid/fps fields in prose, but those are structured in the result contract already.

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 outcome and the style check, then the animation sourcing rules, then the job and credit model — a sensible ordering. It is dense to the point of being run-on, with several nested parentheticals chained into one long sentence block, which costs it a point, but no sentence is filler.

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 async, credit-consuming generation tool with a nested payload and no output schema, the description supplies everything an agent needs: where each referenced id comes from, the animation exclusivity rule, the one-sheet-per-direction result with spritesheet_url, the {id, status} handle, and the poll target. The only omission, return field details, is covered by the existing job/result conventions it points to.

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 field well; the baseline is 3. The description does add relational meaning the schema only partly captures, notably the mutual exclusivity of the three animation sources and the fact that all directions share frame size, scale and floor so sheets line up, which is the key semantic for why 'directions' is not just a render count.

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: 'render a 3D model into one spritesheet per direction, in a style.' That is immediately distinguishable from siblings like createDirectionalStills (stills, not sheets), previewDirectionalSprites (preview), and adjustSpritesheet (post-processing an existing sheet).

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?

Names the exact prerequisite chain and the sibling tools that serve each role: listDirectionalSpriteStyles for style_id, previewDirectionalSprites to check before committing, and listAnimationPresets / animate3DModel / rigModel for the animation source. It also encodes a hard constraint (at most one of animation_url, preset_id, model_animation) and the fallback (no animation = single frame).

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

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

Beyond the annotations, it discloses the credit model in detail: credits are held per direction on acceptance, charged for returned images, refunded on failure or cancellation, at 0.5 credits per direction. It also spells out the async contract (returns {id, status}, poll getApiJob) and the output ordering guarantee, which the annotations cannot convey.

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

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

Purpose is front-loaded in the first sentence, followed by parameter guidance, output shape, and credit terms in a logical progression. The only waste is the near-duplication between the sentence on held/charged/refunded credits and the closing 'Credits: 0.5 per direction' line.

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 async, credit-consuming, nested-payload tool with no output schema, it covers everything an agent needs: input shape, direction ordering, async lifecycle and polling tool, dedupe via request_id, and full credit and refund behavior. Little is left to guesswork.

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 model, directions, style_id, request_id, perspective and style_params are already fully documented. The description largely restates those semantics (up to 8 directions rendered together, order preserved, request_id retrieved via listGenerations) rather than adding new meaning, so the baseline 3 is warranted.

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 concrete verb and resource: render a 3D model, unanimated, into one large image per direction, in a style, on a transparent background. That distinguishes it from animation-oriented siblings like animateSprite. It never explicitly contrasts with the very similarly named createDirectionalSprites or previewDirectionalSprites, so an agent must infer the difference from the 'no animation'/'stills' wording alone.

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 when-to-use context (static directional stills that can later be fed to animateSprite or editImage) and routes style lookup to listDirectionalSpriteStyles and job polling to getApiJob. What it lacks is an explicit statement of when to choose this over createDirectionalSprites or previewDirectionalSprites, which are the nearest alternatives.

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 non-read-only, non-destructive annotations, it discloses asynchronous submission and polling, initial and final result shapes, multi-image behavior, credit holds, refunds on failure or cancellation, and per-result pricing. It also explains request_id replay and retrieval behavior, making side effects, lifecycle, and costs unusually clear.

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

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

The purpose is front-loaded, and the dense text generally spends its words on selection, lifecycle, and billing. It is somewhat long for one paragraph, and the no-upload-limit aside plus the repeated credit-scaling and per-result pricing statements could be tightened.

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 asynchronous generation tool with nested inputs and no output schema, it supplies the missing workflow: `{id, status}` on submission, polling with getApiJob, URL-bearing job results, request_id retrieval, and credit behavior. Together with the comprehensive schema and sibling-routing guidance, this is enough to select and 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 100%, so the fields are already well documented and the baseline is 3. The description adds operational meaning by tying n to both variation count and cost and placing request_id in a retrieval workflow, although several other parameter mentions merely restate 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 opening sentence gives a specific action (“Generate”), resource (“game-art images”), and input mode (“from a text prompt alone”), while image_type and the optional controls establish scope. A later sentence explicitly distinguishes the tool from generateWithStyle, editImage, and removeBackground.

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 selection rule: use createImage for new images from scratch, generateWithStyle to match a reference style, editImage for modifications, and removeBackground for subject cutouts. It also explains when getApiJob and listGenerations belong in the surrounding workflow.

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 the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false); the description adds substantial context on top: 3 credits per call, credits held on acceptance and refunded on failure/cancellation, HTTP 400 for out-of-range duration, and the async job contract returning `{id, status}` polled via getApiJob. The only gap is a slightly awkward fit between the async job contract and the 'single audio result' phrasing, which the agent must reconcile (job result vs. immediate return).

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 examples, then routing, then constraints, then the async contract – a sensible ordering. It is dense but nearly every sentence carries decision-relevant information; minor waste in restating that the description field is required, which the schema already declares.

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 takes on the burden of explaining returns and does so: an intermediate `{id, status}` job object to poll via getApiJob, and a final single audio result whose .mp3/.wav extension indicates format. Combined with credit and error behavior, an agent has everything needed to call 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 baseline is 3; the description earns an extra point by restating the critical constraints in prose (duration must be 0 or multiples of 10 up to 180, out-of-range gives HTTP 400; loop=true for seamless looping) and by explaining request_id's dual role as a dedup key and a listGenerations filter, which goes beyond the schema's local wording.

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 ("Produce a piece of music from a text description") with two concrete example prompts, so the agent knows exactly what it generates. It also explicitly names the sibling tools it is not (createSoundEffect, createAmbiance, createAudioTransform), making it distinguishable 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 an explicit routing rule: songs and musical scores here, short effects to createSoundEffect, looping backgrounds to createAmbiance, remixing to createAudioTransform. It also notes the optional request_id path for later retrieval via listGenerations, so the full workflow is 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?

With annotations already covering the safety profile (non-read-only, non-destructive, non-idempotent, closed-world), the description adds real value: credits are held on acceptance and refunded on failure/cancellation, the result is a single audio asset whose extension reveals MP3 vs WAV, and the call is async returning {id, status} that must be polled via getApiJob. It slightly under-describes the request_id dedup behavior (re-sending the same idempotency key returns the existing job) that the schema states, which is why it doesn't reach 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-loaded with the core action and examples, then constraints, then sibling routing, then the async/credit contract — a sensible order with nearly every sentence earning its place. It runs long for one tool, and the separated "Credits: This endpoint consumes 2 credits per call" line partially duplicates the earlier credit-hold sentence.

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 async, credit-consuming generation job with a nested request body and no output schema, it covers everything an agent needs: what is produced (single audio URL), required input, duration bounds, looping, idempotency tagging, cost, and how to retrieve the result via getApiJob/listGenerations. Nothing material 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% and every parameter (description, duration, loop, request_id, augment_prompt) is already documented in-schema with ranges and defaults. The description restates the headline constraints (required description, 10s cap, 0 = auto, loop for seamless looping, request_id as a tag), which is convenient but adds no semantics the schema lacks. Baseline 3 applies when the schema carries the weight.

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 and resource ("Produce a short sound effect (SFX) from a text description") with two illustrative examples that remove ambiguity about the input. It explicitly positions itself against four siblings (createAmbiance, createMusic, createAudioTransform, listGenerations), so an agent can distinguish 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 an explicit routing rule: "Use this for short, discrete sounds; use createAmbiance for a continuous looping background soundscape, createMusic for musical pieces, and createAudioTransform to remix an existing audio sample." It also names the follow-up call (getApiJob polling, listGenerations with type audio) and the credit condition, leaving nothing 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?

Goes well beyond annotations: input limits (250 chars, 15MB), HTTP 400 on violation, credit hold/refund behavior, async job contract with polling via getApiJob, and result format. The idempotentHint=false is not contradicted — request_id reuse returns the existing job, but the tool is not idempotent without it. Loses a point only because failure modes beyond validation (e.g., cloning quality/rejection reasons) are unaddressed.

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, then constraints, then sibling routing, then async contract — all in one dense paragraph where nearly every sentence carries distinct information. Slightly overpacked; the credit line is repeated in a separate trailing note rather than integrated.

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 inputs, size/character limits, output artifact and format inference from the URL extension, credit accounting, and the async job lifecycle with the polling tool named. Nothing an agent needs to call this correctly is missing, despite there being no output schema.

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 value the schema lacks: the 15MB sample ceiling, the URL/base64 duality framing, the meaning of delivery ('how the line is said') with an example, and the cross-tool use of request_id as a listGenerations filter.

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 ('Convert text to speech by cloning the voice from an audio sample') and explicitly contrasts with createSpeechPreset (named preset voice) and createVoice (design a new voice). An agent can distinguish this from every nearby sibling 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 an explicit selection rule: 'Use this when you have a reference voice sample to clone', plus named alternatives and the conditions that favor them (preset voice, designed voice). No inference required.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false), and the description adds substantial context beyond them: async job semantics, the {id, status} shape, credit hold/refund on failure or cancel, and HTTP 400 on the emotion/delivery mismatch. However, it asserts that resending the same request_id returns the existing job rather than generating again, which reads as deduplicating behavior and is in mild tension with idempotentHint=false; the description never reconciles the two, so an agent must guess whether the endpoint is safe to retry without a request_id.

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

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

The opening sentence front-loads the core operation and constraints, and the sequencing (constraints, voice families, error behavior, output, sibling routing, async contract) is logical. It is long, though, and repeats the emotion/delivery character limits and the 250-character cap that the schema already carries, so a sentence or two could be trimmed.

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 async multi-step generation job with no output schema, the description supplies everything an agent needs to call and follow up: required fields, character limits, voice-family rules, failure mode (HTTP 400), credit accounting, the {id, status} return, and the polling tool. Nothing material 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% and the nested requestBody already documents every field, including the emotion-vs-delivery mutual exclusivity rule and the 250/50 character limits. The description largely restates those rules rather than adding new semantics, so baseline 3 applies; the only genuinely additive note is that request_id can be reused as a listGenerations filter, which the schema also states.

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 (text-to-speech with a named built-in preset voice) and immediately scopes it against the two sibling creators: createSpeech clones from a sample, createVoice designs from a description. An agent can pick the right tool from the description alone 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?

Explicit 'use this when' condition (ready-made catalog voice, no sample needed) plus named alternatives with the exact condition that selects each of them. It also tells the agent the follow-up step (poll getApiJob) and how to retrieve results later via listGenerations with type audio.

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 past the annotations by disclosing the async job contract (returns {id, status}, poll getApiJob), the credit cost (3 per call), the 7-day provenance requirement, and the return shape (only an audio URL, .mp3 or .wav, no video). It also explains the side effect that audio is attached to the spritesheet and resurfaces as audio_url in listGenerations.

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

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

Front-loads the core action and input provenance, then layers exclusions, output shape, and job/credit mechanics in a logical order. It is dense and long-ish, and the request_id/listGenerations sentences could be trimmed, but nothing is redundant filler.

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 async, nested-parameter, credit-consuming generation tool with no output schema, the description covers eligibility, alternatives, async polling, credit cost, return value, and downstream visibility. Nothing an agent needs to invoke it and interpret the result 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; the description earns more by explaining the provenance constraint on spritesheet_video_url (must come from one of four named tools, within 7 days) and the idempotency plus 'must not reuse a request_id' rule for request_id. It adds less on prompt, which is left as the schema states it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Generate a sound effect for a previously generated spritesheet animation') and immediately ties its input to four named sibling tools (animateSprite, animateSpriteKeyframes, transferMotion, editSpritesheet), which cleanly separates it from createSoundEffect and createMusic. An agent can pick this over its siblings 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?

Explicitly states when NOT to call it: 'Spritesheets generated with the hydra model already come with audio_url, so only call this for forge / forge-pixel output or to replace hydra's sound.' It also excludes external videos and stale spritesheets (older than 7 days), so the eligibility conditions are fully enumerated.

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=false, destructive=false, idempotent=false, but the description adds substantial context they don't: it is an async job returning {id, status} that must be polled via getApiJob, credits are held then reconciled with a refund on failure/cancel, incompatible model+duration pairs return HTTP 400, and re-sending the same request_id returns the existing job. The one gap is it never says whether the job can be cancelled or how long polling typically takes.

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 the most important constraint (image required) are front-loaded, and sentences are dense but purposeful. The trailing 'Credits:' paragraph largely duplicates per-model pricing already present in the model and duration schema fields, and the retired-'griffin' sentence muddies the model naming, so it is not fully waste-free.

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 async, credit-consuming generation tool with no output schema, the description supplies everything an agent needs: required inputs, the {id, status} job shape, the polling tool, the final result fields (video URL and actual duration), and the billing contract. Nothing essential to correct invocation 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 earns above that by surfacing a cross-field constraint the schema only hints at ('The chosen model and duration must be compatible ... return HTTP 400') and by explaining what final_image and request_id actually do for the workflow (start/end frame interpolation, later lookup via listGenerations). It loses a point for referencing a 'griffin' 480p model that does not appear in the model enum, which can confuse model selection.

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 ('Generate a short video clip from a source image and a motion text prompt (image-to-video)') and immediately scopes it against siblings: text-only needs createImage + animation, or createVideoFromReferences for reference images. An agent can distinguish it from createVideoFromReferences, animateSprite and editVideo 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?

Explicit when-to-use and when-to-use-something-else: required image input, redirection to createImage/createVideoFromReferences for other cases, and a dedicated 'Related tools' sentence routing static images, sprite animation and listing. It also warns against legacy models ('do not use them for new work'), which is real selection guidance.

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 mark this as a non-read-only, non-destructive, non-idempotent write; the description adds the real behavioral contract: async job returning {id, status}, polling via getApiJob, HTTP 400 on incompatible model/duration pairs, credit hold-and-refund semantics, and request_id deduplication/lookup. The request_id dedupe slightly softens the idempotentHint=false, but it is framed as an opt-in tracing key rather than a genuine contradiction. Minor loss for the naming muddle where the retired model is called `griffin` while the enum value is `griffin-hd`.

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 sibling differentiation, then behavior, then credit details, so an agent can stop reading early. Slightly over-long because the per-model pricing block duplicates what the schema's `model` enum already documents, and the legacy warning appears twice.

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 everything an agent needs for a nested-payload async generation call: input shape and limits, model negotiation, the async job lifecycle and polling tool, error condition, credit mechanics, and result contents (video URL plus actual duration) even though there is no output schema. Nothing material is left to guess.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning beyond it by explaining the model/duration compatibility constraint and its 400 error, that "default" lets the model choose the aspect ratio, and that request_id both dedupes and serves as a listGenerations filter. The credits paragraph largely restates the model descriptions in the schema, so the added value is real but not maximal.

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 and resource ("Generate a video from 1-5 reference images and a text prompt") and immediately contrasts it with the sibling createVideo ("animates a single source image" vs. composing a new scene). The distinction is explicit enough that an agent can pick the right tool 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?

Gives explicit when-to-use and when-not-to-use guidance: use this for reference-based composition, use createVideo for image-to-video, editVideo to modify a generated video. It also warns away from legacy models for new work, which prevents a costly wrong choice.

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?

Carries the full burden of behavior well beyond annotations: 100-character limit causing HTTP 400, credit hold-and-refund semantics, async job contract ({id, status} then poll getApiJob), and request_id dedupe behavior. The only gap is that it defers the job/credit contract to server instructions rather than restating it, which is acceptable given the pointer. Note the annotation idempotentHint=false is not contradicted — keyed dedupe via request_id is a narrower guarantee.

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 primary action, then constraints, then sibling routing, then async/credit notes — a sensible priority order. It runs long and packs the credit line separately, but nearly every sentence adds information; only the credits sentence is mildly redundant with the held/refunded statement earlier.

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, and the description compensates fully: it describes the returned audio result, the URL and MP3/WAV extension convention, the async polling path, and the credit lifecycle. Nothing an agent needs to call this correctly or interpret the result 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 does add a little beyond the schema: the conditional requirement (text plus voice_description or image), the type enum's human/non-human meaning, and the consequence of exceeding 100 characters. But the field-by-field detail (augment_prompt, request_id, image size limits) is already fully documented in the schema, so no credit 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 ('Design a new voice from a character description... or image') plus the concrete outcome ('have it speak a short line of text, returning a sample'). It also names the two nearest siblings (createSpeech, createSpeechPreset) and the exact axis that separates them, so an agent can disambiguate 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?

Explicitly says 'Use this to invent and audition a voice from a description', then gives when-to-use-otherwise: createSpeech for cloning from an audio sample, createSpeechPreset for named presets. The image-vs-description tradeoff is also spelled out, which is the main routing decision inside the tool.

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 the safety profile (not read-only, not destructive, not idempotent), and the description goes well beyond it: 15MB upload rejection with HTTP 400, credit hold/refund semantics and per-result cost, higher cost with a mask, async {id, status} return followed by getApiJob polling, and the checkerboard-transparency failure mode. These are exactly the operational traits 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?

Front-loaded with the core action and inputs, then mask behavior, then alternatives, then job/credit mechanics — a sensible order. It is dense rather than bloated, though the transparent-background warning and the credit/mask cost are each stated twice, adding slight redundancy.

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

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

With no output schema, the description still supplies the return shape (array of image results each with a url) and the async job envelope {id, status} plus the polling tool. Combined with the cost, size-limit, and mask semantics, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and most of what the description says about mask colors, mask_mode, and prompt caveats is already in the schema. It adds some cross-parameter framing (n controls variation count, request_id tags results retrievable via listGenerations, image_type is unnecessary for recent Ludo-generated URLs) but largely restates 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 specific verb+resource (modify an existing image per text instructions) and immediately names the inputs that define the operation (source image, prompt, optional reference image, optional mask). It also explicitly distinguishes itself from createImage, generateWithStyle, and removeBackground, so an agent can route 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 an explicit routing sentence: use editImage to transform a specific existing image, createImage to generate from text, generateWithStyle to borrow a reference's style, removeBackground for background removal. It also states the mask vs. no-mask condition and the replace vs. erase choice, covering when-to-use and when-not.

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

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

Beyond the annotations, the description discloses that this is an async generation job returning {id, status}, that callers must poll getApiJob, that credits are held and partially refunded, and that "improve" returns HTTP 400 on non-hydra sheets. It also explains audio regeneration behavior and result-shape parity with animateSprite, which is substantial behavioral context not carried by 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?

The description is front-loaded and organized around modes, source constraints, prompt rules, credits, and async behavior. However, it is very long, uses dense sentences, and repeats the credit/pricing information twice, which weakens conciseness.

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 async editing tool with no output schema, the description covers the essential gaps: source validity, edit-mode semantics, prompt requirements, billing and refunds, polling, result shape, audio behavior, and retry guidance. An agent has enough information to invoke it correctly without opening the schema.

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 already 100%, so the baseline is 3, but the description adds useful conditional semantics: prompt is required/optional/not accepted by edit_mode, omitted fields inherit source values, model is ignored for outpaint/fix_loop/improve, and request_id tags results for listGenerations. Some of this repeats the schema, but the cross-parameter interactions add real value.

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, "Edit a previously generated spritesheet," and immediately enumerates the four edit modes. It clearly distinguishes this from generation siblings by requiring a spritesheet_url produced by animateSprite, animateSpriteKeyframes, transferMotion, or an earlier edit.

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 detailed mode-specific usage rules: prompt is required for "prompt," optional for "outpaint," and not accepted for "fix_loop" or "improve"; it also explains source-age constraints, parameter inheritance, and pricing behavior. It does not explicitly contrast this tool with the sibling adjustSpritesheet, so the alternative-routing guidance is not complete enough for 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 only cover the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the real burden and does: credits are held at acceptance, final charge is rate × produced seconds and capped at the requested duration, and failures/cancellations are refunded. It also discloses the async contract (returns {id, status}, poll getApiJob), the default duration behavior, and the actual return values (new video URL plus real duration).

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 source constraint, then credits, then the async contract — a sensible order with no filler sentences. Minor waste in the repeated credit/legacy pricing block at the end, which largely duplicates the model enum descriptions and the API docs pointer.

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 nested-payload mutation job with no output schema, the description still tells the agent the response shape, how to poll, what is billed and refunded, the input provenance requirement, and the default duration semantics. Nothing material needed 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 baseline is 3; the description earns above that by adding a behavior not in the schema — the output inherits the source video's duration unless `duration` is passed — and by framing `request_id` as a way to locate results via listGenerations (type video). The image cap and model names are restated from the schema rather than extended, so it stops short of 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Edit a previously generated video with a text prompt and optional reference images (video-to-video)') and immediately scopes it to griffin-hd output. It explicitly separates itself from the generation siblings by naming createVideo and createVideoFromReferences as the upstream steps rather than alternatives.

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?

States the exact precondition for the `video` input (a URL returned by createVideo, createVideoFromReferences, or a prior edit, generated within 7 days) and an explicit exclusion ('arbitrary external videos are not accepted'). It also names the poll target getApiJob and the sibling tools that produce valid sources, so the agent knows both when to use it and what to do next.

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: free/no credits, synchronous, a few seconds with previews, model hosted for 7 days, and a shared single-slot preview queue where a newer preview cancels an older one that returns without previews. The only shortfall is that 'Nothing is saved' sits somewhat in tension with readOnlyHint=false and a hosted model_url, though in context it clearly means no persistent asset is created.

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 and scope before behavior, and every sentence carries operational information. The parenthetical item lists ('a sword, a gun, a staff, a bow, a shield...') and the axis phrasing make it dense enough that a reader must work through a long block, but little is genuinely 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?

With no output schema, the description fully carries the response contract: `placement`, `checks` with their units, and `model_url`/`previews` when `preview` is not false. Required inputs, size limits (30MB), failure mode (HTTP 400 on oversized file), and preview behavior are all covered for a fairly complex tool.

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

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

Schema coverage is already 100%, yet the description still adds real meaning: `size` is a percentage of the automatic fit, `move` is a percentage of character height along forward/up/out, `turn` is degrees about those axes, and the adjustment is relative to an automatic fit recomputed on every call. It also explains what `checks` measure so the numeric adjustments can be interpreted.

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 ('Fit an accessory to a rigged 3D model for Directional Sprites') and scopes it to one bone of the model. It distinguishes itself from siblings by naming the downstream consumers (attachDirectionalAccessories, previewDirectionalSprites) and contrasting with the creation step (create3DModel with rig).

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 iteration instructions ('call again with the new values until it looks right'), warns of the non-obvious constraint that each call starts from the automatic fit so the full adjustment must be resent, and states the follow-on step (pass `placement` to attachDirectionalAccessories). It also states the tool saves nothing, which tells an agent not to expect persistence before attaching.

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 cover the generic read/write and open-world flags; the description adds the credit contract (held on acceptance, refunded on failure/cancel, cost scales with image count, 0.5 credits per result) and the async job lifecycle (returns {id, status}, poll getApiJob). It also discloses the returned array shape and the request_id dedupe/tagging behavior, which annotations do 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?

Front-loaded with purpose and inputs before the routing advice and job/credit contract, which is the right order. Slight redundancy: the credit model is stated twice ("charge scales with the number of images generated" and the trailing "0.5 credits per result"), costing a little tightness.

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 nested-object, single-required-param async job with no output schema, the description supplies everything an agent needs: input forms (URL or base64), output array contents, the suggested motion_prompt hand-off, the polling endpoint, and the credit implications. 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 the baseline is 3; the description adds real value by explaining the "Other" pose value requires a free-text description, the 1-4 range for n, and that request_id doubles as a listGenerations filter. The only minor gap is that the relationship between `description` and pose="Other" is implied rather than spelled out.

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 ("Re-pose an existing sprite into a new target pose while preserving the character") and immediately constrains the input domain to sprite image types, excluding icons and screenshots. It is unambiguously distinguishable from animateSprite and rotateSprite by naming both siblings in 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?

Gives explicit routing: use this first, then feed the result into animateSprite for best animation quality, and use rotateSprite instead when the goal is a camera-angle change rather than a pose. Also states the negative case (only sprite image types, not icons or screenshots).

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 past the annotations: 15MB upload cap rejected with HTTP 400, credits held on acceptance and refunded on failure/cancellation, cost scaling with result count (0.5 credits/result), and an async contract returning {id, status} that must be polled via getApiJob. This is exactly the operational context an agent needs before spending credits.

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 inputs, then routing, then the async/credit contract — a sensible order. Slightly redundant at the end, where the closing 'Consumes 0.5 credits per result' repeats cost information already implied by the charge-scaling sentence.

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, and the description compensates by describing both the immediate return ({id, status}) and the final job result (array of image results, each with a url). Combined with the credit and validation rules, 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 already 100%, yet the description adds real meaning: n controls variations (1-4), image_type defaults to sprite, request_id doubles as a dedupe key and a listGenerations filter. It stops short of explaining the style_image URL vs base64 trade-offs or enum choice guidance, which stays 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?

Opens with a specific verb and resource (generate new images matching a reference image's style) and immediately specifies the required inputs. It names the exact siblings it is not (createImage, editImage, removeBackground), so an agent can distinguish it 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?

Explicit selection rules: use instead of createImage when style consistency matters, use editImage to change content rather than borrow style, and removeBackground to isolate a subject. It also explains when to pass request_id (later retrieval via listGenerations with type image).

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 readOnly/idempotent annotations: it says the call is free and consumes no credits or generations, explains the team_pool case where auto_topup is null and the owner manages it, and clarifies how credits.available is derived. These are exactly the edge behaviors 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?

Three dense sentences, each doing distinct work: what it returns, how to read the fields, and what it costs / where billing lives. The expensive-generation warning is front-loaded in the action-relevant position.

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 so by defining credits.available, resets_at, team_pool, and auto_topup. For a zero-parameter read tool, an agent has everything needed to call it and interpret 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?

There are zero input parameters, so the baseline of 4 applies; nothing in the description is needed to explain request arguments. It does add meaning about response fields, but that value is better credited under transparency and completeness.

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 (show credit balance, plan, auto top-up settings) and scopes it tightly as a free read-only lookup. It also implicitly separates itself from siblings like getPricing by noting that purchasing credits and changing auto top-up happen in the web app, not here.

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 an explicit trigger: check this before an expensive generation instead of waiting for a 402. It also gives an explicit when-not by routing billing actions to billing_url in the web app.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the two terminal states, what field to read in each, recommended polling cadence, and the long-polling semantics of `wait` including that the call is held and returns early on completion, plus the 60s cap.

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 dense sentences, front-loaded with purpose, then the full polling workflow and the long-poll option. Nothing is padding; every clause carries operational 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?

For a 2-param read tool with no output schema, the description supplies the return-shape story itself ('result shaped exactly like the tool's documented output', 'error' on failure) and the timing behavior. An agent has everything needed to call it correctly and interpret the response.

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 `id` and `wait` are already documented. The description still adds real meaning the schema lacks: the relationship between `id` and the generation tool's 202 response, the early-return behavior of long-polling, and the hard max of 60 for `wait`.

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 ('poll the status of a generation job') and scopes it to jobs 'started by any tool', which cleanly separates it from siblings like listApiJobs (enumeration) and cancelApiJob (termination). An agent can pick 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 when-to-use (call after any generation tool returns {id, status}), the loop condition (repeat until succeeded/failed), and named alternatives for the other outcomes (read `result` vs `error`). No sibling is left ambiguous.

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, non-destructive behavior, and the description adds substantial context beyond them: no credit charge, no job queuing, possible 400 with valid values, unmatched_sections/available_sections reporting, and a warning that whole documents can be tens of thousands of characters. It also flags that the docs sometimes describe UI buttons rather than parameters.

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

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

The purpose and the searchDocs alternative are front-loaded, and nearly every sentence carries operational value (TOC flow, size warning, error behavior, credits). It is long for a two-parameter tool and repeats a little of what the schema already states, but the length is justified by the behavioral detail.

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 nonetheless explains the TOC return shape, partial-section matching results, and error behavior. For a read-only discovery endpoint with two optional parameters, an agent has everything needed to call it correctly and recover from bad input.

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: omitting `doc` returns a table of contents, `sections` is only valid with `doc`, matching ignores case/spacing/punctuation, and REST accepts a comma-separated string. Some of this repeats the schema's own descriptions, keeping 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 specific verb and resource ('browse or read Ludo's own documentation in full') and enumerates the kinds of content covered, then explicitly contrasts itself with the sibling searchDocs tool. An agent can distinguish the two 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?

Explicitly says to call searchDocs first for a specific question and to use getDocs to see what documentation exists or read whole documents/sections. It also names the exact no-parameter TOC flow and the follow-up call pattern, leaving nothing 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations: states the call is free (no credits, no job), works with or without an API key on any plan, and returns live data matching the public pricing page. It also discloses the critical downstream rules (Pro/Studio required for API/MCP/CLI, 402 otherwise, per-generation credit costs, 'unlimited' is web-only, plans purchased in the web app not via API) that an agent needs before advising a user.

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 purpose and value proposition, and every clause carries actionable content — pricing scope, key gotchas, purchase channel, and freshness. It is dense rather than padded, though the long semicolon-delimited enumeration makes it heavier than a leaner version could be.

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, and the description compensates by enumerating exactly what is returned — all plans, both price intervals, credits, seats, concurrency, inclusions/exclusions, top-up brackets, per-call costs and policy rules. An agent knows precisely what it will get and how to use it.

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 takes zero parameters, so there is nothing for the description to disambiguate — the baseline of 4 applies. It correctly reinforces that no input (not even an API key) is required, which is the only invocation-relevant fact.

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 definition of the resource: 'What Ludo's paid service costs and includes,' then enumerates the exact payload (plans, monthly/annual prices, credits, seats, queue concurrency, top-ups, per-call cost, rules). No sibling tool returns pricing, so there is no ambiguity about which tool answers this question.

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?

Clear on when to call it: 'for an agent advising a user' about cost or before telling a user to pay, and clarifies it is a prerequisite lookup for API/MCP/CLI usage since those need a paid plan. It does not name a sibling alternative (e.g. getAccount, getDocs) or state when not to use it, keeping it 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 readOnly/idempotent/non-destructive, but the description adds context those hints cannot convey: it is a synchronous GET with no request body, it is a free discovery endpoint that charges no credits, and it describes the shape of the returned arrays. That is exactly the kind of cost and transport information an agent needs before calling.

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 most important facts — what is listed and what it returns — are front-loaded, and each sentence carries content. The final sentence is somewhat dense with sibling references and the parenthetical field enumeration is long, but nothing is truly redundant.

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 takes on the burden of explaining return values and does so field by field, including the deduplicated perspectives array and directions list. Combined with the cost and transport notes, an agent has everything needed to call this 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?

There are zero parameters, so the baseline is 4 and there is no parameter semantics to add. The description does usefully describe the response fields (id, name, category, description, duration, preview_url), which partially substitutes for the missing parameter detail.

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 ("List the available animation presets") and immediately enumerates the returned dimensions (perspectives, eight compass directions). It also names the sibling tools it complements, so an agent can distinguish it from transferMotion or animateSprite 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?

It states an explicit use case: obtain preset_id, perspective, and direction values that transferMotion requires, plus preset names for animating. It then routes the agent to the concrete downstream alternatives (transferMotion, animateSprite, animate3DModelPreset), leaving nothing 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 already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real value: ordering (most recent first), the web-app exclusion, and that it consumes no credits. It stops short of describing the shape of a returned job record.

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 short sentences, front-loaded with scope and the web-app exclusion before the filtering details. The final sentence largely duplicates schema content, so it is efficient but not waste-free.

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, but the description covers ordering, scope, cost, and filtering behavior — everything an agent needs to invoke it correctly. The only omission, the exact job record fields, is discoverable by following up with getApiJob.

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 both parameters are already documented. The description restates the limit default/cap and the comma-separated status syntax, which reinforces but does not extend the schema (e.g., no note on whether unknown statuses error or are ignored).

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 ('List the generation jobs') plus the exact scope: jobs started through the API or MCP, most recent first, explicitly excluding web-app jobs. That scope statement cleanly separates it from siblings like getApiJob (single job) and listGenerations.

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 context on when this tool applies — you want the jobs you submitted via the API/MCP — and rules out web-app jobs. It does not name getApiJob as the alternative when you need details on one job, so the routing guidance is good but not exhaustive.

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 cover readOnly/idempotent/non-destructive, but the description adds non-obvious context: 'Free discovery endpoint: it does not charge credits' — a cost trait annotations cannot express. It also enumerates what the response contains (id, label, description, family, pixel art flag, thumbnail_url, version, settings, advanced_settings), compensating for the absent output schema.

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

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

Purpose and the free-endpoint/ordering guidance lead; the schema of returned fields is listed densely in the middle. Every clause carries information, but the single long sentence listing seven response fields is heavy and could be tabulated or trimmed.

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, and the description fully documents the return shape including nested setting objects and advanced_settings, plus cost and sequencing. An agent can call it and use the result with no gaps.

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?

Zero parameters, so baseline is 4. The description goes slightly further by explaining downstream semantics (the id is passed as style_id; a setting's name is the key in style_params), which helps the agent chain calls, though this is arguably usage rather than parameter info.

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 ('List the styles Directional Sprites can render a 3D model in') plus scope ('perspectives (camera heights)' and 'eight directions'). Clearly distinguishable from creation siblings like createDirectionalSprites and previewDirectionalSprites.

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 it before previewDirectionalSprites, createDirectionalSprites and createDirectionalStills', naming the three alternatives and the ordering condition. No inference required.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful non-annotation context: the return envelope {items, page, page_size, has_more}, the paging loop condition, and the 7-day expiry of API-originated results with a retention warning. That is meaningful behavioral disclosure, though it stops short of stating rate limits or ordering guarantees.

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 sentences, each carrying distinct payload: purpose/scope, return shape plus paging rule, retention caveat, and sibling handoff. No filler, and the scope statement is front-loaded.

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

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

With no output schema, the description compensates by naming the return fields and the has_more paging contract, and it flags the data-loss risk of expired API results. Combined with annotations covering safety, an agent has everything needed to call and iterate 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 all eight parameters are already documented in the schema, including the search-term semantics and the api 7-day window. The description only summarizes the filter categories (type, source, search, date range) without adding syntax or format detail beyond that 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 ("List your generation history across the API and the web app") plus the filterable dimensions, which immediately distinguishes it from listApiJobs and getApiJob. An agent can identify the tool's role 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?

Explicitly routes the agent away with "For an in-flight job's status use getApiJob instead," and the source enum explanation clarifies when to scope to api vs web vs all. Both the when-to-use and the when-not-to-use are stated.

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: synchronous rather than a job, free/no credits, nothing persisted to generations, frames retained 7 days, multi-second latency, and the 204-no-body cancel behavior. The only gap is that it does not spell out what the `render_3d` payload contains field-by-field. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with a non-persisting preview call, so 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?

Front-loaded with a one-line purpose, then behavior, then response shape, then the recommended workflow — a logical order with no filler. Some sentences are dense run-ons (the response-shape sentence in particular) and could be split for faster parsing, but every clause carries 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 full burden of describing the response and does so: one preview per direction, ordering, `frame_urls` frame counts, and `render_3d` as a handoff to the render call. Combined with the free/non-persisted/latency notes and the cancel semantics, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-referential meaning: the request body takes the same model/animation/camera/style fields as createDirectionalSprites, and `render_3d` from the response is fed back into that sibling unchanged. It also notes direction ordering and that each preview carries 4 frames for an animated model and 1 for a still.

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 ('preview') and resource ('directional sprites'), scopes it ('a few frames ... from each direction asked for'), and explicitly contrasts with the sibling createDirectionalSprites (preview-to-check vs full render). An agent can distinguish it from createDirectionalStills and createDirectionalSprites 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 explicit when-to-use guidance ('to check a style before rendering', 'Preview one or two directions while trying styles and render only once the look is right') and names the alternative render tool. It also states the serialization rule (one preview at a time, starting another cancels the older one), which prevents a common misuse.

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

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

Beyond the annotations, it discloses the async job contract, polling via getApiJob, the single-image result shape, the 15MB upload rejection, and credit hold/refund behavior. It also warns that creative_edit may not preserve pixel identity, which is important behavioral context not covered by 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 purpose and return shape are front-loaded, followed by parameter guidance, sibling alternatives, and async/credit details. Despite being dense, every sentence supports correct selection or invocation of this asynchronous generation tool.

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

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

For an async image-processing job with no output schema, the description covers the result shape, polling destination, upload limit, credit behavior, and sibling alternatives. An agent has enough information to invoke it and handle the returned job 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 schema already defines all parameters. The description adds meaningful context beyond the schema, especially the sprite-animation reason to set creative_edit=false and the request_id retrieval path via listGenerations.

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 gives a specific verb and resource: remove the background from a single image and return the isolated subject on transparency. It explicitly distinguishes this from editImage, createImage, and generateWithStyle, so an agent can select it without opening sibling schemas.

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 states exactly when to use this tool for a dedicated cutout, when editImage is better, and why createImage/generateWithStyle are alternatives rather than substitutes. It also gives concrete guidance on crop and creative_edit, including the pixel-identical sprite 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?

Adds substantial behavior beyond the annotations: credits are held at job acceptance and refunded on failure or cancellation, the operation is async with a poll contract, and rigging is non-destructive to geometry but replaces any prior skeleton so old animations no longer apply. That skeleton-replacement caveat is exactly the nuance a destructiveHint=false annotation does not convey on its own.

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, asset input, and rig types before the behavioral caveats. It is dense but nearly every sentence adds information; the enum lists partly duplicate the schema, which costs a point.

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 states the return shape ({id, status}), the eventual downloadable model_url, and the polling path via getApiJob. Credits, failure refunds, and rig-type retargeting limits are all covered, leaving no obvious gap for a single-parameter async mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents model, rig_type, joint_naming, and request_id in comparable detail. The description mostly restates those enum meanings, with only the 'model is not an AI model name' disambiguation adding marginal value (already present in the schema description). Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+outcome: 'Rig a 3D model: generate a skeleton and skin weights for an existing GLB so it can be animated.' That clearly separates it from siblings that create geometry (create3DModel) or apply existing animation (animate3DModel/transferMotion).

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?

Explains the input asset requirement (URL or base64 GLB), which rig_type applies to which asset, and that animation presets retarget onto any rig type, though not onto every model. It also routes the agent to getApiJob for polling. It does not explicitly name the sibling to use when the goal is creating a model or animating instead, so it falls 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 only say it is a non-destructive, non-idempotent write; the description goes well beyond by disclosing the async job contract (returns {id, status}, poll getApiJob), the credit hold/refund lifecycle with per-image scaling, the result payload shape (url plus applied rotation and elevation), and the request_id dedupe/tagging behavior with a pointer to listGenerations. The request_id reuse behavior sits in mild tension with idempotentHint=false, but only when the same request_id is supplied, so it is additive rather than contradictory.

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

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

The purpose and sibling routing are front-loaded before operational details, and nearly every sentence carries information (types restriction, credits, polling, request_id). It is a dense single paragraph, though, and would read better split into purpose / params / job / billing lines.

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

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

Despite having no output schema, the description specifies the result array contents and the intermediate job object, plus polling and billing semantics. For a nested-payload async generation tool, an agent has everything needed to call it, wait for completion, and account for cost.

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, yet the description still adds value: it enumerates the accepted camera_rotation azimuths (the schema declares no enums) and restates that camera_elevation may be omitted to preserve the current elevation, plus explains the request_id retrieval workflow. It does not add format or syntax details for image beyond what the schema already says.

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+resource+scope: re-render an existing sprite from a different camera viewpoint while preserving character and pose. It explicitly contrasts with generatePose (pose change), animateSprite and transferMotion (animation), so an agent can disambiguate it from the sibling set without opening schemas. It even restricts input types ('only works with sprite image types').

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?

States when to use it ('produce alternate view angles of a character') and names the concrete alternatives with the condition that selects each (generatePose for pose, animateSprite/transferMotion for animation). It also gives an exclusion ('not icons, screenshots, etc.'), leaving nothing 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 cover the safety profile (not read-only, not destructive, not open-world), so the description carries the operational burden and does: credit holding at accept time, minimum 3-second hold floor, final charge = rate × seconds generated, refunds on failure or cancellation, async job returning {id, status} with polling via getApiJob, and the 7-day source restriction. That is exactly the kind of cost and side-effect context an agent needs before committing credits.

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 the source-spritesheet constraint are front-loaded, and the prose is dense with no filler sentences. It is a single long block, though, and the trailing 'Credits: Cost varies by model and duration' line restates cost information already given in detail earlier, which is a small redundancy.

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

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

For a nested-payload, credit-consuming async generation tool with no output schema, the description supplies the full contract: required inputs and their provenance, optional steering parameters, model choice and cost behavior, the 5-second cap, the async job/polling pattern, and even the shape of the result (spritesheet_url, video_url, grid fields, optional GIF/frame URLs). Nothing an agent needs before calling 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 baseline is 3; the description goes beyond by explaining that the image becomes the first frame, that final_image defaults to the first frame for cyclic animations, that prompt controls facing/action placement, and that duration should normally be omitted because the output inherits the source length (capped at 5s, longer sources sped up). It leaves the packaging flags (gif, crop, frames, frame_size, use_pixel_grid) entirely to the schema, which is acceptable given full 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?

States a specific verb and resource — re-render a previously generated sprite animation from a new view — and pins it down with a concrete example (front-facing walk cycle turned into the same walk from the back). It also distinguishes itself from nearby siblings by naming rotateSprite as the way to produce the input image and by listing the source tools (animateSprite, transferMotion, editSpritesheet) whose spritesheet_url it consumes.

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 says when this applies (the same motion and timing seen from a different angle), what input is accepted (a spritesheet you generated in the last 7 days; external images rejected), how to build the required image (call rotateSprite on the first frame), and when to omit duration. It even routes between model options and explains that prompt can steer facing or action direction, 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?

Beyond the readOnly/idempotent annotations it discloses several non-obvious traits: no credit charge, no job queued, ranking is best-first with weak matches dropped, empty results mean the docs don't cover the topic, and the corpus is the end-user web docs so it may describe UI buttons rather than API parameters. The 503 behavior and non-retry advice are exactly the kind of operational context annotations cannot carry.

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 the primary routing instruction, then progressively adds edge cases (empty results, 503, UI-vs-API caveat). It is dense but long for a two-parameter tool, and the sentence restating `n` (default 3, max 10) duplicates the schema verbatim and could be dropped.

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 carries the return contract itself: ranked sections, `doc`/`section`/`content` fields, a hard cap of n sections, and what an empty list signifies. Combined with the cost/failure disclosures, 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%, so both params are already documented (including min/max and examples). The description still adds meaning by framing `query` as a plain-language question rather than keywords, and by tying the response's `doc`/`section` fields back into a follow-up getDocs call; it only repeats the `n` default/max already 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?

States a specific verb and resource ('Search Ludo's own documentation') plus the return shape ('only the few sections that answer it'), and explicitly contrasts with the sibling it is not ('Start here rather than reading whole documents', getDocs for browsing). An agent can distinguish searchDocs from getDocs 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?

Gives explicit when-to-use ('before you generate with it', with concrete example questions), when-not/alternative (browse the table of contents via getDocs, re-read a section via getDocs), and a failure-mode fallback ('If it answers 503 ... call getDocs instead rather than retrying in a loop'). It also tells the agent what an empty result means and how to react (rephrase).

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: states the tool is free (no credits), that the team inspects the referenced jobs' inputs and outputs, that personal data/secrets/file contents must be excluded, and that only one report per issue should be sent. These are meaningful operational facts an agent could not infer from readOnlyHint=false / destructiveHint=false. Slightly short of 5 only because delivery/response behavior is not mentioned.

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 purpose, then exclusions, then prerequisites, then parameter requirements — a logical ordering. It is dense and long for a single-parameter tool, with some repetition of the 'not a model limitation' rule across sentences, but nearly every sentence carries a distinct constraint.

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

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

The tool has one nested requestBody whose fields are fully documented in the schema; the description supplies the policy layer (what qualifies, what to include, what to omit) that the schema cannot. With no output schema and a fire-and-forget submission, 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%, so the baseline is 3, but the description adds rationale and emphasis the schema does not: always include every affected job in job_ids, cap of 10, and the reason ('a report about a result we cannot find cannot be investigated'). It also instructs naming the operation and describing intent vs. actual behavior, which shapes how message should be written.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Report a problem with the Ludo API itself to the Ludo team') and scopes it to the API surface rather than generated output. This clearly separates it from the generation siblings like createImage or animateSprite, which produce the artifacts the description explicitly says are out of scope.

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 when-to-use (API errors, failed/stuck jobs, crashes, doc mismatches, unsupported parameters) and when-not-to-use (model limitations, artifacts, prompt adherence), plus concrete alternatives: retry with a different prompt/model/settings, and call searchDocs before reporting a known limitation. The exclusion list is unusually precise and leaves little room for misrouting.

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 generic annotations, it discloses the asynchronous job lifecycle, HTTP 400 conditions, video-over-preset precedence, reference compression, loop trimming, and model-dependent audio. The unusually detailed billing explanation covers credit holds, final charges, caps, refunds on failure or cancellation, and the fact that loop trimming is not deducted.

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

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

The purpose is front-loaded and most sentences contain operationally useful information, but the definition is a dense, very long paragraph followed by a separate pricing block. It repeats model pricing and selection details already present in the fully documented schema, and separating validation, billing, model choice, and asynchronous behavior into shorter sections would improve scannability.

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

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

The description is comprehensive for a complex, paid asynchronous generation tool with no output schema: it describes both immediate and eventual results, prerequisites, errors, timing behavior, charges, refunds, and polling. An agent has enough context to construct a valid request, choose an appropriate model, and handle the resulting job.

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

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

Although schema coverage is 100%, the description adds important cross-parameter semantics, including the model-dependent duration default, the need to pass a preset's own duration to preserve timing, and validation of the video-or-preset triple and model/duration combination. Some other parameter guidance, particularly model rates and request_id usage, repeats the schema rather than adding new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening precisely states the operation, inputs, and output: transferring motion from a reference video or named preset onto a static sprite to produce an animated spritesheet. It also distinguishes the tool from animateSprite by identifying motion copying versus text-prompt-generated animation.

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 says to use this tool when an existing motion clip or preset should be copied and to prefer animateSprite for animation generated purely from a text prompt. Additional guidance covers hydra versus forge, warns against legacy models for new work, and routes preset discovery, result retrieval, and polling to the appropriate sibling tools.

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: it discloses input validation failures (HTTP 400 for oversized pixels and for >15MB), the credit hold/refund lifecycle, and the async contract (returns {id, status}, poll getApiJob). It also clarifies the result is a single image result with a url, not an array — a detail annotations cannot convey.

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

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

Front-loads the operation and its hard limits, then moves to alternatives, tagging, async flow, and credits — a sensible ordering. It is dense and mostly earns its length, though the parenthetical '(not an array)' and the repeated 2048px cap could be trimmed.

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 async mutation with no output schema, the description supplies everything an agent needs: input constraints, cost, result shape, and the follow-up call (getApiJob) to poll. 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 100%, so the schema already documents both parameters; the description adds the consequence of violating the pixel constraint (HTTP 400 rejection) and explains the practical purpose of request_id (tagging for later retrieval via listGenerations, type image). That is useful reinforcement but largely overlaps the schema text.

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 ('Upscale an image') plus scope: up to 4x, capped at 2048px on the longest side. It explicitly separates itself from createImage and editImage, so an agent can route 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 an explicit when-to-use rule ('raise the resolution of an image you already have') and names the alternatives that make new or changed images instead. The preconditions for using it (source below 2048px, under 15MB) are stated as rejection conditions, which is effectively a when-not rule.

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 say it is a non-idempotent, non-destructive write): it discloses per-second billing, that credits are held on acceptance and refunded on failure/cancellation, that oversized sources fail the job and refund, and that this is an async job returning {id, status} requiring polling of getApiJob. It also gives the concrete cost rate (0.2 credits/second).

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

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

Front-loads the core action and the input constraint before the edge cases and billing. It is however dense and partly redundant, repeating the video eligibility rules already in the schema and stating the cost twice ('Billed per second of video' and 'Credits: 0.2 credits per second').

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 async, credit-consuming mutation with no output schema, the description supplies the missing pieces an agent needs: the eligibility rules, the async contract ({id, status} plus getApiJob polling), the shape of the result (new URL at 2x, same duration, plus duration in seconds), and the credit/refund behavior.

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

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

Schema description coverage is 100%, so both the 'video' and 'request_id' semantics are already documented in structured fields, including the listGenerations lookup trick. The description largely restates these constraints (7-day window, 960px limit, request_id tagging) rather than adding syntax, format, or edge-case meaning beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource plus the exact transformation: 'Upscale a previously generated video to twice its resolution (2x).' It also scopes the accepted input to videos produced by createVideo, createVideoFromReferences, or editVideo, which cleanly separates it from upscaleImage and the creation siblings.

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 selection criteria: use the URL returned by the three generation tools, within 7 days, and only when both dimensions are under 960px. It also names the alternatives ('createVideo for image-to-video, editVideo to modify a generated video') and warns that arbitrary external videos are rejected.

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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral detail by specifying the response codes for valid and invalid keys, though it does not explain how the key is supplied or what response body to expect.

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 short sentences with no wasted language. The primary purpose is front-loaded, followed immediately by the observable outcome.

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 validation endpoint with rich annotations and no output schema, the description covers the essential behavior and result codes. It could be slightly more complete by clarifying how the API key is provided, but the core information needed to invoke and interpret it is present.

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 there is no parameter semantics for the description to clarify. The baseline for a no-parameter tool is 4.

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 validates an API key. No sibling tool performs this function, so the purpose is unambiguous without needing to distinguish it from alternatives.

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 intended use is implied by the name and description: call this when you need to check whether an API key is valid. However, it does not explicitly say when to use it versus related tools such as getAccount, nor does it state any prerequisites or exclusions.

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