list_api_nodes

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

With no annotations, the description fully discloses safety/behavioral traits: external API calls, server-side execution, required Comfy account/API key, paid credits, immediate return of prompt_id, empty list when disabled, and explicit 'Do NOT pass auth credentials in inputs'. This goes well beyond the schema.

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 longer than average but organized by action bullets, with the core purpose in the first sentence. Each section adds necessary details; slight repetition (e.g., multiple 'Use action' instructions) is acceptable given the multi-action complexity.

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 3-action tool with nested inputs and no output schema, the description covers list results, schema contents, generate's immediate prompt_id return, auth behavior, and credit implications. It is sufficiently complete for an agent to select and invoke correctly.

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?

The input schema already covers all five parameters (100%), and the description reinforces action-parameter interdependencies: action:list takes filter, schema/generate require class_type, generate requires inputs and optional disable_random_seed. It also adds semantic detail like filter matching against class_type/display/category.

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 a specific verb+resource ('Discover and run hosted partner/API nodes on the connected ComfyUI') and then enumerates three distinct action modes (list/schema/generate), clearly distinguishing this from sibling tools like generate_image by emphasizing external providers and paid credits.

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?

It provides strong context: 'Start here to find a class_type', 'Use action:list first', 'Use action:schema to discover valid inputs', and explicitly frames generate as enqueuing a remote API run. It doesn't name sibling alternatives as exclusions, but the paid-credit vs local-GPU contrast implies when to prefer this.

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