start_image_generation

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

Annotations already signal readOnlyHint=false and destructiveHint=false, so the basic mutation profile is known. The description adds useful behavioral context: exactly one image is produced and the result is persisted in the artifact ledger. However, it does not explain ledger retention, permissions, or what happens on failure, so it adds moderate but not deep 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?

The description is a single, focused sentence with no filler. The primary action and the artifact-ledger side effect are both front-loaded, making it easy to parse quickly.

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 8 parameters, no output schema, and no mention of return values or error behavior, the description is not complete enough for confident invocation. It establishes intent well but leaves practical details such as output_name handling, retry semantics, and result format entirely unaddressed.

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 50%, with effort, max_retries, aspect_ratio, and timeout_minutes left undocumented in the schema. The description does not compensate for this: it mentions no parameter meanings, defaults, or relationships, so an agent gets little semantic help beyond the prompt field.

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 action ('Generate one image'), identifies the underlying mechanism ('Antigravity's native generate_image tool'), and adds a distinguishing side effect ('capture it in the persistent artifact ledger'). This separates it from sibling tools like start_image_edit or start_media_analysis, though the distinction is implicit rather than explicitly named.

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?

There is no guidance on when to use this tool versus the many sibling start_* tools, nor any mention of exclusions or alternatives. The description focuses entirely on what happens internally, leaving tool selection to inference.

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