cluster_patch_compliance

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

The description goes well beyond the readOnlyHint/idempotentHint annotations by explaining that available: False indicates a 503 from vCenter, likely mid-patch, and should be retried rather than treated as failure. It also explicitly states the tool is read-only and never runs remediation, and notes verification against a live VCF 9.1 vCenter. This gives the agent actionable behavioral context.

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 well-structured with labeled sections: purpose, when to use, return behavior, and gotchas. It is front-loaded with the core purpose and maintains focus without redundant filler. Each section adds operational value, and the length is appropriate given the absence of an output 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?

For a tool with no output schema, the description covers return fields, an important error/retry condition, a crucial MoID prerequisite, and the tool's non-destructive scope. Combined with the annotations and 100% schema coverage for parameters, the agent has sufficient context to select and invoke the tool correctly in a patch-compliance workflow.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful value by specifying that 'cluster' must be a cluster MoID such as domain-c123, not a display name, and directs the agent to list_all_clusters for the correct value. It also explains the requirement originates from the REST API, which clarifies parameter semantics beyond the schema.

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 opens with a clear verb and resource: '[READ] vLCM software (patch) compliance for one cluster.' It goes further than a generic statement by explaining what compliance means: checking whether hosts match their assigned image/baseline. It also distinguishes itself from sibling host_memory_tiering by noting per-cluster lifecycle state instead of per-host hardware.

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 provides 'When to use' guidance: check before or after a patch cycle. It also contrasts with host_memory_tiering to help route selection. It gives a concrete prerequisite for the cluster parameter ('get it from list_all_clusters, not the display name'), though it does not enumerate exclusions or alternatives beyond that single sibling.

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