proxmox-mcp
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation4/5
While the tool set is large, each tool targets a distinct resource or action. Potential overlaps like list_backups vs storage_content with content='backup' are clarified by descriptions. A few tools such as resource_summary aggregate data from multiple list tools, but this is an intentional convenience rather than a source of ambiguity.
Naming Consistency4/5Most tools follow a verb_noun pattern (list_guests, create_vm, start_guest), but some use noun-based names (guest_config, node_status) and the pve_* pair deviates. The naming is still predictable and consistent within categories, so the mix is a minor deviation.
Tool Count2/5At 34 tools, this exceeds the threshold for a well-scoped server. While each tool has a clear purpose, the count is high enough to make it heavy, and many tools could be consolidated (e.g., lifecycle actions). The availability of pve_get/pve_discover adds redundancy.
Completeness2/5There are significant gaps in the lifecycle surface: no delete/destroy for guests, no snapshot deletion or rollback, no backup restore, and no network/access management beyond listing. The generic pve_get tool is read-only, so these missing operations cannot be performed at all, causing dead ends.
Average 4.2/5 across 34 of 34 tools scored. Lowest: 3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 4 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states the action without disclosing any behavioral traits such as potential failure conditions, permission requirements, or side effects. With all annotations set to false, the description carries the full burden, and it fails to provide any context beyond the verb itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence that is front-loaded and contains no fluff. Every word contributes to conveying the tool's function, making it an exemplar of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description is minimally adequate but omits important context. It does not clarify what 'resume' entails (e.g., that the guest must already be suspended) nor explain the 'vmid' parameter, leaving gaps in completeness despite the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single parameter 'vmid' with no description, and schema description coverage is 0%. The tool description does not mention 'vmid' at all, leaving the agent to guess that it refers to the VM/container ID. Since coverage is low, the description should compensate, but it entirely omits parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Resume') and resource ('suspended VM or container'), clearly distinguishing it from sibling tools like start_guest or shutdown_guest. The action is unambiguous and directly conveys the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like start_guest or suspend_guest. It neither mentions prerequisites (e.g., guest must be suspended) nor excludes scenarios where other tools are more appropriate, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context beyond annotations, notably that each guest has a 'confirm token used by destructive tools', and it clarifies the scope covers both VMs and containers. However, it does not disclose pagination, ordering, or potential permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the core action and resource, and lists the output fields concisely. Every word earns its place; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the read-only annotations, and the presence of an output schema, the description provides sufficient context. It mentions the confirm token detail, which is valuable for downstream destructive tools. It could have briefly indicated optional filters, but the schema covers them adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for parameter documentation but does not. It makes no mention of `running_only` or `include_templates`. While the property names are self-explanatory, the description itself adds no parameter semantics, so the burden is entirely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List every VM and LXC container' and specifies the output fields. This distinguishes it from sibling tools like guest_status or guest_config, which target individual guests, and resource_summary, which aggregates differently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. There is no mention of exclusions, prerequisites, or scenarios favoring list_guests over similar list tools. The description implies enumeration but does not state context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description must disclose behavior. It adds context about to_disk (hibernate vs RAM) but does not mention reversibility, that the VM must be running, or side effects like resource release. This is partial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a single line plus a compact Args block. Every sentence adds necessary information without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description covers the core action and parameters. However, it omits relational context (e.g., it can be undone with resume_guest) and preconditions (VM must be running), which would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), but the description's Args section clearly explains both parameters: vmid is 'Guest to suspend' and to_disk means 'Write memory state to disk (hibernate) instead of holding it in RAM'. This effectively compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Suspend') and resource ('VM'), clearly stating the tool's action. It distinguishes from siblings like start_guest and stop_guest, though it doesn't explicitly mention alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, nor any exclusions or prerequisites. It simply states the action, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only operation (readOnlyHint: false), and the description adds no extra behavioral context such as side effects, permission requirements, or failure scenarios. With minimal annotation coverage, the description carries little additional transparency beyond the simple action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the action and target. No unnecessary words or repeated information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter tool with an output schema present, and the description conveys the core purpose clearly. It does not specify prerequisites or edge cases, but for a straightforward start operation, the information is sufficient. Slightly lacking in usage guidance but overall complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single required parameter 'vmid' with no description, and the description does not explicitly explain it. However, the parameter name is self-explanatory as a VM ID, and the description 'Start a stopped VM or container' implies the vmid identifies which guest to start, adding some context beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Start a stopped VM or container.' clearly states the action (start), the resource (VM/container), and the condition (stopped). It distinguishes from siblings like stop_guest, shutdown_guest, reboot_guest, and suspend_guest by focusing on the start operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a VM or container is stopped, but provides no explicit guidance on when not to use it or how it differs from related operations like resume_guest. The phrase 'stopped VM or container' gives some context, but it's not clearly differentiated from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses some behavioral traits, such as the 'wait' parameter returning a UPID instead of a result, and mode options including 'snapshot' (no downtime). However, it does not describe broader side effects like backup duration, storage requirements, or what a UPID means to the caller.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear opening line followed by a compact parameter list. No wasted words; every line provides necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the fact that all parameters are explained, the description is fairly complete for invoking the tool. It lacks high-level context such as prerequisites or typical use cases, but these are not critical for this moderate-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by explaining every parameter: vmid, storage, mode (with allowed values), compress (with allowed values), notes, and wait (with behavior). This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Back up') and resource ('VM or container'), and even names the underlying utility (vzdump). This distinguishes it from sibling tools like create_snapshot or list_backups, which are related but different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 only lists parameters with no contextual direction, such as when a backup is preferable to a snapshot or clone. This leaves the agent without clear decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, providing no positive safety information (e.g., not read-only, not idempotent). The description adds little beyond the stated action; it does not disclose side effects, whether the VM needs to be stopped, failure modes, or if changes are immediately applied. The only additional hint is to read first, which is more of a usage guideline than a behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an args list, front-loaded with the purpose. Every element earns its place, including the example settings which convey format and usage without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two parameters and an output schema, so the description covers the core usage. It omits details about preconditions (e.g., running vs. stopped VM) and error behavior, but the guidance to read guest_config first and the example payload provide enough context for a typical agent to invoke the tool correctly. The presence of an output schema reduces the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must clarify parameters. It does so effectively: vmid is explained as 'Guest to reconfigure', and settings are described with concrete examples and the note that values are strings. This adds significant meaning beyond the raw schema, though it could be slightly more explicit about valid key names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Change' with the resource 'configuration keys on an existing VM or container', clearly distinguishing it from create_vm, guest_config, and lifecycle tools. It avoids ambiguity and directly states the scope of the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by instructing to 'Read guest_config first to see current values', which implies the complementary use of guest_config for reading before modifying. It does not explicitly list when-not-to-use or alternatives, but the guidance is sufficient for a typical workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the mutation aspect is already known. The description adds the 'gracefully' qualifier and explains that the timeout parameter concerns 'the shutdown half of the reboot,' which is useful behavioral context. However, it does not disclose what happens if the timeout expires or whether a guest agent is required, so transparency is decent but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: a single purpose sentence followed by a minimal args list. Every word earns its place, and it is front-loaded with the core purpose. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 params, no enums, output schema present), the description is largely adequate. It explains what the tool does and covers both parameters. However, it misses important context such as the requirement that the guest must be running and the effect of a timeout on the shutdown phase, leaving slight gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides concise semantics for both parameters: 'vmid: Guest to reboot' and 'timeout: Seconds to wait for the shutdown half of the reboot.' This adds meaning beyond property names, though it omits details like the default value (60) and potential allowed ranges.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence 'Gracefully reboot a VM or container' clearly states the action (reboot) and the resource (VM or container). The verb is specific and effectively distinguishes this tool from siblings like shutdown_guest, stop_guest, suspend_guest, and resume_guest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by saying 'Gracefully reboot a VM or container' but provides no explicit guidance on when to use it versus alternatives. It does not mention prerequisites (e.g., VM must be running) or scenarios where a forced stop might be preferred. Usage is merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior, and the description is consistent with that. It adds that the listing is specific to the host's configured access entities, but no additional behavioral details beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the tool's function without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only listing with no parameters and an output schema. The description provides sufficient context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema fully covers parameter semantics (100% coverage). The description does not need to add parameter details. Per rubric, baseline 4 for 0 params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists users, groups, roles, and resource pools on the host. This is a specific verb and resource set, and it distinguishes from sibling tools like list_networks and list_guests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives, but the description implies its purpose as the access-listing tool among the sibling group. It does not mention exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the scope (system services and their running status) but does not disclose additional behavioral details such as permission requirements or output format specifics. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, resource, and expected output with relevant examples. Every word contributes value; there is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, parameterless tool with an output schema present, the description sufficiently covers what the tool does and what the user should expect. It is complete for its simplicity and aligns with the context signals.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema trivially covers 100% of them. With no parameters to explain, the baseline is 4, and the description adds nothing needed beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Proxmox system services and indicates whether each is running, providing specific examples (pveproxy, pvedaemon, pve-cluster). This distinguishes it from sibling list tools like storage_content or list_networks, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking system service status, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. It lacks explicit guidance but is not misleading, so it earns an implied-usage score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds context about the UPID format and the limit parameter, but does not disclose additional behavioral nuances like response size or error handling. It provides some value 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-sentence summary followed by a two-item Args list. It is front-loaded with the core purpose and includes only necessary details. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema available, return values need not be described. The description covers the tool's purpose, the UPID identification, and the limit parameter. It does not specify whether the log can be fetched for running tasks, but this is a minor gap given the presence of wait_for_task sibling. Overall, it is sufficient for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description's Args section is critical. It explains the UPID format with an example and defines limit as 'Maximum log lines', which adds meaning beyond the schema's plain property names and types. Both parameters are sufficiently documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and specifies the resource: status and full output log of one task identified by UPID. This clearly distinguishes it from sibling tools like list_tasks (which lists multiple tasks) and wait_for_task (which waits for completion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates this tool is for retrieving the log/status of a single task when a UPID is known. It implies usage for individual task inspection but does not explicitly name alternatives or exclusions. The 'one task' phrasing provides clear context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a mutation (readOnlyHint false). The description adds significant behavioral context by stating the operation is one-way and the guest can no longer be started, only cloned. This goes beyond the annotations, though it omits permission requirements or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences, front-loaded with the action and resource. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, output schema available), the description covers the essential purpose, the prerequisite of a stopped guest, and the irreversible consequence. It is complete for its scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the 'vmid' parameter. It implies the parameter refers to a stopped VM or container and adds the 'stopped' constraint, but it does not explicitly map the parameter name or explain it beyond that. This meets a minimal viable standard.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Convert') and resource ('VM or container') to clearly state the tool's function. It distinguishes from siblings like clone_guest or create_snapshot by the final template state and includes the 'stopped' prerequisite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for converting a stopped guest into a template, and the note 'only cloned from' hints at the subsequent workflow. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive write operation. The description adds valuable context: snapname format constraints, description semantics, and the include_ram effect ('save RAM so the guest resumes mid-run'). This goes beyond the annotations, though it doesn't discuss side effects like guest suspension.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact docstring with a clear Args section. Each line contributes necessary information; there is no fluff, repetition, or irrelevant detail. It is well-structured and easily skimmable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter mutation tool, the description covers all parameters, includes format constraints, and explains optional behavior. An output schema exists, so explaining return values is not necessary. Minor missing context: prerequisites or failure modes are not mentioned, but this is acceptable given annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It explains every parameter in plain language: vmid ('Guest to snapshot'), snapname (with format rules), description ('Optional note stored with the snapshot'), and include_ram (VM-specific RAM saving). This far exceeds the bare type information in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Take a snapshot of a VM or container', which is a specific verb+resource statement. This clearly distinguishes it from sibling tools like create_backup and list_snapshots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the purpose and parameter documentation, but there is no explicit guidance on when to use this tool over alternatives such as create_backup. No exclusions or when-not-to-use scenarios are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the scope of what is listed, but it does not disclose behavioral traits such as required permissions, potential latency, or edge cases (e.g., no interfaces found). This is adequate but not particularly rich, matching the get_calls calibration example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the meaning, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters), the presence of an output schema, and annotations indicating a safe read operation, the description sufficiently conveys the purpose and scope. Additional details about return values are unnecessary because the output schema covers them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is effectively 100% (empty property set). Baseline for zero params is 4, and the description does not need to provide parameter details since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List') and resource ('network interfaces on the node'). It enumerates the exact types of interfaces included (bridges, bonds, VLANs, physical NICs) and what information is returned (configured and active state), which distinguishes it from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly defines when to use the tool: whenever node network interface details are needed. It differentiates from siblings by the resource focus, but it does not explicitly state alternatives or exclusionary conditions, making 'clear context, no exclusions' the best fit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, which establishes the safety profile. The description adds meaningful context about the synthetic 'current' entry and the confirm token included for each snapshot, enriching expectations of the output. No contradictions 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence of about 24 words, front-loaded with the core action and resource. Every phrase adds value: the synthetic 'current' entry and the confirm token purpose. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple parameter set, the presence of an output schema, and annotations covering safety, the description is complete. It adds the key context about the token and synthetic entry that structured data does not provide. No critical information is missing for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required parameter vmid. The description implies vmid is the identifier of the VM or container by saying 'of a VM or container', providing minimal compensation. It does not explain format or how to obtain the value, but for a simple integer parameter this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states the verb 'List' and the resource 'snapshots of a VM or container', which is specific and clear. It also mentions the synthetic 'current' entry and the confirm token, making it distinct from other list-type sibling tools like list_backups or list_guests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by noting the confirm token is needed for delete or rollback, signaling when this tool is a prerequisite. However, it does not explicitly name alternatives or give when-not-to-use guidance, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is established. The description adds the returned fields but does not disclose additional behavioral details such as pagination, error conditions, or permission requirements, which would be needed for a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and the key output fields without redundancy. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, output schema present, safe annotations), the description fully captures the tool's purpose and output coverage. It is complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter burden to explain; the empty schema is fully covered. The description correctly indicates a no-argument listing operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('configured storages') and enumerates the exact attributes returned: type, enabled state, content types, and space usage. This clearly distinguishes it from sibling tools like storage_content, which suggests a different operation on storage contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: retrieving an inventory of storage configurations with no parameters and read-only annotations. It does not explicitly name alternatives or exclusions, but for a simple listing tool the context is sufficiently clear to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and non-destructive, and the description adds valuable behavioral context: it lists tasks newest first and explains that tasks are the job log behind every operation. It does not disclose pagination or default limits, but these are parameterized and the description adds enough 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise paragraph followed by a compact Args list. It front-loads the core purpose and then lists each parameter in a single line, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description covers the core use case and all parameter semantics. It could optionally mention when to use task_log for individual task details, but that is not essential for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter: limit, errors_only, vmid, and typefilter, with a concrete example for typefilter. This makes the parameters meaningful and actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists recent Proxmox tasks and frames it as the job log behind operations, with the specific use case of diagnosing failures. It is a specific verb+resource, but it does not explicitly differentiate from sibling tools like task_log or wait_for_task, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'Use this to find out what happened and why something failed.' It does not, however, mention alternatives or when not to use it, so it falls short of explicit when-to-use vs. when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the specific set of returned metrics but no additional behavioral caveats (e.g., response size, polling behavior), which is acceptable given 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that lists all relevant result dimensions without waste. Every word contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, a read-only annotation, and an output schema present, the description covers the essential information: what the tool returns (CPU, memory, swap, etc.) and for which resource (the node). No further details are necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty, so the description need not add parameter details. Per the rubric, a zero-parameter tool receives a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('detailed live status for the Proxmox node'), and enumerates concrete data points (CPU, memory, swap, etc.). This clearly distinguishes it from sibling tools like guest_status or resource_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the tool's context clear: use it to get detailed live status of the Proxmox node. It does not explicitly name alternatives or exclusions, but its scope is unambiguous enough for an agent to know when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's job is lighter. It reinforces this with 'Read-only — this does not install anything,' which adds a small behavioral nuance beyond the annotations, but there is no deeper detail about refresh behavior or scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose and a clarifying safety note. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, an output schema present, and annotations covering read-only status, the description fully covers what the tool does, including the security-update distinction. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter details; the empty schema covers all parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available package updates for the node, including security updates. This uses a specific verb (list) and resource (package updates), distinguishing it from other list_* tools like list_networks or list_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly name alternatives or exclusions, but the read-only note and the sibling tool set imply this is for checking updates, not applying them. This provides clear context for when to use the tool, though it lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the 'walk the API tree' context, but this is more about usage than behavioral traits. It does not cover rate limits, auth, or response details, though the output schema handles return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: a two-sentence purpose followed by a compact Args section with examples. Every sentence earns its place with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations covering safety, an output schema present, and a single well-explained parameter, the description is complete for an agent to select and invoke the tool. The 'curated tools do not cover' statement provides key ecosystem context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the path parameter, but the description compensates by defining it as the API path to list and providing concrete examples ('/', '/nodes'). This adds significant meaning beyond the bare schema with a default of '/'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and resource 'child endpoints of a Proxmox API path', and explicitly mentions covering endpoints the curated tools do not, which clearly distinguishes it from sibling tools like list_guests or storage_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is for endpoints the curated tools do not cover, providing clear context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full exclusivity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no safety hints (all false), so the description must explain behavior. It discloses that the tool blocks and waits up to a timeout, but it doesn't specify what happens on timeout or whether the operation is non-mutating. This leaves some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, a usage context sentence, and an Args section. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two parameters and an output schema, and the description provides sufficient context. However, it could mention timeout outcome explicitly; the output schema likely covers return values, so a 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite having 0% schema description coverage, the description manually explains both parameters: upid as 'Task ID returned by an earlier tool' and timeout as 'Maximum seconds to wait.' This adds meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Block until a Proxmox task finishes, then report how it ended' which clearly defines the tool's function with a specific verb and resource. It distinguishes itself from sibling tools like list_tasks and task_log by focusing on waiting for completion rather than listing or reading logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when another tool returned a UPID because the job outlived its polling budget,' providing a clear context for when to invoke the tool. It does not mention when not to use it or direct users to alternatives, which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are uninformative (all false), so the description carries the burden. It discloses the core creation behavior, the uniqueness requirement for vmid, the boot disk specification, and that iso is attached as ide2. It does not discuss failure modes or permission requirements, but the primary side effects are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact, labeled list from vmid to extra, with each line dedicating one sentence to meaning and example. The opening sentence establishes purpose, and there is no redundant or promotional text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 11 parameters and no schema descriptions, the description provides all necessary invocation details: required parameters, optional parameters with defaults, format examples, and a prerequisite check. It also mentions the output behavior via the start flag, though the output schema presumably covers return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully documents all 11 parameters with types, defaults (e.g., bridge=vmbr0), units, and concrete examples (e.g., 'local-lvm:32'). This goes far beyond the bare schema and enables correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Create a new QEMU virtual machine' – a specific verb and resource. This clearly differentiates from sibling tools like create_container (container creation) and clone_guest (cloning existing VMs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for new VM creation but does not explicitly state when to prefer this over alternatives like create_container or clone_guest. It does include a prerequisite ('check list_guests first') which offers some guidance, but no explicit exclusions or alternative tool mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the tool spans all backup-capable storages and includes scheduled job configs, which is useful behavioral context. It does not mention additional traits like pagination or performance implications, but with the output schema present, the value is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a brief Args block. It is front-loaded with the primary purpose and contains no unnecessary words. Every sentence earns its place, and the structure is clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one optional parameter, an output schema, and annotations covering read-only/destructive behavior, the description provides sufficient context. It explains what the tool returns (backup archives and scheduled jobs) and the filtering option, making it complete for an agent to select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fully explains the only parameter, vmid, as an optional filter to one guest's backups. This gives the agent all the semantic meaning needed to use the parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists backup archives across all backup-capable storage and also shows configured scheduled backup jobs. This distinguishes it from siblings like create_backup (creation) and storage_content (general storage browsing) by specifying the backup-specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use this tool when you need to see backup archives or scheduled backup jobs across all storages. It mentions the optional vmid filter for narrowing to one guest. However, it does not explicitly name alternative tools or state when not to use it, which would push it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the note 'Always safe — GET never mutates,' which goes beyond the readOnlyHint annotation by explaining the HTTP method and safety. This is useful behavioral context. It does not contradict 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and well-structured: a short definition, a fully worked example, and a brief args list. Every sentence adds value and nothing is extraneous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema is present, so return-value details are not needed. The description provides context, an example, and a pointer to pve_discover. It could mention potential errors or authentication scope, but for a simple generic GET tool this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining path as 'Full API path, starting with /' and params as 'Optional query parameters.' The example illustrates usage, though details on valid param keys or value formats are left generic, so a 5 is not warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads any Proxmox API endpoint directly, with a concrete example (pve_get('/nodes/pve/qemu/100/firewall/rules')). It is specific about the action (read) and resource (API endpoint), distinguishing it from higher-level read tools like guest_config or guest_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly suggests using pve_discover to find paths, giving clear context for when to use this tool (when you need direct endpoint access and have a path). However, it does not explicitly state exclusions or name alternative tools for the same purpose, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to reassert that. It adds useful behavioral detail such as the newest-entries-last ordering and the purpose of parameters, going slightly beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a clear Args list. No redundant or filler content; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with an output schema, the description covers the purpose, parameters, and output ordering. The presence of an output schema means return values don't need explanation. No critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, but the description's Args section fully explains each parameter: limit (maximum lines), since (optional start time with examples), and service (systemd unit filter with example). This fully compensates for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('node's system log') and clarifies output ordering ('newest entries last'). This clearly distinguishes the tool from sibling log-related tools like task_log.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the description, but there is no explicit guidance about when to use this tool versus alternatives like task_log. It lacks exclusions or comparisons to sibling tools, which is a gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds context about the types of volumes returned and the semantics of filters, which helps set expectations beyond the schema, but it does not disclose behaviors like pagination or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose, followed by a structured Args list that is easy to scan. Every sentence contributes necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to detail return values. It covers the tool's purpose, all parameters, and example values, making it sufficient for a straightforward read-only listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions (0% coverage), but the Args section thoroughly explains all three parameters with types, examples, and enumerated allowed values for content. This fully compensates for the schema's lack of detail and adds significant semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists volumes in a storage and enumerates specific content types (disk images, ISOs, container templates, backup archives), clearly distinguishing it from siblings like list_storage. The verb and resource are precise and action-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context by requiring a storage ID and offering optional content and vmid filters, making it easy to infer when to use this tool. However, it does not explicitly name alternatives or exclusion criteria, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits beyond the annotations, such as linked clones depending on a template and remaining dependent on it, and storage defaulting to the source's. This adds value beyond the false flags in annotations, though it does not cover permissions or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured as a concise summary followed by a bullet-style Args list. Every sentence contributes semantic value, and the most important action is front-loaded. It is appropriately sized for a five-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description covers the core inputs and dependencies well. It does not describe the output format, but the output schema presumably handles that. Minor gap: no mention of when to prefer create_vm instead, but overall completion is strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining every parameter's meaning and constraints in the Args block. It clarifies that new_vmid must not already exist, defines full, and specifies storage defaults, exceeding what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Clone a VM or container into a new guest.' This clearly defines the tool's function and distinguishes it from sibling tools like create_vm or convert_to_template by focusing on cloning an existing guest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to clone a source guest) and explains key decision factors like full vs linked clones. It does not explicitly name alternative tools or state when not to use it, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only and non-destructive; the description reinforces this with 'Get' and adds scope detail ('every other config key'), which is useful context about the return value. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the operation and resource, then expands with examples. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only) and the presence of an output schema, the description covers the essential aspects: what it gets, its scope, and what is included. No additional behavior or return format explanation is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only one required integer (vmid) with 0% schema description coverage. The description indirectly clarifies that the parameter refers to a specific VM or container, which is enough for this obvious single parameter. It does not explicitly name vmid but the context makes it clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('full configuration of a VM or container'), enumerates example keys (disks, network, memory, CPU, boot order), and clearly distinguishes from sibling tools like guest_status and set_guest_config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving complete configuration details, which is distinct from siblings like list_guests (summary) or guest_status (state). It does not explicitly name alternatives or exclusions, but the context is clear for a simple getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's consistency with a read-only operation is expected. It adds value by enumerating the exact metrics returned (power state, uptime, CPU/memory usage, disk/network I/O counters), giving the agent a precise expectation of output content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded verb, no filler. Every phrase adds information about the return data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only nature, a single integer parameter, and the existence of an output schema, the description fully captures the tool's purpose and expected data. No gaps for the agent to get lost.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the vmid parameter directly, but it clarifies that the target is a VM or container, which maps naturally to the vmid. With only one obviously required integer parameter, the schema plus the description provide sufficient semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and names the resource 'live runtime status for a VM or container', listing concrete metrics (power state, uptime, CPU/memory, I/O). It clearly differentiates from sibling tools like guest_config (static config) or list_guests (listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'live runtime status' implies real-time monitoring, which distinguishes it from configuration or lifecycle tools. However, it doesn't explicitly state when not to use it or name alternatives, so it lacks explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a safe read-only, non-destructive operation. The description adds valuable context by stating that it returns a host-wide overview in one call, covering health, guests, and storage. It does not mention performance or response details, but the output schema compensates, and there is 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the core purpose ('Get a one-shot overview'), and every phrase earns its place—'whole Proxmox host', the listed contents, and the 'start here' guidance. There is no redundant or filler language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, a read-only annotation, and an output schema, the description is complete for an agent to invoke this tool correctly. It fully communicates what the tool returns and when to use it, and no missing information would hinder selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty, so there are zero parameters to document. Per the rubric, this yields a baseline of 4. The description correctly implies that the tool requires no arguments and provides a complete overview by default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('overview of the whole Proxmox host'), enumerating concrete contents: node health, every VM and container, and every storage. It clearly distinguishes itself from narrower sibling tools like list_guests, list_storage, and node_status by presenting an aggregate one-shot overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Start here' gives explicit guidance on when to use this tool as the first call, and 'instead of a dozen' communicates its role as a replacement for multiple granular queries. It does not name specific alternative tools or explicitly state when not to use it, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a mutating operation (readOnlyHint=false). The description adds key behavioral constraints: vmid must not already exist, start controls post-creation startup, and recommends leaving unprivileged true unless host device access is needed. It stops short of disclosing failure modes or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose, followed by a compact, labeled Args list. Every parameter line adds meaningful guidance without unnecessary prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 13-parameter creation tool, the description covers all inputs, references storage_content for template discovery, and explains 'extra' for arbitrary config keys. An output schema exists, so not detailing return values is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining all 13 parameters with types, examples, and defaults. It even covers the free-form 'extra' parameter and provides an ostemplate example and lookup method.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new LXC container', using a specific verb and resource type. The term 'LXC' clearly distinguishes this from the sibling create_vm tool for virtual machines.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides practical guidance: how to find templates with storage_content, when to keep unprivileged true, and preferring SSH keys over passwords. However, it does not explicitly state when not to use this tool or name alternatives like create_vm.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries responsibility for behavioral disclosure. It adds meaningful context beyond schema: the wait parameter controls whether the tool returns a UPID (async task) versus a completed result, and checksum support is explained. It does not describe overwrite behavior or permission requirements, but the core async behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single clear purpose sentence followed by a compact Args list. Every line adds value, with examples for filename and algorithm enumerations, and no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Coverage is strong for a 7-parameter tool with an output schema: all inputs are defined, the async wait behavior is highlighted, and the output schema handles return values. No major behavioral gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description documents each of the 7 parameters with types, examples, allowed values, and defaults. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb phrase 'Download an ISO or container template straight to a storage', clearly stating the operation and target. The parameter list reinforces the exact purpose and differentiates it from sibling tools like list_storage or storage_content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is for downloading ISOs or container templates to storage, with typical storage 'local'. It doesn't explicitly name alternative tools or when-not-to-use, but the purpose is narrow enough that an agent can infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent, non-destructive operation. The description adds useful context that growth is not destructive (contrasting with shrink), but does not disclose other behavioral traits like prerequisites (e.g., guest state) or reversibility. With annotations present, the bar is lower, so 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured, with a clear purpose statement and an Args block that adds necessary detail without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return value explanation is unnecessary. The description covers purpose, scope, usage boundary, and argument semantics comprehensively. No critical information is missing for an operation of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full burden. It explains each parameter clearly: vmid, disk with examples, and increment with format requirements ('+10G', must start with '+'). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Grow a guest disk' with a specific verb and resource, and explicitly differentiates from shrink_disk by saying 'Growth only'. This is unambiguous and distinguishes from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool vs alternative: 'Growth only — shrinking is destructive and lives in shrink_disk.' This provides a clear exclusion and names the alternative tool for shrinking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds behavioral context: it explains the guest OS is asked to power off and that force_stop can hard-stop if shutdown times out. This aids understanding of the tool's effect and fallback behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: two sentences plus an Args list. Every sentence adds value, with no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a shutdown tool with an output schema, the description covers key aspects: what it does, how it behaves, and parameter semantics. It is complete enough for an agent to select and invoke correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description's Args section fully explains each parameter: vmid identifies the guest, timeout is the wait time, and force_stop triggers a hard stop. This adds meaning beyond the raw schema, which only lists types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Gracefully shut down a VM or container.' It specifies the resource type (VM/container) and the method (asking the guest OS to power off), making it distinct from siblings like stop_guest or reboot_guest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by emphasizing 'gracefully' and 'asking the guest OS,' which implies ideal use for clean shutdowns. However, it does not explicitly mention alternatives or when to prefer stop_guest, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the key behavioral consequence—'The guest OS gets no chance to flush its disks'—revealing potential data loss risk. This goes well beyond the annotations (which only include false hints) and adds critical safety information that an agent needs before invoking a forceful operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences—yet packs in the action, the consequence, and the preferred alternative. It is front-loaded with the verb 'Immediately stop' and every word earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the presence of an output schema, the description is nearly complete. It covers the operation's nature and cautionary note, but could have added when this forceful stop is appropriate (e.g., if no other option) or how it differs from suspend/reboot. Still, it is adequate for the scenario.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the parameter 'vmid' at all, giving 0% schema coverage. However, the schema itself clearly defines 'vmid' as an integer and it is the sole required parameter, making its meaning intuitive. The description adds no extra context, but the parameter is simple enough that the schema suffices.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Immediately stop a VM or container' and uses the vivid analogy 'like pulling the power cord' to convey an abrupt power-off. It also distinguishes from the sibling 'shutdown_guest' by explicitly preferring a graceful shutdown, making the tool's specific purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'prefer shutdown_guest' indicates when NOT to use this tool, and the phrase 'Immediately stop... like pulling the power cord' implies emergency or forced stop scenarios. This clearly differentiates it from graceful alternatives among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ssan9876/proxmox-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server