get_system_stats

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

With no annotations provided, the description fully discloses behavior: it repeatedly states all actions are READ-ONLY and 'nothing here mutates anything.' It also notes error conditions ('Errors if the server is unreachable') and describes what each action returns (e.g., raw /system_stats JSON, aggregated health signals). This is comprehensive for a diagnostic 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 long but well-structured with a clear front-loaded purpose and bulleted action breakdowns. Every sentence serves a purpose: defining each action, its parameters, and its use case. The length is justified by the tool's multi-mode nature, and the structure aids scannability.

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 complex three-action tool with no output schema, the description is remarkably complete. It specifies inputs, outputs, default values, error behavior, and use-case context for each action. It even covers edge cases like 'empty dropdowns from a misconfigured extra_model_paths.yaml.' No critical information is missing.

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 the baseline is 3. The description does not materially add to the parameter semantics already present in the schema; it repeats the action-scoped parameter explanations (e.g., 'max_lines tails the end (default 100)'). It does clarify that 'stats takes no other parameters,' but this is also in the action parameter description. No significant value beyond schema.

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's purpose: 'Inspect the connected ComfyUI server: what it is running on, what it has logged, and whether it is healthy enough to dispatch work to.' It then enumerates three distinct actions (stats, logs, health) with specific verbs and outcomes, effectively distinguishing this tool from siblings like get_history or get_image.

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 provides explicit when-to-use guidance for each action: stats for confirming connectivity and checking VRAM before enqueuing large workflows, logs for debugging execution errors, and health as a pre-flight diagnostic before batch runs or after unexpected failures. It also emphasizes the read-only nature, helping the agent choose this over mutating alternatives like restart_comfyui or clear_vram.

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