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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate them. It adds value by specifying the exact return data, especially the account and permission mode, and by framing the tool as a prerequisite check for write operations, which enriches the behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences: the first states the purpose, the second explains the return fields and usage. Every sentence contributes meaning, and there is no redundancy with the annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with an output schema, the description adequately covers the return fields and provides clear usage context. It explains what the tool does, what it returns, and when to call it, making it complete for its simple, introspective function.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema fully covers the parameter space with 100% coverage. There are no parameter details to elaborate, and the baseline for zero-parameter tools is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a clear verb ('Identify') and specifies the resource ('connected vSphere endpoint'), then enumerates the exact return fields (product name, version, API version, account, permission mode). This clearly differentiates it from sibling tools that manage or list vSphere objects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Call this first' to determine whether write operations are allowed, which is a strong usage directive. It doesn't name alternative tools, but given this tool's unique role as an endpoint/interrogation tool, the guidance is sufficient.

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

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

The description adds transparency beyond the annotations by highlighting that power_off and reset can lose unwritten data, explaining the return behavior of guest actions, and stating the required permission mode. This aligns with destructiveHint=true and readOnlyHint=false without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, well-organized, and front-loaded with the core purpose. Each sentence earns its place: a lead sentence, safety/usage guidance, a permission note, and a clear Args block. No redundant or irrelevant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple power actions, risk of data loss, various vm identifiers), the description fully covers usage scenarios, caveats, permissions, and parameter meanings. The presence of an output schema handles return values, so no additional output documentation is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no parameter descriptions (0% coverage), but the description's Args section provides detailed semantics for each parameter, including accepted vm formats (name, managed object id, UUID, inventory path), the full action enum, and the purpose of wait and timeout_seconds.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it changes the power state of a virtual machine with a specific verb and resource. It lists the exact actions (power_on, power_off, suspend, reset, shutdown_guest, reboot_guest, standby_guest), which distinguishes it from sibling tools that handle listing, snapshots, or deletion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided on when to use guest actions vs hard power operations, with a clear recommendation to prefer shutdown_guest/reboot_guest when VMware Tools is running. It also explains that wait does not apply to guest actions, giving actionable usage context.

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

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

Discloses important behavioral traits: cloning copies every disk (hence slow), defaults to source placement, async behavior with wait parameter, and requires write permission. This goes well beyond the minimal annotations (all false) and gives the agent critical execution expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then key behavioral notes, then a well-organized parameter list. The length is justified by the tool's complexity; each sentence adds value. Could be slightly tightened, but structure is clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters, sparse annotations, and an output schema (present but not shown), the description covers all essential aspects: operation type, placement defaults, performance implications, async patterns, permission requirements, per-parameter meaning, and references the companion task-polling tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The Args block provides meaningful descriptions for all 10 parameters, including the accepted forms for 'vm' (name, moid, UUID, or inventory path) and the purpose of each placement override. Since the input schema has no descriptions (0% coverage), this fully compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair: 'Clone a virtual machine or deploy one from a template.' This clearly defines the action and distinguishes it from sibling tools like vsphere_migrate_vm, vsphere_reconfigure_vm, and vsphere_delete_vm.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage context: explains placement defaults and how to override them, warns about long clone times, and gives explicit guidance on using wait=false to get a task ID and poll with vsphere_get_task. However, it does not explicitly mention when to prefer cloning over alternatives like vsphere_migrate_vm, though this is inferable.

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

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

The annotations only indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description goes far beyond this by warning that snapshots are not backups, that they grow and degrade performance, and by explaining the effects of include_memory and quiesce. It also provides permission requirements and task-related behavior via the 'wait' parameter. This adds substantial behavioral context not available in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured effectively: a one-sentence purpose, a crucial caveat, a permission note, and a clear list of parameters. Every sentence delivers valuable information without redundancy. The length is justified given the seven parameters and the need to explain caveats.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of seven parameters, no enums, and an existing output schema, the description covers all necessary aspects for an agent to correctly select and invoke the tool. It includes lifecycle warnings, permission requirements, and parameter semantics. The output schema handles return values, so the description need not repeat that information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, leaving all meaning to be supplied by the description. The Args section does this thoroughly: it explains the accepted formats for 'vm', the purpose of 'name', the optionality of 'description', the implications of 'include_memory' and 'quiesce', and the behavior of 'wait' and 'timeout_seconds'. This fully compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with a clear, specific statement: 'Take a snapshot of a virtual machine.' This uses a specific action verb and resource, and it is clearly distinguishable from sibling tools such as vsphere_list_snapshots, vsphere_revert_to_snapshot, and vsphere_delete_snapshot, which handle different operations on snapshots.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides important usage context: snapshots are not backups, they grow with writes, degrade performance if left in place, and should be deleted after use. It also states the required permission level ('write or higher'). However, it does not explicitly mention alternative tools or when-not-to-use cases, so it stops 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.

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

Beyond the destructiveHint annotation, the description explains data consolidation, the VM keeps current data, permission mode, waiting behavior, and that large snapshots can take long to consolidate. These details add significant context for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a front-loaded purpose, a brief behavioral note, and an organized Args list. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, behavior, permissions, parameter semantics, wait/timeout concerns, and operational caveats. Given the output schema exists, return values need not be described, making this complete for a destructive snapshot-deletion tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions are absent (coverage 0%), but the description provides a full Args block explaining every parameter, including edge cases like snapshot being ignored when delete_all is set. This fully compensates for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Delete one snapshot, a snapshot subtree, or every snapshot of a VM,' clearly specifying the verb, resource, and scope. This distinguishes it from sibling snapshot operations like create, revert, and list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states the permission requirement (destructive mode) and the operational scope (one, subtree, or all snapshots), which implies when to use the tool. It does not explicitly name alternatives, but the delete purpose is unambiguous and distinct from siblings.

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

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

Goes beyond the destructiveHint annotation by explaining the permanence ('This cannot be undone'), the powered-off requirement, and the confirm guard. Adds meaningful behavioral context that annotations alone do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a one-sentence summary, then important warnings, then a clear Args list. Every sentence earns its place; no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, multi-parameter tool, the description covers preconditions, permission requirements, confirmation guard, wait behavior, and timeout override. Combined with the existing output schema, this is complete enough 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.

Does 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 each parameter: vm accepts multiple identifiers, confirm must be true, wait controls task completion, and timeout_seconds overrides the default. This adds substantial meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb and resource: 'Permanently delete a virtual machine and all of its files from disk.' This distinguishes it from sibling tools like delete_snapshot or power off operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage prerequisites: 'The VM must be powered off' and 'Requires permission mode destructive and an explicit confirm=true.' However, it does not explicitly mention alternative tools or when NOT to use this tool, so it gets a 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavioral context by specifying accepted host identifier formats and the inclusion of attached VMs and datastores in the result, which goes beyond annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short, front-loaded sentences for purpose plus a compact Args clarification. No filler or redundancy—every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only tool with an output schema present, the description covers the core use case, identifier flexibility, and result scope. It does not discuss failure cases or performance, but given the annotations and output schema, this is acceptable. It slightly lacks explicit differentiation from vsphere_get_vm_summary_by_host, but the purpose is clear enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides no description for the 'host' parameter (0% coverage), but the description's Args section fully compensates by explaining accepted formats: host name, managed object ID, hardware UUID, or inventory path. This adds meaning well beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (get) and resource (one ESXi host), and specifies the output scope ('Full detail... including attached VMs and datastores'). This clearly distinguishes it from sibling tools like vsphere_list_hosts and vsphere_get_vm.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving detailed single-host data, contrasting with listing tools, but it does not explicitly name alternatives or state when not to use it. The context is clear but exclusion guidance is absent.

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

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

The description enriches the annotations (readOnlyHint, idempotentHint, destructiveHint) by explaining that counters come back 'summarised (latest, average, minimum, maximum),' that 'realtime' uses 20-second samples, and that counters use a 'group.name.rollup' format. It also notes the default behavior for counters. This adds substantive behavioral context without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured. It leads with a one-sentence purpose, adds a brief note on interval semantics, and then lists parameters in a clear Args block. Every sentence provides necessary information—no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, multiple intervals, counter formats), the description is complete. It covers parameter semantics, return summarization, interval behavior, and default counter set. An output schema exists, so not detailing the exact return shape is acceptable. No gaps are evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no descriptions for its properties (0% coverage), but the description compensates thoroughly. It explains 'entity' accepts a name, managed object id, UUID, or inventory path; 'entity_type' is 'vm' or 'host'; 'interval' enumerates the valid values; 'samples' retrieves most recent first; and 'counters' uses 'group.name.rollup' form with a default standard set. This fully compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Read CPU, memory, disk and network performance counters for a VM or host,' which clearly specifies the action (read), the resource type (performance counters), and the targets (VM or host). This distinguishes it from sibling tools like vsphere_get_vm or vsphere_list_tasks, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool by explaining the available intervals (e.g., 'realtime gives 20-second samples for roughly the last hour; the rollup intervals cover longer periods') and how counters work. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls just 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.

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context about asynchronous workflows and polling semantics, which goes beyond the annotations. It explains the task_id source and that the tool checks progress.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loaded with the main purpose, then the usage scenario, then the parameter. Every sentence adds value; no redundant or irrelevant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and an output schema, so the description covers the essential purpose, usage, and parameter. It could mention what the response includes (e.g., progress percentage) but this is likely covered by the output schema, so the description is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by documenting the sole parameter task_id with its managed object id format and an example. This is complete and unambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Check') and resource ('state and progress of a single vSphere task'), clearly distinguishing from sibling list tools that enumerate tasks. It also explains the polling use case, adding functional clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly specifies when to use this tool (with task_id returned from wait=false or timed-out operations) and implies it for polling a single task. It does not name alternative tools explicitly, but the context is clear enough that an agent would not confuse it with list_tasks.

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

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

Annotations already declare read-only, idempotent, and non-destructive, so the description adds value by specifying what details are included (hardware, guest info, resources, snapshots). It also notes that guest filesystem usage depends on VMware Tools, providing a behavioral caveat beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is succinct and front-loaded, with two concise sentences plus an Args block. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, the scope of returned details, and the parameter formats. With an output schema present and annotations covering safety, the description is complete for a read-only single-VM retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only defines 'vm' as a string with no description. The description compensates by enumerating accepted formats: VM name, managed object ID, BIOS/instance UUID, or inventory path, giving clear guidance for the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: retrieving full detail for one virtual machine. This distinguishes it from sibling tools that list VMs, get summaries, or perform changes. The verb 'get' and the resource 'VM' are explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a complete, detailed view of a VM is needed, but does not explicitly mention alternatives or exclusion scenarios. It would benefit from a note like 'use vsphere_get_vm_summary_by_host for summaries'.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds value by detailing what the summary includes (VM counts, powered-on count, vCPU, memory), giving more behavioral context than just the annotations. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the action 'Aggregate', and every sentence adds meaningful detail. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, a read-only annotation set, and an output schema present, the description fully covers the tool's purpose and use case. It is complete for a straightforward read-only aggregation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the baseline is 4. The description doesn't need to add param details as none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool aggregates VM counts and allocated resources per ESXi host, which is a specific verb+resource. It distinguishes itself from siblings like vsphere_list_hosts (list hosts) and vsphere_list_vms (list VMs) by focusing on per-host summary data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: 'A quick capacity/placement overview' indicates when to use this tool. It doesn't explicitly list alternatives or exclusions, but the use case is well implied, making it a 4.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context by clarifying that it returns only currently triggered alarms (not historical) and covers the entire inventory, with optional filtering. This goes beyond the structured annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose in the first sentence, followed by a use-case note and a concise Args list. Every sentence carries value, and the structure makes it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a straightforward listing operation with an output schema available. The description covers purpose, usage context, and semantics for all four optional parameters, so the agent has everything needed to select and invoke it correctly. No important context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the schema descriptions provide 0% coverage, the description fully documents each parameter: status with red/yellow severity values, include_acknowledged, limit, and offset. This adds meaningful detail—especially the severity values—that the schema alone does not provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with 'List every currently triggered alarm across the inventory,' which clearly specifies the verb (list), resource (alarms), and scope (currently triggered across the inventory). This distinguishes it from sibling tools like vsphere_list_events and vsphere_list_tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'This is the fastest way to answer "what is unhealthy right now"' provides strong contextual guidance for when to use this tool. However, it doesn't explicitly name alternative tools for other scenarios, like vsphere_list_events for historical event analysis, so it stops short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond this: it explains that the result includes capacity, DRS, and HA configuration, and details filtering behavior (case-insensitive substring, glob matching, datacenter filter, paging). 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a one-sentence summary followed by a clear Args list. Every sentence is informative, with no fluff or repetition of schema information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (read-only list with filters) and the availability of an output schema, the description adequately covers purpose, parameters, and result content. It does not mention edge cases like default limits or sorting, but these are likely covered by the output schema or are not critical for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully compensates. Each parameter is given meaningful semantics: name with substring/glob matching, datacenter filtering, limit for max results, and offset for paging. This adds substantial value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'List compute clusters with their capacity, DRS and HA configuration' uses a specific verb and resource, clearly distinguishes from sibling tools like vsphere_list_hosts and vsphere_list_vms, and specifies the scope (compute clusters).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes it obvious this tool is for listing cluster information, with no exclusions or alternatives mentioned. It lacks explicit 'when not to use' guidance, but the context is clear enough for an agent to choose it appropriately among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds a small behavioral detail—the operation lists 'every' datacenter, implying no filtering or pagination—but does not add context about authorization, rate limits, or output volume. It contributes modestly beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that states the action and scope without any redundancy. Every word earns its place, and it is front-loaded with the key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters), the presence of full annotations, and an output schema, the description is entirely sufficient. It clearly states the purpose and scope, and no additional context is necessary for correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameter details, and the schema is already fully covered (vacuously). No additional semantics are required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('every datacenter in the vSphere inventory'), clearly distinguishing it from sibling tools like vsphere_list_clusters or vsphere_list_hosts. It is concise and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or explicitly name sibling tools with different scopes. Usage is left entirely to the reader's inference from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context by explaining the over-provisioning semantics ('provisioned_gib includes space promised to thin disks that has not been written yet, so it can exceed capacity_gib') and what 'overprovisioned' flags. This goes beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: a crisp lead sentence defining the primary purpose, a one-sentence explanation of a nuanced output concept, and a tightly organized Args list. Every line adds information without redundancy or padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with both input schema and output schema present, the description covers the tool's output semantics (capacity, free space, provisioned_gib, overprovisioned) and all parameters, including their purpose and allowed patterns. It provides sufficient context for an agent to decide when and how to invoke it, especially given the strong annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description carries full parameter documentation. The 'Args:' section adds meaningful detail for each parameter: name supports 'substring, or glob with * / ?', datastore_type gives example values like 'VMFS', 'NFS' or 'vsan', and min_used_percent explicitly states its use case. This fully compensates for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific verb+resource statement: 'List datastores with capacity, free space and over-provisioning.' This unambiguously identifies the tool's purpose and distinguishes it from sibling list tools by the resource type and the specific metrics covered.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides strong contextual guidance, such as 'min_used_percent: Only datastores at or above this utilisation, for spotting the ones about to fill up,' explaining why you'd use this filter. However, it does not explicitly compare against alternatives like vsphere_search_inventory or other list tools, so it stops short of giving explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds behavioral context beyond annotations: it specifies the sort order (newest first) and elaborates on the scope of events (audit trail, examples of event types). It does not disclose return format details, but given the output schema exists and the tool is a simple read-only list, this level 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a one-sentence purpose, a brief context paragraph, and a concise parameter list. Every sentence adds value, with no redundancy. The first sentence front-loads the core action, and the parameter explanations are terse yet complete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a simple read-only query with no required parameters. The description covers the purpose, typical use cases, and all parameter semantics. The presence of an output schema means return values need not be explained. Sibling context further disambiguates. No critical gaps are apparent for effective selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explicitly explains every parameter in a numbered Args list: entity (restrict to object and children), entity_type (kind of object), hours (lookback), categories (filter by info/warning/error/user), and limit (max events). This fully compensates for the schema's 0% description coverage. The enum values for entity_type and categories are also enumerated, adding meaning beyond the schema's bare property types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'List recent vSphere events, newest first,' which clearly identifies a specific verb+resource (list events) and adds ordering (newest first). It also distinguishes the tool from siblings like vsphere_list_tasks (tasks vs events) and vsphere_list_alarms (alarms vs events) by providing concrete examples of event types (logins, configuration changes, HA actions, alarm transitions, hardware problems).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool by stating it represents the environment's audit trail and enumerating event categories. It does not explicitly name alternatives or exclusion criteria (e.g., when to use vsphere_list_tasks instead), but the context signals (sibling names and the audit-trail framing) make the primary use case obvious. No explicit 'when not to use' guidance is given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, establishing a safe read operation. The description adds context that it returns hardware, version, and live CPU/memory utilisation, and that pagination is available via limit/offset. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a concise summary followed by a compact parameter list, front-loaded with the action. No wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has six optional parameters all described, and an output schema is present, so return values are already defined. The description covers the essential behavior and parameter semantics, making it complete for a list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description fully explains each parameter: name supports substring/glob, connection_state has enumerated values, limit/offset define pagination, and cluster/datacenter are filters. This provides crucial semantics absent from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('ESXi hosts'), and specifies the included data (hardware, version, live CPU/memory utilisation), clearly distinguishing it from sibling tools like vsphere_get_host which retrieves a single host.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates it's for listing and filtering hosts with several optional filters, so the use case is clear. However, it does not explicitly differentiate from alternatives (e.g., vsphere_get_host for a single host) or state when not to use it.

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

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

Annotations declare the tool read-only, idempotent, and non-destructive. The description adds behavioral insights beyond these: distributed port groups additionally report VLAN configuration and the distributed switch, and the name filter supports substring/glob matching. This enriches what the agent knows about the tool's behavior without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a single-purpose opening sentence, one sentence adding behavioral nuance, and an Args list that adds no fluff. It is front-loaded with 'List networks' and every line contributes value, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there are 5 parameters and the tool is a list operation with an output schema, the description covers the scope (three network types), all parameter semantics, pagination via limit/offset, and extra output behavior for distributed port groups. No critical information is missing 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides zero description coverage (0%), so the description must carry the full explanatory burden. It does so comprehensively: each parameter (name, datacenter, kind, limit, offset) is explained with its purpose and, for kind, the allowed values. 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'List networks' and then specifies the exact resource types: standard port groups, distributed port groups, and opaque networks. This clearly distinguishes it from sibling list tools like vsphere_list_hosts or vsphere_list_vms.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or conditions. It implies usage by describing the network types, but lacks the explicit 'use this when' or 'instead of' guidance seen in higher-scoring examples.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds behavioral context by specifying the returned data (reservations, limits, current usage) and the paging behavior via limit/offset, which goes beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: one clear sentence stating the purpose, followed by a compact list of parameters. Every line earns its place with no redundancy, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with three optional parameters and an output schema, the description covers the core behavior, filtering, and paging. It does not need to elaborate on return values since an output schema exists, and the low complexity means no further context is necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The JSON schema provides only types and defaults with no property descriptions, so the description's Args section adds essential meaning for all three parameters (name, limit, offset). This fully compensates for the 0% schema coverage, clearly explaining each parameter's role.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'List resource pools with their reservations, limits and current usage,' which clearly identifies the verb (list), the resource (resource pools), and the specific fields returned. This distinguishes it from sibling tools like vsphere_list_vms or vsphere_list_hosts, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. However, the context of sibling tools and the straightforward list nature imply its usage, which is acceptable for a simple read-only operation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the temporal scope (running/recent) but does not disclose other behavioral aspects such as result limits, pagination, or the exact meaning of 'just finished'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant information. Every word contributes to the meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple nature of the tool, the presence of an output schema, and strong annotations, the description covers the core functionality sufficiently. However, it lacks explicit differentiation from the sibling 'vsphere_list_tasks', which would help an agent choose between them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters (schema properties are empty), so the baseline for parameter semantics is 4. The description is not required to explain parameters that don't exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb 'List' and resource 'tasks' with a clear scope: 'currently running or has just finished'. This distinguishes it from the sibling 'vsphere_list_tasks' and other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'currently running or has just finished' implies when to use this tool, but there is no explicit contrast with sibling tools like 'vsphere_list_tasks' or guidance on when not to use it. The usage context is clear but not fully explicit.

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

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

Annotations already declare safety (readOnly, idempotent, non-destructive). The description adds valuable output context, such as the tree/flat list structure and the meaning of 'is_current'. No contradictions with annotations are present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured. It leads with the primary purpose, then adds essential details about output fields, then explains the parameter. Every sentence carries value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one simple parameter, an output schema present, and robust annotations, the description covers all necessary aspects: what is returned, how to identify snapshots, and how the output relates to other operations. No significant gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has zero description coverage, but the description's Args section fully specifies the 'vm' parameter, including accepted formats (name, moid, UUID, inventory path). This compensates completely for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('List'), the resource ('snapshots of a virtual machine'), and output format ('both a tree and a flat list'). It is unambiguously distinguished from sibling snapshot operations like create/revert/delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly guides usage by noting that the returned moid is needed for revert/delete operations, which connects this tool to sibling tools. However, it doesn't explicitly mention alternatives or when-not-to-use, so it lacks the full explicitness required for a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by noting results are 'newest first' and by indicating the tool helps observe environment changes and operation outcomes. This goes beyond the annotations and adds interpretative value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a one-sentence summary, a brief usage note, and a clear Args list. Every sentence earns its place, and the formatting makes key information easily scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is a read-only list operation, annotations confirm safety, and an output schema exists (so return format doesn't need explanation), the description covers purpose, usage, and all parameters. 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description includes an 'Args:' block that explains all five parameters (entity, entity_type, hours, states, limits) with clear descriptions. Although the schema itself has no descriptions (0% coverage), the tool description fully compensates by documenting each parameter's meaning and purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'List recent vSphere tasks, newest first,' using a specific verb and resource with clear ordering. It distinguishes itself from siblings like vsphere_get_task (single task) and vsphere_list_running_tasks (filtered to running), making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool: 'Use this to see what changed in the environment and whether an operation someone else started succeeded.' This gives clear context, though it does not explicitly name alternatives or when not to use it. The guidance is strong but stops short of full exclusion criteria.

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

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

Annotations already mark it as read-only and idempotent; the description adds behavioral details like result capping, the truncated field, and glob matching semantics for name filters, which go 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with a one-line summary, and the Args list is structured and free of fluff. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 11 optional parameters and an output schema, the description covers filter semantics, pagination, and the truncated flag, making it sufficient for correct invocation. The output schema presumably covers return values, so no need to describe them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description's Args section fully documents all 11 parameters, including types, semantics, and examples (e.g., substring matching, glob support, power_state values). This adequately compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List virtual machines with power state, resources and guest details' – a specific verb and resource that distinguishes it from sibling tools like get_vm or list_hosts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains that filters are combined with AND and provides pagination instructions with the truncated field and offset, giving clear context for how to use filters and page. It does not explicitly name alternatives, but the listing vs getting distinction is evident from the description.

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

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

Annotations indicate the operation is not read-only, not idempotent, and not destructive. The description adds beyond this by stating that write permission is required, and it explains the wait and timeout behaviors. This provides meaningful context about the operation's side effects and prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized: a one-sentence purpose, a concise explanation of migration variants, a short permission note, and a structured Args list. It is thorough without being verbose, and every sentence adds value. The key info is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema, so return values are covered there. The description covers the main usage modes, required permission, and the minimum target requirement. It could mention edge cases (e.g., resource_pool-only migration) or potential prerequisites like powered-on state, but overall it is sufficient for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no descriptions (0% coverage), so the description's Args section fully compensates. Each parameter gets a clear explanation: vm accepts multiple identifier forms, host/datastore/resource_pool are destinations, priority schedules the migration, wait controls blocking, and timeout_seconds overrides the default. This goes well beyond type names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Move a virtual machine to another host, datastore or resource pool,' which clearly states the specific action and resource. It distinguishes this from sibling tools like clone_vm or delete_vm by focusing on migration, and it explains the three migration types explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete guidance: supplying host performs vMotion, datastore performs storage vMotion, and both at once is combined migration. It also states that at least one target is required, which is essential. However, it does not explicitly mention when not to use this tool or name alternatives, 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.

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

The annotations already signal mutation (readOnlyHint=false), but the description adds valuable behavior beyond that: the requirement for permission mode 'write', the power-state constraint, and the 'only supplied fields are changed' partial-update semantics. These are not inferable from the annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a concise introductory paragraph followed by a per-parameter list. Every sentence earns its place—no redundant fluff, and the format is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mutation tool with 7 parameters, the description covers the purpose, usage conditions, permissions, and all parameter semantics. Return values are handled by the output schema, so no critical context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the 'Args' block in the description fully compensates by explaining every parameter in detail—including the VM identification formats, the divisibility constraint between cores_per_socket and cpu_count, the MiB unit for memory, and the wait/timeout semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description accurately states the tool's purpose with a specific verb ('Change') and resource ('a virtual machine') and identifies the exact attributes (CPU count, memory size, notes). This distinguishes it from sibling tools like vsphere_change_vm_power_state or snapshot operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit precondition: powered off unless hot-add is enabled, and notes that only supplied fields are changed. While it does not explicitly list alternative tools, this context clearly indicates when the tool is applicable.

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

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

The description discloses major behavioral implications: later changes are discarded and everything written since the snapshot is lost. It also explains power-on suppression and waiting behavior, adding value beyond the destructiveHint annotation without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a leading purpose statement, a critical warning, a permission note, and a clean Args list. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and destructive nature, the description provides all essential context: operation, risk, prerequisites, parameter semantics, and task behavior. The presence of an output schema means return values need not be described. Complete and self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description thoroughly explains every parameter, including accepted formats for vm (name/moid/UUID/path) and snapshot (name/path/moid), defaults, and the effect of suppress_power_on, wait, and timeout_seconds. 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reverts a virtual machine to a snapshot and discards later changes, which is a specific verb+resource+effect. This distinguishes it from sibling snapshot tools like create_snapshot and delete_snapshot.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states a prerequisite (requires destructive permission mode) and explains default behavior for the snapshot parameter. It does not explicitly contrast with alternatives or say when not to use the tool, but the context is otherwise clear.

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

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

Annotations already indicate a safe read-only, idempotent operation. The description adds useful behavioral detail: substring/glob matching, default object types, and the limit meaning. This goes beyond the annotations, though it does not describe every edge case like null limit behavior, which is acceptable given the existing annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a clear purpose statement, a usage note, and an Args block. Every sentence adds value, with no fluff or repetition of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the annotations, and the existing output schema, the description provides all necessary context. It explains search behavior, parameter semantics, and when to use it. The output schema covers return values, so no further elaboration is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully compensates by explaining each parameter: query (substring/glob), types (default list), and limit (maximum total matches). This adds meaningful semantics that the bare input schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches the inventory by name across several object types at once. This distinguishes it from sibling tools that list specific object types, and the additional use case of retrieving a managed object ID further clarifies its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use the tool: when you know a name but not the object type, or when you need a managed object ID. It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough that an agent can infer when a type-specific list/get tool would be more appropriate.

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