Control-guided Generation

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

No annotations are present, so the description bears the full transparency burden. It discloses that the tool returns images and preprocessor maps, but gives no context about compute costs, whether images are saved to disk despite the save_images flag, or potential side effects. One sentence is too thin for a generation endpoint with 49 parameters.

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 front-loaded sentence that states the action, endpoint, key requirement, and return value with no wasted words.

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 49-parameter tool with no output schema and no annotations, the description is not contextually complete: it omits usage guidance relative to sdnext_txt2img, any explanation of control_units structure (despite that being the required nested object), and default behaviors (e.g. whether images are returned/saved). The rich schema descriptions mitigate but do not replace missing high-level context.

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 coverage is high (92%), so the baseline is 3; the description adds real value by enumerating what kinds of control units are supported (controlnet / t2i adapter / xs / lite / reference / ip), which the control_units schema entry only crosses-references. However, it adds no semantics for the remaining 48 parameters.

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 opens with an action verb ('Run'), identifies the exact endpoint (/sdapi/v1/control), names the key input concept (control units), lists supported types, and states expected outputs. This clearly differentiates it from sibling tools like sdnext_txt2img and sdnext_img2img.

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 phrase 'with one or more control units' and the listed types imply this is the tool to use for ControlNet/adapter-guided generation, but it never explicitly contrasts it with sdnext_txt2img, explains prerequisites, or says when not to use it. No alternative tools are named.

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