run_workflow

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

Without rich annotations, the description carries the burden and exceeds it: it explains seed re-rolling and persistence versus the raw /prompt API, server-side validation authority, spending gates, timeout behavior that does not kill the ComfyUI job, and recovery via draftsman_submitted after the session dies. This is substantial context beyond what annotations state.

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?

Long but every paragraph earns its place: core behavior first, then wait/front semantics, then edge cases and long-render polling guidance. The structure is scannable and the wording is dense without filler.

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 no output schema, the description provides the full return contract, including failure and queued responses. It also tells the agent what to do when the pipeline times out and where prompt_id can be recovered after an interrupted session. For a 9-parameter tool with side effects, the contextual surface is fully covered.

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 0%, so the description must compensate. It explains wait, roll_seeds, allow_invalid, confirm_spend, return_preview, front, save_dir, and timeout_seconds. workflow_id is the sole obviously-nameable parameter and does not need elaboration, so the coverage is nearly complete.

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?

Uses a clear verb+resource pair ('Queue the workflow') and then enumerates exactly what it returns (status, node errors, output file refs, data_outputs, inline preview thumbnail). It also explicitly separates itself from view_output and get_run_status, so an agent can distinguish it from siblings.

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?

Provides concrete conditional guidance: use wait=False for long renders, poll with get_run_status, save with save_output, pass return_preview=False when no image input is needed, set confirm_spend=True only after explicit user agreement, and allow_invalid only when local validation can be lax. It even names the alternative tools and the scenarios that select them.

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