add_lab_network

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

With no annotations provided, the description carries full burden. It discloses key behavioral traits: conditional fetching of type list, cloud name resolution, default name and positions, and the exact effect of hideme. It does not mention error handling or prerequisite checks, but the main behaviors are transparently described.

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 well-structured with a clear opening sentence and an Args section. It is slightly verbose (e.g., long cloud explanation) but every detail earns its place. The note about hideme is slightly tangential but adds value. Overall, it is appropriately sized and front-loaded.

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 6 parameters, only 1 required, and an existing output schema (so return values need not be explained), the description covers all parameters with usage details and behavioral caveats. It could mention that the lab must already exist, but that is implicitly assumed. The contextual completeness is high for the tool's complexity.

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%, meaning the schema itself provides no descriptions. The tool description compensates fully by detailing each parameter: lab_path is a .unl file path, network_type references list_network_types and explains cloud aliases, name defaults to 'NetX', left/top are numeric strings, hideme has explicit 0/1 semantics with a corrective note. This adds significant meaning beyond the bare 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+resource: 'Add a network (bridge/cloud/ovs/pnetX) to a lab's canvas.' This clearly states the tool's purpose and distinguishes it from sibling tools like list_lab_networks, edit_lab_network, and delete_lab_network.

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 guidance: explains behavior when network_type is omitted (fetches list and prompts), references list_network_types for valid values, and clarifies cloud-to-pnet mapping. It also warns what hideme does NOT do (direct-line rendering). No explicit alternatives are listed, but the add vs edit/delete distinction is clear from context.

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