conversational_image

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

Annotations provide readOnlyHint=false (mutation) and destructiveHint=false. The description adds behavioral traits beyond annotations: provider locking across conversations (cannot switch mid-conversation), dialogue modes impact on interaction depth, and the usage pattern for continuation via conversation_id. These details are useful but not exhaustive (e.g., no mention of output_path creation).

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 well-structured with clear sections (purpose, when-to-use, dialogue modes, provider selection, usage pattern, returns). It is concise and front-loaded with essential information. The usage pattern could be slightly shorter, but overall it efficiently conveys the tool's workflow.

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 (conversational image generation with many parameters and multi-turn refinement), the description covers core concepts, when to use, dialogue modes, provider locking, and continuation pattern. The output schema exists, so return details are not needed. It lacks discussion of some advanced parameters (e.g., reference_images, input_image_file_id), but schema handles those. It is sufficient for an AI agent to select and invoke.

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% (main description does not detail individual parameters), but the schema itself has thorough descriptions for all parameters. The description adds some context for 'dialogue_mode' (enum values) but largely repeats schema info. Baseline is 3 due to high schema coverage, and no significant extra meaning is added.

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 tool's purpose: 'Generate images conversationally with iterative refinement.' It specifies the resource (images) and the verb (generate with conversation), and distinguishes from sibling tools like 'generate_image' by emphasizing conversation and iterative refinement. The dialogue modes further clarify the scope.

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 lists 'USE THIS TOOL when:' conditions, such as vague prompts, iterative refinement, or user asking for guidance. It does not directly state when not to use it (e.g., when prompt is clear and no refinement needed), but the context effectively implies when alternatives like 'generate_image' are better. It also covers dialogue modes and provider selection, offering solid guidance.

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