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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description reinforces this with a [READ] tag. It adds the important caveat that it 'Only reports vCenter-level support — a listed cluster may still be CONFIGURING,' which is exactly the behavioral nuance an agent needs. No contradictions.

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

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

The description is compact and front-loaded: the [READ] tag, purpose, and prerequisite appear first, followed by return values and downstream usage. Every sentence adds information without redundancy.

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

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

With no output schema, the description compensates by naming return fields and their types (bool, string, cluster/status objects). It also explains how to use the output as cluster_id for two sibling tools and warns about the CONFIGURING state. This is complete for an optional-parameter read-only check, though exact status values are left unspecified.

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

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

Schema coverage is 100% with the target parameter fully documented ('vCenter in config.yaml; omit for default'), so the description does not need to add parameter-level detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description uses a specific verb and resource ('Check whether this vCenter supports VKS'), states a hard prerequisite (vSphere 8.x+), and lists concrete return fields, distinguishing this read-only compatibility probe from the other vSphere/TKC tools.

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

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

It explicitly says 'Start here' and maps the returned cluster MoRefs to cluster_id for get_supervisor_status and create_namespace, giving immediate downstream routing. It also warns that vCenter-level support does not guarantee cluster readiness, signaling when to follow up. It does not enumerate all when-not-to-use cases, but the guidance is concrete.

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 goes far beyond the annotations by explaining the preview-only default, the exact return shape for confirm=True, refusal conditions, and the required confirmation workflow. This is especially valuable because the annotations only indicate readOnly=false and idempotent=false; the description reveals the nuanced two-phase behavior.

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

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

Every sentence earns its place. The description is front-loaded with the core purpose, then efficiently covers preview behavior, user decision, refusal conditions, and follow-up verification. It is detailed but not bloated, and the structure guides the agent through the correct call sequence.

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

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

For a 9-parameter creation tool with no output schema, the description is remarkably complete. It explains the preview return, the confirmed return, failure modes, and post-creation verification. It also refers agents to the right sibling tools for name conflicts and verification, leaving no critical ambiguity for correct invocation.

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

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

Schema coverage is already 100%, but the description adds meaningful parameter-level context by explaining what confirm actually controls, what blast_radius contains, and why the agent should not set confirm=True unilaterally. It doesn't repeat every parameter, but it clarifies the most behaviorally important one beyond the schema.

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

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

The description opens with a specific verb and resource: 'Create a vSphere Namespace on a Supervisor Cluster.' It clearly distinguishes this creation tool from sibling operations like update_namespace, delete_namespace, and get_namespace, and the [WRITE] tag reinforces that this is a mutating 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?

The description provides explicit usage rules: without confirm=True it only previews, the user must see the preview before confirming, and the agent must not set confirm=True on its own. It also names alternatives directly: use update_namespace when the name is taken, and verify with get_namespace afterwards.

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?

Even with annotations present, the description adds critical behavioral context: without confirm=True the tool only previews and changes nothing; confirm=True provisions in the background and returns {action: 'created', status: 'creating'}, requiring polling of get_tkc_cluster until running. It also discloses refusal behavior when the name is taken or namespace clusters cannot be read. This goes well beyond the annotation signals.

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

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

The description is dense but every sentence earns its place: it covers purpose, preview semantics, user-approval requirement, confirmation behavior, polling, refusal conditions, and prerequisites. The critical safety warning is front-loaded early. The length is justified by the complexity and the severe consequence of an unconfirmed create.

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

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

Given the tool's complexity, the description is comprehensive: it explains return values for both modes, background provisioning, polling expectations, refusal cases, and required setup calls. The input schema covers parameter defaults and types, while the description covers the behavioral contract. Nothing essential for safe 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 100%, so the baseline is 3. The description adds meaning beyond the schema by linking k8s_version and vm_class to prerequisite calls (get_tkc_available_versions and list_vm_classes), and by clarifying the behavioral significance of confirm. It does not restate the schema, but it enriches the most safety-critical parameter without covering every field.

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

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

The description opens with a clear [WRITE] marker and explicitly states the action: 'Create a TanzuKubernetesCluster in a vSphere Namespace.' This distinguishes it from sibling tools that scale, upgrade, delete, or list clusters. The purpose is immediately unambiguous and the tool's resource is precisely named.

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

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

The description gives strong operational guidance: it explains the preview-then-confirm flow, warns 'Do not set confirm=True on your own because the user asked earlier', and instructs the agent to show the preview to the user first. It also states prerequisites ('Call get_tkc_available_versions for k8s_version and list_vm_classes first') and refusal conditions. This is explicit when-and-how-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?

Beyond the destructiveHint annotation, the description discloses irreversible destruction, preview-only behavior, refusal conditions when inner resources cannot be read, and the returned blast_radius structure. The behavior is fully transparent.

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

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

The description is dense but every sentence earns its place, covering purpose, safety, refusal conditions, return shape, and alternatives. The critical warning is front-loaded and clearly separated from supporting details.

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

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

For a destructive, irreversible tool with no output schema, the description covers the action, the preview mechanism, the return values, the blocking conditions, and the recommended sibling tool. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds operational semantics: confirm=False previews, confirm=True returns {action: 'deleted', namespace, status, blast_radius}, and deprecated aliases are clarified in context. This goes beyond the schema field descriptions.

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

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

Description clearly states a specific verb and resource: 'Delete a vSphere Namespace and everything inside it (irreversible).' It distinguishes itself from siblings by warning it refuses while TKC clusters exist and by directing users to update_namespace for quota-only changes.

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

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

Provides explicit when-to-use and when-not-to-use guidance: preview with confirm=False, show blast_radius to the user, never set confirm=True autonomously, run delete_tkc_cluster on existing TKC clusters first, and prefer update_namespace for quota changes. This is unusually complete.

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, the description reveals the irreversible nature, the preview mode returning blast_radius, the refusal conditions while workloads run, and the force flag's effect of skipping the workload check. It also states what confirm=True returns, giving the agent a clear model of the tool's behavior.

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

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

The description is long but every sentence carries essential safety or routing information for a destructive tool with no output schema. It is front-loaded with the irreversible destructive action, then explains the preview flow, refusal conditions, and alternatives in a logical order with no redundancy.

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

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

Since there is no output schema, the description properly explains return values for both preview and confirmed deletion, including blast_radius contents. It also covers failure/refusal cases, the force escape hatch, deprecated aliases, and sibling-tool routing, making it complete for an agent to call this tool correctly.

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

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

The schema already covers all parameters with 100% description coverage, but the tool description adds important context beyond it: confirm=False previews, confirm=True deletes, force=True skips the workload check, and dry_run/confirmed are deprecated aliases. This adds real semantic value on top of the schema.

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

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

The description states a specific verb and resource: 'Delete a TKC cluster and all of its nodes (irreversible).' It clearly differentiates from siblings by explicitly directing agents to scale_tkc_cluster for fewer nodes and noting delete_namespace requires an empty namespace. This gives an unambiguous purpose.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it instructs the agent to preview without confirm=True, never set confirm=True unilaterally, and drain workloads or use force=True only when appropriate. It also names scale_tkc_cluster and delete_namespace as alternatives, so the agent can route correctly.

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?

Although annotations already declare readOnlyHint/idempotent/non-destructive, the description adds substantial behavioral context they cannot: it needs only System.View, checks privileges on the root folder only, explains that not_granted_at_root is not the same as no access, that undetermined means vCenter did not answer, that Kubernetes calls (TKC, VM Service, kubeconfigs) cannot be checked and report undetermined, and that namespace writes need Namespaces.Configure. This is exactly the value-add the dimension rewards.

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?

It is longer than average but front-loaded with a [READ] tag and the core purpose, and every clause carries load — the Gotchas block encodes non-obvious failure interpretations rather than filler. Slight density could be trimmed, 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, the description compensates by describing the return shape (target, account, privilege states, per-tool requires/verdict/meaning, or all tools grouped by verdict) plus the caveats that would otherwise mislead an agent interpreting results. Complete for this tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning about parameter effect: with 'tool' it returns requires/verdict/meaning for that one tool; without it, every tool grouped by verdict. That behavioral differentiation of the optional parameter goes beyond the schema text.

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 statement of what it returns — the account the server uses and whether it holds each tool's vSphere privileges. No sibling tool (get_harbor_info, get_supervisor_status, the namespace/TKC CRUD tools) does permission introspection, so it is immediately distinguishable.

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

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

It gives explicit triggering conditions: 'when a tool fails with a permission error, or before a write, to check what the configured account may do.' That is clear when-to-use guidance. It stops short of a full when-not/alternative framing, but there is no competing sibling to route away from, so the gap is minor.

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, openWorldHint, idempotentHint, and destructiveHint=false, and the description layers substantial context on top: the exact return shape ({registries: [...]}), the detail-call behavior ('status and storage come from a detail call and are null if it fails'), and the error contract ('returns {error, hint} rather than raising'). No contradiction exists — the readOnly annotation matches the [READ] prefix and status-retrieval semantics.

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

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

Every sentence carries distinct information: purpose, return shape, two error behaviors, use cases, and the prerequisite. The critical 'what it does' is front-loaded in the first sentence, and the supplementary detail is compact and scannable without wasted words.

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

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

With no output schema present, the description carries the full burden of explaining return values — and it does, including nullable fields (status, storage_used_mb) and the failure path. Error cases (Harbor not enabled, detail call failing) and the prerequisite for a possibly-down Supervisor are all covered, making this complete for a read-only tool with one optional parameter.

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

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

The single optional parameter `target` is fully documented in the schema ('vCenter in config.yaml; omit for the default.'), so schema coverage is 100% and the baseline 3 applies. The description adds no new parameter-level detail beyond the 'on the Supervisor' context, which is acceptable because nothing about the parameter is left undocumented.

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+scope: 'Get status of the embedded Harbor container registry on the Supervisor.' The [READ] prefix makes the operation type explicit, and the sentence 'it does not list repositories or images' differentiates it from any registry-related sibling. The primary use cases ('check registry health or find the push URL') further pin down what the tool is for.

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 concrete when-to-use: 'Use it to check registry health or find the push URL.' It names the prerequisite sibling explicitly — 'Run check_vks_compatibility first if the Supervisor may be down' — and excludes the adjacent use case of listing repositories or images. This gives an agent clear routing logic without needing to inspect other sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond those hints: it returns a raw vCenter object rather than a list envelope, and warns that a CONFIGURING namespace may not yet have quotas applied. This helps the agent interpret results correctly.

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

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

The description is dense but well-organized: a clear opening statement, the return shape, routing guidance to related tools, and a caveat. Each sentence earns its place and no filler is present.

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

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

Even though there is no output schema, the description names the key returned fields (config_status, description, storage_specs, quotas) and explains how to discover the required name parameter. It also points to the correct sibling tools for follow-up queries, making it sufficiently complete for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description reinforces that 'name' comes from list_namespaces, matching the schema's example, but does not add additional parameter-level meaning beyond what the 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?

The description states a specific verb and resource: 'Get detailed configuration for a single vSphere Namespace.' It also distinguishes itself from sibling tools by explicitly saying it returns 'one raw vCenter namespace object, not the list envelope,' which differentiates it from list_namespaces and related listing tools.

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

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

The description gives explicit usage sequencing: use list_namespaces first to discover the name, then call this tool; follow with list_namespace_storage_usage for PVC usage or list_tkc_clusters for clusters inside. It also provides a point-in-time caveat that helps the agent know when the result may be incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description goes beyond annotations by disclosing the exact returned fields, including config_status semantics (RUNNING = healthy, else CONFIGURING / ERROR / REMOVING) and kubernetes_status values. This is useful behavioral context for interpreting the response.

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

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

The description is front-loaded with purpose, followed by a compact list of returned fields and a single workflow sentence. Every sentence contributes useful information; there is no repetition of schema content or filler.

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

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

Without an output schema, the description enumerates the key return fields and their meaning, states prerequisites, and names the dependent operations. For a simple read-only health-check tool with only one required parameter, 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 coverage is 100%, so the baseline applies. The description adds one contextual link for cluster_id by pointing to check_vks_compatibility as the source of cluster IDs, matching the schema's 'wcp_clusters field' note, but it does not need to explain target further.

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

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

The description opens with a specific verb and resource: '[READ] Get the health of one Supervisor Cluster (vSphere with Tanzu control plane).' It clearly identifies the tool's output (health status fields) and names the workflow context, which distinguishes it from sibling tools like check_vks_compatibility and get_supervisor_kubeconfig.

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

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

It gives explicit sequencing: 'Run check_vks_compatibility first for cluster IDs; use this to confirm a Supervisor is healthy before create_namespace or create_tkc_cluster.' This tells an agent when to call this tool relative to relevant siblings and what decision it supports.

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 idempotentHint=true. The description adds meaningful behavioral context: it returns results newest first, and it degrades gracefully with an empty versions list plus error/hint when the API is unavailable rather than raising. This goes beyond what the annotations convey.

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

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

Three terse, purposeful sentences: the READ action, the return shape and ordering, and the error behavior plus usage guidance. Every sentence contributes value and the most important information is front-loaded.

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

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

Even with no output schema, the description supplies the return shape, example version format, ordering, error behavior, and the exact workflow context. An agent has enough information to call this tool correctly and interpret the result.

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

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

Schema coverage is 100% and both parameters (target, namespace) already have descriptions in the schema. The tool description does not add deeper parameter semantics, but a baseline of 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description states a specific verb ('List') and resource ('Kubernetes versions / TanzuKubernetesReleases available on the Supervisor'). It clearly differentiates this read-only query from the cluster lifecycle siblings (create_tkc_cluster, upgrade_tkc_cluster) by framing it as a prerequisite for choosing a valid k8s_version.

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

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

It explicitly advises calling this before create_tkc_cluster or upgrade_tkc_cluster to pick a valid k8s_version, giving clear contextual placement. It does not explicitly list when not to use it or compare against sibling query tools, but the intended usage is unmistakable.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail: it returns a single object with a defined field set, confirms it is not the list envelope, explains the namespace-uniqueness constraint, and positions it as a polling mechanism for async operations. This goes well beyond what the annotations alone provide.

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

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

The description is compact and efficient: [READ] tag, one-sentence purpose, field list, then two pieces of workflow guidance. Every sentence earns its place, and the most important information is front-loaded. No fluff or repetition.

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

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

For a single-object getter with no output schema, the description covers the full picture: purpose, return shape, key fields, namespace scoping, and when to call it. The input schema covers the parameters, and annotations cover safety. No obvious gap would leave an agent uncertain about how to invoke or interpret the tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds useful contextual emphasis about looking up names via list_tkc_clusters and names being namespace-scoped, but it does not add significant new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

Description begins with a clear verb and resource: 'Get detailed status for a single TKC cluster.' It explicitly differentiates from list_tkc_clusters by stating it returns one object, not the list envelope, and lists the returned fields. This leaves 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?

Provides explicit workflow guidance: run list_tkc_clusters first because a TKC name is unique only within a namespace, and poll this tool after create/scale/upgrade operations to observe async changes. It clearly states context, though it does not explicitly describe when to choose an alternative tool beyond the implied list-vs-single distinction.

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

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

Goes well beyond the annotations: discloses that the kubeconfig embeds a Supervisor bearer token acting as the configured vCenter account, that the JWT expires after hours independent of the process, and that the written file is created owner-only (0600). Annotations only say write/idempotent/non-destructive; the sensitive-credential and permission semantics come entirely from the description.

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] marker and the core action, then proceeds in a tight sequence: usage constraint, return shapes, token semantics, permission mode, alternative tool. Dense and mostly waste-free, though the token-lifetime parenthetical 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?

Despite having no output schema, the description fully specifies both possible return payloads ({namespace, kubeconfig} vs {namespace, written_to}) and the credential lifetime, so an agent can handle the result safely. Nothing material is missing for a single-resource credential-issuing tool.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds operational meaning beyond the schema: it prescribes always passing output_path to keep the token out of agent context and explains the two return shapes that follow from that choice. It does not add anything for `target` beyond the schema text.

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 ('issue a kubeconfig for the Supervisor K8s API') and immediately distinguishes itself from the near-namesake sibling by naming issue_tkc_kubeconfig and the cluster scope it targets. An agent can route correctly without opening either 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?

Explicit when-to-use ('Call only when the user explicitly asks for this kubeconfig'), explicit when-not ('never as a side step'), and an explicit alternative ('Use issue_tkc_kubeconfig instead to reach workloads inside a TKC cluster'). All three conditions an agent needs are stated.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true): it discloses the embedded Supervisor JWT bearer token and its expiry, recommends output_path to keep the token out of agent context, and warns that output_path creates parent dirs and truncates the file at 0600 (e.g. '~/.kube/config' clobbers the user's kubeconfig). One mild tension worth noting: it describes a file overwrite while destructiveHint=false, but the description explicitly scopes that claim ('Nothing in the managed cluster changes') and its disclosure makes the risk visible rather than hiding it, so this is added safety context, not a 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 [WRITE] credential-access label and the core action in the first line, and the routing/alternative guidance is in the final line. Dense parentheticals and em-dash clauses make it heavy to scan, but essentially every sentence carries unique, load-bearing 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 states the return shape both ways ({cluster, kubeconfig} vs {cluster, written_to}), documents the credential's lifetime, the safety-relevant side effects, and the required sequencing. An agent has everything needed to call this correctly and handle the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value beyond the schema for output_path (creates parent directories, truncates the target, writes owner-only 0600, and the strong 'always pass output_path' recommendation) and states the return-shape difference between providing and omitting it. 'target' is left entirely to the schema, so it is not a full 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?

Specific verb+resource+scope: 'issue a kubeconfig for one TKC cluster', tagged [WRITE] and 'Credential access'. It explicitly distinguishes itself from the closest sibling by naming issue_supervisor_kubeconfig as the Supervisor-level alternative, so an agent can route without opening either 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 an explicit when ('only when the user explicitly asks') and when-not ('never as a side step'), names the prerequisite ('Run list_tkc_clusters first for name and namespace'), and names the alternative for the adjacent use case. Nothing is left to inference.

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

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

The description discloses the response envelope, item shape, status semantics, and pagination behavior ('one call returns them all, so truncated is always false'). This adds substantial value beyond the annotations, which already declare read-only, idempotent, non-destructive behavior.

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

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

The description is compact and front-loaded with the core purpose and [READ] marker. Every sentence carries useful information: what is listed, what the return envelope contains, and how to proceed through sibling tools. No filler or repetition.

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

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

For a simple list tool with one optional parameter, this is complete. The description covers the response format, status values, pagination behavior, and provides navigation to relevant sibling tools, so an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the single optional target parameter is already well documented in the schema. The description does not add further parameter details, but no compensation is needed given the high schema coverage.

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

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

The description names a specific verb and resource: 'List all vSphere Namespaces on the target vCenter with their status.' It also distinguishes itself from related siblings like get_namespace and list_tkc_clusters by noting that it returns the full set of namespaces and is the intended entry point.

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

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

Explicit guidance is provided: 'Start here, then call get_namespace for detail, list_tkc_clusters for what runs inside, or update_namespace / delete_namespace to change one.' This tells an agent exactly when to use this tool and what to use next based on intent.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: it names the API path ('Via the Supervisor K8s API'), documents the full return envelope, explains that truncated is always False, and warns about deprecated aliases removed in 2.0.

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

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

The description is dense but well-organized: purpose, return shape, behavioral guarantee, prerequisite, and deprecation note. Nothing is filler, and the most important information is front-loaded.

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

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

Despite having no output schema, the description fully specifies the return envelope and field semantics. It also covers prerequisites, the alternative tool, the optional target parameter, and backward-compatibility caveats, making the tool safely callable by an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by emphasizing the namespace scope and telling the agent to run list_namespaces first to obtain a valid namespace value. It does not add much about the target parameter, but the schema already handles that fully.

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

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

The description opens with a specific verb and resource — 'List PersistentVolumeClaims and storage usage' — and scopes it to 'one vSphere Namespace'. It also distinguishes itself from the sibling tool list_supervisor_storage_policies by explicitly noting the PVC-level vs policy-level difference.

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

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

The description gives explicit routing guidance: 'Run list_namespaces first for the namespace' and 'use list_supervisor_storage_policies instead for policy-level rather than PVC-level information.' This clearly tells the agent when to use this tool versus the relevant sibling.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond annotations by specifying the return envelope (items of policy/name/description plus returned/total/truncated) and guaranteeing one call returns all results with truncated always false. This is useful behavioral context not present in the schema or annotations.

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

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

The description is well-structured: it leads with purpose, then return envelope details, then usage guidance and alternative. Every sentence carries useful information, and nothing is redundant with the schema or annotations.

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

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

The return format, pagination behavior, and usage pattern are all explained. With such a simple input schema and rich annotations, this is a complete context for agents.

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

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

Schema coverage is 100%: the only parameter 'target' is fully described in the input schema ('vCenter in config.yaml; omit for the default.'). The description does not add parameter-level detail, but with full schema coverage, baseline 3 is appropriate.

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

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

The opening phrase states the exact verb and resource with a clear scope, and the final line explicitly contrasts with the sibling tool list_namespace_storage_usage, so an agent can differentiate them immediately.

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

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

It explicitly says 'Call this before create_namespace or update_namespace and pass the policy ID as their storage_policy.' It also gives an exclusion: 'For PVC-level usage use list_namespace_storage_usage instead.' This is direct when-to-use and alternative routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the returned envelope shape, that the Supervisor list is walked to completion so 'truncated is always False', and the deprecation of the 'clusters' alias. It does not mention auth or rate-limit needs, 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 [READ] tag and purpose, then envelope details, then the navigation hint. Well-ordered and largely tight, though the envelope field enumeration is somewhat dense for a description.

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

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

No output schema exists, so explaining the return envelope (items, returned, limit, total, truncated, hint) is valuable and done. Deprecation guidance is included. An agent has enough to call this correctly, though pagination/auth specifics 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 100%, so both parameters (target, namespace) are already documented, making 3 the baseline. The description reinforces namespace scoping ('optionally in one namespace') but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('List TanzuKubernetesCluster (TKC) clusters') and adds the scope qualifier ('optionally in one namespace'). Clearly distinguishable from siblings like get_tkc_cluster (detail) and list_namespaces (different 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?

Explicitly routes the agent: 'Start here, then call get_tkc_cluster for full detail or issue_tkc_kubeconfig for access.' This names both alternatives and the condition that selects each, leaving nothing to inference.

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

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

Annotations already mark this as read-only and safe, and the description adds meaningful behavior beyond that: it explains the exact list envelope shape, confirms that one call returns all results and truncated is always false, and discloses the resource-reservation distinction between class prefixes. No contradiction with annotations exists.

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

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

The description is front-loaded with the tool's core purpose and contains no filler. Every sentence contributes: what it lists, what the response contains, why the list is complete, how to use the result, and the meaningful class-prefix distinction. It is compact despite carrying substantial 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 simple read-only list tool with no output schema, the description fully compensates by specifying the envelope structure, item fields, pagination behavior, and downstream usage. It gives an agent everything needed to invoke the tool and interpret its 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?

The only parameter, target, is fully documented in the schema with 100% coverage, and the description does not add new meaning about it. The description's guidance about the returned id being used as vm_class is useful for output consumption, but it does not deepen understanding of the target parameter itself, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List VM classes available for sizing TKC cluster nodes.' It clearly identifies what the tool returns and connects it to a concrete use case. It also distinguishes itself from sibling operations like create_tkc_cluster by framing the call as a prerequisite.

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

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

It explicitly instructs when to use this tool: 'Call this before create_tkc_cluster and pass the chosen id as its vm_class.' It also provides decision-relevant semantics by explaining that 'guaranteed-*' classes reserve resources while 'best-effort-*' do not, which helps an agent choose the appropriate class.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial context: runtime CRD version discovery, the returned envelope structure including items, boot_order, member_count, returned/total/truncated, served_version, and a teaching error for older Supervisors. This is rich behavioral disclosure beyond the annotations.

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

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

The description is front-loaded with the core purpose and then layers technical and return-value details efficiently. It is dense but each sentence contributes context, though the length is on the higher side for a list 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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly with envelope fields, truncation semantics, and version discovery. It also covers the error behavior for older Supervisors, making it complete for an agent to invoke and interpret results.

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

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

Schema description coverage is 100%, and the schema already documents both the target and namespace parameters. The description adds no additional syntax, format, or constraints for those parameters, so the baseline 3 is appropriate.

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

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

States a specific verb ('List') and resource ('VirtualMachineGroup objects and their bootOrder') with scope ('in a Namespace'). The resource and CRD identification make it clearly distinguishable from sibling list tools such as list_namespaces or list_vm_service_snapshots without needing to open 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?

The description gives no explicit when-to-use guidance, prerequisites, or alternatives among sibling tools. Usage is only implied by the tool name and purpose statement; it does not say when to prefer this over list_namespaces or other list tools.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the bar is lower, and the description still adds real value: the CRD served version is discovered at runtime, a VM without a network block returns an empty list rather than an error, and the return envelope is described. It omits pagination/truncation semantics despite mentioning a truncated flag.

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 core action, then a compact paragraph on mechanism and return shape. The return-envelope enumeration is slightly dense but earns its place given there is no output 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, the description compensates by naming the returned fields (name, network_name, network_kind, network_api_version) plus returned/total/truncated and vm_name/served_version, and it clarifies the empty-list edge case. An agent has everything needed to call and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents target, vm_name, and namespace. The description reinforces the provenance of namespace (via list_namespaces) and vm_name (own inventory) but adds no format or syntax detail beyond the schema, which is the baseline-3 case.

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 the network interfaces (multi-NIC) of one VirtualMachine') and bounds the scope to a single VM. No sibling tool lists NICs, so an agent can select it unambiguously from the surrounding list_* family.

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 concrete routing: run list_namespaces to obtain the namespace and take the VM name from the caller's own inventory in that namespace. It stops short of naming when-not-to-use conditions or an alternative tool, so it is clear context rather than 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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuine context beyond that: runtime CRD version discovery, the specific error when the Supervisor predates v1alpha5, and the truncation semantics (walked to completion, so truncated is always false). It stops short of stating auth/permission needs, keeping it at 4.

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 [READ] marker and the core purpose, then detail; every sentence carries information. The dense parenthetical clauses (CRD version, envelope fields) are useful but slightly heavy, so not a 5.

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 spelling out the return envelope (items shape plus returned/total/truncated/served_version) and the error path for old Supervisors, and it covers the prerequisite and sibling routing. Nothing an agent needs to invoke this 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 description coverage is 100%, so both parameters are already documented (namespace 'via list_namespaces', target defaulting to config.yaml). The description only restates the namespace source and adds nothing about the target parameter, so the baseline 3 is appropriate.

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

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

States a specific verb (list) and resource (VirtualMachineSnapshot objects) with explicit scope (a vSphere Namespace), plus the CRD origin (vmoperator.vmware.com, v1alpha5). It names the sibling it is not (list_vm_service_network_interfaces), so an agent can distinguish it without opening a 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?

Explicitly routes the agent: 'Run list_namespaces first for the namespace' gives the prerequisite, and 'use list_vm_service_network_interfaces for a VM's NICs' names the alternative and the condition that selects it. No inference required.

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=false, and idempotentHint=false. The description adds valuable behavioral context: the operation is asynchronous, returns a scaling status immediately, and lowering worker_count drains removed nodes. It also clarifies that other pools are always preserved, going beyond the structured annotations.

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

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

Every sentence earns its place: the first states the action, the second explains the async behavior and polling follow-up, the third disambiguates from upgrade_tkc_cluster, and the fourth warns about scale-down drain. No fluff, and key behavioral caveats are front-loaded.

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

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

As an async mutation with no output schema, the description is nearly complete: it covers return status, how to observe completion, and the drain behavior on scale-down. A minor gap: it does not explicitly mention that an agent should avoid scaling during other operations or whether scaling is allowed repeatedly, but given the annotations and schema richness, this is a strong definition.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter context by explaining the asynchronous response shape, the meaning of worker_count as desired total, and the pool_name default behavior ('Omit for the first; other pools are always preserved'). This goes beyond 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 ('Scale') and precise resource ('worker node count of an existing TanzuKubernetesCluster (TKC)'). Explicitly distinguishes from upgrade_tkc_cluster by noting it scales workers only and that upgrade is for the K8s version.

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

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

Gives clear when-to-use guidance: scale worker count, and explicitly routes to upgrade_tkc_cluster for K8s version changes. Also notes the non-destructive nature of lowering worker_count and that nodes drain, which helps an agent decide when this tool is appropriate.

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

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

Discloses patch semantics, the no_changes response when all fields are omitted, immediate application with no dry run or undo, and the success result shape. These behaviors go well beyond the annotations, which only provide hints that the operation is a non-read-only, non-idempotent, non-destructive write. No contradiction with annotations exists.

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

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

The description is compact and front-loaded with the action and target. Each sentence contributes distinct value: patch behavior, no-op response, immediacy/no-undo, sibling differentiation, and parameter sourcing. No filler or redundancy.

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

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

For a 5-parameter mutation tool with no output schema, the description covers what is updated, how updates are applied, what happens when no fields are passed, what the success response looks like, and where to find valid values. The absence of an output schema is mitigated by the explicit return shape in the description.

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

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

Schema coverage is 100%, so the schema already explains each parameter. The description adds meaningful context by clarifying that passing no optional fields produces no_changes without an API call, and by pointing to list_supervisor_storage_policies as the source for valid storage_policy values. This elevates it above the baseline.

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

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

Description opens with a specific verb and resource: 'Update resource quotas or storage policy of an existing vSphere Namespace.' It clearly distinguishes from the sibling create_namespace by stating to use this when the namespace exists. The [WRITE] marker reinforces that this is a mutating 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 'Use this rather than create_namespace when the namespace exists,' giving an unambiguous when-to-use rule with a named alternative. It also advises where to get valid storage_policy values, which is actionable guidance for selecting and preparing the call.

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

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

Beyond the annotations, the description discloses that the upgrade is asynchronous and irreversible, that downgrading is impossible, that no dry run exists, and it specifies the exact return shape. This is essential behavioral context for a mutating, non-idempotent tool, especially with no output 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?

The definition is compact and front-loaded: purpose first, then return and behavior, then routing guidance. Every sentence earns its place, with no redundant or filler content.

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

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

For a complex asynchronous mutation with no output schema, the description covers the critical operational details: what it returns, how to confirm completion, irreversibility, lack of dry run, and how to choose between this tool and scale_tkc_cluster. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters, including that k8s_version should come from get_tkc_available_versions. The description does not add parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Upgrade a TKC cluster to a new Kubernetes version.' It also clearly distinguishes this tool from scale_tkc_cluster by scoping it to Kubernetes version changes, making sibling differentiation easy.

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

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

The description provides explicit usage guidance: 'Use this only for the K8s version; prefer scale_tkc_cluster for node counts.' It also instructs the agent to poll get_tkc_cluster until the phase is running and warns that there is no dry run.

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