create_segment

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

Discloses write nature (PUT overwrite), return format (dict or error), and the nuance that subnet is the gateway address, not network address. Annotations confirm readOnlyHint=false, no contradictions.

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?

Well-structured with a clear intro and bullet-like arg details. Some repetition (subnet explanation), but overall efficient. Could be slightly more concise.

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, no nested objects, no output schema, the description is highly complete: covers prerequisites, behavior, return, parameter details, and post-creation steps. No gaps.

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?

Adds detailed meaning for all 6 parameters despite 0% schema coverage. Explains constraints (e.g., segment_id alphanumerics/hyphens/underscores), format (transport_zone_path full path), and examples (vlan_ids '100,200', subnet '192.168.1.1/24'). Addresses the mutually exclusive nature of subnet and vlan_ids.

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 it creates an overlay or VLAN-backed NSX network segment. It distinguishes between the two types and mentions the overwrite behavior. Sibling tools are different (e.g., delete, get), and the description sets it apart.

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?

Explicitly advises to run list_transport_zones first to get the transport_zone_path, explaining how it determines whether subnet or vlan_ids applies. Also provides guidance on linking the segment with create_tier1_gateway and verifying with get_segment.

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