Ludo AI Game Assets

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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses that the job is async, returns {id, status}, requires polling getApiJob, holds credits once per call regardless of variant count, refunds on failure or cancellation, and that animation quality is hit-or-miss. It also describes the output artifacts (standalone animation-only GLB in glb_url plus mp4 preview_url) so the agent knows exactly what comes back.

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

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

The description is a single, dense paragraph that is front-loaded with the core purpose and then layers in prerequisites, output format, mode selection, and billing behavior. Every sentence adds useful information, but the length and density could be trimmed slightly for easier scanning.

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

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

Given the tool's complexity—an async, credit-consuming generation job with multiple parameters and no output schema—the description is complete. It explains the return shape ({id, status}), the need to poll getApiJob, the nature of the output artifacts, and the credit contract, leaving no critical gaps for an agent to call and follow up on the tool correctly.

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

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

The input schema already contains detailed descriptions for every inner parameter (loop, mode, model, prompt, request_id, num_variants, augment_prompt), so the schema does the heavy lifting. The tool description largely repeats that information (model must have skeleton, mode options, num_variants default 4) and adds little parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Generate text-driven skeletal animations for an already-rigged 3D model.' It distinguishes itself from rigModel by noting the model must already have a skeleton and that rigModel should be used first. However, it does not explicitly differentiate from close siblings like animate3DModelPreset or transferMotion, leaving that to inference from the tool name.

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

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

The description gives clear context: use it for an already-rigged model with a skeleton, and rig first with rigModel if not. It also explains when to use mode rot_trans vs rot_only and warns against disabling augment_prompt. It does not, however, name alternative animation tools (e.g., animate3DModelPreset, transferMotion) or explicitly state when not to use this 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?

With no annotations, the description carries the full burden and does so: it discloses the async job contract (returns {id, status}, poll getApiJob), the credit lifecycle (held on acceptance, refunded on failure/cancel), the 0.2-credit cost, and the exact result shape (standalone animation-only GLB in glb_url plus mp4 preview_url in the animations envelope). It also explains the behavioral effect of crop_loop and in_place, including the default when omitted.

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 prerequisites, then output/credit contract, then per-flag semantics. Dense but every clause adds operational value. Heavy parenthetical nesting makes it slightly harder to scan than an ideal two-tier structure.

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 no-annotation, no-output-schema async tool, the description supplies everything an agent needs: rig precondition, preset source, async polling path, credit implications, and return fields. 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?

Reported schema coverage is 0%, so the description must compensate, and it does: it clarifies model is a rigged asset file (not an AI model name), that preset_id accepts any id from the presets list, and that crop_loop/in_place fall back to the preset's own flags when omitted. This is meaningful beyond a bare parameter list, though request_id semantics are only partially echoed from 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+resource ('Apply a curated animation preset to an already-rigged 3D model (retargeting)') and immediately distinguishes itself from siblings by requiring a preset_id from listAnimationPresets rather than freeform motion (animate3DModel) or motion transfer (transferMotion). An agent can route to 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?

Gives concrete prerequisites: the model must carry a humanoid-template rig (rig_type humanoid_template or humanoid_template_hands) and the preset_id must come from listAnimationPresets. It also routes the async follow-up to getApiJob. It stops short of explicitly naming the alternative sibling (animate3DModel) and the condition that would select it, so it is strong context rather than full when/when-not routing.

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 no annotations provided, the description carries the full behavioral burden. It discloses side effects (credits refunded), cost (free), a key error condition (running jobs return 409), and the return value (the canceled job). This is substantive and useful, though it omits details like ownership requirements or irreversibility.

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

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

The description is three short sentences with no wasted words. The main action is front-loaded, followed by the refund behavior, the running-job restriction, and the no-cost note. Every sentence earns its place.

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

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

For a one-parameter cancellation tool with no output schema, the description covers purpose, conditions, side effects, cost, and return value. It is reasonably complete, though it could have mentioned where to obtain the job id or how to verify a job is queued.

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 0% and the description does not explain what 'id' refers to beyond 'a job.' The single parameter id is left entirely to inference from the tool name. For a low-coverage schema, the description should clarify the id's source or format, but it does not.

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 clear verb and resource ('Cancel a queued job') and explicitly ties the tool to jobs started through the API or MCP. It distinguishes itself from sibling tools like getApiJob and listApiJobs by focusing on the cancellation action.

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

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

The description gives explicit conditions: queued jobs can be canceled, running jobs cannot (409). It also notes the operation is free. However, it does not mention alternatives like checking status via getApiJob or listApiJobs first, so guidance is strong but not fully comparative.

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 no annotations, the description carries the full burden and succeeds: it discloses async generation, the returned `{id, status}` shape, polling via getApiJob, credit hold/refund behavior, cost (2 credits), and the output URL format. This is rich behavioral context beyond what the schema alone provides.

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

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

The description is front-loaded with purpose and well-structured, moving logically to alternatives, request tagging, async behavior, and credits. It is somewhat long and repeats a few schema details, but every sentence serves practical invocation or selection value.

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

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

Given no annotations and no output schema, the description is complete enough: it explains the async job lifecycle, result format, polling, credit contract, required and constrained parameters, and sibling alternatives. An agent has everything needed to select and correctly invoke the 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 the nested properties in detail. The description restates that `description` is required and that duration is capped at 10 seconds (0 means auto), but adds no syntax, format, or semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Produce a looping background ambiance soundscape from a text description.' It also names the sibling tools it is not (createSoundEffect, createMusic, createAudioTransform), so an agent can distinguish its role without opening other 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 explicitly says when to use this tool: 'Use this for continuous, atmospheric background loops,' and gives three alternatives with their own use cases: createSoundEffect for short discrete effects, createMusic for musical pieces, and createAudioTransform for remixing. The async polling instruction also guides proper invocation.

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 no annotations, the description carries the full burden and does so well: it discloses the 15MB size cap and the HTTP 400 failure mode, the allowed duration values, the credit hold/refund contract, and the async job shape ({id, status}) with polling guidance. The output's file format (.mp3 vs .wav) is also explained via the URL extension.

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 purpose, then constraints, then routing to siblings and polling guidance — every sentence carries operational information. It is dense and long, but no sentence is pure filler, so a 4 rather than a 5.

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

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

For a nested-payload async mutation tool with no output schema, the description covers input constraints, async lifecycle, credit semantics, result shape, and sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what modification_strength controls (0.6 default, departure from the original) and links request_id to the listGenerations (type audio) filter. It largely mirrors the schema's own text, so it stops 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?

The description states a specific verb and resource ('Remix an existing audio sample ... into a variation guided by a text prompt') and explicitly distinguishes itself from the generation siblings (createSoundEffect, createAmbiance, createMusic). An agent can select it correctly 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 an explicit when-to-use ('transform existing audio you already have') and names the three alternative tools plus the condition that selects them ('generate audio from scratch'). It also states the async workflow (poll getApiJob) and the optional request_id/listGenerations tagging pattern.

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 no annotations, the description carries the full burden and does so: it discloses that credits are held for every direction on acceptance and charged only for returned sheets with refunds on failure/cancel, that it is an async job returning {id, status} to poll via getApiJob, and the result shape (one sheet per direction with spritesheet_url, grid fields, fps, render_3d).

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 stays content-dense with almost no filler, though it is a long single paragraph that could be split for scannability. Every sentence still carries actionable information.

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

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

For a complex, annotation-free tool with no output schema, the description covers inputs, cross-tool prerequisites, async job contract, credit/refund behavior, and return payload — 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 property descriptions are rich for the nested fields, but the description adds relationship-level meaning the schema does not: the mutual exclusivity of animation_url/preset_id/model_animation, the rig requirements, and how directions render together on a shared frame/scale/floor. It largely complements rather than repeats 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 concrete verb+resource+output: 'render a 3D model into one spritesheet per direction, in a style.' This clearly distinguishes it from createDirectionalStills (stills) and previewDirectionalSprites (preview) without needing 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 to prerequisites and alternatives: use create3DModel with rig or rigModel for a rigged model, listDirectionalSpriteStyles to pick style_id, previewDirectionalSprites to check first, and the animate tools for animation_url/preset_id. It also states the 'at most one animation' exclusion.

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 no annotations present, the description carries the full burden and does so well: it declares the async job contract (returns {id, status}, poll getApiJob), the credit lifecycle (held per direction at acceptance, charged for returned images, refunded on failure/cancellation), the 0.5 credits-per-direction cost, render-together ordering guarantees, and the rest-pose/no-animation constraint.

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 followed by parameters, workflow links, credit contract, and async contract in a logical order. It is dense and runs long, but nearly every clause carries operational information an agent needs; only the repeated credit restatement at the end is mildly 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?

No output schema exists, yet the description states the return shape (one image per direction, in requested order), the job envelope ({id, status}), and how to poll it. For a nested-body, async, credit-consuming tool with no annotations, nothing essential 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 description adds meaning beyond the field list: `directions` are 'rendered together so they line up' and returned 'in the order asked', `model` accepts a URL or base64 GLB, and `request_id` is described as a dedupe key and a listGenerations filter. The nested schema also documents these fields, so the description reinforces rather than rescues them; the per-direction credit cost is the main added semantic.

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 ('render a 3D model as it is (no animation) into one large image per direction') plus the key modifiers: style and transparent background. It is immediately distinguishable from animation siblings (animate3DModel, animateSprite) and from previewDirectionalSprites, which it implicitly supersedes for actual generation.

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

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

Explicitly routes to listDirectionalSpriteStyles for valid styles, animateSprite for animation, editImage for editing, getApiJob for polling, and listGenerations for retrieval. It gives clear context for the surrounding workflow but never states when NOT to use this tool (e.g. previewDirectionalSprites as the cheaper dry run), so a sibling remains unaddressed.

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 no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses async job nature (returns {id, status}), polling via getApiJob, credit hold/refund policy, per-result credit cost, and that n controls number of variations. It also notes no source image means no upload size limit.

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

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

The description is front-loaded with the core purpose and then proceeds logically through parameters, result format, credit behavior, and sibling alternatives. It is slightly dense but every sentence contributes useful information; minor tightening could improve readability.

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

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

Given a nested schema with 100% coverage, no output schema, and no annotations, the description supplies the missing operational context: async job contract, credit mechanics, request_id usage, and sibling differentiation. Nothing essential for correct invocation appears to be 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 all parameters in detail. The description repeats key parameters (n, image_type, art_style, perspective, aspect_ratio) but adds little syntactic or semantic detail beyond what the schema provides, meriting the baseline 3.

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 (Generate) and resource (game-art images) and explicitly distinguishes itself from siblings by naming generateWithStyle, editImage, and removeBackground and their distinct purposes. An agent can immediately tell it creates new images from text rather than editing or stylizing.

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

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

Provides explicit when-to-use guidance: 'Use createImage to make new images from scratch; use generateWithStyle to match a reference image's art style, editImage to modify an existing image, and removeBackground to cut out a subject.' Also instructs to poll getApiJob for async results.

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 no annotations, the description carries the full burden and does so: async job semantics, credit hold/refund on failure or cancel, 3-credit cost, HTTP 400 on out-of-range duration, and result payload shape (URL whose extension indicates MP3 vs WAV). It even points to the server instructions for the job/credit contract.

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 result shape, then constraints, then alternatives. Dense and mostly earned, though the duration enumeration and some parenthetical detail push it long enough that a tighter version would lose little.

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 request body, the description covers result format, error behavior, cost, cancellation/refund, and the polling endpoint, deferring only the generic job contract to server instructions. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds behavioral meaning beyond the schema: the allowed duration values, that 0 means auto, and that out-of-range values return HTTP 400. The request_id tagging/lookup semantics are also reinforced, though augment_prompt is left entirely to the schema.

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

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

States a specific verb+resource ('Produce a piece of music from a text description') with concrete examples, and explicitly distinguishes itself from three named siblings (createSoundEffect, createAmbiance, createAudioTransform). An agent can route correctly 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 ('songs and musical scores') and when-to-use-something-else, naming each alternative and its domain. Also documents the optional request_id + listGenerations lookup workflow and the async poll path 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?

No annotations, so the description carries the full burden and does so: it discloses the credit-hold and refund-on-failure/cancel policy, the 2-credits-per-call cost, and the async contract (returns {id, status}, poll getApiJob). This is well beyond what the schema conveys.

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 output format are front-loaded before routing and job/credit details. Some sentences (the sibling routing run-on, the request_id clause) are dense, but nothing is padding.

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

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

With no output schema, the description explains the return shape (audio URL, MP3 vs WAV by extension), the async job envelope, and how to poll. Combined with annotations absent, everything an agent needs to call and follow up 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?

Schema coverage is 100%, so the baseline is 3. The description restates duration cap/0-semantics and loop behavior that the schema already documents, and its request_id note (locating via listGenerations) largely mirrors the schema text, adding little new semantics.

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

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

States a specific verb+resource ('Produce a short sound effect from a text description') with concrete examples, and explicitly distinguishes itself from createAmbiance, createMusic, and createAudioTransform. An agent can pick it out without reading 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 use condition ('short, discrete sounds') and names three sibling alternatives with the condition that selects each (ambiance = continuous looping background, music = musical pieces, audio transform = remix an existing sample). Routing is fully specified.

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 no annotations, the description carries the full behavioral burden and does so well: it discloses the async job contract ({id, status}), the need to poll getApiJob, the 3-credit cost, idempotency behavior, the 7-day input validity window, attachment of audio to the spritesheet, and that only an audio URL is returned. It also explains how the result surfaces later 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?

The description is long but front-loads the purpose, then layers usage rules, behavioral contract, and credit cost in a logical order. It is dense and mostly earns its length, though some schema-covered constraints are repeated and could be trimmed without losing meaning.

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 no annotations and no output schema, the description covers every element an agent needs: valid input source, optional parameters, idempotency, job polling, return shape, cost, and downstream visibility. Nothing critical 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 the nested requestBody, spritesheet_video_url, prompt, and request_id. The description mostly repeats those constraints, adding only a minor clarification that request_id must not have been used for another generation; it does not add enough beyond the schema to lift the 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: 'Generate a sound effect for a previously generated spritesheet animation.' It immediately distinguishes this from general sound-effect tools by tying the input to a specific spritesheet video URL, and names the sibling tools that produce that input.

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

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

Gives explicit when-to-use and when-not-to-use guidance: only call for forge / forge-pixel output or to replace hydra's sound, because hydra spritesheets already include audio_url. It also rules out arbitrary external videos, leaving no ambiguity about valid invocations.

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 no annotations, the description carries the full behavioral burden and does so: it discloses the async contract (`{id, status}`, poll getApiJob), the credit hold/refund policy (never charged more than requested duration, full refund on failure or cancellation), the HTTP 400 incompatibility failure mode, that audio is bundled with no separate step, and the actual return values (video URL and produced 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 the image requirement, then alternatives, then behavior. It is dense but mostly earns its length; the per-model credit/shortest-duration list duplicates the `model` field description verbatim and could be dropped without loss.

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-request async generation tool with no output schema, the description supplies everything needed: required input, compatibility constraint, job lifecycle, polling target, cost model, refund behavior, and the shape of the result (video URL plus duration).

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 a 3 is the baseline; the description earns above that by adding cross-parameter semantics the schema cannot express, notably that `model` and `duration` must be compatible or the call returns HTTP 400, and that `request_id` doubles as a listGenerations filter. It otherwise largely restates what the schema fields already document, including the per-model credit table.

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') and immediately distinguishes itself from siblings by naming createImage and createVideoFromReferences as the paths for text-only or reference-based generation. An agent can tell this apart from 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-not-to-use: a source `image` is required, and if the agent has only text it is told to call createImage first or switch to createVideoFromReferences. It also enumerates related tools (createImage, animateSprite, listGenerations) with the condition that selects each.

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

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

No annotations are supplied, so the description carries the full burden and does so well: async job contract ('returns {id, status}', poll getApiJob), credit hold/refund semantics including failure and cancellation, HTTP 400 on incompatible model+duration, and higher per-second rate than createVideo. This is far more than the schema conveys.

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 sibling differentiation are front-loaded, and the pricing/credit paragraph carries real decision value. However, the per-model credits/s line duplicates the schema's model enum descriptions almost verbatim, which is the one segment that does not earn its space.

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

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

For a nested, async, credit-metered generation tool with no output schema, the description supplies the return contract (video URL + actual duration), the polling path, and the cost model, so an agent has everything needed to invoke and follow up correctly.

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

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

Schema description coverage is 100% and each parameter (model, images, duration, request_id, aspect_ratio) is already fully documented with enums, defaults, and examples. The description largely restates this ('Choose the output shape with aspect_ratio', request_id tagging via listGenerations) and adds little syntax or format detail beyond it, so the baseline 3 applies.

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

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

Opens with a specific verb+resource+modality ('Generate a video from 1-5 reference images and a text prompt (references-to-video)') and immediately contrasts it with createVideo ('which animates a single source image'), making the boundary unambiguous.

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

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

Explicitly routes the agent: 'Related tools: createVideo for image-to-video, editVideo to modify a generated video,' and states the distinguishing condition (composing a new scene vs animating one image). When-to-use and the alternatives are both named.

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?

No annotations are provided, so the description carries the full burden and does so richly: upload/validation behavior, the 15MB rejection with HTTP 400, credit-hold/refund semantics, charge scaling with output count, and the async job contract ('returns {id, status}', poll getApiJob). This is exactly the behavioral detail a write/generation tool needs.

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

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

Well front-loaded (core action first, then parameters, then alternatives, then job contract and credits). It is long but nearly every sentence carries routing, behavioral, or contract information; only minor tightening is possible.

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 nested-object generation tool with no output schema, the description covers inputs, alternatives, return shape, polling, credit contract, and an error case. An agent has everything needed to call it and handle the async result.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: n controls edited variations, request_id tags results retrievable via listGenerations, reference_image supplies style/content guidance, and augment_prompt's behavioral caveat. It goes beyond restating field labels.

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 according to text instructions') and immediately distinguishes itself from named siblings createImage, generateWithStyle, and removeBackground. An agent can route correctly 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?

Explicitly gives the when-to-use condition ('transform a specific existing image') plus a contrast against three alternative tools with their own use conditions. Nothing is left 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?

With no annotations, the description carries the full burden and does so well: it discloses the async job contract ({id, status} + polling getApiJob), the 7-day source constraint, the duration inheritance rule, and the credit hold/refund mechanics including the failure and cancellation cases. This is exactly the behavioral context an agent needs for a mutation job.

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

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

Front-loaded with purpose and input constraints, and every clause is informative. However, the trailing credits paragraph duplicates pricing/legacy-model information already present in the schema's model description, adding some 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 an async generation job with no output schema, the description supplies the return shape (new video URL and actual duration), the polling path, and the billing contract. Nothing essential to invoking or interpreting the job is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds real meaning beyond the schema, notably that output duration follows the source unless a duration is supplied and that reference images guide the edit. The maxImages and request_id semantics largely restate the schema descriptions, keeping it out of the top band.

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 (edit) and resource (previously generated video) plus the modality (text prompt + optional reference images, video-to-video), and names the sibling tools that produce acceptable inputs (createVideo, createVideoFromReferences). An agent can distinguish this from createVideo/createVideoFromReferences 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?

Explicitly states the precondition (the video must be one you generated in the last 7 days; arbitrary external videos are rejected), points to the related generation tools, and names the alternative paths. Both when-to-use and when-not-to-use are covered.

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 no annotations, the description carries the full burden and discloses async job semantics ({id, status} return, poll getApiJob), credit mechanics (held then refunded, 0.5 credits per result), and the shape of the result array (image url, pose, description, suggested motion_prompt). This is exceptionally complete for a creation tool.

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

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

Front-loaded with the core purpose and dense with relevant detail; nearly every sentence earns its place. It is somewhat long, but the length is justified by the async, credit, and workflow context.

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 describes the return value and async polling pattern; credits, constraints, and sibling workflow are all covered. 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; the schema already documents all nested parameters. The description repeats the key params (image URL/base64, pose, n=1-4) and adds little beyond that, though it confirms request_id ties to 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?

States a specific verb and resource ('Re-pose an existing sprite into a new target pose while preserving the character') and distinguishes it from siblings by naming animateSprite and rotateSprite as adjacent steps. An agent can select 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?

Explicitly states constraints ('Only works with sprite image types (not icons, screenshots, etc.)') and workflow placement ('typically the first step before animating'), plus a direct alternative ('use rotateSprite instead when you want to change the camera angle'). Nothing is left 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?

With no annotations, the description carries the full burden and does so: upload/validation of style_image, 15MB rejection with HTTP 400, credit hold on accept and refund on failure/cancel, charge scaling with images produced, and the async `{id, status}` return contract. This is unusually rich behavioral disclosure.

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 the async/credit contract. It is long and slightly redundant with the schema's parameter descriptions, but nearly every sentence adds operational value.

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

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

No output schema exists, yet the description still specifies the return shape (`{id, status}`) and the polling path, plus credit semantics and the upload size limit. Given the nested requestBody and single-parameter signature, 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 already 100%, so the baseline is 3, but the description adds cross-tool meaning the schema lacks: request_id tags results for later listGenerations(type image) retrieval, and n (1-4) controls variations. Some overlap with schema text (style_image URL/base64, image_type default) keeps it from 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+resource ('generate new images that match the visual style of a reference image') and immediately names the key inputs. It is distinguishable from createImage, editImage, and removeBackground, which are all named and contrasted.

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 routing: use this instead of createImage when style consistency matters, use editImage to alter content, and removeBackground to isolate a subject. It also tells the agent to poll getApiJob for the async result and mentions listGenerations for retrieval.

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 no annotations provided, the description carries the full burden and does so well: it states this is a 'free read-only lookup (no credits, no generation)' and explains team_pool and auto_topup null behavior, which is not inferable from the tool name or schema.

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

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

The description is compact yet information-dense, leading with the core purpose and then adding only necessary details: field semantics, team-pool behavior, a direct usage trigger, and the billing URL. Every sentence earns its place.

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

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

Given no output schema, no annotations, and zero parameters, the description is remarkably complete: it explains return values, edge-case behavior, cost implications, and the correct workflow. An agent can safely invoke this tool without guessing.

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)Skip, so the description appropriately requires no parameter explanation. The baseline for a zero-parameter tool is 4, and the description does not need to compensate for any schema gaps.

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 ('Show') and resource ('your account's credit balance, plan and auto top-up settings'), and names the exact fields returned. It is clearly distinguishable from the generative sibling tools because it describes a read-only account lookup.

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

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

The description gives explicit guidance on when to use the tool: 'Check this before an expensive generation instead of waiting for a 402.' It also tells the agent when not to use it for billing actions, directing those to the web app at billing_url.

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 no annotations, the description carries the burden and does it well: it reveals polling semantics, terminal states (succeeded/failed), result/error fields, blocking behavior up to wait seconds, and early return on completion. Minor omission: no mention of authentication, rate limits, or behavior for unknown ids, but core runtime behavior is transparent.

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 with no filler: action, workflow, and polling strategy are each front-loaded in their sentence. Every clause earns its place, and the parenthetical limits are efficient.

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

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

Despite no output schema or annotations, the description explains the full call contract: when to poll, what statuses indicate completion, how to read result/error, and how long a wait may block. For a simple two-parameter polling tool, nothing essential 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 a baseline of 3 applies, but the description adds real value: it ties id to the id returned by generation calls and explains the wait parameter's long-polling effect and default return behavior. This exceeds the schema's bare parameter definitions.

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

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

The description opens with a specific verb+resource pair, 'Poll the status of a generation job', and explains the job lifecycle with {id, status}. This clearly differentiates it from sibling tools like cancelApiJob and listApiJobs, which deal with cancellation and listing rather than status polling.

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

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

It explicitly states when to call this tool: after any generation tool returns {id, status}, poll until terminal. It also gives polling cadence and long-poll guidance. It does not explicitly contrast with siblings (e.g., when to prefer listApiJobs or cancelApiJob), but the intended usage is unmistakable.

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 no annotations provided, the description carries the full burden and executes excellently. It discloses the read-only and free nature ('does not charge credits and does not queue a job'), the exact response structure for the no-parameter call, partial-match behavior via 'unmatched_sections' and 'available_sections', the 400 error with valid values for retries, the case/spacing/punctuation-insensitive matching semantics, and the size warning about tens of thousands of characters.

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

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

The description is long but dense, with every sentence earning its place: what the tool does, sibling differentiation, a content-parity caveat, the browse workflow, a size warning, matching/error semantics, and cost behavior. It is front-loaded with purpose before details, and the structure flows logically from overview to edge cases.

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 no annotations, so the description must explain return values, cost, and failure modes on its own — and it does. It covers the TOC structure (id, label, section titles, no bodies), partial and total failure responses, how to retry once, and the fact that this endpoint costs nothing and queues no job. An agent has everything needed to invoke it correctly across all edge cases.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely useful semantics beyond the schema: that the no-parameter call returns a table of contents listing document ids, that sections should be copied from that TOC, that sections is only valid together with doc, and the REST comma-separated string caveat. It also explains the fallback behavior when titles don't match, which the schema does not address.

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: 'Browse or read Ludo's own documentation in full' and enumerates concrete use cases. It explicitly distinguishes itself from the sibling searchDocs by contrasting behaviors ('To answer a specific question, call searchDocs first' vs 'Use getDocs to see what documentation exists, or to read a whole document or named sections').

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

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

The description gives explicit when-to-use guidance, naming the alternative tool and the condition that selects it: 'To answer a specific question, call searchDocs first'. It also provides a concrete invocation workflow (call with NO parameters for the table of contents, then re-call with doc/sections) and a practical rule about preferring named sections over whole-document fetches.

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?

No annotations exist, so the description must carry the behavioral load, and it does well: it discloses the synchronous GET with no request body, that it is a free discovery endpoint that charges no credits, and the exact return shape. It stops short of auth requirements or rate-limit behavior, but the cost and call-mechanics disclosures are meaningful additions.

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

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

Front-loaded with what is listed and the call mechanics, with no filler sentences. It is on the dense side, packing the full return contract into one paragraph, but since no output schema exists every clause earns its place.

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

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

With no output schema present, the description supplies the return contract (animations array fields, perspectives array, directions list) and the caller's downstream routing. For a zero-param discovery endpoint this is complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly conveys that no inputs are needed.

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 ('List the available animation presets') and enumerates exactly what the response contains, including the eight compass directions. An agent can distinguish this discovery tool from the animation siblings it names 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 ('to obtain the preset_id, perspective, and direction values that transferMotion needs') and names three concrete alternative consumers (transferMotion, animateSprite, animate3DModelPreset) with the scenario each fits. Nothing about routing is left 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?

With no annotations provided, the description carries full responsibility. It explicitly says this is a 'free read-only lookup (no credits, no generation)', discloses ordering, defaults, and the limit cap. This is strong transparency for a safe read operation.

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

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

Three concise sentences, each earning its place: scope and ordering, safety and cost, then filtering and limit behavior. No filler or redundant 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?

For a simple list operation with two optional parameters and no output schema, the description covers everything needed: scope, order, exclusions, read-only nature, filter syntax, default limit, and cap. Nothing essential 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 both parameters. The description repeats the comma-separated status behavior and the 50/100 limit without adding new parameter-level meaning, making the baseline 3 appropriate.

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

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

The description states a specific verb ('List'), a specific resource ('generation jobs' started through API/MCP), and ordering ('most recent first'). It also excludes web-app jobs, which clearly distinguishes it from getApiJob 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?

It gives clear context for when the tool applies: listing API/MCP-started generation jobs, not web-app jobs. It does not explicitly name alternatives like getApiJob or listGenerations, but the scope is precise enough for an agent to route correctly.

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 no annotations provided, the description carries the full behavioral burden and does so well: it discloses that the endpoint is free/does not charge credits, and it enumerates the returned fields (id, label, description, family, pixel-art flag, thumbnail_url, version, settings and advanced_settings). It does not mention auth requirements or rate limits, so it falls just short of a 5.

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

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

Front-loads the purpose, then the return shape, then the usage guidance. The field enumeration is dense but earns its place because there is no output schema. Slightly long, but no redundant sentences.

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

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

No output schema and no annotations exist, so the description must cover return values and behavior; it describes the returned fields and the settings structure in detail and states the free/cost behavior. Nothing an agent needs to call this no-arg discovery tool 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?

The tool takes zero parameters, which sets the baseline at 4. The description still adds useful cross-tool semantics by explaining that each style's id is 'passed as style_id' and that setting names are 'the key in style_params', clarifying how the output maps onto other tools' inputs.

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

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

States a specific verb and resource: 'List the styles Directional Sprites can render a 3D model in, with the perspectives (camera heights) and the eight directions.' It also names the sibling tools it feeds (previewDirectionalSprites, createDirectionalSprites, createDirectionalStills), so an agent can distinguish it from the create/preview 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 routes usage: 'Free discovery endpoint: it does not charge credits. Use it before previewDirectionalSprites, createDirectionalSprites and createDirectionalStills.' This tells the agent both the cost profile and the correct ordering relative to 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the pagination contract (has_more-driven paging), output shape, and the 7-day expiration of API-originated results. It does not mention sorting or error behavior, but the disclosed behaviors are substantial.

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?

Each sentence earns its place: scope/filters, pagination protocol, retention warning, and alternative routing. It is front-loaded with the core purpose and contains no filler or repetition.

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

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

Despite having no output schema and no annotations, the description tells the agent what the response looks like, how to page through results, that results may expire, and which sibling tool to use for a different need. That is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's first sentence summarizes filter capabilities but does not add meaning beyond the schema. The only meaningful extra information is the pagination/output shape, which is behavior rather than parameter semantics.

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

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

The description names a specific verb and resource: listing generation history across API and web app. It also gives the exact filtering dimensions (type, source, text, date), making the tool's scope immediately identifiable and distinct from job-status 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?

The description explicitly routes in-flight job status checks to getApiJob instead, and it warns that API-originated results expire after 7 days so the agent knows when to download. This gives clear when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the full burden and delivers: synchronous call (not a job), free/no credits, nothing written to generations, frame images retained 7 days, several-second latency, and single-flight concurrency where a new preview cancels the running one and it answers 204 with no body. That is exactly the behavioral context an agent needs.

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 response shape, then cost/retention, then concurrency caveat, then guidance — a sensible order with no filler. Mild redundancy between the opening 'check a style before rendering' and the closing 'render only once the look is right' keeps it from a 5.

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

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

No output schema exists, and the description fully covers the return shape (one preview per direction in the order asked, each with frame_urls and render_3d, the latter feeding straight back into createDirectionalSprites). Cost, retention, timing, and concurrency edge cases are all present, so nothing needed 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?

Individual field docs live in the nested schema, but the description adds real cross-tool semantics by stating it takes the same model/animation/camera/style fields as createDirectionalSprites, and explains how input translates to output (4 frames for an animated model vs 1 for a still). It stops short of covering defaults or per-field constraints for directions, style_params, and size parameters.

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 (preview Directional Sprites) plus scope: a few frames of a 3D model in a style, from each requested direction, to vet a style before rendering. It explicitly positions itself relative to createDirectionalSprites, so an agent can tell the two apart without opening either schema.

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

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

The closing line gives direct when-to-use guidance: preview one or two directions while iterating on styles, then render with createDirectionalSprites only once the look is right. The alternative tool is named and the condition that selects it is explicit.

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 no annotations or output schema, the description carries the full burden and fully delivers. It discloses async job behavior, polling via getApiJob, the single-image URL result, upload validation, a 15MB HTTP 400 rejection, credit holding/refunding, and the 0.5 credits per result cost. There is no contradiction with any annotation.

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

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

The description is long but every sentence earns its place: purpose, parameter guidance, output shape, error behavior, credit handling, sibling routing, and async polling. It is front-loaded with the core purpose and structured so an agent can quickly extract the key call semantics.

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

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

For a tool with nested requestBody, async execution, no output schema, and no annotations, this description covers all essential operational details: how to supply the image, what the result looks like, how to retrieve it, failure behavior, and cost. Nothing critical for correct invocation is left unspecified.

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 the schema already documents all parameters at 100% coverage, the description adds meaningful guidance beyond the schema: creative_edit's pixel-identity tradeoff, request_id's role in retrieving results via listGenerations, and crop's trimming behavior. This gives the agent practical decision-making information rather than just schema repetition.

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: 'Remove the background from a single image, returning the subject isolated on a transparent background.' It also explicitly contrasts this tool with editImage, createImage, and generateWithStyle, so an agent can distinguish it from relevant siblings without guessing.

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 says 'Use removeBackground for this dedicated cutout task' and names editImage as the alternative for broader edits, plus createImage/generateWithStyle as generation-only tools. It also gives a concrete condition: set creative_edit false when the subject must stay pixel-identical, e.g., an existing sprite.

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 no annotations, the description carries the full burden and does so: it discloses the credit contract (held on accept, refunded on failure/cancel, scaling with image count), the async job pattern and polling requirement via getApiJob, the result shape, and the input-type restriction. That is well beyond what the schema conveys.

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 constraint, and every sentence carries information (params, restriction, credit behavior, alternatives, async contract). It is dense and runs long as one block, 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?

No output schema exists, so the description correctly supplies the return contract: an array of results each with image url plus applied camera_rotation/camera_elevation, and the async `{id, status}` envelope with polling via getApiJob. Combined with the type restriction and credit notes, an agent has everything needed to invoke and follow up.

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

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

Schema coverage is 100% and the nested schema already documents n, image, request_id, augment_prompt, camera_rotation, and camera_elevation with examples and value lists. The description largely restates these (rotation azimuth list, elevation values, omit-to-keep-elevation), adding no syntax or format beyond the schema, so 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?

States a specific verb+resource ('Re-render an existing sprite from a different camera viewpoint') and immediately constrains scope (keeps same character and pose, sprite image types only). It explicitly distinguishes itself from generatePose, animateSprite, and transferMotion, so an agent can route correctly without opening 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?

Gives explicit when-to-use plus named alternatives with the condition that selects each: 'use generatePose instead to change the character's pose rather than the camera, and animateSprite or transferMotion to bring a sprite to life.' Also states the negative constraint that it only works on 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?

With no annotations, the description carries the full behavioral burden and handles it thoroughly: weak matches are omitted, empty results mean the documentation doesn't cover the question, results include doc/section/full markdown, 503 means the backend is unavailable, and the endpoint is free and does not queue a job. It also flags that the docs occasionally describe 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 description is long but appropriately packed with necessary behavioral and fallback information. It is front-loaded with purpose and actionable guidance, though a few clauses are slightly redundant ('Start here rather than reading whole documents' restates the fastest-way 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?

Despite having no output schema, the description fully explains return shape (doc, section, content), ordering, empty results, n defaults, and error fallback. An agent has everything needed to invoke the tool 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 description coverage is 100%, so the baseline is 3. The description reinforces that query is a plain-language question and n caps the number of sections, but it does not add meaningful parameter semantics beyond what the schema already 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 ('Search') and resource ('Ludo's own documentation'), and explains the search is question-driven and returns only the few sections that answer it. It clearly differentiates from getDocs by saying results carry doc/section identifiers to pass to getDocs for re-reading.

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 tells the agent when to start here ('before you generate', 'Start here rather than reading whole documents') and what to do when results are empty or the backend returns 503, including naming getDocs as the fallback. This is direct and actionable 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?

With no annotations, the description carries the full burden and does so richly: precedence rule (video wins over preset), specific HTTP 400 failure conditions, credit hold/refund semantics, async job contract ({id,status} + poll getApiJob), and legacy-model deprecation warning. This is far beyond a minimal restatement.

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?

Long but dense and front-loaded, with the core action and inputs leading. Nearly every sentence adds a rule (precedence, defaults, errors, credits), though the credit/pricing block is somewhat redundant with the schema's model descriptions.

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 deeply nested schema, it covers inputs, precedence, duration/model defaults, error cases, credit lifecycle, and polling workflow, and names the sibling alternative. Nothing essential to invoking it correctly is missing; there is no output schema to explain, and it still summarizes the result fields.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the required preset_id/perspective/direction triple, that video overrides preset, that duration defaults to 1.5s otherwise the model's shortest (hydra 3s), and that preset timing should be preserved by passing its own duration.

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+outcome: transferring motion from a video or preset onto a static sprite to produce an animated spritesheet. It explicitly distinguishes from its sibling animateSprite (text-prompt generation) and names the preset source (listAnimationPresets), so an agent can place it precisely.

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 condition ("Use this when you have an existing motion clip or preset to copy") plus a named alternative with the counter-condition ("prefer animateSprite to generate animation purely from a text prompt"). Model-selection guidance (omit model for hydra, forge for cheaper/simple motion) further routes the agent.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: 2048px source cap and 15MB limit both rejected with HTTP 400, 4x ceiling, single-url (not array) result shape, credit hold/refund semantics, 0.5 credit cost, and the async job contract returning {id, status} to be polled via getApiJob.

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 limits are front-loaded, and nearly every sentence carries distinct constraints or routing info. It is on the long side, with some repetition of schema-documented request_id behavior, but 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 tool with no output schema and no annotations, the description supplies the return shape, polling path, failure modes, cost, and credit lifecycle. 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 both image and request_id are already documented in the schema. The description adds the 2048px constraint and the listGenerations retrieval angle, but this largely overlaps the schema text, so the baseline 3 applies.

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

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

States a specific verb and resource ('Upscale an image') with concrete scope: up to 4x, capped at 2048px on the longest side. It also explicitly distinguishes itself from siblings createImage and editImage, so an agent can route correctly without opening a schema.

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

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

Gives an explicit when-to-use ('raise the resolution of an image you already have') plus named alternatives with their differing purpose ('createImage and editImage make new or changed images instead'). Nothing is left to inference about tool selection.

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 are none, so description carries full burden. It discloses async behavior (returns {id, status}), polling via getApiJob, credit billing per second, refund on failure/cancellation, and the result format (new URL and duration). It mentions credit hold and refund policy. It doesn't detail error handling or retry behavior, but covers main behaviors. No contradictions with annotations (none provided).

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?

Description is thorough and well-organized, but somewhat dense and lengthy. It front-loads key info (upscale to 2x, use generated videos) but includes multiple clauses and parentheticals (e.g., 'landscape or portrait (only a square 720x720 would)') that could be simplified. Still, every sentence adds value, and it's not bloated with fluff. A 4 for efficient but slightly overloaded structure.

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

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

Given no annotations or output schema, description provides comprehensive context: input constraints, billing, async nature, polling method, result format, and relationship to siblings. It even includes credit cost (0.2 credits/sec). An agent has everything needed to call and interpret the tool correctly, including failure/refund behavior. Very complete.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by explaining the video parameter's constraints (7-day, model-specific) and the request_id semantics (idempotency, listGenerations filter). This goes beyond schema, but since schema already covers these, the addition is moderate, not exceptional.

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?

Description clearly states action ('upscale a previously generated video'), resource (video url), and specific effect (2x resolution). It explicitly differentiates from siblings by mentioning createVideo, editVideo, and related tools, and is specific about input constraints (7-day old, 480p vs 720p). No ambiguity about what the tool does.

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

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

Provides explicit when-to-use guidance: pass a URL from specific generation tools, ensure source is under 960 pixels, use griffin for generation if upscaling is intended. Clearly states what is NOT accepted (external videos, griffin-hd outputs except square). It doesn't explicitly list alternatives for when not to use, but it thoroughly covers conditions and prerequisites, making it easy for an agent to decide correctly.

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 no annotations, the description carries the burden of behavioral disclosure. It does disclose the success/error status codes, which is useful, but it fails to explain how the API key is supplied (since the schema has zero params) or mention any potential side effects. The 200/403 detail is valuable but the input mechanism remains opaque.

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 one efficient sentence that conveys the core purpose and expected responses with zero waste. It is ideally concise and front-loaded.

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

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

For a simple tool with no schema, annotations, or output schema, the description covers the essential purpose and responses. The only gap is the lack of explanation on how the API key is provided, but given the zero-parameter design, this is likely handled externally, making the description largely complete.

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

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

There are zero parameters, so the baseline is 4. The description identifies the subject (API key) but does not clarify how the key is transmitted, given the empty schema. However, since no parameters are expected, the description does not need to detail parameter values; still, a note about implicit authentication context would improve it.

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

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

The description uses a specific verb 'validates' and the resource 'API key', clearly stating what the tool does. It also provides distinct status codes (200/403) that set it apart from sibling tools, which are all media-related.

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

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

The description implicitly indicates this is for checking API key validity, but it does not explicitly state when to use it or mention any alternatives. Given that all sibling tools are unrelated, some contextual guidance on when to invoke validation would be helpful.

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