generate_with_controlnet

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

No annotations are provided, so the description carries full burden. It discloses that the tool returns prompt_id immediately and asset_id later via notification. It states that the tool does not run the preprocessor (control_image must be preprocessed). It mentions auto-resolution of checkpoint and controlnet_model. While not exhaustive (e.g., no mention of rate limits or side effects), these are reasonable for a generation tool.

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 paragraph of about four sentences. It is concise and front-loads the core purpose. There are no redundant words. However, it could be slightly more structured with bullet points or separate sentences for key points, but it remains efficient.

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 13 parameters (2 required) and no output schema, the description covers the usage flow (upload image first), return values (prompt_id then asset_id), prerequisites (running ComfyUI, preprocessed image, model availability), and auto-resolution behavior. It is complete enough for an AI agent to successfully invoke the tool.

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%, so baseline is 3. The description adds context beyond the schema: it clarifies that control_image must already be a preprocessed map (schema only says filename), and that checkpoint and controlnet_model auto-resolve if omitted. This additional information helps the agent understand parameter usage.

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 generates an image conditioned by a ControlNet preprocessed image and a text prompt. It specifies the resource (image) and the conditioning method, distinguishing from sibling tools like generate_image (no ControlNet) and generate_with_ip_adapter (IP adapter instead).

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 instructs to upload the control image first via upload_image, then pass its filename. It notes that unspecified params fall back to defaults, and checkpoint/controlnet_model auto-resolve. It also clarifies prerequisites: the control image must be preprocessed, a running ComfyUI is required, and the model must exist in the correct directory. This tells when to use the tool and what steps are needed.

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