list_network_interface_cards

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

No annotations are provided, so the description carries the behavioral burden. It discloses that this is a read-oriented listing operation, explains how the returned nic_id must be paired with a network_label_id, and clarifies that base_vm_id + base_snapshot_id filters for instant-clone pools while vm_template_id filters for full/linked-clone pools. It does not mention pagination or rate limits, but the list semantics and integration behavior are well documented.

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 compact, front-loaded with purpose, and every sentence adds practical value. The embedded JSON example for the nics array is high-signal and immediately shows how the output relates to creation tools, with no filler or redundancy.

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 output schema exists and all parameters are described in the schema, the description focuses on the integration context and filter semantics, which is the only necessary justification. It could optionally state what happens when no filters are supplied, but the default-empty schema values and the general 'list NICs' wording make this inferable enough.

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 coverage is already 100%, as each parameter has a description. The description adds meaningful pairing semantics: base_vm_id + base_snapshot_id filter for instant-clone pools, while vm_template_id filters for full/linked-clone pools. It does not describe vcenter_id, but the semantic role there is self-evident from 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: 'List network interface cards (NICs)' and scopes it to 'pool or farm NIC configuration'. It then explains how the returned nic_id pairs with a network_label_id, which clearly separates this tool from label-focused siblings like list_network_labels.

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 identifies the exact context where the tool is used: building the nics array in create_desktop_pool or create_rdsh_farm provisioning settings, and that results can be filtered by clone-type parameter combinations. It does not state explicit 'when-not-to-use' exclusions, but the usage context is concrete and unambiguous.

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