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

With no annotations, the description carries the full burden and does well: it discloses exact credit costs (3/4/6 at 1k/2k/4k), reveals the operation is asynchronous by instructing 'Poll with wait_for_image', and notes a live preview in app-capable hosts. It omits the return format (image URL vs. ID) and any failure/rate-limit behavior, so it stops short of full transparency.

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 list are front-loaded in the first sentence, then short declarative sentences cover credit costs, polling, and rendering. Every sentence carries information, though the opening enumerates seven output types and is somewhat dense. No filler or restated boilerplate.

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 6-parameter tool with a nested object, 3 enums, no output schema, and no annotations, the description covers cost, async polling, downstream usage, and output types. The main gap is that with no output schema it should more explicitly state what the call returns (e.g., an image reference/URL to poll for), but it is otherwise complete enough to invoke 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%, including a detailed enum key for mode and a rich nested params object, so the schema already does the heavy lifting and the baseline is 3. The description's listing of output types loosely maps to the mode values but adds no syntax or constraints (e.g., resolution/ratio interplay, referenceImageUrls count) beyond what the schema 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 (Generate) and resource (pre-production reference images for AI films/ads) and enumerates exactly what it produces: faces, full-body refs, turnarounds, locations, first frames, mood boards, and storyboards. It distinguishes itself from siblings like create_image and create_video by scoping to pre-production reference material. An agent can tell what this does without opening the schema.

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

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

Explicitly names the downstream consumer ('Feed the results to create_video as reference images') and the polling tool ('Poll with wait_for_image'), giving clear workflow context. However, it never states when to use this over create_image or create_thumbnail, nor any exclusion conditions, so the routing guidance against the closest sibling is implied rather than stated.

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