vmk_ping

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower, but the description adds substantial behavioral detail: DF behavior, the 'Message too long' fault semantics, the need to read success and fault together, and the exact return shape. It even explains error handling ('error' + hint). This goes well beyond what annotations provide.

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 dense but efficiently organized: a one-line purpose header, a mechanism note, bulleted diagnostic semantics, and a compact return summary. Every sentence adds operational value, with no filler or tautology. The format is front-loaded with the tool's identity and safety posture.

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?

Despite 8 parameters and no output schema, the description covers return structure, fault behavior, error handling, and the diagnostic meaning of key parameter combinations. The schema handles the remaining parameter definitions. An agent has enough context to invoke the tool correctly and interpret results without guessing.

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 100%, so the baseline is 3, and the description adds meaningful interpretive value beyond the schema. It explains that size proves size+28 MTU, that df=True makes oversized packets fail instead of fragmenting, and gives concrete examples for source_vmk and netstack. The description does not redundantly restate every schema property, but it enriches the most diagnostic-critical ones.

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 states a specific verb and resource: a DF-bit-capable ping sourced from a host vmk for MTU path validation. It clearly identifies the underlying mechanism (esxcli network diag ping through the vSphere API) and distinguishes itself from sibling tools like list_host_vmks. The READ prefix and the diagnostic framing make the purpose unmistakable.

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 clear use context: MTU path validation with specific probe sizes (1572 for >=1600 MTU, 8972 for jumbo) and explains the failure-mode interpretation. It explicitly contrasts with no-host-SSH execution, which helps an agent choose this over an SSH-based approach. It does not name an alternative ping tool, but none exists among siblings, so the contextual guidance is sufficient.

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