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

Annotations already declare the write/destructive/non-idempotent profile, and the description adds genuinely new context: it auto-handles ETag (concurrency) and 'captures prior state', implying an undo path via undo_list/undo_apply. It does omit what state transition occurs and why the tool is flagged destructive, which keeps it short of a 5.

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 mode/risk tag leads, the one-line purpose follows, and the Args block is terse with no filler. Every sentence adds information an agent needs before calling.

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 2-parameter mutation tool with no output schema and annotations covering safety, the description plus annotations give enough to invoke it correctly: both params are explained, concurrency handling is disclosed, and prior-state capture is noted. Only the resulting state change after acknowledge is left unstated.

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

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

Schema description coverage is 0%, so the description carries the full burden and does document both parameters. 'alert_ext_id as returned by alert_list' gives a concrete provenance for the required ID, and target is explained as a Prism Central config name with an explicit omit-for-default rule — meaning the bare schema does not provide.

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

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

States a specific verb+resource ('Acknowledge an alert') and tags it as a WRITE operation with a risk level. It is clearly distinguishable from alert_list and alert_triage_rca, but it never contrasts itself with the close sibling alert_resolve, which performs a semantically adjacent action on the same resource.

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

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

There is no when-to-use guidance, no prerequisites, and no routing away from alternatives. With alert_resolve and analyze_alert in the sibling set, the agent gets no signal about when acknowledging is the right action versus resolving or triaging.

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

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

Annotations already declare readOnlyHint=true, and the '[READ]' prefix merely restates that. The genuinely additive detail is the disclosure that results report 'returned', 'limit', and 'truncated' so a capped read is visible — useful output-behavior context — but nothing about authorization, ordering, or rate limits.

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

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

Front-loaded with the purpose and return fields, then a compact per-argument breakdown. Every line carries information; the only near-redundancy is restating the default of 500 that the schema already declares.

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 usefully names the returned fields and explains the truncation reporting, which is enough for a simple read-only list tool. It stops short of explaining pagination strategy (how to get past a truncated result) or ordering.

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

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

Schema description coverage is 0%, so the description must carry the load, and it largely does: severity is a single-severity filter with an example (CRITICAL), limit defaults to 500 and drives the truncation flag, target names a Prism Central config entry. The only gap is that valid severity values are never enumerated and the schema has no enum to fall back on.

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 ('List alerts') and enumerates the entity's key fields (extId, title, severity, impact, ack/resolved, affected entity), so an agent knows exactly what comes back. It does not, however, differentiate itself from adjacent list siblings such as event_list or audit_list, which an agent might confuse it with.

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?

Per-argument guidance is decent ('omit for all severities', 'omit for the default' target), implying usage context. But there is no explicit statement of when to reach for alert_list versus analyze_alert, alert_triage_rca, or the other *_list tools, so tool selection 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?

Adds real context beyond the annotations: it flags [WRITE][risk=medium], notes that ETag handling is automatic, and states that prior state is captured. The 'captures prior state' note is valuable since undo_list/undo_apply exist as siblings. It does not contradict the destructiveHint=true annotation, though 'risk=medium' somewhat underplays destructiveness.

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

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

Front-loaded with the [WRITE][risk=medium] tag, then a tight one-line summary, then a compact Args block. Every line carries information, though the Args block partially restates the schema.

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

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

With no output schema and only two parameters, the description covers inputs, side effects (ETag, prior-state capture), and the write/risk profile. It stops short of describing the resulting alert state transition or how the captured prior state can be undone.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it delivers: alert_ext_id is tied to alert_list output, and target is explained as a Prism Central config name that may be omitted for the default. Both parameters are semantically covered.

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+resource ('Resolve an alert'), which is clearly distinct from siblings like alert_acknowledge, alert_list, and analyze_alert. It does not explicitly name those alternatives, but the action itself is 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?

Provides a useful workflow pointer by stating alert_ext_id comes 'as returned by alert_list' and explains the optional target's default behavior. However, it never says when to resolve vs. acknowledge or triage an alert, which is the key routing decision among its alert 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?

readOnlyHint=true is consistent with the [READ] prefix, so no contradiction. Beyond the annotation it adds real behavioral context: aging is clock-free/reproducible (aged against newest alert in the same feed), and it flags criticals that no one has acknowledged. It does not disclose output ordering or volume/pagination behavior, keeping it short of a 5.

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

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

Front-loads the verb, resource, and primary outputs in the first sentence, then qualifies. The parenthetical about clock-free aging is slightly dense but earns its place by explaining the age metric; no filler sentences.

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

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

With no output schema, the description still specifies the return shape (per-level counts, flagged criticals, oldest unresolved with age in days), which is exactly what an agent needs to interpret results. The single parameter is documented and the read-only nature is established.

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

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

Schema description coverage is 0%, so the description must carry the single parameter, and it does: target is the Prism Central target name from config, omittable for the default (matching default null). No format details for a target name, but meaning is fully conveyed.

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 (triage) and resource (active Prism alerts) and enumerates the concrete outputs: per-severity counts, flagged unacknowledged criticals, and oldest unresolved alert with age. This distinguishes it clearly from alert_list (raw listing) and analyze_alert (per-alert correlation).

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 routes the agent to analyze_alert for per-alert event correlation on an individual extId, which is a clear alternative. However, it does not contrast itself against the sibling alert_list or state when a broad triage is preferable to viewing all alerts, leaving one boundary 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 declare readOnlyHint=true, so safety is covered. The description adds valuable behavioral context beyond annotations: 'deterministic', 'resilient', and confirmation that it returns probable cause, suggested actions, and related events. This goes beyond the basic read-only annotation.

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

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

Front-loads the [READ] marker and the core purpose, then adds behavioral guarantees, then documents parameters in a compact Args block. No wasted sentences.

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

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

No output schema exists, so the description correctly mentions the return shape (probable cause, suggested actions, related events). It covers safety, behavior, and parameters. Missing only explicit comparison to sibling RCA tools.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that alert_ext_id comes from alert_list, which is useful relational context, and that target is a Prism Central target name from config with a default fallback. This is considerably more guidance than the bare schema provides.

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

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

States a specific verb and resource: 'Root-cause analysis: correlate an alert with recent same-entity events.' This clearly distinguishes it from alert_list (which lists) and from cluster_health_rca/alert_triage_rca (which are sibling RCA 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?

Explains what the tool does and notes it is 'safe to run on a live, alerting cluster,' which implies when to use it. However, it doesn't explicitly differentiate from alert_triage_rca or cluster_health_rca, which are the most likely alternatives in the sibling set.

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

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

Annotations already declare readOnlyHint=true, so safety is covered structurally. The description adds genuinely useful behavior by explaining that results report `returned`, `limit`, and `truncated`, making a capped read visible. However it does not disclose ordering, default newest/oldest, or how to page beyond the limit.

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

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

Front-loaded with the read marker and the record shape, then a compact Args block. Some redundancy between the limit description and its truncation reporting, but overall efficient.

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

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

Covers both parameters and the truncation behavior, adequate for a two-param read with no output schema. It stops short of ordering, paging strategy beyond limit, and distinguishing this audit feed from the other event/task list tools in the same namespace.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It documents `limit` (max rows, default 500) and `target` (Prism Central target name, omit for default), adding meaningful semantics that the bare schema lacks, though it could note units or a maximum for limit.

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+resource: 'List config audit records' with the fields returned (extId, operation type, user, creation time). Clearer than a tautology, but does not differentiate itself from the many other *_list siblings (event_list, task_list, alert_list, undo_list).

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

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

No statement of when to use this tool versus the sibling list tools such as event_list or task_list. The '[READ]' prefix implies a safe read but gives no 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?

Annotations only give readOnlyHint=true; the description adds genuine context beyond them: the [READ] tag, full determinism ("No clock or randomness — same inputs, same answer"), and the explicit failure mode when growth data is absent. It stops short of describing return shape or limits, but for a read-only computation this is solid added value.

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

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

The core purpose and the [READ] marker are front-loaded, and the Args block is compact and scannable. The determinism point is made twice ('No clock or randomness — same inputs, same answer' alongside 'Deterministic'), which is slight redundancy but not bloat.

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

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

With no output schema, the description steps in to name the key return notion (daysToFull) and the 'insufficient-data' outcome, plus cross-tool provenance for the required ID. It could say more about the forecast model or output fields, but an agent has enough 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 0%, so the description carries the full burden and does: it gives units for daily_growth_bytes (bytes/day), explains that omitting it skips the forecast, identifies cluster_ext_id as coming from cluster_list, and clarifies that target defaults to the config value.

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

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

States a specific verb+resource: a deterministic storage-runway (days-to-full) estimate for a cluster. This is clearly separable from siblings like cluster_utilization (current usage) or cluster_health (state), since the output metric here is a projected time-to-full rather than a snapshot.

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

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

It explains the conditional behavior of daily_growth_bytes (supply it to get daysToFull, omit it and the forecast is 'insufficient-data'), which implies when the parameter is needed, but it never states when to reach for this tool over cluster_utilization/cluster_health or what prerequisites (e.g., a cluster must exist) apply.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the mutating profile is covered structurally; the description's [WRITE] tag is largely redundant with that. What it adds is the risk=medium qualifier and the "Bulk" nature of the operation. It does not say what happens to pre-existing category assignments, whether the call is synchronous or task-backed, or what permissions are required.

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 operation tag and one-line purpose are front-loaded, followed by a compact Arg list with no filler. It reads as a docstring restatement rather than prose, but nothing is wasted and the size matches the tool's simplicity.

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 bulk mutation with no output schema, the description documents every parameter and defers safety to the annotations. However, it omits operationally relevant facts: error behavior on invalid extIds, whether the result is a task (task_list exists), and whether the change is reversible given undo_list/undo_apply are available siblings.

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

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

Schema description coverage is 0%, so the description carries the full burden — and it does document all three parameters, including the origin of category_ext_id and vm_ext_ids and the fact that target may be omitted for the default. This meaningfully compensates for the empty schema titles.

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: "Bulk-associate a category to a set of VMs," which is clearly distinct from siblings like category_create, category_list, and vm_update. The [WRITE][risk=medium] prefix sets operation type up front. It never names an alternative sibling, so full marks for differentiation are not earned.

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

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

Usage is implied through ID provenance ("as returned by category_list," "from vm_list"), which sketches the list-then-assign workflow. There is no explicit when-to-use vs. when-not guidance and no mention of alternatives such as vm_update or category_create, so the guidance stops at inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds the [WRITE][risk=medium] tag, which is useful framing, but says nothing about what the operation affects, permission requirements, or behavior when the key/value already exists. 'risk=medium' also sits slightly awkwardly beside destructiveHint=true, though it is not a direct 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?

Front-loaded with the operation and risk tag, followed by a tight Args block with no filler. The bracketed tag and indented list are compact and scannable, though the tag duplicates information partly conveyed by annotations.

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

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

For a non-idempotent destructive write with no output schema, the description covers inputs but omits outcome semantics: no mention of what is returned, what happens on a duplicate key, or whether the new category is scoped to a tenant/cluster. The Args block is complete, so it is adequate but not fully self-sufficient.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it largely does: all four params are documented, with concrete examples for key/value ('Environment'/'Production') and a clear explanation of target ('Prism Central target name from config; omit for the default'). It does not cover format constraints or max lengths, but the semantic gaps are filled.

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: 'Create a category key/value pair,' which is unambiguous and clearly a mutation. It does not distinguish itself from siblings like category_list or category_assign, so an agent must infer where it sits in the category workflow.

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 never says when to use this tool versus category_assign or category_list, nor mentions prerequisites (e.g. whether the category must exist before assigning, or that key/value creates it). Only the Args block is provided, which documents inputs rather than usage context.

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

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

Annotations declare readOnlyHint=true, and the description adds genuinely new behavioral context: a default cap of 500 rows and the fact that the result self-reports `returned`, `limit`, and `truncated` so silent truncation is visible. That truncation disclosure is exactly the kind of trait annotations cannot express, though permissions and error behavior remain unstated.

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 read-only marker and purpose are front-loaded in the first sentence, followed by a tight two-item args block. Every line earns its place; only the literal 'Args:'/'limit:'/'target:' scaffolding feels slightly docstring-mechanical.

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 2-param, read-only list tool with no output schema and no required params, the description covers both parameters and the truncation behavior an agent needs to interpret results correctly. Filtering/sorting options and permission requirements are absent, but nothing essential to calling 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 description coverage is 0%, so the description must carry the load and largely does: `limit` is defined as max rows with a 500 default, and `target` is explained as a Prism Central target name from config that can be omitted for the default. Neither param's type/format edge cases (e.g. what happens if limit exceeds the available rows) are covered, keeping it short of a 5.

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+resource ('List categories') and even enumerates the returned fields (extId, key, value, description), so the agent knows exactly what comes back. It does not explicitly distinguish itself from sibling category_create/category_assign, but the read-vs-write split is obvious from the name and the '[READ]' tag.

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?

Nothing states when to prefer this over category_create or category_assign, or whether any prerequisite exists. The only usage-flavored text is 'omit for the default' on the target arg, which is parameter guidance rather than tool-selection 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?

readOnlyHint=true already declares the safety profile, and the '[READ]' tag is consistent with it rather than contradictory. The description adds a useful scope statement (which health facets are reported), but says nothing about latency, aggregation level, or failure modes when a cluster is unreachable.

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 read scope is front-loaded in the first clause, and the Args block is tight with no filler. Minor overhead from the bracketed tag and label formatting, but nothing is wasted.

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

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

With no output schema and no annotation beyond readOnlyHint, the description does enough by naming the returned health facets. The remaining gap is the relationship to cluster_health_rca for deeper diagnosis, which an agent would need to route correctly between the two.

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

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

Schema coverage is 0%, so the description carries the full burden and largely succeeds: it identifies cluster_ext_id as an extId sourced from cluster_list, and explains that target comes from config and defaults when omitted. It does not clarify the expected extId format or whether target is a strict config key.

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 ('One cluster's health') and enumerates the health domains returned (services, resiliency/fault-tolerance, upgrade state), which separates it from cluster_list. It does not, however, differentiate itself from the sibling cluster_health_rca, leaving the agent to infer the boundary between summary health and root-cause analysis.

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

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

Usage guidance exists only for the 'target' parameter ('omit for the default'), and cluster_ext_id is indirectly routed via cluster_list. There is no explicit statement of when to call this versus cluster_health_rca or cluster_utilization, so selection between these related tools remains 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 declare readOnlyHint=true, so safety is covered, but the description adds real behavioral value: it aggregates multiple resource types, reports 'worst-first', applies explicit 80%/90% thresholds, and states that every finding cites the measured percentage or raw Prism state string. Rate limits and auth are not mentioned, keeping it short of a 5.

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

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

Front-loaded with the '[READ]' marker and a one-line summary before detail. The enumeration of findings is dense but each clause conveys distinct behavior; slightly long but nothing clearly wasteful.

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

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

For a complex multi-source aggregation tool with no output schema, the description details the return findings, thresholds, and evidence format, which is exactly what an agent needs. Coverage is strong, though pagination/ordering beyond 'worst-first' is unstated.

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

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

Schema coverage is 0% for the single 'target' parameter, so the description must compensate — and it does, explaining 'Prism Central target name from config; omit for the default'. That adds meaning beyond the bare anyOf/schema, though it is only one parameter.

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

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

States a specific verb and resource ('Estate health RCA'), then enumerates exactly what it collects (every cluster's health + utilization, all hosts, all storage containers) and what it reports. This clearly distinguishes it from single-resource siblings like cluster_health, host_list, and cluster_utilization.

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

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

Usage is implied through the scope description (estate-wide RCA) and the '[READ]' tag, but the description never explicitly states when to choose this over cluster_health or cluster_utilization, nor any when-not conditions. It leaves the agent to infer that this is the broad diagnostic versus the narrower 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?

readOnlyHint=true is already declared, and the description reinforces it with the [READ] tag while adding genuinely new behavior: the result reports `returned`, `limit`, and `truncated` so a capped read is detectable. It does not cover rate limits or result ordering, so it falls slightly short of exhaustive.

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

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

Front-loaded with the core action and the critical call-first instruction, then a compact per-parameter block with no filler. The bracketed [READ] tag is mildly redundant given readOnlyHint, which keeps it from a perfect score.

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 steps in by naming the returned fields and the truncation metadata, and it explains both parameters plus the ordering dependency on other tools. An agent has everything needed to call this correctly on the first attempt.

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

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

Schema description coverage is 0%, so the description carries the burden and largely meets it: `limit` is explained with its default and, more usefully, how truncation is surfaced in the response; `target` is identified as a Prism Central config name with "omit for the default." Both parameters gain meaning beyond the bare schema types.

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

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

States a specific verb and resource ("List registered clusters") and enumerates the returned attributes (extId, name, AOS version, hypervisors, nodes), which cleanly separates it from siblings like cluster_health and cluster_utilization that operate on a single cluster rather than enumerating the inventory.

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?

"Call this first — most other tools need a clusterExtId from here" gives explicit, actionable sequencing guidance that an agent can act on immediately. It stops short of naming concrete alternatives or stating when NOT to use it, so it is not a 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?

readOnlyHint=true already declares this is a safe read, so the bracketed '[READ]' tag is largely redundant. The description does add one genuine behavioral trait beyond the annotations: the values are 'point-in-time' rather than historical or averaged, which affects interpretation. It does not disclose required permissions, metric units, or sampling window.

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

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

Front-loaded with what the tool returns, followed by a tidy Args block; no filler sentences. The '[READ]' prefix duplicates what the readOnlyHint annotation already states, a minor redundancy. Overall appropriately sized for a two-parameter tool.

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 is responsible for signalling the return shape, and it does by naming the four metric families (CPU, memory, storage, IOPS) plus their point-in-time nature. For a read-only tool with two well-documented parameters, little is missing apart from units or sampling cadence.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it largely does: cluster_ext_id is explained as 'Cluster extId as returned by cluster_list' (a useful provenance pointer unavailable in the schema), and target is described as a Prism Central target name from config with the omission default. This meaningfully exceeds the bare schema.

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

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

The description states a specific verb+resource combination — point-in-time CPU/memory/storage/IOPS utilization for a cluster — so the agent knows exactly what data comes back. It is clearly distinct from siblings like snapshot_list or task_list, though it never explicitly contrasts itself with the closest sibling, cluster_health, or capacity_runway. Clear but no sibling differentiation.

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

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

There is no when-to-use guidance: no statement of when to prefer this over cluster_health, capacity_runway (which implies trend/capacity analysis), or host_list. The 'point-in-time' phrasing hints at scope but does not tell the agent which question this tool answers versus alternatives. No exclusions or prerequisites beyond the target parameter note.

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

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

readOnlyHint=true already covers the safety profile, and the description adds the meaningful extra that the result reports `returned`, `limit`, and `truncated` so a capped read is visible — real behavioral context an agent would not otherwise know. It still doesn't say anything about ordering, time window, or pagination beyond the cap.

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

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

Front-loaded with the read marker and the resource, then a compact Args block with no filler. The docstring-style formatting is slightly verbose but every line carries 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?

No output schema exists, yet the description still names the returned fields and explains the truncation reporting, so an agent knows what to expect back. For a two-parameter read-only list tool this is close to complete; only result ordering and default time scope are unstated.

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

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

Schema description coverage is 0%, so the description has to carry the load, and it does: it explains `limit` (max rows, default 500, with truncation reporting) and `target` (Prism Central target name from config, omit for default). That is genuinely more than the bare schema types convey.

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+resource ("List events") and even enumerates the salient fields returned (extId, title, creation time, source entity). It does not, however, distinguish itself from the many other list tools in the fleet (alert_list, audit_list, task_list, snapshot_list), so an agent gets no explicit routing signal.

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

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

There is no statement of when to reach for event_list versus alert_list, audit_list, or task_list, all of which are plausible alternatives for a similar list-shaped call. Usage is only implied by the name and the returned fields.

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

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

readOnlyHint=true already covers the safety profile, but the description adds genuinely new behavior: a default cap of 500 rows and self-reported `returned`/`limit`/`truncated` fields so a truncated read is detectable. That truncation disclosure is real value beyond the annotation, though it doesn't cover auth or per-cluster scoping caveats.

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

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

Front-loaded with the READ tag and purpose, then a compact Args block. Every sentence earns its place — no filler, no restatement of the tool name.

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

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

For a two-param read with no output schema, the description supplies both parameter semantics and partial return-shape information (the truncation fields vs. the listed entity columns). Nothing critical is missing, though it could clarify whether results are paginated beyond the single cap.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: 'limit' is defined as max rows with a default of 500 and its effect reflected in the result, and 'target' is explained as a Prism Central target name from config that defaults when omitted. A limit range or upper bound is not given, keeping it just short of a 5.

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 ('List') and resource ('hosts') with explicit scope ('across all clusters') plus the fields returned (extId, cluster, hypervisor, CPU/mem). No sibling tool overlaps this resource, and the '[READ]' prefix reinforces the operation class, so an agent can select it without 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?

Usage is implied by the verb and scope rather than stated: there are no explicit when/when-not rules and no alternatives named. The only routing guidance is the 'target' note (omit for the default), which is parameter-level rather than tool-selection guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description goes well beyond that by disclosing the audit tier ('review'), the optional NUTANIX_AUDIT_APPROVED_BY/RATIONALE approval annotations, the dry_run preview behavior, and that the image's prior name is captured on the audit trail. This is exactly the additional behavioral context annotations cannot 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?

Front-loaded summary, then a compact audit paragraph, then a clean Args block. Every element is useful, though the audit-boilerplate sentence is dense enough that it slightly delays the parameter semantics.

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 mutation with no output schema and no annotation coverage of return values, the description covers parameters, safety preview, and audit implications. It only partially describes what a successful delete or dry_run actually returns, leaving a small gap.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden and does so for all three args: ext_id is tied to its source ('as returned by image_list'), dry_run is defined behaviorally ('return what WOULD be deleted without deleting'), and target explains the config lookup and default.

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 first sentence gives a specific verb and resource ('Delete an image') and immediately flags the write/high-risk classification, which cleanly separates it from the read-only image_list sibling. An agent needs nothing more to know what this tool does.

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 a concrete invocation guideline ('pass dry_run=True to preview first') and explains the audit-approval path, so the agent knows the safe way to call it. It does not state when deletion is inappropriate or contrast it with the sibling image_list, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral trait beyond the annotations: that a capped read surfaces `returned`, `limit`, and `truncated`, making truncation visible to the caller. Auth needs and rate limits are not addressed, but the truncation disclosure is meaningful added 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 purpose is front-loaded after the [READ] tag, and the Args block is compact with no filler. Only mild redundancy between the summary field list and the parameter notes keeps it from being maximally tight.

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

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

For a simple two-parameter read tool with no output schema, the definition covers purpose, both parameters, and truncation behavior adequately. It lacks routing guidance relative to sibling listing tools, which is the only notable gap.

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

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

Schema description coverage is 0%, so the description carries the burden and does so well: it documents both parameters, explaining that limit defaults to 500 and drives the truncation reporting, and that target is a Prism Central name that may be omitted for the default. It adds meaning beyond the bare types in the schema.

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

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

States a specific verb (List) and resource (content-library images), and even enumerates the returned fields (extId, name, type, size, cluster placement). This is precise enough to distinguish it from siblings like image_delete or the various other *_list tools without opening any 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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The [READ] tag and target parameter hint at context, but nothing tells the agent when this tool is the right choice versus vm_list, snapshot_list, or other listing siblings.

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

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

Annotations already declare readOnlyHint=true, and the description adds genuine behavioral context beyond that: it discloses that results report `returned`, `limit`, and `truncated` so a capped read is visible, plus the target-resolution behavior. It stops short of describing rate limits or ordering.

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

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

Front-loaded with the core purpose, then a compact Args block. Every line earns its place; only the multi-line wrapping of the limit note is slightly verbose.

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

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

For a simple two-parameter read tool with no output schema, the description covers what is returned at a high level (versions, updateAvailable, truncation metadata) and how to scope the read. The term 'LCM-managed entities' remains a little abstract, which keeps it from a 5.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does: limit is explained with its default of 500 and truncation reporting, and target is explained as a Prism Central config name with omission defaulting. Both parameters are meaningfully documented, though no format examples are given.

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: list LCM-managed entities with current/available versions and updateAvailable. The '[READ]' tag and version-focused content make it distinguishable from the mutation siblings lcm_precheck and lcm_update, though it doesn't name them 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?

Usage is implied by the read tag and the mention of omitting target for the default, but there is no explicit when-to-use vs. alternatives guidance (e.g., relative to lcm_precheck/lcm_update) and no stated preconditions.

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

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

The description labels this a 'read-safe validation', implying no state change, while the annotations declare destructiveHint=true and readOnlyHint=false. These directly conflict, so an agent cannot tell whether the call mutates the cluster. This is an Annotation 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?

Front-loads the operation tag and purpose, then a tight Args block with one line per parameter. No filler; every 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?

For a validation tool with no output schema, the description never explains what a precheck returns or what the agent should do with the result (pass/fail, blocking errors). Combined with the read-safe/destructive contradiction and absent success criteria, it leaves an agent unable to interpret the outcome correctly.

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

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

With 0% schema description coverage, the description carries the full burden and largely meets it: it names each of the three parameters and gives provenance (cluster_list, lcm_inventory, config) plus the default behavior for target. It stops short of clarifying whether entity_ext_ids accepts mixed entity types or how many, but it meaningfully compensates for the schema gap.

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

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

States a specific verb and resource: 'Run LCM prechecks for entities on a cluster'. It distinguishes itself from the sibling lcm_inventory (source of entity_ext_ids) and cluster_list (source of cluster_ext_id), so an agent can place it in the LCM workflow. It does not, however, contrast with lcm_update or explain how precheck relates to the actual update.

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

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

Usage is implied by the provenance hints ('from lcm_inventory', 'as returned by cluster_list'), which tell the agent where the inputs come from. But there is no explicit when-to-use guidance, no statement that this should precede lcm_update, and no exclusions or prerequisites. The context is inferable but not stated.

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

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

Annotations already declare destructive/not-idempotent, and the description adds substantial context beyond them: the operation is NOT undoable, it sits in audit tier 'review', NUTANIX_AUDIT_APPROVED_BY/RATIONALE can annotate who/why, and the precheck gate is enforced even for dry_run. That dry_run parity guarantee is exactly the kind of behavioral disclosure an agent needs before calling a destructive tool.

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

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

Front-loaded with the write/risk tag and refusal conditions, then a clean Args block — no filler. Slightly long, and the audit-tier detail plus the dry_run parity sentence could be tightened, but both carry real safety information.

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

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

For a high-risk, non-undoable mutation with no output schema, the description covers the safety profile, the mandatory precheck workflow, the dry_run escape hatch, and every parameter's source. An agent has everything needed to call it correctly or decide not to.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: it documents all five parameters, says where each ID comes from (cluster_list, lcm_inventory, lcm_precheck), explains dry_run semantics and target defaults, and flags precheck_task_ext_id as required even though the schema marks it optional with an empty-string default.

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 ('Perform an LCM firmware/software update') and tags it as a WRITE/risk=high operation up front. This is clearly distinguishable from the sibling read/inventory tools (lcm_inventory, lcm_precheck) and from unrelated write tools like vm_update.

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

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

Gives explicit prerequisites and ordering: run lcm_precheck first, wait for SUCCEEDED (verified via task_list), then pass the returned taskExtId, and the update is refused otherwise. It also names the dry_run preview path as the safe alternative before committing.

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

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

Annotations declare destructive/readOnly/idempotent profile, and the description adds substantial context beyond them: the risk=high tag, audit tier 'review', the optional NUTANIX_AUDIT_APPROVED_BY / NUTANIX_AUDIT_RATIONALE approval annotation fields, and the dry_run preview path. This is exactly the richer behavioral detail the annotations cannot 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?

Front-loads the [WRITE][risk=high] signal, then purpose, then a clean Args block. Slight redundancy between '[risk=high]' and 'Tagged risk=high', but otherwise tight and well-structured.

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 high-risk mutation with no output schema, the description covers safety profile, preview mechanism, audit-approval metadata, and all parameter sourcing. Nothing an agent needs to invoke it correctly 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 0%, so the description carries the full parameter burden and does so well: it explains each of the four params and, critically, names the source endpoint for the extIds (protection_domain_list, cluster_list) and that target is a Prism Central name from config defaulting when omitted.

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 (fail over) and resource (protection domain) plus the target (cluster) and frames it as a DR event. An agent can cleanly distinguish it from siblings like protection_domain_list, vm_protect, and snapshot_restore without opening any 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?

Gives the operative usage condition: it is a destructive DR operation and dry_run=True previews it before executing. It does not name a specific alternative sibling tool for the non-failover case, so it stops short of explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds genuinely non-obvious context beyond that: the limit cap of 500 and the fact that the result reports `returned`, `limit`, and `truncated` so a capped read is visible — useful behavioral disclosure about truncation.

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

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

Front-loaded with the operation and returned fields, then a compact Args block. Every sentence earns its place, though the formatting is slightly terse rather than optimally polished.

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 annotations covering safety and no output schema, the description compensates by naming the returned fields and the truncation contract. Complete enough for correct invocation; only the lack of sibling routing and pagination continuation semantics keeps it from the top.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so for both params: it explains limit's default of 500 and its truncation-reporting effect, and clarifies that target is a Prism Central target name from config that should be omitted for the default.

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 ('List') and resource ('protection domains / policies') and even names the fields returned (extId, name, replicationType). Sibling differentiation is absent, however: nothing distinguishes it from recovery_point_list or other list tools beyond the resource noun.

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

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

Usage is only implied by the '[READ]' prefix and the target-parameter note ('omit for the default'). There is no explicit statement of when to prefer this over siblings like pd_failover or recovery_point_list, nor any prerequisite conditions.

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

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

Annotations already declare readOnlyHint=true, so safety needs no restating. The description adds genuine behavioral context beyond the annotations: the 500 default cap and the fact that the result reports `returned`, `limit`, and `truncated` so a capped read is visible. This is exactly the kind of pagination behavior an agent needs.

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

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

Front-loaded with the [READ] tag and the one-line purpose, then a compact per-argument breakdown. No filler sentences; slightly list-like formatting but every 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?

For a simple two-parameter, no-required-args list tool with no output schema, the description covers both parameters, the return fields, and truncation behavior. An agent has enough to call it correctly; only cross-tool routing guidance is absent.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: `limit` is documented with its default (500) and truncation semantics, and `target` is explained as a Prism Central target name from config with the omit-for-default rule. This meaningfully exceeds the bare schema types.

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

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

States a specific verb+resource ('List recovery points') and even enumerates the fields returned (extId, vmExtId, create/expiration time, locationType), making the tool's scope clear. It does not explicitly distinguish itself from the closest sibling, snapshot_list, so it falls short of a 5.

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

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

There is no when-to-use guidance, no mention of alternatives like snapshot_list, and no conditions for selecting this tool over siblings. The only contextual note ('omit for the default') is about a parameter, not about when the 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?

Annotations already declare destructiveHint=true, so safety is partially covered; the description adds the key extra fact that the operation is reversible via snapshot_delete. It also discloses the ETag auto-handling behavior, which is real operational context. It does not mention auth/permissions, but the core behavioral traits are surfaced.

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

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

Front-loads the write/risk/reversibility facts in one bracketed line, then lists args compactly. Every sentence earns its place; minor redundancy in the 'Args:' block style but no 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?

A write tool with no output schema and no annotation coverage on reversibility: the description supplies the reversibility, the ETag handling, the foreign-key lookup (vm_list), and the target default. Enough to call correctly; only auth/prerequisite detail for a medium-risk write 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 0%, so the description must compensate, and it does: vm_ext_id is cross-referenced to vm_list, target is labeled as a Prism Central config name with an omit-for-default rule. The name param gets the least value (title only), keeping this from a 5.

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 ('Snapshot a VM') and immediately distinguishes itself from siblings by naming the reversal path (snapshot_delete) and lifecycle siblings exist (snapshot_restore). An agent can tell it apart from snapshot_list/restore 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?

Includes the risk tag [risk=medium] and the reversibility note, which implies when it is safe. But it gives no explicit when-to-use vs snapshot_restore or vm_protect, and no exclusion conditions. Usage is only 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?

Goes well past the annotations: reveals the 'review' audit tier, the NUTANIX_AUDIT_APPROVED_BY / NUTANIX_AUDIT_RATIONALE env vars needed to annotate who/why, that the snapshot's prior name is captured on the audit trail, and that dry_run returns a preview rather than performing the delete. This is rich behavioral context an agent cannot get from readOnlyHint/destructiveHint alone.

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

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

Front-loaded with risk tag and one-line purpose, then a compact Args block. Every sentence carries information, though the audit-tier paragraph is dense and slightly heavy for a description whose core job is delete semantics.

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?

A destructive mutation with no output schema and no annotations documenting the audit workflow — the description covers the safety path (dry_run), audit requirements, and deletion scope, which is what an agent needs to call it correctly. Return shape is only implied ('what WOULD be deleted'), a minor gap.

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

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

Schema description coverage is 0%, yet the description documents all four parameters and adds meaning: vm_ext_id comes from vm_list, snapshot_ext_id from snapshot_list, dry_run's exact semantics, and target's defaulting behavior. This fully compensates for the schema's lack of descriptions.

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

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

Opens with a specific verb+resource: 'Delete a VM snapshot.' The [WRITE][risk=high] tag immediately separates it from read siblings like snapshot_list, and the destructive framing distinguishes it from snapshot_restore/snapshot_create.

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 the preview path explicitly ('pass dry_run=True to preview') and gives operational context for the audit tier, which tells the agent when this call needs extra authorization. It does not contrast against alternatives like snapshot_restore, but the destructive framing implies the boundary.

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

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

readOnlyHint=true is echoed by the [READ] prefix, so no contradiction. Beyond annotations it discloses genuinely useful behavior: the result reports `returned`, `limit`, and `truncated` so a capped read is visible, and it explains the default target resolution. It omits pagination/next-page behavior, keeping it short of a 5.

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

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

Front-loaded with the read tag and purpose, then a compact Args block. The wording is efficient with no filler, though the multi-line arg formatting is slightly verbose for a three-parameter tool whose schema has no descriptions.

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?

No output schema exists, and the description compensates by naming the key return fields and the truncation indicators (`returned`/`limit`/`truncated`). Combined with full parameter documentation, an agent has enough to call it correctly; only pagination semantics beyond the capped-read signal are unstated.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so for all three parameters: vm_ext_id is cross-referenced to vm_list, limit is given a default (500) and a truncation note, and target is explained as a Prism Central config name that can be omitted for the default. This meaningfully exceeds the bare schema titles.

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 (List) and resource (a VM's snapshots), names the returned fields (extId, name, createTime), and gives a purpose tagline ('spot lingering snapshots'). It is cleanly distinguishable from siblings snapshot_create, snapshot_delete, and snapshot_restore.

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?

'Spot lingering snapshots' implies a usage context, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives for related tasks (e.g., snapshot_create/delete). Usage is inferable but not spelled out.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds material context: the revert overwrites current VM state, is NOT undoable, is gated at audit tier 'review', and can be annotated via NUTANIX_AUDIT_APPROVED_BY/NUTANIX_AUDIT_RATIONALE. This is exactly the extra behavioral detail annotations cannot express.

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

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

Front-loaded with the risk/undoability warning before the Args block, so the critical information lands first. There is mild redundancy between the [risk=high] tag and 'Tagged risk=high (audit tier review)', but nothing is padded.

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 high-risk, 4-parameter mutation tool with no output schema, the description covers safety, preview workflow, audit provenance, and every parameter. It could note post-revert VM state (e.g., power state), but an agent has everything needed 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 0%, so the description must carry the load, and it documents all four parameters, including where the IDs come from (vm_list, snapshot_list) and that target defaults to config. It stops short of 5 only because 'target' semantics are thin (just 'Prism Central target name from config').

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 ('Revert a VM to a snapshot'), which is clearly distinguishable from sibling snapshot_list, snapshot_create, and snapshot_delete. The lead tags [WRITE][risk=high] immediately signal the operation class.

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 operational guidance: destructive, not undoable, preview first with dry_run=True, and the audit approval/rationale env vars for the 'review' tier. It does not name sibling alternatives (e.g., snapshot_list to obtain IDs is only implied in the Args), so it falls short of explicit when-not routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/mutation profile is covered structurally; the description reinforces it with [WRITE][risk=medium]. It adds the default replication factor and config-based target behavior, but says nothing about permissions required, name-collision behavior, or non-idempotency beyond the annotation.

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

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

Front-loaded with the operation and risk tag, followed by a tight Args list where every line carries information. No filler sentences, though the tagged-prefix plus args block is slightly more structural overhead than a single crisp sentence would need.

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 4-parameter mutation tool with no output schema, the description covers purpose, all parameters, defaults, and risk level. Gaps remain around failure modes and required privileges, but the essentials an agent needs to invoke it correctly are 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 0%, so the description must compensate, and it does: all four parameters are explained with meaning beyond the schema, including defaults ('Copies kept per block (default 2)') and the omit-to-use-default semantics of target. It does not specify the expected format of cluster_ext_id beyond its source, which keeps it from a 5.

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 ('Create a storage container on a cluster') with an explicit [WRITE] tag, which cleanly separates it from the sibling read tools (storage_container_list) and the mutate siblings (storage_container_update/delete). No ambiguity about what the tool does.

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

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

Usage is implied by the create verb and the [WRITE] tag, and one workflow hint is given (cluster_ext_id 'from cluster_list'), but there is no explicit when-to-use vs alternatives, no prerequisites, and no when-not guidance. Adequate but leaves routing to inference.

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

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

Beyond the destructiveHint=true annotation, it discloses the audit tier ('review'), the NUTANIX_AUDIT_APPROVED_BY / NUTANIX_AUDIT_RATIONALE environment variables for attribution, and that prior capacity/RF is captured on the audit trail. These are real operational facts an agent cannot get from the annotations or schema.

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

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

Front-loads the [WRITE][risk=high] tag and the destructive warning before the trailing audit metadata, so the most decision-relevant content comes first. The audit-tier detail is slightly dense but each sentence carries distinct information.

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

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

For a high-risk mutation with no output schema, it covers dry-run behavior, approval env vars, audit capture, and target selection, which is close to complete. It stops short of stating what a successful (non-dry-run) invocation returns or how long deletion takes, a minor gap given the tool's risk profile.

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

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

Schema description coverage is 0%, and the Args block compensates fully: ext_id's provenance (from storage_container_list), dry_run's exact semantics (return what WOULD be deleted), and target's meaning (Prism Central target from config, omit for default). All three parameters are given meaning absent from the schema.

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

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

States a specific verb+resource ('Delete a storage container') and immediately frames it as destructive and high risk. It is cleanly distinguished from the sibling storage_container_list/create/update tools by naming the delete operation and its blast radius.

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 'pass dry_run=True first', which is actionable sequencing guidance, and notes that ext_id comes from storage_container_list. It does not spell out when deletion is inappropriate beyond the blanket destructiveness warning, so it stops just short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: the result reports returned/limit/truncated so a capped read is visible, and it names the returned fields. This truncation-awareness is genuinely helpful.

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

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

Front-loaded with the [READ] tag and resource list, followed by a compact Args block. Every sentence earns its place, though the truncation note is slightly verbose.

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

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

For a simple read-only list tool with no output schema and 0% schema coverage, the description supplies both parameter semantics and the return-field/truncation behavior. Nothing critical is missing, though pagination beyond limit is not discussed.

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

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

Schema description coverage is 0%, so the description must carry both parameters, and it does: limit is defined as max rows with a default of 500, and target is identified as the Prism Central target name from config, omittable for the default. Both parameters are meaningfully explained.

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 (List) and resource (storage containers), then enumerates the returned fields (extId, name, cluster, capacity, usage, RF). This clearly distinguishes it from the sibling storage_container_create/update/delete 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?

Usage is implied by the [READ] tag and the parameter notes (limit caps rows, omit target for default), but there is no explicit when-to-use-vs-alternatives guidance or exclusions. Adequate but leaves the agent to infer context.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true; the description adds the risk grade (medium), states the change is reversible to the prior state, and notes that omitting capacity/replication leaves them unchanged. It does not mention that non-idempotent behavior means repeated calls are not safe to assume, but the added context is substantive.

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

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

Front-loaded with the operation class and risk tag, then a one-line purpose, then a tight arg list; nothing is padded. The '(reversible -> prior)' shorthand is slightly cryptic, which keeps it out of 5 territory.

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

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

For a mutation tool with no output schema, the definition covers parameters, risk, reversibility, and required identifier well. It omits failure modes, permission requirements, and any post-change verification step, but nothing essential 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 description coverage is 0%, yet the description documents all four parameters: ext_id with its provenance (storage_container_list), max_capacity_bytes and replication_factor with units and the 'omit to leave unchanged' semantics, and target with its config-prefix and default behavior. This compensates fully for the bare schema.

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

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

States a specific verb and resource ('Resize a container's capacity / replication') and scopes exactly which attributes change. It is immediately distinguishable from sibling storage_container_create, storage_container_delete, and storage_container_list.

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

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

The [WRITE][risk=medium] tag and the '(reversible -> prior)' note tell the agent this is a mutating, undoable operation, which implies usage context. However, it never says when to use this versus storage_container_create/delete or when resizing is inappropriate, so guidance is only 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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=true, so the safety profile is covered. The description adds a risk grading ([risk=medium]) not present in annotations, which is genuine added context, but it says nothing about failure modes, name-uniqueness constraints, or reversibility.

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 write/risk tag is front-loaded and the Args block is dense and scannable with no filler sentences. It is slightly longer than strictly needed because two of the arg notes restate schema defaults.

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 mutating tool with no output schema, the description covers all inputs, the operation's nature, and a risk level, while annotations cover the safety hints. Missing only secondary details such as idempotency behavior or error conditions, which is a minor gap.

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

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

Schema coverage is 0%, so the description carries the full burden, and it documents all five parameters with meaningful semantics: value provenance ('from cluster_list', 'from config'), purpose of vlan_id, and the omit-for-default behavior of target. Defaults for subnet_type and target duplicate the schema, but the provenance and intent notes go beyond it.

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

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

The description states a specific verb and resource ('Create a subnet on a cluster'), which is unambiguous against siblings like subnet_list, subnet_get, and subnet_delete. It does not explicitly name or route away from any sibling, but the verb+resource pairing is clear enough to select it.

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

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

There is no explicit when-to-use or when-not-to-use guidance, but the arg hints imply a prerequisite chain ('cluster_ext_id: Target cluster extId (from cluster_list)'), telling the agent it must resolve a cluster first. That is useful but partial; nothing says when this should be preferred over other subnet operations.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it flags an audit tier ('review'), names the approval env vars (NUTANIX_AUDIT_APPROVED_BY/RATIONALE), explains irreversibility, and details what the audit trail captures (name, description, type, VLAN id, cluster, IP config and pools). This is rich behavioral context an agent needs before a high-risk mutation.

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

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

Front-loaded with [WRITE][risk=high] and the core action, then the preview hint, then audit metadata, then Args. The risk/audit section is slightly verbose but every sentence conveys operational meaning. Overall tight and well-ordered.

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 high-risk destructive tool with no output schema and three zero-coverage params, the description covers the action, preview capability, audit/approval requirements, irreversibility, and all three parameters. It stops short of describing the return shape of dry_run output, but that is a minor gap for a delete 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 0%, so the description must carry parameter meaning. It does: ext_id is explained as 'Subnet extId as returned by subnet_list', dry_run is described as a no-op preview, and target is identified as the Prism Central target name from config with a default-omit rule. This fully compensates for empty 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?

States a specific verb and resource ('Delete a subnet') and immediately adds the destructive nature and preview mechanism. Distinguishes itself from siblings like subnet_list/subnet_get/subnet_create by being the delete operation.

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 says to pass dry_run=True to preview before deleting, which is actionable when-to-use guidance. It does not name alternative tools or state when-not to use, but the preview-before-delete instruction is a clear usage directive.

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

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

Annotations declare readOnlyHint=true, so the safety profile is covered, and the description adds genuinely new context: it surfaces an ETag for downstream writes, which signals optimistic-concurrency usage. It doesn't mention pagination or error behavior, but for a single-item read the disclosure is above average.

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

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

Front-loaded with the [READ] tag and one-line purpose, then a compact args block. The docstring-style formatting is slightly verbose but every line earns its place by documenting a parameter.

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 2-param read with no output schema, the description covers the purpose, both parameters, and the ETag-return contract. It could mention what happens when the ext_id isn't found, but it is complete enough to invoke correctly.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it explains ext_id is the Subnet extId from subnet_list and that target is a Prism Central name from config with a default-omission rule. Both parameters get meaning the bare schema lacks.

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

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

States a specific verb ('get') and resource ('One subnet by extId'), and the '[READ]' prefix distinguishes it from sibling mutators like subnet_create/delete. An agent can immediately tell this is a singular read operation versus subnet_list.

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

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

The description implies the read use-case and explains the ext_id comes from subnet_list ('as returned by subnet_list'), which routes the agent through the list-then-get pattern. It doesn't explicitly state when NOT to use it (e.g., bulk retrieval), but the context is 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 only declare readOnlyHint=true, and the [READ] tag merely restates that. The genuinely additive disclosure is that the result reports `returned`, `limit`, and `truncated` so a capped read is visible — valuable pagination/truncation semantics that the agent cannot get from the annotations or schema. It stops short of describing ordering, scope across clusters, or the full response shape.

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?

One summary line followed by a compact per-parameter block; the core purpose is front-loaded before the Args section. Every sentence earns its place — the field list aids selection and the Args entries resolve the two undocumented parameters.

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

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

For a two-parameter read tool with no output schema, the description covers both parameters and the truncation behavior, which is enough to call it correctly. It is slightly thin on scope (does it span clusters/targets by default?) and on the exact response shape, but 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 0%, so the description must carry both parameters — and it does. `limit` is given a default (500) plus the truncation-reporting behavior, and `target` is explained as a Prism Central target name from config that may be omitted for the default. Both parameters gain meaning beyond their bare integer/string types.

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

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

States a specific verb and resource ('List subnets') and enumerates the returned fields (extId, name, type, VLAN, cluster, IP config), so the agent knows exactly what this returns. The [READ] tag and 'List' verb cleanly distinguish it from subnet_get, subnet_create, and subnet_delete 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?

The description never says when to choose this over subnet_get (single subnet) or the other subnet siblings, nor does it state any prerequisites. The listing scope is self-evident from the name, which is implied usage at best; there is no explicit when-to-use or when-not-to-use guidance.

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

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

The readOnlyHint annotation already covers the safety profile, but the description adds real behavioral context beyond it: the default cap of 500 rows and the fact that the result reports `returned`, `limit`, and `truncated` so truncation is visible. That truncation disclosure is the kind of thing annotations cannot express.

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 one-line summary is front-loaded and the per-arg breakdown is scannable. The Args block is slightly verbose in formatting but every line carries parameter information that the schema lacks.

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 naming the returned fields, and all three parameters are documented. Nothing critical for a correct read-only list call 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 0%, so the description carries the burden and does so for all three params: status with example values (RUNNING/SUCCEEDED/FAILED), limit with its default of 500, and target with the config-name/omit-for-default convention. The status values are only illustrative ("e.g.") rather than exhaustive, which keeps it short of a 5.

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 ("List Prism Central tasks") and even enumerates the returned fields (extId, operation, status, %complete, entity), so an agent knows exactly what this retrieves. No sibling tool covers tasks, so no differentiation is required.

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 [READ] tag and the optional filters imply the usage context, and the target arg explains how to fall back to the default. However, there is no explicit statement of when to reach for this tool versus other listing tools, nor any exclusion guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds real value beyond that: the inverse executes through its own governed tool with its own risk tier and audit row, dry_run previews without executing, and the one-time token constraint explains the non-idempotency. This is meaningful behavioral context, though it doesn't describe failure modes or what the inverse call returns.

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

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

Front-loaded with a risk tag and a one-line summary, followed by an Args block. Sentences are tight and each adds information, though the risk-tier/audit-row sentence is slightly verbose for the value it conveys.

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

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

For a 3-param write tool with no output schema and only basic annotations, the description covers purpose, the dry-run preview path, the one-time constraint, and all parameters. It is nearly complete, missing only what the inverse dispatch returns or how failures surface.

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

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

Schema coverage is 0%, so the description carries the full param burden and does so: undo_id is explained as the token from undo_list, dry_run as a preview switch, and target as a pass-through to the inverse tool when accepted. This compensates well for the empty schema, though target's valid values/format remain unspecified.

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 gives a specific verb+resource ('Apply a recorded undo') and explains the mechanism (dispatching its inverse tool), which distinguishes it from undo_list, which only enumerates tokens. An agent can tell immediately this executes a pending undo rather than listing them.

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 clearly states how to preview safely (dry_run=True) and that a token can only be applied once, plus where the undo_id comes from (undo_list or an _undo_id in a write result). It stops short of explicitly naming when NOT to use it or contrasting against re-issuing the original tool, so it is strong context without full alternative routing.

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

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

Annotations only carry readOnlyHint, so the description does the heavy lifting: it explains the truncated flag is measured via an extra row fetch, and that effectVerified=false means the reversed change is only PROBABLE and needs live-state verification before reporting a restore. That is exactly the kind of non-obvious behavioral disclosure the annotation cannot 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?

Front-loaded with the READ tag and the core action, then structured into entry contents, cautionary semantics, and an Args block. Slightly long — the effectVerified warning is repeated in two clauses — but every sentence carries operational value.

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, yet the description enumerates what each entry contains (original tool, inverse tool, human note) and explains the two salient fields, truncated and effectVerified. An agent has enough to call it and interpret the result 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 0%, so the description must compensate and does: limit is documented with its default (50) and the pagination behavior tied to truncated, and target is explicitly declared unused but accepted for CLI uniformity. With only two optional params, nothing is left ambiguous.

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+resource with scope: lists recorded, not-yet-applied undo tokens, most recent first. The distinction from the sibling undo_apply (which consumes these tokens) is explicit in the very next sentence.

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 a clear usage path ('Use the undoId with undo_apply') and a re-run condition when truncated is true. It does not, however, contrast against near-neighbors like snapshot_list or recovery_point_list, leaving the agent to infer why undo tokens rather than snapshots.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, so the safety profile is covered. The description corroborates with '[WRITE][risk=medium]' but adds nothing about reversibility, expected duration, whether the clone lands as a task, or permission requirements. Adding a risk qualifier is modest value on top of the annotations, not 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?

Four short lines, front-loaded with the operation tag and the one-line purpose, then the arguments. No filler sentences and nothing redundant with the schema.

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

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

For a non-idempotent write with three parameters and no output schema, the description is adequate but leaves gaps: no statement of what the tool returns, whether cloning is asynchronous, or what failure modes exist (name collision, insufficient capacity). The annotation set covers the safety dimension but not the operational one.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents all three parameters: vm_ext_id as the source VM id 'as returned by vm_list', new_name as the clone name, and target as a Prism Central name with a documented default when omitted. This is solid compensation, though it lacks format examples.

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: 'Clone a VM to a new name', with a functional tag '[WRITE][risk=medium]'. It distinguishes itself from vm_create by naming a source VM (vm_ext_id), but it never explicitly contrasts with vm_create or vm_migrate, which are the nearest 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?

There is no when-to-use guidance, no prerequisites (e.g., powered-off state, capacity on target), and no exclusions relative to vm_create/vm_migrate. The only contextual hint is 'omit for the default' for the target parameter, which is parameter-level, not 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false; the [WRITE][risk=medium] tag corroborates rather than contradicts. The description adds that target comes from config, but says nothing about failure modes, required permissions, or whether retries could create duplicates (relevant given idempotentHint=false).

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

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

Front-loads the write/risk tag and the core action, then lists arguments compactly with no filler. Every sentence earns its place and the argument block maps cleanly onto the required vs optional split.

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

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

For a mutation tool with no output schema and destructiveHint=true, the description omits what the call returns (e.g. the new VM's extId needed for follow-up vm_power_on/vm_get) and any warning about the destructive annotation on a create operation. It is adequate to invoke correctly but incomplete for a write tool of this class.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely succeeds: it documents all five parameters, including that cluster_ext_id comes from cluster_list, the socket default of 1, and memory in bytes with a 4 GiB default (consistent with the schema default 4294967296). Only 'name' and the exact form of 'target' are left thin.

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 (Create), resource (VM), scope (minimal, on a cluster), and a risk/write tag. 'Minimal VM' implicitly distinguishes it from vm_clone, but no sibling is named to make the distinction explicit.

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

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

Context is implied: use when you need a bare VM rather than a copy (vm_clone), and cluster_ext_id explicitly points to cluster_list as the source. There is no explicit when-not guidance or statement of prerequisites such as powering the VM on after creation.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotence, so the safety profile is covered. The description adds real value beyond that: audit tier 'review', the NUTANIX_AUDIT_APPROVED_BY / NUTANIX_AUDIT_RATIONALE attribution variables, and the fact that prior name/power state is captured on the audit trail. It stops short of saying whether the delete is reversible or how child resources/snapshots are handled.

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

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

Front-loaded with the risk/write tag, then the core action, then structured Args. The dry_run preview is stated twice (opening line and Args block), which is mild redundancy, but the block is compact and every section is scannable.

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

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

For a 3-parameter destructive tool with no output schema, the description covers risk level, preview mechanism, audit attribution, and all parameters. It omits post-delete side effects (irreversibility, snapshot/protection-domain handling) and any required VM state, which an agent about to destroy a VM would benefit from knowing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: vm_ext_id is tied to vm_list output, dry_run is explained as a preview that returns what WOULD be deleted, and target is described as a Prism Central config name that defaults when omitted. Only formatting details (extId shape, valid target names) are left implicit.

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 ('Delete a VM') and immediately flags it as destructive, which cleanly separates it from siblings like vm_power_off, vm_update, or snapshot_delete. The [WRITE][risk=high] prefix gives an instant operation-class signal.

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 tells the agent to pass dry_run=True to preview first, which is actionable invocation guidance, but never states when this tool is the right choice versus alternatives such as vm_power_off or protection/undo workflows. No prerequisites (e.g., power state, protection domain removal) are mentioned.

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

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

Annotations declare readOnlyHint=true, and the description reinforces that with '[READ].' More importantly, it discloses a behavioral detail beyond annotations: the ETag is surfaced for downstream writes, which is useful context for optimistic concurrency. It doesn't mention auth requirements or rate limits, but for a read operation this is adequate.

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

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

The description is extremely concise: a single sentence for purpose plus two short argument descriptions. It is front-loaded with the core action and scope, with zero 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?

For a simple read tool with no output schema, the description provides enough to call it correctly: it states the required identifier, its source, the optional target, and the ETag behavior. It could go further by explaining when the ETag matters or what happens if the VM doesn't exist, but it is largely complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains that vm_ext_id is the VM extId returned by vm_list, and that target is the Prism Central target name from config, omitting for the default. Both parameters are covered with meaning beyond the schema's bare types.

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

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

The description opens with a specific verb+resource: '[READ] One VM by extId.' This clearly distinguishes it from vm_list (listing) and vm_update/vm_delete (writes). However, it doesn't explicitly name siblings or state what sets it apart beyond the read vs write distinction.

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

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

Usage is implied: fetch one VM by its extId. The description notes 'extId as returned by vm_list,' which suggests a natural workflow (list then get). But it does not state when to prefer vm_get over vm_list or other alternatives, nor does it provide explicit exclusions or conditions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true. Beyond those, the description adds real context: the medium risk level, that the state change is reversible via power-on, and that dry_run runs a self-lockout guard. It does not describe timing or completion semantics, so not a 5.

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

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

Front-loads the [WRITE][risk=medium] tags and the one-line purpose before the Args block, so the critical facts are read first. Slightly terse on argument formatting but 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?

With no output schema and 3 fully documented parameters, the description supplies what an agent needs to select and invoke the tool correctly, including reversibility. The only gap is the absence of any comparison with the adjacent power/rebooot tools.

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

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

Schema description coverage is 0%, yet the description documents all three parameters: vm_ext_id ('as returned by vm_list'), dry_run (preview behavior and guard), and target ('Prism Central target name from config; omit for the default'). This fully compensates for the empty schema and adds meaning the agent could not otherwise infer.

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+resource ('Graceful in-guest shutdown'), and the qualifier 'in-guest' plus 'graceful' clearly separates it from the sibling vm_power_off (hard power off) without needing to open either schema. An agent can identify the operation and its mechanism 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?

The description explains the dry_run preview and the self-lockout guard, which is invocation guidance, but never states when to choose this over vm_power_off, vm_reboot, or vm_power_on, nor any exclusions. Usage is implied by 'graceful' rather than explicitly routed.

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 cover readOnlyHint=true; the description adds substantial behavioral context beyond that — reads hit separate AHV/ESXi endpoints, a failed ESXi read still returns AHV rows with esxiError set and truncated: null (completeness unknown). This false-negative warning is exactly the kind of trait structured fields cannot 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?

Front-loaded with the [READ] tag and one-line summary, then a dedicated Args block. The middle paragraph on partial reads is slightly dense but earns its place as operational guidance; overall tight with minimal waste.

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

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

No output schema exists, yet the description names the key return fields (hypervisor, esxiError, truncated, returned, limit) and the degraded-mode semantics. For a 3-param, zero-required read tool, nothing an agent needs to call or interpret 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 0%, so the description must carry all three parameters — and it does: include_esxi (default True, scope), limit (default 500, cap), target (config name, omit for default). It further explains the returned/limit/truncated reporting that makes a capped read visible.

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 ('[READ] List VMs') and immediately sharpens scope: AHV plus (by default) ESXi-backed, with the hypervisor field distinguishing them. This is clearly separable from siblings like vm_get (single VM) and vm_create/vm_delete (mutations).

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?

Clear context for use: a bulk read that spans both AHV and ESXi endpoints, with explicit guidance that an ESXi read failure yields a partial list rather than 'no ESXi VMs'. It does not name alternatives (e.g. when to use vm_get instead) or state exclusions, so it stops short of a 5.

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

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

Goes beyond the annotations by disclosing live migration, reversibility back to the prior host, risk=high audit tier 'review', and optional approval/rationale env vars. It doesn't state what happens on failure or partial migration, but the risk and audit context is richer than the raw hints.

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

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

Front-loads the [WRITE][risk=high] tags and one-line purpose, then a compact Args block. Efficient overall, though the audit/approval sentence is slightly run-on and the tag prefixes duplicate the annotation hints.

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 mutating tool with no output schema, it covers risk, reversibility, preview, and every parameter. Only failure semantics and post-migration state are unaddressed, which is a minor gap given how much is otherwise specified.

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?

Despite 0% schema description coverage, the description documents all four params and their provenance (vm_ext_id from vm_list, target_host_ext_id from host_list, dry_run preview behavior, target config default). This meaningfully compensates for the empty schema, though formats are still terse.

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 (live-migrate a VM) plus the destination (another host), which cleanly distinguishes it from sibling write operations like vm_clone, vm_protect, and vm_power_on. An agent can identify the operation without opening 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?

Implies usage context ('Live-migrate', use dry_run=True to preview) but never states when to choose this over alternatives such as vm_protect or cluster-level rebalancing, nor any prerequisites for the source/target hosts. The dry_run preview hint is the only 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 declare destructiveHint=true and idempotentHint=false, and the description adds real value beyond them: the [WRITE][risk=medium] tag, the reversibility note (power-on can restore state), and the fact that dry_run exercises a 'self-lockout guard'. It does not say whether the call blocks until the VM is off, which is the main remaining gap.

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?

Extremely tight and front-loaded: risk tag, one-line purpose with reversibility, then a three-item Args block. No sentence is filler and the critical safety tag leads.

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 medium-risk write with no output schema and zero schema coverage, the description covers purpose, all parameters, risk level, reversibility, and the dry-run guard. It omits whether the operation blocks/returns a task id and any permission requirements, which would matter for a mutating VM call.

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

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

Schema coverage is 0%, so the description carries the full burden and does document all three parameters. It adds meaning beyond the bare schema: vm_ext_id points to the sibling that produces it (vm_list), dry_run explains the preview and the guard it triggers, and target explains the config lookup and the omit-for-default behavior.

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+resource ('Hard power off a VM') and the 'Hard' qualifier implicitly separates it from the graceful vm_guest_shutdown sibling. It also notes reversibility ('→ power-on'). However, it never names the alternative tool, so an agent must infer the graceful-vs-hard distinction rather than being told.

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

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

Usage is only implied by the 'Hard' qualifier and the risk tag; there is no explicit guidance on when to prefer this over vm_guest_shutdown or vm_reboot, nor any stated preconditions. dry_run gives a preview path, which is useful but not a when-to-use rule.

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

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

Annotations already declare write/destructive/idempotency profile, yet the description adds real value beyond them: risk=medium, the reversibility path (power-off), and 'Auto-handles ETag' (meaning concurrent-update conflicts are handled internally). It still doesn't say whether repeated calls are safe, which matters given idempotentHint=false.

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

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

Front-loaded tag block plus a compact args list; every line earns its place. The parenthetical could be tightened, but nothing is wasted.

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

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

For a 3-param mutation with annotations and no output schema, the description covers purpose, reversibility, dry-run behavior, and every parameter's meaning. Return-value shape is the only omission, and that is minor for this tool class.

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

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

Schema coverage is 0%, so the description carries the burden and does so: vm_ext_id is tied to its source ('as returned by vm_list'), dry_run is explained with its exact semantics ('return what WOULD be powered on'), and target is explained as a config-sourced Prism Central name with a default. Only slight gap is no format example for extId.

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+resource ('Power on a VM') and immediately scopes it against its inverse ('reversible → power-off'), which disambiguates it from the sibling vm_power_off. The [WRITE][risk=medium] tag further pins the operation class.

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

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

Usage context is implied by the reversibility note and the dry_run argument, but there is no explicit guidance on when to prefer this over alternatives or any preconditions (e.g. VM must be powered off first). Adequate but inferential.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false. The description adds the non-structured "risk=medium" severity tag, which is genuinely useful context. But it does not explain the destructive aspect of an operation that superficially reads as additive association, nor whether re-associating overwrites existing policy membership.

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

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

Front-loaded with the operation tag and a one-line purpose, followed by a compact Args block. Every line contributes; the Python-docstring formatting is slightly ceremonial but not wasteful.

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-prone mutation tool with no output schema, the description covers purpose and all params but is silent on consequences: whether existing policy associations are replaced, whether the action is reversible, and what a successful call returns or triggers. Adequate but incomplete for a write operation.

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

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

With 0% schema description coverage, the description carries the full burden, and it documents all three parameters: vm_ext_id (sourced from vm_list), policy_ext_id (from protection_domain_list), and target (PC target name from config, omit for default). The sourcing provenance and the default-omission rule add real meaning beyond the bare schema.

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

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

States a specific verb and resource: "Associate a VM with a protection policy." This is clearly distinguishable from sibling write operations like snapshot_create, pd_failover, and vm_clone. The [WRITE][risk=medium] prefix further signals the operation class.

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

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

The description implies usage by pointing to prerequisites ("as returned by vm_list", "as returned by protection_domain_list"), which helps the agent source valid extIds. However, it never states when to use vm_protect versus alternatives like pd_failover or snapshot_create, nor any exclusions or preconditions.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=false, and the description reinforces this with '[WRITE][risk=medium]' and 'no distinct inverse' (i.e., no undo path). The dry_run behavior adds real operational context beyond the annotations, though it stops short of stating permission requirements or expected duration.

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

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

Front-loaded with the WRITE/risk tag and the core action, then an Args block that is efficient and earns its lines. Minor redundancy between the risk tag and the annotations, but no 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 3-param mutation tool with no output schema, the description covers the destructive nature, irreversibility, parameter sourcing, and dry-run preview. It lacks only a note on what a successful response looks like and any permission/auth requirements.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: vm_ext_id is tied to vm_list's output, dry_run is explained as a preview mode, and target is described as a Prism Central name with a default. target's description is terse but sufficient.

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

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

States a specific verb+resource ('Reboot a VM') and immediately distinguishes itself from the power-state siblings (vm_power_on, vm_power_off, vm_guest_shutdown) by naming the distinct operation. An agent can identify this tool's role without opening 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?

Usage is implied by the verb, but the description never says when to prefer reboot over vm_guest_shutdown or vm_power_off/on, nor does it list prerequisites. The 'no distinct inverse' note hints at irreversibility but is not 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/disruptive nature is covered structurally. The description adds real value beyond that: risk=medium and, critically, 'reversible → prior values', which tells the agent that a rollback path exists (consistent with the undo_list/undo_apply siblings). It stops short of saying whether the resize is disruptive to the running guest.

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

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

Front-loaded tag, then a one-line purpose with the reversibility caveat, then a compact Args list. No sentence is redundant; each parameter line adds information the schema lacks.

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 must cover the rest, and it does cover inputs and reversibility. It omits operational prerequisites that matter for a medium-risk resize: required VM power state, whether the guest is disrupted or rebooted, and whether reducing below current usage is rejected.

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

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

Schema description coverage is 0% and the schema provides only titles, so the description carries the full burden — and it does: vm_ext_id is tied to vm_list output, num_sockets and memory_bytes are defined with units and default-to-unchanged semantics, and target is explained as a config-sourced Prism Central name with a default fallback.

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+resource+scope: 'Resize a VM's CPU sockets / memory'. This is immediately distinguishable from siblings like vm_create, vm_clone, vm_migrate, and the vm_power_* family, all of which touch VMs but do something else.

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

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

Usage is implied by the write tag and the mutation semantics, and the 'omit to leave unchanged' notes give per-parameter behavior. However, it never states when to choose this over vm_create/vm_clone for capacity changes, nor any prerequisite such as required power state or permissions.

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