add_node

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

With no annotations, the description carries full behavioral disclosure. It explains the template_defaults mechanism, what fields are auto-applied, how explicit overrides work, the console and icon fallback behavior, and the fact that the node is added stopped. This is comprehensive and gives the agent safe expectations for a mutating create operation.

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 every paragraph adds necessary behavioral detail. It is front-loaded with the core action, then explains defaults and fallbacks in a logical order. No sentences are wasted; the length is justified by the tool's 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?

Given the tool's high parameter count (22), no annotations, and an output schema to handle return values, the description covers the essential behavioral aspects: creation, defaults, overrides, console/icon fallbacks, and initial state. It omits a few minor positional and network parameters, but overall it gives an agent enough to invoke the tool correctly without guessing.

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 0%, so the description must compensate. It explains the key parameters type, template, template_defaults, console, icon, and the set of fields included in template defaults (image, ram, cpu, qemu_*, config_script). It doesn't cover all 22 parameters (e.g., top, left, delay, serial, ethernet, firstmac, pci_mode), but the most ambiguous and impactful ones are addressed, leaving minor positional and hardware details to the 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 opens with a specific verb and resource: 'Add a node to the open lab.' It clearly distinguishes this from sibling tools like update_node, delete_node, and start_node by stating the create action and the node scope. The reference to list_templates for type/template further clarifies its role in the workflow.

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 gives clear when-to-use context: it tells the agent to obtain type/template from list_templates, explains that template_defaults=True usually avoids needing list_images, and notes that the node is added stopped so start_node is needed to boot it. It doesn't explicitly contrast with update_node or delete_node, but the guidance is sufficient for most cases.

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