Cluster Info

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds useful context by specifying that update_options requires elevated permissions and by explaining what status and options return. It does not detail the destructive scope of update_options, but it does not contradict the annotations.

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 a single pipe-separated sentence that front-loads the resource and action semantics. There is no redundant phrasing or unnecessary repetition of schema details.

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?

The description is adequate for the status and options actions, and the permission note is valuable. But because the tool includes a mutating action and has no output schema, the description should say more about the options object's expected keys, response format, and the destructive implications hinted at by destructiveHint=true.

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 description adds meaning to the action enum values, which the schema leaves undocumented. However, the options parameter is only described as 'Cluster options to update', matching the schema's own description without listing valid options or clarifying when it is required, so the 50% schema coverage gap is only partially compensated.

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?

States a clear resource (Proxmox cluster) and lists three concrete actions: status, options, and update_options, each with a brief result description. It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools like proxmox_cluster_config or proxmox_cluster_firewall.

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 gives action-level guidance, such as using status for cluster status and update_options for changing options, plus a note about elevated permissions. However, it does not state when to choose this tool over the many sibling cluster-related tools or provide explicit exclusions.

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