host_memory_tiering

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

The annotations already mark the operation as read-only and idempotent; the description adds useful behavioral detail beyond that: it reads pyVmomi HostSystem.hardware.memoryTierInfo, requires ESXi 8.0U3+/9.x, reports 'unknown' for older hosts, and clarifies that 'noTiering' means a real checked-none state rather than missing data.

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 well-organized, with front-loaded purpose, a 'When to use' section, return envelope details, and gotchas. The only minor redundancy is restating 'Read-only' at the end after '[READ]' and despite the readOnly annotation, but overall every section earns its place.

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 there is no output schema, the description fully explains the return shape, row fields, per-tier breakdown, and the special meaning of 'noTiering'. It also covers version prerequisites and behavior on older hosts, making it complete for an agent to call this tool 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 input schema already documents all three parameters completely, including defaults and filtering intent, with 100% coverage. The description does not add parameter-level detail, but the schema carries that burden adequately, so the baseline of 3 applies.

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 purpose: reporting per-host memory tiering and NVMe uplift ratio. It also differentiates itself by claiming to be 'the only source of measured tier byte sizes,' which helps distinguish it from generic host-list tools.

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 explicitly begins with 'When to use' and lists concrete scenarios: identifying ESXi hosts backed by NVMe, checking tier sizes, and understanding how much memory rides on NVMe. It does not enumerate alternatives or explicit 'when not to use' conditions, but it provides clear contextual guidance.

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