create_network

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

There are no annotations provided, so the description fully carries the burden of explaining behavior. It thoroughly discloses the side effect of D12 auto-exclusion (networks silently added to custom-tagged port profiles, blackholing VLANs), explicitly states local validation with error naming, and notes the controller's enforcement of management-mode-specific schema. It also clearly indicates that field names are camelCase and there is no 'purpose' field, preventing common mistakes.

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 detailed but organized with clear sections: a one-line summary, field definitions, parameter requirements, and a distinct warning block. It front-loads the core purpose, then provides essential nested schema, then the critical behavioral warning. Every sentence earns its place, and the formatting makes it easy to scan.

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 that there is no annotation schema and the input schema is minimal, the description provides comprehensive information: the full required schema for the main management mode, optional fields, validation semantics, error behavior, and the D12 auto-exclusion side effect with remediation instructions. It fully equips an agent to construct a correct request and handle a known failure mode. The return output schema exists and includes a warnings entry, which is acknowledged.

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 only lists host, site, and network_config as generic strings/objects with 0% description coverage. The description compensates by defining what each top-level field means (host: console name, ID, or composite ID; site: site name or ID), and provides the full nested schema for network_config when management='GATEWAY', including types for each field. It doesn't document every possible management mode, but it does explain the structure and optional fields for the main case.

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 action 'Create a new network/VLAN on a site' with the primary resource (network/VLAN) and context (site). It distinguishes this from sibling tools by specifying it creates a network as opposed to updating, deleting, or listing networks. The additional detail about management-mode-specific schema further clarifies the scope.

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 context: it details the required parameters (host, site, network_config), gives a concrete example of the GATEWAY management-mode schema, and warns about the D12 auto-exclusion behavior with specific remediation steps (run allow_network_on_port_profile). It also implicitly distinguishes this from update_network, delete_network, and list_networks by focusing on creation and the unique caveats.

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