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?

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?

Goes well beyond the annotations (which only give the generic readOnly/idempotent/destructive/openWorld hints) by disclosing the exact return shapes, that the kubeconfig embeds a live Supervisor bearer token acting as the configured vCenter account, that the token lifetime is hours and not tied to the process, that the written file is mode 0600, and that output_path truncates and creates parent directories. This is exactly the kind of security-relevant 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-loads the [WRITE]/credential-access framing and the when-to-use gate, then return shapes, then the security rationale, then the sibling disambiguation. Every sentence carries distinct, load-bearing information with 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?

There is no output schema, and the description fully compensates by specifying both possible return payloads ({namespace, kubeconfig} vs. {namespace, written_to}), the token semantics, and file-permission behavior. Nothing an agent needs to invoke this credential-returning tool 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 real guidance the schema lacks: pass output_path preferentially so the token never enters agent context and only the path is reported. Target and namespace meaning is left to the schema, keeping this just under 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 ('get a kubeconfig for the Supervisor K8s API') and immediately distinguishes itself from the near-identical sibling get_tkc_kubeconfig by scope (Supervisor API vs. workloads inside a TKC cluster). An agent can select 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 constraint ('Call only when the user explicitly asks for this kubeconfig; never as a side step') and an explicit named alternative ('Use get_tkc_kubeconfig instead to reach workloads inside a TKC cluster'). Both the positive and negative routing conditions 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?

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?

Annotations only say readOnlyHint=false/destructiveHint=false/idempotentHint=true/openWorldHint=true; the description goes far beyond by disclosing the return shapes, the embedded JWT bearer-token lifecycle (hours, not tied to this process), and the concrete file side effects of output_path (creates parent dirs, truncates the target, 0600 owner-only, overwriting ~/.kube/config). It also gives the mitigating instruction to always pass output_path so the token never enters agent context. The file-truncation disclosure slightly exceeds the destructiveHint=false annotation, but it is added transparency rather than 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] tag, purpose, and gating condition before the detail. The single dense paragraph is long and dash-heavy but nearly every clause (token lifetime, return shapes, overwrite warning, prerequisites) earns its place; minor tightening is possible in the token sentence.

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 carries the return-value burden and does so fully, specifying both possible return shapes. It also covers the safety-critical side effects, the credential lifetime, and the prerequisite call, so an agent has everything needed 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning: output_path changes the return shape ({kubeconfig} vs {written_to}), carries the side-effect semantics (directory creation, truncation, permissions), and is framed as a strong recommendation rather than an optional toggle. It also implies name/namespace should be sourced from list_tkc_clusters.

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

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

States a specific verb and resource ('get a kubeconfig for one TKC cluster') and immediately frames it as credential access, which sets it apart from non-credential siblings like get_tkc_cluster. It also names the sibling it is not for (get_supervisor_kubeconfig) so the agent can disambiguate the two kubeconfig tools 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?

Explicit when-to-use ('only when the user explicitly asks') and when-not ('never as a side step'), plus a prerequisite ('Run list_tkc_clusters first for name and namespace') and a named alternative for the adjacent use case ('use get_supervisor_kubeconfig instead for Supervisor-level access'). Nothing about 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?

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?

The description adds substantial behavioral detail beyond the annotations: it specifies the exact response envelope fields, states that the Supervisor list is walked to completion so truncated is always False, and documents the deprecated 'clusters' alias. This gives the agent a precise model of the tool's behavior without needing to call it.

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

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

The description is dense but every sentence carries useful information: purpose, response shape, routing advice, and a deprecation warning. It is front-loaded with the core action, and the details are logically 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?

Even with no output schema, the description fully documents the return envelope, pagination behavior, and how to proceed for more detail or access. Combined with the strong annotations and simple two-parameter schema, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents target and namespace. The description only restates that namespace filtering is optional, adding no new parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List TanzuKubernetesCluster (TKC) clusters, optionally in one namespace.' It clearly distinguishes from the sibling get_tkc_cluster by framing this as the listing entry point and directing further detail lookup to get_tkc_cluster.

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

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

The description gives concrete guidance: 'Start here, then call get_tkc_cluster for full detail or get_tkc_kubeconfig for access.' This provides context for when this tool should be the first step and which siblings to use next. It stops short of explicitly stating when not to use it, but the routing is clear enough.

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?

The description goes well beyond annotations by describing the exact return envelope, the structure of boot_order, runtime discovery of the served CRD version, pagination/completion behavior, and the teaching error on older Supervisors. It fully discloses behavioral traits an agent needs to interpret results.

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

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

The description is front-loaded with the core purpose, and every subsequent sentence adds meaningful detail about return shape, version behavior, and error handling. No filler or redundant rephrasing of the schema 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?

With no output schema, the description fully compensates by specifying the returned fields, pagination semantics, CRD version behavior, and boot_order structure. An agent has enough information to invoke the tool and interpret the response 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%, with both target and namespace already documented. The description adds general context but little parameter-specific detail beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

Description opens with '[READ] List VirtualMachineGroup objects and their bootOrder in a Namespace', naming a specific verb, resource, and scope. It clearly identifies the VM Service CRD and Supervisor K8s API, making it unambiguous what the tool does and distinct from sibling list tools.

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

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

The description gives clear context: the tool operates in a specific Namespace and targets Supervisor VM Service groups. It does not explicitly name alternatives or exclusion conditions, but the namespace scoping and the version-related note about older Supervisors provide practical 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals important runtime behavior: it reads via the Supervisor K8s API, discovers the served CRD version at runtime, returns a structured list envelope, and handles a VM without a network block by returning an empty list rather than an error. This is exactly the kind of behavior an agent cannot infer from annotations or schema 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?

Every sentence earns its place: a concise one-line summary, the data source and return envelope, a key edge case, and prerequisite guidance. There is no fluff or repetition of the schema, and the most important scoping information is front-laoded.

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

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

The description is complete for this tool given its moderate complexity and the lack of an output schema: it explains what is returned, the empty-list behavior, the backend accessed, and how to supply the required parameters. An agent can select and invoke this tool correctly without needing additional context.

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 at 100%, so the baseline is 3. The description adds meaning by telling the agent how to obtain values: run list_namespaces for the namespace and source the VM name from the VM inventory in that namespace. It also implies that target is optional by not needing explanation, while the schema already gives its 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 description opens with a specific verb and resource: 'List the network interfaces (multi-NIC) of one VirtualMachine.' It names the exact data source (spec.network.interfaces[] on a VM Service VirtualMachine via the Supervisor K8s API) and clearly scopes this to a single VM, distinguishing it from the sibling VM 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 practical usage context: run list_namespaces to obtain the namespace and use the VM name from the VM inventory in that namespace. It does not explicitly name alternative tools or when-not-to-use conditions, but the single-VM scoping and prerequisites make the intended use clear.

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

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

Annotations already mark readOnly/idempotent/non-destructive, and the description adds meaningful behavioral detail: the served CRD version is discovered at runtime, the return envelope includes specific fields, truncated is always false because it walks to completion, and old Supervisors produce errors naming the required version. This goes well beyond the annotations and conditions the agent to expect a specific 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?

The description is front-loaded with the core purpose, then efficiently packs only relevant operational details: CRD discovery, return envelope fields, completion behavior, error semantics, and prerequisites. No filler or redundant restatement of the schema is present. Every clause contributes to safe invocation.

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

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

Given there is no output schema, the description's explanation of the returned envelope (items fields, returned/total/truncated, served_version) is essential and fully supplied. It also covers error behavior, prerequisite calls, and the alternative for NICs, making it complete for an agent to use 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% (target and namespace both have explanatory descriptions), so the schema already communicates parameter meaning. The description adds minor value by noting the namespace comes from list_namespaces and target defaults via config.yaml, but it does not substantially extend the schema definitions. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List VirtualMachineSnapshot objects in a vSphere Namespace.' It clearly differentiates this from siblings by explicitly naming list_vm_network_interfaces for NICs and referencing the vSphere Namespace scope. The 'READ' tag reinforces the intent 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?

It gives explicit when-to-use guidance: run list_namespaces first for the namespace, and use list_vm_network_interfaces for a VM's NICs instead. It also explains the behavior when the Supervisor predates v1alpha5, which tells an agent what to expect and how to respond. This is strong routing guidance relative to alternative 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=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.