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

Annotations indicate destructiveHint=true and idempotentHint=true, but the description doesn't explain what 'update' does beyond the name. It doesn't disclose that update may delete entries (via the 'delete' parameter), that changes may propagate to sub-paths, or that a digest may be required for concurrency control. The description adds minimal behavioral context beyond 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 short sentence that is front-loaded with the verb and resource. It is concise and easy to parse, though it could add a bit more context without becoming verbose.

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?

With 11 parameters, no output schema, and destructive annotations, the description is too thin. It doesn't explain the difference between get and update semantics, how filters work, or what happens on update (e.g., delete flag, propagate). An agent would need to inspect the schema and guess at behavior.

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 91%, so the schema already documents most parameters. The description adds no extra meaning beyond the action enum. Baseline 3 is appropriate because the schema carries the burden, but the description doesn't clarify how parameters combine (e.g., filters vs. update fields).

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 'Manage ACL entries (get, update)' states a clear verb and resource, and names the two actions. However, it doesn't distinguish this from other ACL-related sibling tools like proxmox_cluster_firewall or proxmox_role, and the title 'Access Control Lists' is generic. It is clear enough but lacks differentiation.

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 no guidance on when to use this tool versus alternatives. It doesn't mention that 'get' retrieves ACLs and 'update' modifies them, nor does it explain when to use path/roleid/userid filters. No exclusions or alternative tool references are provided.

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

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

Beyond the annotations, the description adds the important auth requirement that create/update/delete operations need elevated access. The destructive and read-only hints are already carried by annotations, so the description's added elevation note is useful supplemental 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 a single compact sentence with no filler. The action routing is front-loaded, and the elevated note is attached directly to the write actions.

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 plus schema is adequate for basic invocation, especially listing accounts. However, it does not clarify which parameters are required or meaningful for each action, such as needing name for get/update/delete or contact for create, and there is no output schema to compensate.

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. The description adds value by mapping the action enum values to query vs. management behavior and by correcting the schema's action description, which says 'List all ACME accounts' even though the enum also includes create/update/delete.

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 resource, 'ACME accounts', and distinguishes query actions (list/get) from management actions (create/update/delete). It is clear enough to be separated from related ACME tools by resource and action type, though it does not explicitly name sibling alternatives.

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 explicit internal usage guidance: use list/get for queries and create/update/delete for management, with writes requiring elevated privileges. It does not explain when to prefer sibling tools like proxmox_acme_info or proxmox_acme_cert, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the risk profile is covered structurally. The description adds useful extra context by stating that certificate operations 'requires elevated' permissions and that config is a retrieval action. It does not detail side effects of revoke or force renew, but the annotations plus clear action names carry most of that burden.

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 compact sentence with the core verb/resource front-loaded and the action categories laid out immediately. No filler or redundant restatement of 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?

For a 3-parameter, multi-action tool with no output schema, the description covers action selection and the important elevation requirement. It does not explain return shapes or prerequisites such as an existing ACME account, but the full schema coverage and annotations provide enough for an agent to invoke the 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?

Schema coverage is 100%, so the baseline is 3. The description adds genuine value by clarifying the action enum, and it corrects the misleading schema description 'Order new ACME certificate', which would otherwise under-represent renew/revoke/config. The node and force parameters are already well described in 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 names the resource ('ACME certificates') and breaks the tool into concrete actions: order, renew, revoke, and config. The action list makes the tool's scope fairly clear, but it does not explicitly contrast itself with sibling tools like proxmox_acme_info or proxmox_acme_account, so it stops short of full sibling differentiation.

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 some usage context by separating 'certificate ops (requires elevated)' from 'action=config: get ACME config', and it flags an authorization prerequisite. However, it does not say when to prefer a sibling tool or when not to use this tool; the guidance is implied mostly by the action names.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds the action enum values, which clarify the scope of queries, but it does not disclose return format, pagination, or any other behavioral traits. With annotations covering the safety profile, a 3 is appropriate.

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 sentence that front-loads the verb and resource, then lists the action options. It is efficient and has no wasted words. It could be slightly more structured by separating the action list, but it is appropriately sized.

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 read-only info tool with 100% schema coverage and no output schema, the description is mostly adequate. However, it does not explain when 'id' is required (e.g., for get_plugin) or what 'directories' returns, which could leave an agent uncertain about how to invoke the tool correctly for each action.

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 schema already documents both parameters. The description adds the action enum values but does not explain the relationship between 'id' and 'action' (e.g., that id is needed for get_plugin). Baseline 3 is correct when the schema does the heavy lifting.

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 clear verb and resource: 'Query ACME information.' It also enumerates the three actions (list_plugins, get_plugin, directories), which distinguishes it from sibling tools like proxmox_acme_cert and proxmox_acme_account. However, it does not explicitly differentiate itself from those siblings by name, so it loses one point.

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 implies usage by listing the action enum values, which tells an agent what operations are available. It does not explicitly state when to use this tool versus proxmox_acme_cert or proxmox_acme_account, nor does it provide exclusions or alternative routing. The context is clear for the action parameter but not for tool selection among ACME-related siblings.

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

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

Annotations already establish destructive, non-read-only, non-idempotent behavior, so the description adds only the elevated-permissions caveat for status. That is useful, but it does not disclose the two-step exec/status interaction or guest-side prerequisites.

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 compact, front-loaded clause that states the mechanism and then enumerates the operation modes without redundancy. Every clause contributes operational information.

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 with the schema, the description omits the central workflow: exec returns a pid that status then consumes, and it does not say what either operation returns given there is no output schema. Prerequisites such as the QEMU agent being installed/running in the guest are also absent, making correct invocation harder for an agent.

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 89%, but the operation parameter carries no schema description; the tool description supplies meaning for its enum values ('exec: run command', 'status: check execution status') and adds the permission requirement. This goes beyond the bare enum names.

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 clearly identifies the action ('Execute commands via QEMU agent') and breaks out the two operations (exec, status) with distinct behaviors. It distinguishes the tool from LXC execution by specifying QEMU agent, though it does not explicitly name any sibling alternative.

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 does not explain when to choose this tool over alternatives such as proxmox_lxc_exec or proxmox_agent_file. It gives no workflow guidance (e.g., use exec first, then status with the returned pid), only notes that status requires elevated permissions.

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

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

Annotations already mark readOnlyHint=false and destructiveHint=true, and the description adds 'requires elevated permissions' and specifies the QEMU agent mechanism. This is useful but doesn't elaborate on side effects or failure modes; no contradiction with 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 sentence with no fluff, front-loading the core action and resource, then adding the operation and permission constraint. Efficient and scannable.

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 6-param mutation tool, the description is thin; it doesn't mention that the guest agent must be running or that the guest must be online. However, the schema covers parameter details and annotations cover safety, so the description is minimally adequate.

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 83%, so the schema documents most parameters. The description adds a brief note on operation=read|write, which is already in the enum, and mentions permissions but doesn't add meaning beyond the schema's property descriptions.

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 clearly states 'Read/write files via QEMU agent' linking a specific action (read/write) to a resource (guest files) and mechanism (QEMU agent). It distinguishes this from sibling exec and other agent tools by focusing on file access. The operation=read|write detail reinforces the purpose.

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 implies usage for reading or writing files inside a VM through the QEMU agent, and notes elevated permissions as a prerequisite. However, it doesn't explicitly provide when-to-use vs alternatives or exclusions, such as preferring storage/backup tools for non-running guests.

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

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

Annotations mark destructiveHint=true, but the description goes no further. It does not explain the consequences of freezing (e.g., guest may become unresponsive until thaw), the need to thaw after a freeze, or the side effects of fstrim. The phrase 'requires elevated permissions' hints at sensitive operations but does not disclose behavioral traits beyond the annotation.

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, compact sentence that leads with the purpose and immediately lists the valid operations. It is efficient and easy to parse, though it could benefit from a brief explanation of each operation or a note on when to use it. No unnecessary words.

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?

With no output schema and four distinct operations each having significant side effects, the description is incomplete. It does not explain what the tool returns (e.g., status results), nor does it warn about the need to thaw a frozen filesystem to avoid data corruption. The 'requires elevated permissions' is the only operational caution. For a tool that can disrupt a guest, this lack of context is inadequate.

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 descriptions cover node and vmid, giving the operation parameter only an enum without explanation. The description repeats the enum values and adds the generic 'requires elevated permissions' note, which applies to the operation. It does not clarify what each operation does (e.g., what 'fstrim' achieves), but the listing does help map the enum. Given 67% schema coverage, the description adds marginal value.

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 clearly states the tool manages filesystem freeze via the QEMU agent and enumerates the four operations (status, freeze, thaw, fstrim). It distinguishes itself from sibling agent tools like exec, power, and info by focusing on freeze operations. However, the verb 'Manage' is somewhat generic, and a more precise phrasing would list the actions directly.

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 no guidance on when to use this tool versus alternatives, such as when freezing before a snapshot or when trimming after deletion. It only notes 'requires elevated permissions,' which is a prerequisite, not a usage context. Sibling tools like proxmox_agent_exec handle other guest operations, but no comparison or selection criteria are mentioned.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, and the description adds a permission caveat. It does not disclose behaviors like what happens if the QEMU agent is unavailable or whether results reflect live host state, but the annotation covers the main safety profile.

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 front-loaded sentence that states the action, resource, supported operations, and a permission caveat with no filler or repetition.

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 a simple read-only query tool: it names the purpose, operations, and permission requirement. However, it omits the prerequisite that a QEMU agent must be running, and with no output schema it does not hint at the expected return shape.

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?

Node and vmid already have schema descriptions, while the operation parameter has an enum in the schema. The description mostly repeats the operation enum values and adds the 'requires elevated permissions' note, providing only marginal semantic value 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 uses a specific verb and resource: 'Query guest hardware via QEMU agent,' and enumerates the supported operations. This clearly distinguishes it from most agent siblings like proxmox_agent_exec or proxmox_agent_file, though it does not explicitly contrast it with proxmox_agent_info or proxmox_guest_status.

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 no guidance on when to choose this tool over alternatives, and it does not state exclusions or prerequisites such as the guest agent needing to be installed and running. The only usage hint is 'requires elevated permissions,' which is a precondition rather than a selection rule.

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

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

Annotations declare readOnlyHint=true, which aligns with the description's 'query' nature. The description adds value by mentioning 'requires elevated permissions', which is a behavioral constraint not captured in annotations. However, it doesn't disclose what specific permissions are needed or whether there are rate limits or side effects, though the read-only hint covers most safety concerns.

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 sentence that packs essential information: the action (query guest info), the method (via QEMU agent), and the operation enum with a permission note. It is front-loaded with the core purpose and no wasted words.

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?

Given the tool's moderate complexity (multiple operation types) and no output schema, the description provides the operation enum and permission requirement. However, it doesn't explain what each operation returns or when to choose one over another. The lack of output schema means the description should clarify expected return formats, which it doesn't. The annotations cover safety, so the main gap is operational detail.

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 documents node and vmid adequately (67% coverage). The description adds value by explaining the operation parameter with its enum values and the permission requirement. Since operation is the key parameter for selecting the query type, the description compensates for the schema's brief description by listing options and emphasizing elevated permissions.

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 clearly states the tool queries guest info via the QEMU agent and lists the specific operations it supports (ping, osinfo, fsinfo, etc.). It distinguishes from sibling agent tools (proxmox_agent_exec, proxmox_agent_file) by focusing on info retrieval rather than execution or file operations.

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 implies usage for querying guest information, and the enum operation parameter provides clear options. However, it does not explicitly state when to use this tool instead of others, such as when to use proxmox_agent_hw or proxmox_guest_config. The mention of 'requires elevated permissions' gives a hint but no explicit alternatives or exclusion criteria.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds useful context beyond annotations: it is agent-mediated and requires elevated permissions. However, it does not disclose side effects such as VM shutdown vs. suspension behavior, whether the operation is graceful, or what happens if the agent is unavailable.

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?

A single, efficiently worded sentence that front-loads the main purpose and then lists the operation values and permission requirement. There is no redundant filler or 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?

For a destructive, state-changing tool with no output schema, the description is somewhat thin. It captures the essential operation set and permission note, but omits important context such as when this tool should be chosen over sibling guest control tools, the need for a running QEMU agent, and expected effects/return behavior.

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 documents node and vmid, and the operation enum fully defines allowed values. The description repeats the operation choices but does not add deeper meaning about node/vmid semantics or operation-specific prerequisites. With schema coverage at 67%, the description provides marginal additional value.

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 clearly identifies the resource (guest power control) and the mechanism (via QEMU agent), and enumerates the exact supported operations. This distinguishes it from sibling tools like proxmox_node_power or proxmox_guest_shutdown by specifying agent-based control rather than node-level or direct guest control.

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 no explicit guidance on when to use this tool versus alternatives such as proxmox_guest_shutdown, proxmox_guest_stop, or proxmox_agent_freeze. It mentions elevated permissions but does not state prerequisites like 'guest agent must be installed and running' or situations where this tool is preferred.

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

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

The description adds the elevated-permissions requirementaint, which is useful beyond the annotations. However, it does not disclose that the existing password is overwritten, that the QEMU agent must be running, or any side effects beyond what destructiveHint and idempotentHint already imply. No contradiction with 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 short and mostly front-loaded, with no filler. The broad phrase 'Manage guest users' is less precise than the operation-specific detail, but the overall compactness helps an agent parse it quickly.

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 single-operation tool with no output schema, the description is minimally viable but leaves gaps: it does not state that the VM must be running, that the QEMU agent must be installed/active, or what result/confirmation the agent should expect. Annotations cover the destructive and idempotent nature, so the omission is not critical.

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 83%, so the schema already documents most parameters. The description adds little beyond restating 'operation=set_password,' which is already encoded as an enum. This meets the baseline but does not elevate meaning for parameters like crypted or username.

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 clear verb and resource: manage guest users via QEMU agent, and narrows the action to operation=set_password. It is clear enough to distinguish from agent info/exec/file siblings, though it does not explicitly name them or contrast with proxmox_guest_config_update.

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?

There is no explicit guidance about when to use this tool versus alternatives, and no exclusions are stated. The only contextual hint is 'requires elevated permissions,' which is a prerequisite rather than a use-case selector.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds the elevated privilege requirement and notes that versions is a list operation, which is useful. It does not, however, disclose what upgrade changes, whether changes are reversible, or what system-level consequences may occur.

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 compact and front-loaded with 'Manage APT packages.' The action mapping is dense but mostly efficient; the phrase 'package ops' is vague filler and the inline pipe-separated format could be clearer, but the overall size is appropriate.

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 simple tool with no output schema, it covers the main actions and required node parameter. However, it does not clarify whether the optional package filter applies to all actions or only some, nor does it describe what result to expect from update/upgrade. Adequate but with clear gaps.

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 documents node and package, but the action enum has no per-value descriptions. The description supplies semantics for all three enum values and flags elevation, which is meaningful added value 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 clearly identifies APT package management and enumerates the supported actions (update, upgrade, versions), which tells an agent what the tool can do. It falls short of 5 because 'Manage' is generic and update/upgrade are lumped under the vague phrase 'package ops' without defining their distinct effects.

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 action mapping provides some in-tool guidance, and 'elevated' hints at a privilege requirement. However, it does not state when to prefer this tool over alternatives, when not to use it, or what conditions should trigger update versus upgrade.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutable nature is known. The description adds 'requires elevated permissions', which is useful operational context. However, it does not disclose side effects like restore overwriting existing guests, or that some actions (list) are read-only while others are destructive. Given the annotation coverage, the description contributes minimal extra behavioral detail.

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?

A single concise sentence with no filler. The action list and guest type are front-loaded, and the permission note is appended efficiently. Every word 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?

With 9 parameters and 4 distinct actions, the description is thin. It does not explain how parameters map to actions (e.g., archive/volume for restore, storage/compress for create). No output schema exists, so the description could clarify typical return values. The high schema coverage mitigates, but the lack of action-specific guidance leaves an agent to infer parameter requirements from the schema alone.

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 89%, so parameters are already largely documented. The description adds no parameter-level semantics (e.g., which parameters apply to which action). Since the schema carries the semantic weight, a baseline 3 is appropriate; no additional value is provided.

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 clearly states the resource ('guest backups') and enumerates the actions ('create, list, restore, delete'), and specifies the guest types (VMs and LXC containers). This distinguishes it from sibling tools like proxmox_guest_snapshot (snapshots) and proxmox_file_restore (file-level restore), leaving no ambiguity about its scope.

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 context (guests, elevated permissions) but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or specific conditions that would route an agent to another tool. The 'requires elevated permissions' is a prerequisite but not a usage selector.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds value by enumerating the specific data fields returned (health, FSID, monitors, OSDs, placement groups), which is useful beyond the annotation. No contradiction, and the added detail improves transparency without overreach.

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?

A single, front-loaded sentence that states the verb, resource, and specific outputs. Zero waste, and the most critical information (action=status) appears early. It is appropriately sized for a simple read-only query.

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 two-parameter read-only status tool with no output schema, the description lists the returned fields, which is the key missing information. It does not mention potential error cases or the node's role, but those are minor given the tool's simplicity. Overall, it is sufficient for an agent to call 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?

Schema coverage is only 50% (node is described, action is not). The description compensates by explaining action=status and its outputs, but it adds no new meaning for the node parameter beyond the schema's 'Node name'. It partially fills the gap but does not fully clarify the node's role (e.g., whether it is the node to query or just a routing parameter).

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 clearly states the tool queries the Ceph cluster and specifies the action=status, listing the exact outputs (health, FSID, monitors, OSDs, placement groups). It distinguishes itself from sibling tools like proxmox_ceph_osd by focusing on cluster-level status, leaving no ambiguity about its purpose.

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 makes it obvious that this tool is for overall Ceph cluster status, but it does not explicitly mention alternatives or when not to use it. Given the large set of Ceph-related siblings, explicit routing would be helpful, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations declare readOnlyHint=false, implying mutation, which is consistent with the 'create' action. However, the description adds no behavioral context beyond that: no mention of side effects, permission requirements, reversibility, or what happens to existing resources. For a create operation, this is a significant gap. There is no contradiction with annotations, but the description contributes almost nothing beyond what the action enum already implies.

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 short sentence, which is concise, but it is under-specified. It front-loads the actions, which is good, but it sacrifices necessary detail for brevity. It is not verbose, but the minimalism leaves out critical context, making it more of a placeholder than a helpful description.

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?

This is a tool with 6 parameters, no output schema, and an action enum that switches between a read operation and a mutating create. The description provides no explanation of which parameters are required for each action, what 'node' refers to, or how to properly configure a create (e.g., needing a metadata pool and data pool). An agent cannot correctly invoke the create action without additional knowledge. The description is inadequate for the tool's complexity.

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 high (83%), so the parameters are well-documented in the schema itself. The description adds no additional semantics or relationships (e.g., that pool is required for create, or how data_pool and metadata_pool differ). Since coverage is high, the baseline is 3, and the description neither helps nor hurts.

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 the tool manages Ceph filesystems and explicitly lists the supported actions (list, create). This clearly identifies the resource and verb. It distinguishes from sibling Ceph tools like proxmox_ceph_pool or proxmox_ceph_mds by naming 'filesystems' specifically, though the verb 'manage' is somewhat generic. Overall it is clear and specific enough.

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?

No guidance is provided on when to use this tool versus alternatives such as proxmox_ceph_pool or proxmox_ceph_osd. The description does not mention any conditions, prerequisites, or exclusions. An agent has no information about when 'list' or 'create' is appropriate or what distinguishes this from other Ceph tools.

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

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

The annotations already include destructiveHint=true, and the description adds 'delete' as an action, but that is also visible in the schema enum. The description provides no additional behavioral context such as irreversibility of deletion, required node context, or effects on the Ceph filesystem. 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 compact sentence with the resource and operations front-loaded. It contains no filler, though it could marginally be structured to call out per-action requirements.

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 destructive, multi-action tool with no output schema, the description is thin. It leaves the agent to infer that create/delete likely need a daemon name, what a list returns, and what destructive consequences delete carries beyond the annotation flag.

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 documents 'name' and 'node' (67% coverage), and the description's parenthetical loosely mirrors the action enum. The description does not clarify when 'name' is required (e.g., for create/delete vs. list) or provide detail beyond the schema, but the schema plus enum are reasonably self-sufficient.

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 the specific resource (Ceph MDS daemons) and enumerates the supported operations (list, create, delete), so an agent can tell what the tool does. The resource name also distinguishes it from sibling Ceph tools like proxmox_ceph_osd and proxmox_ceph_mon, though the verb 'manage' is somewhat generic.

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?

Usage is implied through the resource name: use it when managing Ceph MDS daemons. However, it does not explicitly state when to prefer this tool over related Ceph siblings (e.g., proxmox_ceph_fs, proxmox_ceph_pool) or note any prerequisites or ordering constraints for create/delete operations.

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

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

The annotations already flag this as destructive and non-read-only, and the description only restates the action enum from the schema. It adds no extra behavioral context such as side effects, node-scoping implications, prerequisites, or safety caveats about deleting a monitor.

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, front-loaded sentence with no filler, and the parenthetical action list is compact. It earns a strong score for structure, though the brevity comes at the cost of useful elaboration.

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 destructive tool with three parameters and no output schema, this description is too thin. It omits return-value expectations, prerequisites, and any warning about what creating or deleting a Ceph monitor actually does, leaving the agent under-informed for correct invocation.

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 67%, so the description should compensate for the remaining parameter ambiguity, but it does not. It only repeats the action values already present in the enum and never explains the role of monid, action-dependent requirements, or the meaning of the node parameter.

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 clear resource—Ceph monitors—and lists explicit operations (list, create, delete), so an agent can tell what domain the tool covers. However, 'manage' is generic and the description does not explicitly differentiate this tool from related siblings like proxmox_ceph or proxmox_ceph_osd, though the resource name helps.

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?

There is no guidance about when to use this tool versus the many proxmox_ceph_* siblings, nor any exclusions or alternative recommendations. The only implicit cue is the resource name 'Ceph monitors,' leaving the agent to infer the appropriate context.

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

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

The annotations already flag destructiveHint=true and readOnlyHint=false, and the description merely restates the action enum without adding context about what deletion destroys, whether create overwrites existing device data, or what permissions are needed. It does not contradict the annotations, but it also adds no behavioral transparency beyond them.

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 front-loaded sentence with the resource named and operations compactly listed. It is efficient with no wasted words, though it is terse enough that it sacrifices useful context.

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 9-parameter tool with destructive create/delete operations and no output schema, this description is too thin. It does not explain action-specific requirements, e.g., that create needs a device and delete needs an existing OSD ID, nor does it describe side effects. The schema helps with parameter names but cannot convey the operational context.

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 89%, so parameter meaning is mostly carried by the schema itself (e.g., dev path, optional dbdev/waldev, encryption flag). The description adds no parameter-level detail, but with this high coverage it does not need to; baseline 3 is appropriate.

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 the specific resource (Ceph OSDs) and enumerates the supported actions (list, create, delete), which clearly distinguishes it from sibling Ceph tools like proxmox_ceph_pool, proxmox_ceph_mon, and proxmox_ceph_fs. It is not a 5 because 'Manage' is generic, but the action list compensates.

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 no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or conditions for create versus delete. An agent cannot tell from the description when this tool is the right choice compared to other proxmox_ceph_* siblings.

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

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

The annotations already carry the safety profile (destructiveHint=true, readOnlyHint=false), so the description's burden is to add context such as that deleting a pool destroys stored data, that operations require privileged/root access, or which actions mutate state. It adds none of this; the description only lists operations already present in the action enum. It does not contradict the annotations, but it repeats structured data instead of enriching it.

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 compact sentence with the resource and operation scope front-loaded. No wasted words. It loses a point only because it is so terse that it borders on merely echoing the schema rather than adding information.

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 an 8-parameter, 4-action mutation tool with no output schema, the description should compensate by mapping parameters to actions (e.g., pg_num/size/min_size apply to create/update, name is required for update/delete) and hinting at return values. It does neither. An agent selecting this tool cannot tell which of the 8 parameters are relevant for the action they intend, and there is no indication of what the response contains.

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 88% (above the 80% threshold), so the schema documents name, node, size, pg_num, min_size, crush_rule, and pg_autoscale_mode well. The description adds no parameter-level meaning beyond this, so the baseline 3 applies. A small gap: the action parameter lacks a schema description but is self-explanatory via the enum, which the description parenthetical reinforces.

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 verb+resource ('Manage Ceph pools') and enumerates the four operations (list, create, update, delete), which clearly distinguishes it from siblings like proxmox_ceph_osd, proxmox_ceph_mon, and proxmox_ceph. However, the parenthetical merely repeats what the action enum already declares, and 'Manage' is a generic verb that relies on the operation list for specificity.

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?

No guidance is given on when to use this tool versus alternatives, no prerequisite conditions (e.g., Ceph must be configured on the node, or a pool must already exist before update/delete), and no exclusions or warnings. The description leaves an agent to infer that action='delete' is destructive and that 'list' requires no pool name, which the schema does not make explicit.

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

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

Annotations already carry readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds the '(requires elevated)' permission note for upload/delete and implies list is read-only via 'view certs', which is useful beyond the annotations. No contradiction with annotations: mutable and destructive operations match destructiveHint=true.

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?

Compact single sentence using pipe-separated action enumeration. Purpose is front-loaded ('Manage node SSL certificates') followed immediately by the action breakdown. Every segment earns its place, and the structure is highly scannable for an agent parsing the definition.

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?

Given a 6-parameter, 3-action tool with no output schema, there are notable gaps: no per-action parameter mapping, no explanation of what the 'restart' and 'force' booleans do in context of each action, and the return of 'list' (certs, fingerprints, expiry) is left to inference. The description covers the what but not the how-combined, leaving an agent to guess parameter interactions.

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 all six parameters (key, node, force, action, restart, certificates) are already documented. The description's action explanations mirror the enum already in the schema. It does not add field-level guidance such as which parameters each action requires (e.g., upload needs certificates+key, delete likely uses force or restart). Baseline 3 is appropriate since the schema does the heavy lifting.

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 the resource ('node SSL certificates') and enumerates three actions with concrete outcomes ('list: view', 'upload: upload custom cert', 'delete: remove custom cert'). The 'node SSL' qualifier distinguishes it from the ACME-cert sibling (proxmox_acme_cert), though it never names that alternative. The verb 'Manage' is soft, but the explicit action breakdown carries the meaning.

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?

No when/when-not guidance. It describes the three actions internally but offers no reason for choosing this tool over proxmox_acme_cert, proxmox_node_service, or other cert/node siblings. There are no exclusions, alternatives, or conditions that would tell an agent when this tool is the right one.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true. The description adds that regenerate 'requires elevated', which is permission context not in annotations. However, it does not explicitly warn that regenerate overwrites or destroys the existing cloud-init drive, which would be valuable given the destructive hint. It adds a bit but not much beyond 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 sentence with pipe-separated action definitions. It is front-loaded with the purpose and packs the essential information without fluff. Every word 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?

For a multi-action tool with no output schema, the description covers the three actions, their specific parameters, and a permission note. It does not explicitly state that dump_type is only relevant for dump, but the inline text implies it. It is complete enough for an agent to correctly invoke each action.

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 parameters are documented. The description adds value by explaining the meaning of the action enum and how dump_type maps to dump (user|network|meta). It also clarifies that regenerate is separate and requires elevated, which the schema does not convey. This goes beyond the baseline.

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 resource ('cloud-init for a QEMU VM') and enumerates three explicit actions (get, dump, regenerate) with their behaviors. This clearly differentiates it from the many sibling tools, which are about nodes, clusters, guests, etc. The verb 'Manage' is generic, but the action breakdown makes 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 explains what each action does, which implies when to use the tool (whenever cloud-init for a VM needs handling). However, it does not explicitly contrast it with alternatives or state when not to use it. For instance, it doesn't mention that guest config updates are separate. The guidance is implied rather than explicit.

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

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.

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is mostly covered. The description adds only the vague 'elevated' marker for mutating actions and does not explain what deletion destroys, whether updates are in-place, or what list/get return. This is acceptable but thin, not contradictory.

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 compact, front-loaded with the resource name, and each segment of the action list carries information. The repeated '(elevated)' marker is slightly wasteful and could be consolidated, but there is no filler or unnecessary prose.

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 38 parameters, no output schema, and destructive mutations, the description is far too thin. It provides an action dispatch table but lacks per-action parameter requirements, return-value expectations, and any guidance on side effects, making it insufficient for an agent to safely construct complex create/update/delete calls.

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?

With schema description coverage at only 11%, the description was expected to compensate for the many undocumented parameters, but it only restates the action enum and adds no meaning for the other 37 parameters. It does not say which parameters apply to create, update, get, or delete, nor which are required beyond the schema's minimal 'action' field.

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 the resource ('cluster backup jobs') and enumerates five concrete actions with verb-object phrasing, so an agent knows what the tool operates on. However, it starts with 'Manage' rather than a specific verb and does not differentiate this tool from close siblings like proxmox_backup or proxmox_cluster_replication_job.

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 action list gives some internal routing (list vs get vs create vs update vs delete) and marks mutations as 'elevated', but it never says when to choose this tool over alternatives or what conditions should select one action over another. No exclusions, prerequisites, or comparison with sibling backup tools are provided.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description adds only 'elevated' for the join action. It does not explain that join modifies cluster state, what side effects may occur, or whether elevated refers to permissions or credentials.

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 pipe-separated action mapping is compact and front-loaded, with minimal filler. Slight repetition of 'config' is harmless, but the format could be more structured to distinguish read-only actions from the join mutation.

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?

With five actions, six parameters, and no output schema, the description leaves critical invocation details unspecified: per-action required parameters, return shapes, and side-effect expectations. An agent cannot reliably construct valid calls for join or get_node without additional external knowledge.

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 high at 83%, so the parameter burden is mostly handled by the schema. The description paraphrases the action enum values but does not clarify which parameters are expected or required for each action, such as hostname/password/fingerprint for join.

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 clearly identifies the tool as managing cluster config and enumerates five distinct actions with their meanings. It is specific enough to separate config operations from broader cluster lifecycle tools, though it does not explicitly contrast it with siblings like proxmox_cluster.

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 no guidance on when to use this tool instead of alternatives such as proxmox_cluster or proxmox_cluster_firewall. It implies usage through the action list but lacks explicit when/when-not direction or preconditions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description's 'Query/manage' plus 'update_options' is consistent with those. It adds the useful 'elevated' permission note, but it does not explain the consequences of destructive updates, such as whether enabling the firewall can disrupt connectivity.

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 front-loaded sentence with a compact action map; there is no filler. The pipe-separated list is information-dense and fast to parse, though it is slightly less readable than separate bullet lines.

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 multi-action tool with no output schema, the description does not specify which parameters apply to each action or what the read actions return. The schema documents parameter meanings but not the action-parameter binding, which an agent needs for correct invocation; the action list covers basic selection but not full usage.

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 action parameter has no schema description, and the description supplies meaning for all four action values. Other parameters (type, enable, policy_in, policy_out, log_ratelimit) are already documented in the schema, so the description adds value without repeating those details.

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 'Query/manage cluster firewall metadata' and enumerates four concrete actions (get_options, update_options, list_macros, list_refs). The resource is clear, and the action list helps distinguish it from sibling tools for rules, aliases, groups, and ipsets, although those siblings are not explicitly named.

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 action list implies when to use the tool—for firewall options, macros, and refs—and flags update_options as '(elevated)'. However, it does not explicitly state exclusions or name alternative tools such as proxmox_cluster_firewall_rule, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description doesn't need to repeat. It adds that create/update/delete are 'elevated', providing extra context about permission requirements not captured in annotations. No contradiction.

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 compact and front-loads the purpose, using a clear pipe-separated action list. Every word earns its place, with no fluff or redundancy.

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 multi-action tool, it lacks explicit mapping of required parameters to each action. It also doesn't mention return values or side effects beyond the actions, though annotations cover destructiveness. This is a notable gap for an agent needing to know exactly what to pass for each action.

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 documents most parameters (80% coverage). The description ties actions to parameters implicitly (e.g., 'get alias by name' implies name parameter) but doesn't explicitly state which parameters are required for each action, leaving some ambiguity for an agent assembling calls.

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 it manages cluster firewall aliases and enumerates the specific actions (list, get, create, update, delete). The resource and operations are clear, distinguishing it from sibling tools that manage other firewall entities like rules or groups.

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?

Does not explicitly state when to use this tool vs alternatives, but the name and description imply it's for alias management. No mention of when not to use or which alternative to prefer, leaving some ambiguity for an agent comparing sibling tools.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds that create, update, and delete require elevated permissions, which is useful beyond the annotations. However, it does not disclose side effects, reversibility, or what happens on conflict, so it only moderately supplements the annotation 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 compact and front-loads the actions in a pipe-separated format, avoiding unnecessary prose. It is efficient, though the dense single line could be slightly clearer with a more structured presentation. No words are wasted.

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?

With six parameters, no output schema, and many sibling firewall tools, the description is not complete enough for reliable invocation. It fails to explain required parameter relationships (e.g., group needed for get/create/update/delete), optional parameter meanings, return behavior, or side effects. The action list covers part of the needed context but leaves significant gaps.

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 only 17%, so the description must compensate for undocumented parameters. It does clarify the action enum and that 'get' uses a group name, but it leaves delete, digest, rename, and comment unexplained. An agent would not understand the role of digest or rename for update/delete operations.

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 identifies the resource as cluster firewall groups and enumerates concrete actions (list, get, create, update, delete), so an agent can tell what the tool operates on. It is not perfectly specific because 'Manage' is vague, and it does not explicitly differentiate from sibling tools like proxmox_cluster_firewall_rule or proxmox_cluster_firewall_alias, but the resource name and action list are sufficient for basic purpose clarity.

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?

No guidance is provided about when to choose this tool over its many siblings, such as proxmox_cluster_firewall, proxmox_cluster_firewall_rule, or proxmox_cluster_firewall_ipset. The action list implies usage patterns, but there are no exclusions, preconditions, or alternative tool references.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds 'elevated' permission context for create/delete, which is useful beyond the annotations. However, it does not describe side effects of delete (e.g., impact on associated rules) or any other behavioral nuances.

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 sentence followed by a terse action breakdown. It is front-loaded with the purpose and each action is presented clearly without waste.

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 three actions and no output schema, the description covers action semantics but does not clarify that create/delete require the 'name' parameter while list may not. It also doesn't mention whether delete is irreversible or how this tool relates to proxmox_cluster_firewall_ipset_entry, leaving some details to inference.

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 67% and the action parameter only has an enum. The description adds meaningful semantics to each enum value ('list IP sets', 'create IP set (elevated)', 'delete IP set (elevated)'), which helps the agent select the correct action. The name and comment parameters are minimally described, but the schema already provides basic descriptions.

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 ('Manage cluster firewall IP sets') and enumerates three actions, which distinguishes it from siblings for rules, aliases, and groups. However, it does not explicitly clarify that individual entries within an IP set are handled by proxmox_cluster_firewall_ipset_entry, leaving a small ambiguity.

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 clear context of what the tool does and notes that create/delete require elevated permissions. But it does not explicitly direct the agent to alternative tools (e.g., alias, rule, ipset_entry) or state when not to use this tool, so guidance is mostly implied.

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

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

The description adds one useful behavioral detail—create/update/delete require elevated privileges—beyond the annotations. It does not elaborate on destructive consequences or idempotency, but annotations already declare destructiveHint and idempotentHint, so the added context is sufficient for a neutral score.

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 compact and structured as an action dispatch list, making the operation set easy to scan. The generic 'Manage' opener adds little, but the overall length is appropriate and free of unnecessary prose.

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 tool dispatches across multiple actions, so an agent needs conditional parameter guidance (e.g., cidr required for create/delete?) to call it correctly. That information is absent, and there is no output schema to clarify return behavior for list versus mutation actions.

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 80%, and parameter meanings such as cidr, name, comment, and nomatch are already provided in the schema. The description clarifies the action values but does not explain action-specific parameter requirements, such as which fields are needed for create versus update.

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 identifies the resource ('cluster firewall IP set entries') and enumerates the four concrete operations (list/create/update/delete), so an agent knows what the tool does. It does not explicitly distinguish it from the sibling tool managing IP sets themselves, but the 'entries' scope is clear enough.

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?

There is no guidance on when to use this tool versus proxmox_cluster_firewall_ipset or other firewall-related siblings. The action list is essentially a restatement of the enum, and no conditions, prerequisites, or exclusions are provided.

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

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

The description adds the useful detail that create/update/delete are elevated, which is not present in the annotations. The annotations already convey readOnlyHint=false and destructiveHint=true, so the mutation/destruction risk is covered; the description does not contradict them. It does not disclose additional behavioral details such as position shifting or update prerequisites.

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 compact, front-loaded with the resource name, and uses a clear action-keyed format. Every part contributes directly to understanding the tool's operations, with no filler or redundant explanation.

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 17-parameter action-dispatch tool with no output schema, this description is under-specified. It fails to indicate which parameters apply to each action, which are required for create/update/delete, or what positional and rule-field semantics matter, leaving agents to guess for anything beyond a trivial list or get call.

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 only 18%, so the description must compensate for the many undocumented parameters, but it only clarifies the action parameter and partially explains that 'get' uses a position. The remaining 16 parameters, including dest, source, dport, digest, rule_action, and iface, receive no meaningful semantic guidance.

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 clearly states the resource, cluster firewall rules, and enumerates the five supported operations: list, get, create, update, and delete. It is specific enough to identify the tool's purpose, though it relies on the tool name rather than explicit contrast to distinguish it from sibling firewall 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 gives per-action guidance and notes that create/update/delete require elevated privileges, which is useful context. However, it does not explain when to choose this tool over related siblings like proxmox_cluster_firewall_group, proxmox_cluster_firewall_alias, or proxmox_guest_firewall_rule, nor does it state any exclusions.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the safety profile is clear. The description adds a minor behavioral note by marking create/update/delete as 'elevated', which is useful. However, it doesn't disclose side effects or edge cases (e.g., what happens on delete), so it only marginally exceeds the annotation baseline.

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, terse sentence that front-loads the core purpose and then lists actions via pipes. It is efficient with no filler. However, it's dense and could benefit from line breaks or clearer grouping, but overall it's appropriately concise.

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?

Given the tool has 14 parameters, no output schema, and multiple actions, the description is severely under-specified. It doesn't explain which parameters are relevant for each action, what a replication job is, or how the 'elevated' flag affects invocation. An agent would struggle to construct correct calls without additional documentation. The description is far from complete for this complexity level.

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 only 21% (only 3 of 14 parameters have descriptions). The description provides zero parameter information—no mapping of actions to required parameters, no explanations of fields like 'source', 'target', 'schedule', or 'remove_job'. With such low schema coverage, the description should compensate, but it doesn't mention any parameters at all.

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 clearly states the tool manages cluster replication jobs and enumerates five specific actions (list, get, create, update, delete). This is a specific verb-resource combination that distinguishes it from node-level replication tools. However, it doesn't explicitly contrast it with proxmox_node_replication or other cluster job tools, so it's not a full 5.

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?

There is no guidance on when to use this tool versus alternatives like proxmox_node_replication. The description only lists actions without any context about prerequisites, when to choose this over sibling tools, or what scenarios warrant each action. The '(elevated)' hints at permissions but not usage context.

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

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

Annotations already indicate the tool is not read-only (readOnlyHint=false), not idempotent, and not destructive. The description adds the elevated-permission caveat, which is valuable, but it does not disclose other behaviors such as ticket expiry, side effects, or return format. Given the annotation coverage, the additional context is modest but present.

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, well-structured sentence that front-loads the action and resource. It contains no filler and conveys the essential purpose and permission requirement efficiently.

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?

With no output schema, the description should clarify what the tool returns and how the ticket is to be used. It only states that a ticket is obtained, leaving the agent to infer the response structure and subsequent usage. For a low-complexity tool, this is a moderate gap, but the description is otherwise sufficient for invocation.

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%, with both parameters (node and vmid) already documented. The description adds no extra parameter-level detail, so the baseline score 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 clearly states the action ('Get'), the resource ('SPICE proxy ticket'), and the target ('QEMU VM'), distinguishing it from sibling console tools like proxmox_console_vnc and proxmox_console_term. It also adds a meaningful prerequisite ('requires elevated permissions').

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 notes the permission requirement, which is useful context, but it does not explicitly specify when to use SPICE over the alternative console tools (VNC or terminal) or provide any exclusions. Since siblings exist, more guidance on selection would be helpful, but the protocol name itself implies its use case.

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

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

The description adds one useful behavioral detail beyond the annotations: the requirement for elevated permissions. It also implies a read-like retrieval operation through 'Get,' but does not disclose the returned ticket format, how it should be consumed, expiration behavior, or whether issuance has side effects. Since annotations provide no contradicting signals, this is moderate but not rich transparency.

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, tightly written sentence that front-loads the core action and resource before the scope and permission note. Every word earns its place, with no filler or redundant restatement of the title.

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 schema fully documents the three required parameters and the core purpose is clear. However, there is no output schema, and the description does not explain what the returned terminal proxy ticket looks like or how the agent should use it, which is important for a ticket-issuing tool. The elevated-permission note helps, but the missing return-value guidance leaves a noticeable gap.

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 all three parameters are already documented. The description adds a small semantic mapping by explaining that type=vm refers to a VM and type=lxc to a container, but this largely restates the enum values already present in the schema. No additional parameter semantics such as constraints or relationships are provided.

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 clearly states a specific verb ('Get') and resource ('terminal proxy ticket'), and scopes it to VM or LXC container via the type parameter. However, it does not explicitly distinguish itself from sibling tools like proxmox_console_vnc or proxmox_console_spice, so an agent may need to infer the difference.

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 only usage guidance is the parenthetical 'requires elevated permissions,' which is a prerequisite rather than a directive. There is no mention of when to choose this tool over proxmox_console_vnc, proxmox_console_spice, or proxmox_lxc_exec, nor any exclusions or alternative conditions.

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

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

Annotations are all false, offering no safety profile. The description describes a 'get' operation but does not disclose whether it is read-only, what side effects it might have, or the nature of the returned ticket. The mention of elevated permissions is a prerequisite, not a behavioral description, and no information is given about how the ticket is used.

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 concise sentence that front-loads the action, includes the key distinction (vm/lxc), and mentions the permission requirement. There is no redundant information or unnecessary elaboration, making it highly efficient.

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 tool is simple with three required parameters, but the description lacks information about the response format (since there is no output schema) and the intended use of the ticket. It does not explain what the agent should do with the ticket or how to connect to the VNC console, and it does not address potential error behavior for a tool requiring elevated permissions.

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 each parameter (node, vmid, type) is already described in the schema. The description adds no new semantic meaning beyond restating the type enum, which is already in the schema. It does not clarify relationships or format constraints beyond the schema, so a baseline 3 is appropriate.

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 clearly states a specific action: 'Get a VNC proxy ticket' and explicitly specifies the resource types (VM or LXC) via the type parameter. It distinguishes itself from sibling tools like proxmox_console_spice by naming VNC specifically, making the purpose unambiguous.

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 no guidance on when to use this tool versus alternatives such as proxmox_console_spice or proxmox_console_term. It only states the action and a permission requirement, without any 'when not to use' or reference to alternative tools, leaving the agent to infer usage context.

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

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

Annotations already mark this as not read-only and not idempotent; the description adds the useful auth requirement of elevated permissions. It does not disclose other behavioral context such as whether creation is asynchronous, what resources are consumed, or what happens on validation failure. No contradiction with 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 definition is a single front-loaded sentence: action and resource first, permission caveat parenthetically. It is efficient, though it forgoes the opportunity to weave in usage guidance without bloat.

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 9-parameter create operation with no output schema, this is minimally adequate: the schema covers all parameter semantics, and the description flags the key permission requirement. It is missing high-level behavioral context such as success output or how a node/template is validated, but it is not misleading.

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%, with rich descriptions and examples for all 9 parameters (e.g., net0 format, vmid uniqueness, ostemplate example). The description adds no parameter-level detail, so it stays at the baseline 3.

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?

Description states a clear action ('Create') and specific resource ('LXC container'), and the qualifier 'LXC' distinguishes it from the sibling proxmox_create_vm. The parenthetical adds a relevant permission constraint without obscuring the purpose.

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 provides one prerequisite ('requires elevated permissions') but no guidance on when to choose this tool over alternatives such as proxmox_create_vm or how to determine whether an LXC container vs a VM is appropriate. No exclusions or conditions of use are stated.

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

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

Annotations already indicate readOnlyHint=false and idempotentHint=false. The description adds the useful auth requirement ('requires elevated permissions') but does not disclose side effects, return value, or behavior when the vmid already exists. No contradiction with 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?

A single focused sentence with no filler; the core action and the permission caveat are front-loaded. Every word 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?

The schema fully covers parameter semantics, and the description adds the critical elevated-permission prerequisite. However, with no output schema and no mention of postconditions (e.g., whether the VM is started or what response is returned), an agent must infer several operational details.

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 documents all 11 parameters with descriptions and defaults, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides.

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 action and object: 'Create a new QEMU virtual machine'. This tells an agent the tool creates VMs rather than containers or clones, though it does not explicitly name alternatives like proxmox_create_lxc or proxmox_guest_clone.

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?

No guidance on when to prefer this tool over siblings. The only usage hint is 'requires elevated permissions', which is a prerequisite rather than a selection rule or exclusion.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the description does not need to restate safety. However, the description adds no behavioral context beyond the schema's action enum: it omits side effects of delete, prerequisites for create/update, or parameter interdependencies. It neither contradicts nor enriches 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, front-loaded sentence: the verb and resource appear first, followed by a compact parenthetical action list. There is no filler or repetition; every token 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?

For an 18-parameter, multi-action tool with no output schema, a one-line description is insufficient. It does not explain which parameters apply to which actions (e.g., create requires realm and type; LDAP needs server1 and base_dn), whether delete requires a digest, or what the tool returns. An agent would struggle to invoke non-trivial actions 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?

With schema description coverage at 94%, the schema already documents nearly all 18 parameters (e.g., 'Bind DN', 'Config digest', 'Primary server'). The description itself contains no parameter-specific information, so it adds no value over the schema; the baseline 3 applies because the schema does the heavy lifting.

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 resource, 'authentication domains', and enumerates the exact operations (list, get, create, update, delete), which distinguishes it from sibling tools targeting nodes, users, or storage. However, the verb 'manage' is generic and the description does not clarify what an authentication domain is (e.g., Proxmox realms such as LDAP/AD), so it is clear but not maximally specific.

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 implies usage when an agent needs to perform CRUD operations on authentication domains, but it offers no explicit when/when-not guidance or alternative tools. It does not mention that user/group management belongs to proxmox_user or proxmox_group, leaving the choice to inference from the resource name.

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

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

Annotations declare readOnlyHint=true, and the description aligns with that by specifying list and download actions, which are read-only. The description adds minimal behavioral context beyond the annotation: it clarifies the two operations but does not mention permissions, response formats, or side effects. Since annotations already cover the read-only nature, the description's contribution is modest but not redundant.

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 extremely concise: two short lines that state the purpose and enumerate the actions. It is front-loaded with the main intent and contains zero fluff. Every word earns its place, making it highly efficient for an agent to parse.

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 6 parameters (4 required) and no output schema, the description is too sparse. It does not explain which parameters are needed for each action (e.g., list likely uses 'path' while download uses 'filepath'), nor does it describe the return structure. Without this guidance, an agent may supply incorrect parameters or misread the results. The absence of an output schema increases the description's responsibility, which it fails to meet.

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 83%, so the schema already documents most parameters. The description adds value only for the 'action' parameter by enumerating its values (list, download), which is helpful. However, it does not clarify how 'path' and 'filepath' relate to the different actions, or explain the purpose of node, storage, and volume beyond their schema descriptions. The baseline for high coverage is 3, and the description adds only marginal clarity.

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 clearly states the tool's purpose: 'Restore files from backup' and immediately specifies the two actions (list and download). It is specific about the resource (backup files) and distinguishes the two modes. However, it does not explicitly differentiate from sibling tools like proxmox_backup or proxmox_storage_content, though the actions make it clear it is about file-level operations.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when list vs download should be chosen, or any context about the backup storage. The only hint is the action enumeration, which is already in the schema. There is no explicit 'use this instead of X' guidance, leaving the agent to infer usage.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds minimal behavioral context beyond that—it doesn't explain how the ID is determined (e.g., whether it scans existing guests, whether it's guaranteed unique, or whether it might return an ID already in use). With annotations covering the safety profile, a 3 is appropriate.

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?

A single, clear sentence with no wasted words. The description is front-loaded with the verb and resource, and there's no extraneous information.

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 zero-parameter read-only tool, the description is mostly complete. However, it doesn't mention what the return value looks like (e.g., an integer) or whether the ID is guaranteed to be free at the moment of creation. Since there's no output schema, a brief note on the return format would improve completeness.

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 tool has zero parameters, and the schema coverage is 100% (vacuously). The description correctly indicates the tool takes no input and simply returns a value. There's nothing more the description could add about parameters, so the baseline 4 for zero-parameter tools 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 verb ('Get') and resource ('next available VM/Container ID number'), which clearly identifies the tool's function. It doesn't explicitly differentiate from siblings, but the resource is specific enough that an agent can distinguish it from the many other proxmox 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 implies usage context: it's a read-only lookup for the next available ID, likely used before creating a VM/container. However, it doesn't explicitly state when to use it versus alternatives like proxmox_guest_list or proxmox_create_vm, nor does it mention that it's a prerequisite for creation workflows.

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

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

Annotations already convey readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds the explicit action set (create/update/delete), which aligns with the destructive annotation. However, it adds no context about side effects, permissions, or behavior beyond what the annotations and schema already state.

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, front-loaded sentence with no filler. It efficiently names the resource and the four actions, earning its place. It is slightly terse but appropriately concise for the scope.

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 multi-action CRUD tool with 7 parameters and no output schema, this description is minimal. It lacks context about group semantics, update behavior (e.g., replacing vs. appending users), or effect of the digest parameter. The agent must rely entirely on the schema to understand call semantics, which is a notable gap for confident invocation.

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 86%, so the schema already documents most parameters (users, append, delete, digest, comment, groupid). The description adds no parameter-level meaning beyond the action list, which is also captured by the action enum. With high schema coverage, a baseline of 3 is appropriate.

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 uses a specific verb 'Manage' with the resource 'Proxmox groups' and enumerates the supported actions: list, create, update, delete. This makes the scope clear and distinguishes it from many sibling tools, though it does not explicitly differentiate itself from proxmox_ha_group or other group-adjacent resources.

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 no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or reasons to prefer a sibling tool like proxmox_user or proxmox_role. The agent must infer usage solely from the generic action list.

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

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

Annotations are all false and therefore provide no meaningful behavioral safety profile. The description adds one behavioral fact, elevated permissions, and clarifies supported guest types. However, it does not disclose side effects, postconditions, or whether the operation is asynchronous, so it only partially compensates for the absent annotation support.

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 sentence with no wasted words. The core action and supported resource types are stated efficiently, and the permission requirement is included as a compact parenthetical.

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?

This is a mutating tool with no output schema and no useful annotation hints, so the description carries the burden of explaining consequences. The one-line description covers the basics but omits clone semantics, error conditions, and any return value information; the schema covers parameter details, making the bare minimum for invocation present.

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 83%, so the schema already documents most parameters (node, vmid, newid, name, hostname). The description only echoes the type parameter's enum values, adding no meaning beyond what the schema provides, 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 uses the specific verb 'Clone' and clearly names the resource ('VM (type=vm) or LXC container (type=lxc)'). It matches the tool name and makes the core operation unambiguous, though it does not explicitly distinguish itself from create-style sibling 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 only usage hint is 'requires elevated permissions,' which is a prerequisite rather than a selection guideline. There is no guidance on when to use clone versus create_vm/create_lxc or other guest operations, leaving the agent to infer the appropriate context.

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

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

readOnlyHint=true already establishes that the operation is safe, and the description's 'Get' aligns with that annotation. The description adds useful scope (hardware configuration for vm/lxc) but does not disclose return format, error behavior, or any additional behavioral traits; acceptable given the read-only annotation.

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 front-loaded sentence with no filler. It states the action, the resource, and the relevant type distinction, earning each word.

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 simple read-only 3-parameter tool, the description plus schema and annotation are sufficient for correct invocation. It does not describe the output structure or explicitly exclude sibling tools, but the low complexity makes those gaps minor.

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 documents 'node' and 'vmid' well, and the description compensates for the undocumented 'type' parameter by explaining that vm means VM and lxc means LXC container. This adds meaning beyond the raw enum values without duplicating schema descriptions.

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 ('Get'), a specific resource ('hardware configuration'), and immediately disambiguates the two target types (vm/lxc). This clearly separates it from runtime status tools and the config update sibling.

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 makes it clear that the tool applies to VM or LXC guests, but it does not explicitly distinguish when to use this over related siblings like proxmox_guest_status, proxmox_guest_pending, or proxmox_guest_config_update. Usage context is implied rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's job is lighter. The description adds the 'requires elevated permissions' context and the delete parameter explicitly clarifies it removes config keys, not the VM. This adds meaningful behavioral context beyond 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 concise sentence that front-loads the action and resource, with the type constraint and permission requirement appended. It earns its place without redundancy, though it could be slightly more structured with explicit when-to-use guidance.

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 mutation tool with no output schema, the description plus annotations cover the key aspects: what it does, that it is destructive, that it is idempotent, and that elevated permissions are needed. The main gap is not explaining the effect of the config object on existing settings (merge vs replace), but the pointer to proxmox_guest_config partially mitigates this.

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 80%, so the schema already documents most parameters. The description adds value by clarifying the delete parameter's semantics ('Does NOT delete the VM') and by pointing to proxmox_guest_config for valid keys. The config parameter's free-form object nature is partially compensated by that pointer.

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 ('Update') and resource ('VM/LXC config key-value pairs'), and distinguishes the target type (vm|lxc). It is clear enough to separate from sibling tools like proxmox_guest_config (read) and proxmox_guest_delete (delete VM), though it does not explicitly name those alternatives.

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 implies usage context: it is for updating config key-value pairs on a VM or LXC, and the config parameter description points to proxmox_guest_config for discovering valid keys. However, it does not explicitly state when to use this tool versus alternatives like proxmox_guest_pending or proxmox_guest_config, nor does it mention prerequisites beyond elevated permissions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the destructive nature is covered. The description adds useful behavior beyond annotations by stating the elevated permission requirement and clarifying the VM/LXC type distinction. No contradiction with annotations exists.

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, front-loaded sentence with no filler. It states the action, the target resource, and the permission caveat in a compact and immediately scannable format.

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 simple deletion tool with only three parameters and no output schema, the description plus annotations cover the essential operational context: what is deleted, the required parameters, the elevated permission requirement, and the destructive nature. It could mention consequences like permanent removal of disks, but the destructiveHint annotation mitigates that gap.

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 67%, with 'node' and 'vmid' already described in the schema. The description adds semantic meaning for the 'type' parameter by pairing 'vm' with 'VM' and 'lxc' with 'LXC container', which is helpful but modest. It does not add further parameter details beyond what the schema already provides.

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 uses a specific verb ('Delete') and clearly identifies the resource types ('VM' and 'LXC container'), including how the 'type' parameter maps to each. It is unambiguous and easily distinguished from sibling tools like proxmox_guest_stop or proxmox_guest_shutdown, which imply non-destructive state changes.

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 clearly implies the tool is for permanent removal of a guest rather than stopping or shutting it down, and it adds a prerequisite ('requires elevated permissions'). It does not explicitly name alternatives or give when-not-to-use guidance, but the deletion intent is contextually clear enough for tool selection.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description does not need to restate those. The description adds one useful behavioral fact: elevated permissions are required. However, it does not disclose that the move may delete the source disk by default or that the operation is a live storage migration, relying on the schema's delete parameter and the destructive annotation to carry that weight.

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 sentence with no filler and front-loads the primary action. The parenthetical 'type=vm' and 'type=lxc' is somewhat redundant with the schema enum, but it is compact and useful. It earns a high score for brevity without losing core information.

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?

Given the destructive annotation, high schema coverage, and no output schema, the description is minimally viable: it states the action, target resource types, and a permission requirement. Still, it lacks any mention of operational consequences such as source disk deletion by default or expected task behavior, which would help an agent fully anticipate the outcome.

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 83%, and the schema already documents parameters such as disk examples, node, vmid, storage, and the delete default. The description only restates the type enum values and adds the permission note, providing no new parameter-level meaning. This meets the baseline for high schema coverage but adds little beyond it.

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: 'Move guest storage for VM (type=vm) or LXC container (type=lxc)'. It clearly identifies the tool's scope and the required type distinction slash target. However, it does not explicitly contrast with sibling disk/storage tools such as resize or migrate, so it falls short of full differentiation.

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 no guidance on when to use this tool versus alternatives like proxmox_guest_migrate or proxmox_guest_disk_resize. 'Requires elevated permissions' is a permission prerequisite, not a usage condition. There is no mention of constraints such as target storage availability or whether the guest should be stopped.

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