Generate reference images for a game asset

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

The description adds meaningful behavioral context beyond the annotations: it discloses the credit cost ('SPENDS IMAGE CREDITS'), the asynchronous execution model ('waits up to waitSeconds, then returns a job id to poll'), and the output nature ('candidate image URLs for YOU to look at'). It does not contradict the readOnlyHint=false or idempotentHint=false annotations, and it provides insight into side effects that annotations alone do not convey.

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

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

The description is moderately long but each sentence adds value: credit cost, generation framing, output, not-3D warning, workflow, and async behavior. It front-loads the credit warning and core action. A minor redundancy exists in explaining the framing and the not-3D aspect, but overall it is efficient and well-structured.

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 (7 parameters, nested objects, no output schema), the description covers the high-level workflow and async behavior but omits parameter-level guidance. It does not explain what fields in 'spec' are essential or how waitSeconds interacts with job polling via get_asset_job. The mention of 'call select_reference then create_3d_asset' hints at the pipeline but leaves the agent to infer details from the schema. It is adequate for a basic invocation but incomplete for full correct usage of all options.

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

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

Schema description coverage is only 57%, leaving many parameters undocumented. The description does not compensate: it mentions 'waitSeconds' implicitly but does not explain the role of spec, numImages, or other nested parameters beyond what the schema already says. For a tool with complex nested objects (spec.artDirection, spec.geometry), the description offers almost no help in constructing valid parameters, falling short of the burden placed on it by low schema coverage.

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

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

The description clearly states the verb ('generates'), the resource ('candidate reference images for a game asset'), and the specific framing ('for 3D reconstruction rather than concept art') with concrete visual details (isolated object, neutral background). It also explicitly distinguishes from the sibling create_3d_asset by stating it does NOT create a 3D model, making the purpose unambiguous.

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

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

The description provides a clear workflow: 'after inspecting the candidates, call select_reference then create_3d_asset'. It also notes asynchronous behavior and the need to poll for a job id. However, it does not mention when NOT to use this tool (e.g., for generating variations) or how it contrasts with generate_reference_variations, so it lacks explicit exclusion guidance.

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