Skip to main content
Glama
vmware-skills

vmware-nsx-security

by vmware-skills
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Remote

run_traceflow

Trace a packet's path through the NSX overlay to find which distributed firewall rule drops a flow. Injects a synthetic probe and returns hop-by-hop observations with drop reasons and ACL rule IDs.

Instructions

[WRITE] Run a Traceflow to trace a packet's path through the NSX overlay.

Injects a synthetic probe from the source port. Returns traceflow_id, operation_state (IN_PROGRESS / FINISHED / FAILED) and hop-by-hop observations typed by resource_type; Dropped* ones carry reason and acl_rule_id. Use it to find which DFW rule drops a flow, then get_dfw_rule_stats on that rule. A FINISHED traceflow is deleted server-side and its id 404s; only one still IN_PROGRESS at timeout_seconds survives for get_traceflow_result to poll.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
ttlNoIP TTL (default 64).
dst_ipYesDestination IP.
src_ipYesProbe source IP.
targetNoOptional NSX Manager target from config.
dst_portNoDestination port for TCP/UDP (default 80).
protocolNoTCP, UDP or ICMP (default TCP).TCP
src_portNoSource port for TCP/UDP (default 1234).
src_lport_idYesSource logical port ID — the VM NIC attachment UUID. This skill does not enumerate ports; run vmware-nsx's get_segment_port_for_vm to obtain one.
timeout_secondsNoMax seconds to wait (default 20).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv1.10.0
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / dst_ip / description
      Added value: +"Destination IP."
    • addedInput schema / properties / dst_port / description
      Added value: +"Destination port for TCP/UDP (default 80)."
    • addedInput schema / properties / protocol / description
      Added value: +"TCP, UDP or ICMP (default TCP)."
    • addedInput schema / properties / src_ip / description
      Added value: +"Probe source IP."
    • addedInput schema / properties / src_lport_id / description
      Added value: +"Source logical port ID — the VM NIC attachment UUID. This skill does not enumerate ports; run vmware-nsx's get_segment_port_for_vm to obtain one."
    • addedInput schema / properties / src_port / description
      Added value: +"Source port for TCP/UDP (default 1234)."
    • addedInput schema / properties / target / description
      Added value: +"Optional NSX Manager target from config."
    • addedInput schema / properties / timeout_seconds / description
      Added value: +"Max seconds to wait (default 20)."
    • addedInput schema / properties / ttl / description
      Added value: +"IP TTL (default 64)."
  2. Addedv1.5.29
  3. Removedv1.5.28
  4. First observedv1.3.2

TDQS

A4.9/5.0
Behavior5/5

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

Discloses that a FINISHED traceflow is deleted server-side and its id 404s, and that only one still IN_PROGRESS at timeout_seconds survives for get_traceflow_result to poll. This goes beyond the annotations and clearly explains side effects, lifecycle, and the non-idempotent nature of the operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence contributes: purpose, return values, use case, follow-up tool, and lifecycle. There is no filler or unnecessary repetition of schema details, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, it describes return fields (traceflow_id, operation_state, hop-by-hop observations with Dropped* details), the follow-up workflow, and the server-side cleanup behavior. This covers what an agent needs to invoke the tool and process the result correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context for src_lport_id (VM NIC attachment UUID, how to obtain it) and timeout_seconds (survival for polling), elevating the semantic guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Run a Traceflow to trace a packet's path through the NSX overlay' with a specific verb, resource, and goal, and the [WRITE] prefix signals mutation. It is clearly distinct from the DFW policy/rule sibling tools and complements get_traceflow_result by describing the run action versus polling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly directs the agent: 'Use it to find which DFW rule drops a flow, then get_dfw_rule_stats on that rule,' and describes the polling condition for get_traceflow_result. It also points to vmware-nsx's get_segment_port_for_vm to obtain a source port, providing an alternative for a prerequisite.

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

Install Server

Other Tools