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

Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description adds meaningful state behavior beyond that: alarm remains active, acknowledged=true persists until condition clears, and an unknown pair returns a not-found error. It also explicitly labels the action as [WRITE], reinforcing the mutation 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?

Each sentence earns its place: purpose, non-effect, persistence behavior, alternative tool, prerequisite/error, and return format. The [WRITE] marker front-loads the key action, and the structure is scannable without fluff.

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 write tool with no output schema, the description covers the action, the state change, the sibling alternative, the required data source, error behavior, and the return fields. An agent has enough to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by instructing the agent to source entity_name and alarm_name from list_vcenter_alarms output and warning that an unknown pair causes a not-found error, which is practical guidance beyond the schema field 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?

Description states a specific verb ('acknowledge') and resource ('vCenter alarm'), and immediately distinguishes the action by saying it marks as seen WITHOUT clearing. It explicitly names reset_vcenter_alarm as the different alternative, so an agent can tell this tool apart from siblings without opening schemas.

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 explicit when-to-use ('marks it as seen'), when-not-to-use (does not clear it), when to choose the sibling instead (remove entirely after fixing cause, use reset_vcenter_alarm), and a concrete prerequisite (get exact entity_name and alarm_name from list_vcenter_alarms first). Nothing is left to inference.

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

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

Beyond the annotations, the description discloses the preview/confirm gate, exactly what confirm=False does (validates and returns spec without writing), what confirm=True does (creates and returns device name), and the error return format. It also notes the operation is audited. This is rich 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 the write marker and core purpose, followed by concise usage context, parameter behavior, and a returns section. There is no filler; every sentence adds operational insight. The structure makes it easy for an agent to parse the key facts 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 write tool with no output schema, the description fully covers what an agent needs: the operation, the safety gate, validation behavior, return shapes including errors, and pointers to verification and removal. It also names relevant sibling tools. The context is complete enough to call this tool correctly without additional lookup.

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 100% schema coverage, baseline is 3. The description adds value by explaining the confirm parameter's two-phase behavior, clarifying that the DVS port allocation is handled internally so only the portgroup name is needed, and stating that no gateway or services are part of the intended shape. This meaningfully supplements the schema definitions.

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 and resource: 'Add a static-IP VMkernel adapter on a DVS portgroup'. It also highlights the unique preview/confirm gating and minimal shape, which clearly differentiates it from sibling tools like list_host_vmks, remove_host_vmk, and set_vmk_service. An agent can tell exactly what this tool does and how it differs without inspecting the schema.

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

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

The description gives clear when-to-use context: 'Deliberately minimal shape for throwaway test vmks on L2-only segments' and states the constraints (static IPv4, no gateway, no services). It also directs verification and removal to list_host_vmks and remove_host_vmk. It lacks an explicit when-not-to-use alternative for more complex adapter configurations, but the minimal-shape framing implies the limitation.

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

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

Beyond the annotations, the description discloses key behavioral traits: it replaces any mounted ISO, reconfigures the existing CD-ROM or adds one on the IDE controller, works whether the VM is powered on or off, and returns a status string or specific errors. This adds substantial value beyond readOnlyHint/idempotentHint/destructiveHint.

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 tight and well-structured: a one-line action statement followed by concise behavioral details, failure modes, and return value. Every sentence adds necessary information without fluff, and the main purpose 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?

For a tool with a complete input schema, an output schema, and relevant annotations, the description covers purpose, usage steps, edge cases (no IDE controller), power state, and return behavior. Nothing an agent needs to correctly invoke it 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?

Schema coverage is 100%, so the parameters (vm_name, iso_ds_path, target) are already fully documented in the schema. The description adds a useful hint about finding ISO paths with browse_datastore, but does not provide additional semantic detail for the parameters themselves. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Mount a datastore ISO into a VM's virtual CD-ROM drive.' It clearly defines the operation and distinguishes it from siblings like browse_datastore (finding ISOs) and vm_reconfigure (general VM reconfiguration). The [WRITE] prefix also signals mutation, aligning with the write intent.

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

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

The description gives explicit context: it tells agents to find ISO paths first with browse_datastore using pattern '*.iso', and explains when the operation fails (no IDE controller). It does not spell out 'when not to use' alternatives, but the prerequisite and failure condition provide clear usage 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?

The [WRITE] prefix, sequential execution warning, full-copy pipeline description, and return-value note ('one dict per VM') all add behavior beyond the annotations. Since readOnlyHint is false and idempotentHint is false, these details are genuinely useful and consistent.

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: purpose, workflow, return shape, performance caveat, and alternative are all covered in four concise sentences. No filler or redundant restatement.

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 batch operation with a full input schema canvassing all 7 parametersable, the description covers the key operational expectations: sequential execution, optional post-clone steps, return format, and when to choose the linked-clone sibling. Nothing essential for selecting and invoking it 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?

Schema coverage is 100%, so the baseline is 3. The description adds useful semantic context by calling the source a 'gold image' and mapping the pipeline stages to the optional reconfigure/snapshot/power-on parameters, which is beyond the raw schema field 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 a specific verb-resource pair: 'Batch clone multiple VMs from a source VM'. It also clarifies the workflow (full copy, optional reconfigure, snapshot, power on) and differentiates from the linked-clone sibling by naming batch_linked_clone_vms 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 explicit when-to-use guidance: use this for full independent clones, and 'prefer batch_linked_clone_vms for disposable test copies'. It also sets expectations for long vm_names lists by noting clones run sequentially.

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 non-obvious execution behavior: VMs deploy sequentially, one VM's failure does not stop the rest, and a per-VM status dict is returned. This goes beyond the annotations, which only indicate write/non-idempotent behavior.

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 dense but well-organized: purpose first, usage guidance second, spec semantics and failure behavior next, and Returns clearly delimited. Every sentence earns its place for a complex batch operation.

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

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

For a tool with only two parameters, the description fully covers target selection, spec file meaning, YAML channel semantics, defaults/overrides, execution order, failure isolation, and return format. Nothing essential 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.

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

Although schema coverage is 100%, the description adds essential meaning to spec_path by explaining the YAML contract: source/template/linked_clone/ova/iso keys, defaults block, and per-VM overrides. This is critical semantic content absent from the schema's one-line path description.

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?

Opens with a specific verb+resource+method: 'Deploy multiple VMs in one call from a declarative YAML spec file.' It clearly separates itself from single-VM siblings by naming deploy_vm_from_template, vm_clone, deploy_vm_from_ova, and deploy_linked_clone as alternatives.

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

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

States when to use it ('fleet provisioning (several VMs, shared defaults)') and when not to ('for a single VM prefer ...'). It also explains channel selection via spec keys, so the agent understands the tool covers multiple deployment modes from one spec.

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 only indicate readOnlyHint=false and destructiveHint=false; the description adds meaningful behavioral context: clones share the source disk via copy-on-write, the source must remain intact, and each clone returns one dict. This goes beyond what the structured annotations convey.

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

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

The description is compact, front-loaded with the core action, and each sentence earns its place: purpose, behavioral constraint, return shape, and sibling routing. No filler or redundant schema 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 tool with 8 parameters and a rich output schema, the description covers the critical non-obvious aspects: copy-on-write semantics, source immutability, return format, and the relevant alternative. It does not need to restate parameter details since the schema fully documents 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema, though it reinforces the cloning mechanism tied to source_vm_name and snapshot_name.

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 and resource: 'Batch create linked clones from a VM snapshot'. It clearly distinguishes itself from batch_clone_vms by noting the alternative is for independent copies, so an agent can tell them apart immediately.

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 explicitly states when to use this tool over the sibling: 'Prefer batch_clone_vms for independent copies.' It also communicates a hard precondition—'the source must stay intact'—which informs safe usage.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: it explains the list envelope ('items' one row per file, 'returned'/'total'/'truncated' completeness) and guarantees that 'Every match in the searched folders is returned, so truncated is always false.' This is genuinely useful behavioral disclosure beyond structured fields.

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 three short sentences, each earning its place: core action, usage guidance with alternatives, and return-envelope behavior. The '[READ]' prefix is slightly redundant with annotations but aids quick scanning and does not inflate the length. 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?

With no output schema, the description compensates by explaining the response structure and the truncation guarantee. It also provides workflow context and names the alternative tool, making the definition self-sufficient for correct selection and invocation. Minor details like recursion behavior are not essential for this directory-browsing use case.

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

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

Schema description coverage is 100%, so all four parameters (path, target, pattern, datastore_name) are already documented in the input schema. The description does not add parameter-specific meaning beyond contextual hints about common file types (OVA/ISO/VMDK), so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Browse files in a vSphere datastore directory.' It explicitly differentiates from related siblings by stating it is for finding OVA/ISO/VMDK paths before deploy_vm_from_ova or attach_iso_to_vm, and that scan_datastore_images is the alternative for estate-wide sweeps. This makes the tool's purpose unambiguous relative to its siblings.

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

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

The description gives explicit when-to-use guidance: 'Use this to find OVA/ISO/VMDK paths before calling deploy_vm_from_ova or attach_iso_to_vm; for an estate-wide image sweep use scan_datastore_images.' It names the specific alternatives and the conditions that select them, leaving no ambiguity about when to invoke this tool.

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 explicitly states 'Idempotent: a host already in the cluster returns success without change,' but the annotations declare idempotentHint=false. This is a direct contradiction, so despite adding otherwise useful behavioral context, this dimension must score the lowest.

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 '[WRITE]' and a clear one-line purpose. Each subsequent sentence adds distinct value, though it is longer than strictly necessary; the structure is logical and scannable.

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

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

Given output schema exists and parameter coverage is complete, the description covers prerequisites, idempotency, maintenance-mode expectations, a recommended pre-check, and the return status values. An agent has enough context to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds helpful context like 'takes no host credentials' and that cluster_name references a cluster created via cluster_create, but it does not substantially expand parameter meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Move an ESXi host that vCenter already manages into a cluster.' It clearly scopes the operation to already-managed hosts and distinguishes this tool from registration workflows and from cluster_remove_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?

It gives explicit when-to-use and when-not-to-use guidance: no brand-new host registration, no host credentials, use the vCenter UI for first-time registration. It also references cluster_info as a precursor and contrasts maintenance-mode requirements with cluster_remove_host.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false) establish the write/safety profile, so the description carries a lower burden but still adds real value: it discloses the return contract ('status string naming what changed'), the partial-update behavior (untouched settings remain), and the conditional dependency of drs_behavior on DRS being enabled. 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?

Three sentences with zero filler. Purpose is front-loaded in sentence one, the return contract and delta semantics follow, and the conditional caveat closes. Every sentence earns its place, and the [WRITE] tag is a compact one-token signal. No redundancy with schema 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?

For a 5-parameter mutation tool with 100% schema coverage and an output schema, the description covers the essential decision-making surface: what it changes, how partial updates work, what it returns, and how to verify the result. Notable omissions are prerequisites (e.g., cluster must exist) and any caveat about side effects of disabling HA/DRS on running workloads, but these are minor given the rich schema and output schema.

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

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

Schema coverage is 100%, so the baseline is 3 given every parameter (ha, drs, name, target, drs_behavior) already has a schema description. The description adds genuine meaning beyond the schema by stating the delta semantics ('None leaves a setting untouched', reinforcing the nullable defaults) and the conditional rule that drs_behavior only applies when DRS is enabled — information absent from the input 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?

States a specific verb ('Reconfigure') and a concrete resource ('cluster HA/DRS settings'), which clearly separates this mutation tool from cluster_create, cluster_delete, and cluster_info. The [WRITE] tag reinforces the mutation intent. It doesn't explicitly name a sibling it is not, but the verb+resource combo leaves little ambiguity.

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

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

Provides clear usage semantics: 'Pass only the fields to change; None leaves a setting untouched' defines the delta update pattern, and 'verify with cluster_info' routes the agent to the correct read-side sibling. The precondition 'drs_behavior applies only when DRS is enabled' is a genuine guardrail. It doesn't explicitly state when to use cluster_create instead, but 'reconfigure' makes that boundary implied.

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

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

Annotations already indicate this is a write operation and not idempotent, so the description adds value by disclosing failure behavior: it fails with a clear error and no partial state if the name exists or drs_behavior is invalid. It also discloses the return value as a status string naming enabled features, going beyond the structured fields.

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

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

The description is compact, front-loaded with the core purpose, and every sentence contributes: purpose, failure/atomicity behavior, related workflow, and return value. There is no filler or repetition of schema details.

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

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

For a tool with six parameters and a full schema, the description supplies the critical non-schema context: failure conditions, no partial state, follow-up sibling operations, and the shape of the returned status. Combined with the rich schema and output schema, an agent has everything it needs to invoke this correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter and its defaults. The description adds a bit of semantic context by warning that invalid drs_behavior causes failure and that HA/DRS are optional, but it does not significantly expand on the parameter meanings already provided.

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

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

The description uses a specific verb and resource: 'Create a new empty cluster in a datacenter, optionally enabling HA and DRS.' It clearly distinguishes itself from sibling tools by stating the cluster is empty and by explicitly connecting to cluster_add_host, cluster_configure, and cluster_info for subsequent actions.

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

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

The description gives explicit usage context: use this to create an empty cluster, then add hosts with cluster_add_host, modify HA/DRS with cluster_configure, and verify with cluster_info. It names the alternatives and indicates the sequencing, which leaves little to inference.

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

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

Annotations already mark destructiveHint=true, but the description meaningfully extends this by explaining the preview/apply dual mode, the blast_radius return value, and the refusal cases. It also warns against self-confirming without user consent, which is behavioral context far 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 front-loaded with the core purpose, then organizes safety behavior, refusal conditions, and return type in clear sections. Every sentence carries operational meaning; there is no filler or repetition of schema 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 destructive nature, the description fully equips an agent: prerequisites (cluster_info), associated sibling action (cluster_remove_host), preview behavior, return shape, and explicit refusal conditions. No output schema exists, so the stated return dict (action, blast_radius) is essential and present.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description reinforces confirm's preview-vs-apply semantics and the returned dict, but it does not substantially add new parameter-level meaning beyond what the schema provides; it instead adds usage and safety context.

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 precise verb and resource: 'Delete an empty cluster', and immediately scopes it with '(no hosts must remain)'. It differentiates itself from related operations by naming cluster_remove_host as the evacuation step, so an agent can distinguish deletion from member removal.

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

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

The description gives explicit when-to-use guidance: only empty clusters, check cluster_info first, use cluster_remove_host for evacuation, and never set confirm=True before showing the preview to the user. It also states refusal conditions, making the decision boundary 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 cover read-only and idempotent behavior, and the description adds value beyond them: it delegates to vmware-monitor, returns a snapshot without trending, ranks top_issues worst-first, and reveals the response shape. No contradiction with annotations.

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

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

The description is front-loaded with the core question ('is anything on fire?'), then organizes behavior, usage, and return format in tight paragraphs. Every sentence adds information, and the return-field ordering guidance earns its place.

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

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

With no output schema present, the description compensates by documenting the return object and which fields to lead with. It also names sibling drill-down tools, explains status semantics, and clarifies the point-in-time nature — leaving no critical gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters well. The description adds useful context about top_issues and return ordering but doesn't materially enrich parameter meaning beyond the schema.

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

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

Description names a specific verb and resource ('health rollup for every cluster') and defines the artifact precisely: statuses per cluster plus a ranked top_issues list. It also distinguishes itself from deeper investigation tools by explicitly positioning this as the fast cross-cluster triage view.

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?

Explicitly instructs the agent to 'Use it FIRST for a cross-cluster glance, then drill in with vm_investigation_bundle or host_investigation_bundle.' It also sets expectations with 'Point-in-time — no trending,' so the agent knows not to use it for temporal analysis.

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?

With annotations already declaring readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description's 'Read-only, no side effects' is largely redundant. It earns credit by adding the error-return contract ('Errors return a dict with error + hint') and by enumerating the full return schema, which annotations cannot convey. 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?

Well-structured and front-loaded: [READ] tag, one-sentence purpose, usage guidance, then a compact return-format block. Every sentence earns its place; the only mild redundancy ('Read-only, no side effects' vs annotations) is brief and reinforces safety.

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

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

Even with no output schema, an agent has everything needed: the exact return dict (all fields listed down to per-host maintenance_mode and CPU/MHz memory/GB units), the error format, usage timing, and a read-only safety profile from annotations. For a 2-parameter read tool, nothing critical 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?

Schema description coverage is 100% — 'name' is documented as 'Exact cluster name' and 'target' as the config.yaml vCenter target with default behavior. The description adds no per-parameter meaning beyond the schema, so the baseline 3 applies; the description's return-field list is useful but concerns outputs, not parameter 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?

States a specific verb and resource ('Get detailed cluster information') plus the exact contents (member hosts, HA/DRS config, resource capacity). The [READ] prefix and the named write-siblings (cluster_add_host, cluster_remove_host, cluster_configure) make the read-vs-mutate distinction unambiguous among the many cluster_* 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?

Gives explicit when-to-use context: 'Use before cluster_add_host / cluster_remove_host' and 'to verify cluster_configure changes.' This is clear and actionable, but it names no when-not-to-use case or stated alternative (e.g., cluster_health_summary for health-focused checks), so it stops short of the full 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 description discloses preview-vs-apply behavior, refusal conditions, maintenance-mode requirement, powered-on VM blocking, and the fact that the host remains in vCenter inventory. This adds material context beyond the destructiveHint annotation.

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

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

Every sentence earns its place, covering the preview flow, user-consent constraint, refusal cases, inventory behavior, and sibling reference. It is front-loaded with the [WRITE] tag and the safety-critical preview warning.

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, human-in-the-loop tool with no output schema, this description is complete: it identifies the returned dict, the blast_radius fields, the failure modes, and the prerequisite cluster_info call. An agent can invoke it safely and interpret the result.

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 already covers all parameters, but the description enriches them significantly: confirm=false means preview/return blast radius, confirm=true applies, and host_name should be the exact name from cluster_info output.

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 opening states a specific verb ('Remove'), resource ('host from a cluster'), and a hard precondition ('must be in maintenance mode'). It also distinguishes itself from cluster_delete by clarifying that the host is not deleted, and from cluster_add_host as a way to move it back.

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 explicitly instructs the agent to run cluster_info first for exact host names, to preview with confirm=False, to show the blast radius to the user, and not to set confirm=True on its own. It names cluster_add_host as the alternative for reversing the 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?

Beyond the annotations, the description discloses important behavioral effects: the VM becomes a template, cannot be powered on, and serves only as a clone source. It also states the return value is a status string. Since the annotations only indicate readOnly=false and destructive=false, the description adds meaningful state-change context 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 three short sentences with no filler. It front-loads the operation verb and resource, then adds the most important consequence and downstream usage. 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 state-changing tool with two parameters and an output schema, the description covers the prerequisite, the effect, and the follow-up tool. It does not mention failure modes or whether the conversion is reversible, but these are secondary given the schema and output schema already provide structural coverage.

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

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

Schema description coverage is 100%, so the input schema already documents vm_name and target fully. The description reinforces that the VM must be powered off but adds no new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the load.

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

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

The description uses a specific verb and resource: "Convert a powered-off VM to a vSphere template." It clearly differentiates from siblings by explaining the resulting role as a clone source for deploy_vm_from_template, leaving no ambiguity about what this tool accomplishes.

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 a clear use case: "freeze a golden image" and explains the consequence that the VM cannot be powered on afterward. It does not explicitly name alternatives or when-not-to-use conditions, but the downstream workflow with deploy_vm_from_template provides enough context for an agent to select it appropriately.

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 significantly augments the annotations by disclosing the preview/confirm gating, the exact behavior of confirm=false vs true, the return dict shapes, error shape, auditability, and membership requirements. Annotations only say readOnlyHint=false, so this added context is genuinely valuable and non-contradictory.

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

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

The description is front-loaded with the core action and gating flag, then gives rule semantics, constraints, exclusions, verification path, and return format in compact bullets. Every sentence earns its place and there is no redundant filler.

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

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

With no output schema, the description properly explains the return shapes for preview, created, and error cases. Combined with 100% schema parameter coverage, the tool is fully transparent about what happens at each confirm state, what constraints apply, and how to verify the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning for rule_type by explaining the behavioral difference between affinity and antiAffinity, and it reinforces the VM count/cluster membership precondition, going slightly beyond the schema's field-level 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 verb and resource: "Create a VM-VM DRS rule (affinity or anti-affinity)". It distinguishes this tool from sibling DRS tools by explicitly stating VM-Host rules are not created here and pointing to list_drs_rules for verification.

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

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

The description gives explicit usage context: it is a preview/confirm gated creation flow, requires >=2 distinct cluster VMs, and excludes VM-Host rules. It references list_drs_rules for verification, though it does not enumerate every sibling alternative (e.g., set_drs_rule_enabled vs create), so it stops short of a full when-not map.

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 important behaviors not in the annotations: preview/confirm gating, that confirm=False writes nothing, that confirm=True waits for the task, that the operation is audited, and the exact return dict shapes for success and error cases. Annotations only indicate readOnly=false and destructive=false, so the description carries the full behavioral burden and does so thoroughly.

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 somewhat long but well-structured: a one-line purpose header, a gating/validation paragraph, an ephemeral binding paragraph, and a returns section. Every section carries essential information, and the purpose is front-loaded. Minor redundancy with parameter schema descriptions keeps it from being perfectly concise.

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

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

With no output schema and a complex 7-parameter tool with open-world hints, the description covers what an agent needs: preview/confirm semantics, return value structure (including error dicts), validation behavior, and edge-case binding behavior. It leaves no critical gap for selecting or invoking the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining ephemeral binding implications (attachable when vCenter is down, num_ports ignored) and clarifying the output of confirm=False versus confirm=True. It does not deeply explain target or dvs_name, but the schema already covers them adequately, so this is solidly above baseline.

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

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

The description states a specific verb and resource: 'Create a VLAN-tagged portgroup on a dvSwitch.' It also immediately signals the preview/confirm gating, which clearly distinguishes this from read-only or other network tools. The scope (VLAN-tagged, dvSwitch) makes it unambiguous among siblings like list_dvs_portgroups or VM 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?

It gives explicit workflow guidance: confirm=False to validate and preview, confirm=True to actually create, and verify afterwards with list_dvs_portgroups. It also names a concrete scenario for ephemeral binding (self-hosted VCSA management portgroup) and explains when num_ports is ignored. This is strong when-to-use and alternative-routing 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses important runtime behavior: it degrades gracefully when a target is unreachable, lists unreachable targets separately, aggregates remaining results, and is point-in-time. It also names the underlying library and confirms read-only behavior, giving an agent confidence in side-effect safety.

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 dense but well-structured, front-loading the core value proposition and then providing behavior, fallback semantics, and follow-up guidance. Every sentence contributes useful information; there is no filler or repetition of schema 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?

Even without an output schema, the description sufficiently describes the return shape: a globally ranked top_issues list tagged by vcenter, a per-target rollup, and an unreachable list. It also covers failure behavior, read-only safety, point-in-time semantics, and a suggested drill-in path, making it complete for a 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?

Schema description coverage is 100%, and both parameters (top_n and cluster_filter) are already clearly documented in the schema. The tool description adds context about ranking and aggregation but does not need to repeat parameter details. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description clearly states a specific purpose: aggregate attention-worthy issues across every configured vCenter into one ranked list. It explicitly names the underlying operation (runs cluster_health_summary against every target) and distinguishes itself from single-target tools by emphasizing the cross-vCenter scope.

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

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

The description gives clear context for when to use this tool: as the first estate-wide triage step, and it explicitly suggests following up with vm_investigation_bundle for deeper drill-in. It does not explicitly state when not to use it or compare it directly to cluster_health_summary as an alternative, but the 'across EVERY configured vCenter' scope makes the usage context unambiguous.

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, and the description reinforces this with '[READ]' and 'read-only'. The description adds valuable behavioral guidance beyond annotations: it delegates to the vmware-monitor library, should not be dumped raw, and is point-in-time. 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.

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

The description is tightly structured: a short headline, a clear bullet-like list of correlated data, a behavioral note, and a usage trigger. Every sentence earns its place, and the key purpose 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?

Because there is no output schema, the description compensates by enumerating what the bundle contains: capacity, free space, accessibility, hosts, VM rollups, alarms, and an event timeline. Combined with the usage trigger and read-only caveat, an agent has enough context to invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already documents datastore_name with exact-match semantics, hours as an event-timeline look-back window, and target as an optional vCenter/ESXi selection. The description adds only a high-level 'point-in-time' hint rather than parameter-specific details, so it meets the baseline but does not exceed it.

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

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

The description uses a specific verb/resource combination: it 'correlates' a datastore's capacity, free space, accessibility, mounting hosts, backed VMs, alarms, and event timeline. This clearly distinguishes it from sibling investigation bundles (vm_investigation_bundle, host_investigation_bundle) and individual datastore browsing 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?

It explicitly states when to use it: 'AFTER cluster_health_summary flags storage pressure.' It also gives a when-not signal by noting that per-datastore latency is a separate perf report. It does not name a specific sibling tool for that alternative, so it stops short of a full routing matrix.

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 well beyond the destructiveHint annotation by explaining the confirm-gated preview/delete flow, that both preview and result record the full rule definition for audit recovery, that the operation is audited, and that errors return a dict with 'error' and 'hint'. This gives the agent a clear model of side effects and failure behavior.

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?

Well-structured and dense: the WRITE marker and purpose are first, then the key exclusion, then behavioral/audit context, then return shape. Every sentence earns its place and nothing is redundant.

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 confirm-gated tool with no output schema and no enum constraints, this description covers the essential operational context: what it deletes, what it refuses, the preview/delete contract, auditability, and error shape. An agent has enough to invoke it safely and interpret the response.

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

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

Schema coverage is 100% and the schema already provides strong descriptions for confirm, cluster, rule_name, and target. The description adds useful behavioral context about the preview/result flow, but it does not substantially add parameter-level meaning beyond what the schema already says.

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?

Starts with a specific verb and resource: 'Delete a VM-VM DRS rule'. It also narrows the scope to VM-VM rules only and clearly distinguishes this from sibling tools like create_drs_rule, set_drs_rule_enabled, and list_drs_rules.

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?

Explicitly states when not to use the tool: non-VM-VM rules are refused and should be managed in the vSphere UI. It also reinforces the confirm-gated workflow by warning that the caller should not blindly set confirm=true before a preview has been seen.

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 only state low-level hints (readOnly=false, destructive=false), so the description carries the behavioral burden. It discloses the copy-on-write mechanism, the source-dependency risk ('depends on the source staying intact'), and the return type ('status string with the new clone name'). This adds meaningful behavioral context beyond the annotations.

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

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

The description is compact and front-loaded: purpose first, then behavior, use case, alternative, prerequisite, and return value. Every sentence earns its place 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?

Despite 8 parameters, the output schema and 100% parameter coverage handle the details. The description adds exactly the missing context an agent needs: what the tool does, when to choose it, the critical source dependency, and the required snapshot workflow. Nothing essential is omitted.

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

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

Schema coverage is 100%, so parameters are fully described in the schema. The description adds context for snapshot_name/source_vm_name via the prerequisite and source-dependency note, but most parameter meaning is already present in the schema. Baseline 3 is appropriate.

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

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

Description states a specific action ('Create a linked clone from a VM snapshot'), the core characteristics ('near-instant, minimal disk usage'), and explicitly differentiates from vm_clone ('use vm_clone for fully independent copies'). This makes the tool's role unmistakable among many VM-related siblings.

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?

Gives clear when-to-use guidance ('Fastest provisioning for test/dev fleets'), names the alternative for a different need (vm_clone), and states a hard prerequisite ('Requires the named snapshot — run vm_list_snapshots first'). It also implies a when-not via the dependency on the source staying intact.

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 meaningful behavioral details beyond the annotations: it returns a status string naming the new VM, upload time scales with OVA size, and it 'fails before creating anything if the datastore is not found.' This gives the agent a clear picture of side effects, performance, and a failure atomicity guarantee that annotations alone do not convey.

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 four sentences with no filler. It front-loads the core actioneb7a and [WRITE] marker, then the usage differentiation, return value, and behavior caveats. 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 an 8-parameter creation tool, the description plus fully described schema covers what the agent needs: the operation, usage conditions, return value, failure behavior, and performance expectation. The output schema exists and the annotations cover mutability, so no critical decision-making 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?

Schema description coverage is 100%, so the schema already documents all 8 parameters including defaults and semantics. The description adds no parameter-specific detail beyond mentioning the datastore failure condition, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb-resource pair: 'Create a new VM by importing a local .ova file' and even names the underlying mechanism (OVF parse + VMDK upload). It also explicitly distinguishes itself from deploy_vm_from_template and vm_clone, making its unique purpose unmistakable.

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

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

'Use for local OVA files; for vSphere templates use deploy_vm_from_template, to copy an existing VM vm_clone' gives explicit when-to-use guidance and names the relevant alternatives. It also adds a practical caveat about upload time and a failure condition (datastore not found), helping an agent decide when this tool is appropriate.

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 [WRITE] prefix reinforces that this is a mutating operation, consistent with readOnlyHint=false. The description adds value by stating that a return status string is produced and by disclosing the prerequisite that an existing template is required. It does not dwell on safety since destructiveHint=false, so a 4 is appropriate.

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

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

Every sentence in the description earns its place: purpose, return value, correct use case, and prerequisite. It is compact, front-loaded, and avoids restating schema fields or 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?

Given the output schema exists, annotations are present, and all parameters are already described in the schema, the description covers the remaining contextual needs: when to use it, what it returns, and what must exist beforehand. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the input schema already documents all eight parameters and their meanings. The description adds no parameter-specific detail beyond the prerequisite relationship to template_name, so the baseline score of 3 is correct.

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 action and resource: 'Deploy a new VM by cloning from a vSphere template.' It also distinguishes itself from vm_clone by explicitly saying it is for VMs marked as templates, not running source VMs. This is enough for an agent to separate it from the relevant siblings.

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

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

The description gives explicit usage conditions: use for templates, use vm_clone for a running source VM, and require an existing template, with convert_vm_to_template named as the way to create one. This is clear, actionable routing guidance that leaves little to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond those: it delegates to the vmware-monitor library, instructs the agent not to dump the result raw, and notes the result is point-in-time. This helps set expectations about how the tool behaves and how its output should be consumed.

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 clear question and purpose, followed by a compact list of correlated data, then workflow guidance. It is a little list-heavy, but every sentence contributes to either purpose, usage, or safe handling. No filler or tautology.

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 investigation bundle with no output schema, the description covers the main data categories returned, the trigger condition, read-only safety, and the point-in-time nature. It does not describe return formatting or potential error behavior, which would make it fully complete, but it gives sufficient context 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?

Input schema coverage is 100%, with each parameter already described in detail (host_name aliasing, hours look-back, optional target). The description does not add parameter-level semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The description opens with a clear, specific question and states the tool correlates a host's state, cluster context, VMs, datastores, alarms, live performance, and a merged event timeline. This clearly identifies the resource (host) and the action (correlated drill-down), and differentiates it from sibling investigation bundles by explicitly centering on the 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 gives an explicit usage trigger: 'Use this AFTER cluster_health_summary flags a host.' This names a sibling tool and the condition under which this tool becomes relevant. It does not spell out when-not-to-use alternatives like vm_investigation_bundle or datastore_investigation_bundle, but the workflow guidance is clear and actionable.

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 [READ] prefix and the return-value contract (a dict with cluster, count, and rules sorted by name; errors as dict with error + hint) add meaningful behavior beyond the readOnlyHint and idempotentHint annotations. It also discloses per-rule fields, giving an agent a concrete expectation of what will be returned.

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 primary action, then follows with per-rule details, usage context, and return format. Every sentence earns its place with no filler or repetition.

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

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

Even without an output schema, the description explains the return structure and error format, and the input side is fully covered by the schema. The tool's purpose, scope, and edge-case behavior are all described, leaving no critical gap for an agent to call it 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 already covers both parameters (target and cluster) with descriptions and 100% coverage, so the description adds no parameter-specific meaning beyond what's structured. The mention of 'cluster' in the description is redundant with the schema's 'Exact cluster name.'

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 a cluster's DRS rules' and enumerates the exact rule types (VM-VM affinity/anti-affinity and VM-Host), giving a specific verb and resource. It also distinguishes itself from sibling mutation tools by explicitly stating it is the verify pair for create/delete/set_drs_rule_enabled.

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 states 'The verify pair for create/delete/set_drs_rule_enabled,' explicitly placing the tool as the read-back verification after those mutations. This is a clear, actionable guideline for when an agent should invoke it, and it distinguishes it from the three mutation 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 readOnly, idempotent, and non-destructive, and the description adds substantial behavioral context: the exact fields returned per portgroup, the family list envelope, the deprecated alias for items, and the error dict shape. This goes well beyond what annotations alone 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 the action, followed by useful use-case and output details. Every sentence adds value: scoping, per-item fields, when to use it, and the response shape and error format. It is informative without being bloated.

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?

Despite the absence of an output schema, the description fully explains the return envelope, item contents, deprecated alias, and error behavior. Combined with the well-documented input schema and safety annotations, an agent has enough 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?

Schema description coverage is 100%, so the schema already documents all four parameters and their defaults. The description only reinforces that dvs_name scopes the listing, which adds context but does not materially expand on the schema.

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

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

The description names a specific verb and resource ('List distributed virtual portgroups') and adds the optional dvSwitch scoping. It distinguishes itself from siblings like create_dvs_portgroup by clearly being the read-side counterpart, and no sibling covers the same resource and action.

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 it: 'verify create_dvs_portgroup results or to survey network config before changes.' It does not spell out when not to use it or name alternative tools, so it stops one step short of the top score.

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, so the safety profile is covered. The description adds substantial behavioral context: vCenter serves cached data for unreachable hosts, rows appear with reachable:false and null device, hosts_unreachable and unreachable_note fields, and truncated is a paging fact rather than an estate-completeness signal. This is exactly the kind of non-obvious behavior an agent needs to interpret results correctly.

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 long but every section earns its place: the gotcha about unreachable hosts is critical and the return-format section is dense but necessary. The '[READ]' prefix and front-loaded purpose sentence make the core action immediately clear. It could be slightly tightened, but the length is justified by the behavioral complexity it discloses.

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 no output schema, the description fully compensates: it explains the envelope fields, the unreachable-host edge case, the deprecated alias, and error shape. The annotations cover safety, the schema covers parameters, and the description covers interpretation. Nothing an agent needs to call this correctly and interpret the result 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?

Schema description coverage is 100%, so the schema already documents all four parameters (limit, offset, target, host_name). The description adds the semantic nuance that host_name scopes to one ESXi host and omitting it lists across all hosts, which is already in the schema. It doesn't add new parameter-level detail beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a clear verb and resource: 'List VMkernel adapters, optionally scoped to one ESXi host.' It then enumerates the per-vmk fields returned, which distinguishes it from sibling tools like add_host_vmk/remove_host_vmk and set_vmk_service. The 'verify pair' phrasing further anchors its role relative to mutation siblings.

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 it (list/verify VMkernel adapters) and names its sibling relationship: 'The verify pair for add_host_vmk/remove_host_vmk.' It also gives a strong when-not-to-trust-it warning: check hosts_unreachable before reporting the result as the full picture. This is explicit usage guidance beyond what the schema or annotations provide.

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 the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond those hints: it explains the pagination envelope, that 'total' is the real active-alarm count, and that every alarm is collected before the limit is applied. This prevents misinterpretation of truncated results.

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 the purpose and usage guidance, then follows with the necessary return-envelope details. Each sentence adds relevant information, and there is no repetition or filler.

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

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

With no output schema present, the description compensates by fully specifying the return envelope fields and their meaning. The two optional parameters are already documented in the schema, and the safety profile is covered by annotations, so the description is complete enough for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by clarifying pagination semantics around 'limit' and 'total'—specifically that 'total' is the true count and that limiting is applied after collection. This goes beyond the schema's simple 'max number to return' phrasing.

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 action and resource: 'List active/triggered alarms across the vCenter inventory.' It also distinguishes this tool from alarm-related siblings by positioning it as the starting point that supplies the entity_name/alarm_name pair needed by acknowledge_vcenter_alarm and reset_vcenter_alarm.

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 'Start here for alarm work' and explains that the output provides the exact pair that acknowledge_vcenter_alarm and reset_vcenter_alarm require. This clearly instructs the agent when to use this tool relative to its named 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?

Beyond the annotations' destructiveHint, the description explains the confirm-gated preview flow, fail-closed semantics for unverifiable state, the absolute protection on the management vmk, and the audit trail. It also details return shapes for preview, success, and error cases. This is rich 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 dense but every sentence earns its place for a destructive, guarded operation. It front-loads the core action and safety posture, then covers guardrails, overrides, and return behavior without wasted prose.

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

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

For a dangerous mutation with no output schema, the description fully explains preview vs. removal results, error shape, override behavior, and audit outcomes. Combined with fully documented schema parameters secret, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning to confirm and force_unprotected (e.g., "confirm=False returns the blast radius", "force_unprotected=True together with confirm=True overrides"), which clarifies the interplay between parameters beyond their individual 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 "[WRITE] Remove a VMkernel adapter," giving a specific verb and resource. It clearly distinguishes itself from sibling tools like add_host_vmk and list_host_vmks by scoping exactly what it does and its destructive nature.

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 explicit when-not conditions: it refuses for management-enabled vmks, service-bound vmks, non-default netstacks, and default gateway routes unless forced. It also identifies a safe use case ("Test vmks created by add_host_vmk trip none of these"). It doesn't explicitly route to sibling alternatives for inspecting or reconfiguring vmks, but the exclusion conditions are strong enough for an agent to gauge suitability.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the crucial gotcha: vSphere has no per-alarm clear, so this tool clears ALL triggered alarms matching the entity type and status. It also discloses the return value's shape (a dict with a 'scope' field). This is significant behavioral context that the annotations do not provide, making the 'blast radius' explicit and reducing the risk of unintended side effects.

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 clear [WRITE] tag and a one-sentence purpose. Every subsequent sentence adds essential usage or behavioral information: when to use, the alternative, the parameter source, the critical gotcha, and the return value. There is no fluff or redundancy; each line 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?

Despite lacking an output schema, the description explains what the tool returns ('a dict whose 'scope' field states exactly what was cleared'). It covers the core workflow (fetch parameters from list_vcenter_alarms), the safety caveat (blast radius), and the conceptual difference from acknowledge_vcenter_alarm. For a tool with modest complexity and rich annotations, this description is sufficient for an agent to call it 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 already provides 100% parameter description coverage, including where alarm_name comes from (list_vcenter_alarms output) and what entity_name means. The description's instruction to 'Get entity_name and alarm_name from list_vcenter_alarms first' restates what the schema already says for alarm_name, adding no new semantic meaning to the parameters. It is useful as a usage ordering cue, but not as parameter semantics, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('Clear triggered vCenter alarms back to normal state') and differentiates from the sibling tool by explicitly naming acknowledge_vcenter_alarm as the alternative for merely marking an alarm seen. This makes the tool's purpose unambiguous and clearly distinguishes it from closely related operations.

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

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

The description provides explicit when-to-use guidance ('Use this after resolving the underlying issue'), identifies the alternative (acknowledge_vcenter_alarm), and instructs the agent to obtain parameters from list_vcenter_alarms first. It also flags a critical prerequisite by advising to confirm the blast radius with the user. This is exactly the practical routing information an agent needs.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable context: it refreshes a local cache file, may be slow on large estates, and describes the return envelope (including a deprecated alias). This goes beyond what annotations convey and is consistent with 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 well-organized: a one-line purpose, a usage note, and a returns section. It front-loads the core action and packs the return format into a compact paragraph. While not as terse as the best examples, every sentence earns its place and there is no filler.

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 scan tool with one optional parameter and no output schema, the description explains the return envelope, the cache side effect, and the performance caveat. It gives the agent everything needed to decide when to call it and what to expect, making it complete for its complexity.

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

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

The single parameter 'target' is fully described in the schema (coverage 100%) as 'Optional vCenter/ESXi target name from config.' The description does not add any additional meaning or syntax details about this parameter, so the baseline of 3 applies since the schema handles it completely.

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, 'Scan all accessible datastores for deployable images (OVA/ISO/OVF/VMDK)', and immediately contrasts itself with browse_datastore, so an agent can distinguish it without opening the schema. It names the exact image types it looks for, which is concrete 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?

It explicitly states the triggering condition ('Use this when you do not know which datastore holds an image') and the alternative ('prefer browse_datastore once you do'), including a rationale about performance ('walks every datastore and may take minutes on a large estate'). This is textbook 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 say write, idempotent, non-destructive; the description adds the preview/confirm gate, noop on matching state, exact-match/ambiguous-name behavior, and audit trail. This is exactly the behavioral context an agent needs beyond the flags.

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?

Starts with a purpose + write marker, then a short motivating scenario, then bullets for idempotency/name matching/audit and return shapes. No filler; all sentences carry 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?

With no output schema, the description supplies return variants (preview/noop/set/error) and key fields, plus safety and matching behavior. An agent can invoke it correctly without needing external lookup.

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

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

Schema coverage is 100% and parameter descriptions are already strong, so the baseline applies. The description reinforces exact rule_name matching and preview/confirm behavior but does not need to explain fields the schema already documents.

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

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

Description states specific verb 'enable or disable' on 'existing DRS rule' and immediately distinguishes the tool from the create/delete/list DRS siblings. The preview/confirm gating and day-2 toggle context make its niche unmistakable.

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

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

Provides concrete scenario: anti-affinity rules disabled when cluster temporarily too small and re-enabled when hosts return. It does not explicitly name sibling alternatives, but 'existing rule' and 'day-2 toggle' make the boundary to create/delete obvious.

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

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

Beyond the annotations, the description discloses preview/confirm gating, idempotent no-write noop behavior, audit logging, fail-closed behavior when the service map cannot be read, and the absolute safeguard against disabling management on the only management-enabled vmk. This is substantial non-obvious 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 longer than average but every sentence earns its place: it front-loads the operation and gating model, organizes safety behaviors clearly, and ends with a concise return-value breakdown. There is no filler or repeated boilerplate.

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 the absence of an output schema, the description is unusually complete. It covers valid inputs, preview/confirm behavior, idempotency, failure modes, safety guards, and the exact shapes of all return dicts. An agent has everything needed to invoke it 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?

Even though schema coverage is 100%, the description adds real value for parameters: it enumerates valid nicType service names, warns about the exact 'vSphereProvisioning' spelling, and clarifies confirm semantics, including the instruction not to set confirm=true before the user has seen the preview. This goes well beyond the schema's basic descriptions.

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

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

The description opens with '[WRITE] Enable/disable a host service on an existing vmk - preview/confirm gated,' naming a specific verb, resource, and operation mode. It also distinguishes itself from add_host_vmk by explaining that adapters are created serviceless and then tagged by this tool.

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

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

The description gives clear usage context: it completes the add_host_vmk story and tells the agent to verify results with list_host_vmks. It does not explicitly list when-not-to-use conditions or contrast with every sibling, but the context is sufficiently clear for an agent to select it appropriately.

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

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

Annotations already declare destructiveHint=true, but the description adds substantial behavioral detail: confirms are preview-only, destructive steps inherit the measuring and blocking semantics of their underlying tools, deferred steps are measured immediately before execution, the plan file is deleted on success and retained on failure, and rollback_available is returned after a failure. This is well beyond what annotations alone convey.

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 long but well-structured into preview behavior, measurement semantics, refusal cases, and execution outcomes. It is front-loaded with the central purpose and every sentence carries safety-relevant information, though a few clauses are dense enough that they could be tightened without losing clarity.

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?

There is no output schema, so the description must explain return behavior, and it does: it lists what the blast_radius contains, how destructive steps are measured, what happens on failure (stops, keeps plan file, returns rollback_available) and success (deletes plan file). Combined with the cross-tool routing and rollback guidance, nothing essential is missing for an agent to invoke this tool safely.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents plan_id, target, and confirm. The description adds extra semantic nuance around confirm=False/True behavior, the requirement that target match the plan's original target, and refusal cases such as delete_vm requiring acknowledge_blast_radius. That pushes it above baseline but not to 5, since the schema already carries most parameter meaning.

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 action and resource: 'Execute a previously created plan step by step.' It immediately separates this tool from plan-creation and rollback siblings by naming the apply workflow and explicitly referencing vm_rollback_plan and vm_create_plan contexts.

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 is explicit about when to use the tool and what the agent must do first: show the preview and get explicit user decision, never set confirm=True on its own, and ask before rolling back. It also lists excluded step types (iscsi_*, storage_rescan) and routes the agent to the correct sibling tools, which is strong, actionable 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 indicate a write operation and non-destructive behavior; the description adds specific context: 'only removes the schedule and never touches the VM itself.' This clarifies the scope beyond the raw annotation flags 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?

Three short sentences with no filler. The [WRITE] marker and action are front-loaded, followed by return type, prerequisite, and safety clarification—each 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 one-parameter operation with an output schema and annotations, the description covers purpose, return behavior, prerequisite, and non-destructive scope. Nothing necessary for correct invocation 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?

Schema coverage is 100% for the single parameter, so the baseline is 3. The description adds the practical requirement to obtain the 'exact vm_name' via vm_list_ttl, which goes beyond the schema's generic parameter description.

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

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

States a specific verb and resource: 'Cancel an existing TTL for a VM' with the effect 'prevents auto-deletion.' The mention of vm_list_ttl for the exact vm_name disambiguates it from the related TTL tools in the sibling set.

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?

Explicitly instructs the agent to 'Use vm_list_ttl first for the exact vm_name,' establishing the correct precondition. It does not explicitly state when not to use this tool, but the workflow context is clear and actionable.

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 well beyond the annotations by explaining the preview-only mode, blast_radius contents, automatic power-off behavior, irreversibility, refusal conditions, and the return dict. An agent knows exactly what will happen in each confirm mode and what can go wrong.

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?

Four short, dense paragraphs front-load the action and then walk through preview, apply, irreversibility, and refusal cases. Every sentence earns its place; the length is justified by the destructive and guarded nature of the operation.

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

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

For a destructive tool with no output schema, the description supplies everything needed: mode semantics, side effects, failure conditions, and return shape. The remaining parameter details are already covered by the input schema, so there is no essential gap.

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