get_transport_node_status

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

Beyond the safely annotations, the description discloses that it returns one dict rather than a list envelope, enumerates the status fields, and warns that the data is 'Point-in-time only — no history'. This goes well beyond what readOnlyHint and idempotentHint already communicate.

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 front-loaded with the core operation, then compactly covers when to use it, what it returns, and when to switch to a sibling tool. Every sentence earns its place and nothing repeats the schema.

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?

Even though no output schema exists, the description tells the agent exactly what the return dict contains, that it is point-in-time, and which sibling tools cover broader or segment-specific diagnossis. Given the annotations and 100% schema coverage, an agent has everything needed to invoke it correctly.

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 schema already covers both parameters at 100%, so the baseline is strong. The description adds useful meaning by clarifying that node_id refers to an ESXi host or Edge node and by directing the agent to list_transport_nodes as the source of valid IDs. The default target parameter needs no extra explanation.

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 names a specific operation and resource: 'Get realized runtime status of one transport node (ESXi host or Edge node)'. It also distinguishes itself from get_edge_cluster_status and get_logical_port_status, so an agent can select it without opening schemas.

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?

It gives explicit triggers ('Use after list_transport_nodes when a node looks degraded or overlay tunnels are suspect'), an explicit alternative ('for cluster-wide edge health use get_edge_cluster_status instead'), and a follow-up instruction for segment-local tunnel failures. Usage guidance is complete.

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