Generate image

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

Beyond the annotations (which only say non-read-only, open-world, non-idempotent, non-destructive), the description discloses the real behavioral facts: credits are charged per image and scale with model, the call blocks by default and polls up to timeoutSec, and it returns asset ids plus download URLs. It does not quantify cost or explain what happens to partial results, but the key operational traits are covered.

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

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

Four dense sentences, each doing distinct work: capability, reference modes, cost, and completion behavior. Front-loaded with the core action, no filler, and the routing hints are embedded rather than appended as noise.

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 15-parameter generation tool with no output schema, the description is nearly sufficient: it explains the expensive, asynchronous, reference-driven nature of the call and what comes back. The one gap is that it does not explain how the various reference-URL parameters differ in practice, which the schema covers only partially.

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 87%, so parameters are already well documented. The description adds only marginal meaning — that reference URLs must be public and that products/testimonials correspond to the app's # / @ mentions. With the schema doing most of the work, 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?

The description opens with a specific verb and resource ("Generate one or more images on VIVID from a text prompt") and immediately scopes the reference modes. It is unambiguous against siblings such as vivid_generate_video or vivid_retouch, which operate on different inputs.

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 routes the agent well: list saved references with vivid_list_references, host ad-hoc images via vivid_upload_file, and pick a model slug from vivid_list_models. It never states when NOT to use it (e.g. versus vivid_retouch for editing an existing asset), so it falls short of explicit alternatives.

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