comfy_cli

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

With no annotations, the description carries full burden and does well: it discloses that models_download runs for minutes and is gated on an idle-liveness timeout to avoid kills, that skills install/uninstall default to dry-run unless apply=true, that workflow_run is async unless wait=true, and that some actions fall back to server endpoints without the CLI. These are important behavioral traits beyond just the operation name.

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 extremely long with substantial repetition. For example, the action list in the description mirrors the enum values in the schema, and many actions are listed with similar phrasing like 'action:"..." — required for...' which duplicates schema properties. The structure is a flat job list without grouping headers or a summary, making it hard to scan 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?

Given the high complexity (31 params, 26 actions), the description covers each action's purpose and required params, and it explains key behaviors like fallbacks, dry-runs, and timeouts, which is commendable. However, the lack of a user mapping for skills (despite mentioning the skill names), and no info on return values (output schema absent) leaves some gaps. It does not address relationships with sibling tools beyond two mentions, so completeness is average.

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 100%, so baseline is 3. The description adds some context by grouping actions on parameters (e.g., 'promptId required' for several actions) and clarifying defaults like 'relativePath' defaults to models/checkpoints. However, it does not systematically link each parameter to its action family; it often only repeats the required/optional flags already in the schema, and some parameters like 'where' have no additional explanation beyond the schema enum description.

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 lists many actions with specific verbs and resources (e.g., 'status — Inspect the comfy-cli integration', 'jobs_wait — Wait for jobs'), clearly specifying each operation. It differentiates from siblings by mentioning 'search_nodes' complements 'search_custom_nodes' and references other tools. However, it does not explicitly distinguish from all 38 sibling tools, and the purpose overall is a toolbox covering many functions, diluting a single clear purpose.

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 explicit when-to-use guidance: e.g., 'Call this before local CLI operations when workspace or server routing is uncertain' for status, and 'Complements search_custom_nodes' for search_nodes. It also clarifies when fallback occurs. However, it lacks explicit 'when not to use' statements for most actions, and alternative tools are mentioned only for search_nodes, not comprehensively.

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