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 most critical behavioral trait is disclosed: the tool is 'a dry run unless dry_run=False', meaning the default call does not actually create anything — exactly the kind of surprise an agent needs to avoid. It also reveals the dual return contract ({namespace, status, cluster} vs {dry_run, spec}). This adds substantial context beyond annotations, which only state readOnlyHint=false and destructiveHint=false; no contradiction exists.

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

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

Three sentences, zero filler: purpose, return contract with the critical default, then sibling routing. The essential safety caveat (dry-run default) is front-loaded in the second sentence rather than buried, and every clause earns its place.

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

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

With no output schema, the description correctly carries the return-format burden and covers the full create/update/verify lifecycle. What's missing for an 8-parameter creation operation is an error/null contract (e.g., what happens if creation fails or the namespace exists) and any permission prerequisites, but the fully-documented schema and clear sibling routing make the tool safely callable.

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 every parameter including the dry_run default of true, sources for cluster_id and storage_policy, and units for limits. The description only restates the dry_run default, adding nothing that meaningfully improves parameter understanding 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 ('Create a vSphere Namespace on a Supervisor Cluster') and the '[WRITE]' tag marks it as a mutation, distinguishing it from the many read-only siblings. It explicitly names update_namespace as the tool it should not be confused with, so an agent can disambiguate 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?

Gives explicit routing: 'Use update_namespace instead when it already exists' names the alternative and the exact condition that selects it. It also prescribes a follow-up step ('confirm with get_namespace afterwards'), which is actionable usage guidance beyond mere capability description.

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

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

The description discloses critical behavior beyond annotations: the dry-run default, the need to pass dry_run=False for actual provisioning, background execution, the returned shape, and the polling requirement. This is exactly the kind of behavioral context an agent needs to invoke the tool safely.

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 every sentence contributing: purpose, dry-run behavior, return shape, background provisioning, polling, and prerequisites. There is 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 9-parameter creation tool with no output schema, the description covers the essential workflow: what happens by default, how to cause real creation, what to expect in the response, how to verify completion, and which prerequisite tools to call first. This is sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents every parameter's meaning, type, and default. The description adds workflow hints for k8s_version and vm_class, but it does not substantially improve on the schema's parameter documentation.

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 the exact action, 'Create a TanzuKubernetesCluster in a vSphere Namespace,' with a specific verb and resource. The [WRITE] marker and clear resource name distinguish it from sibling operations like get_tkc_cluster, scale_tkc_cluster, and delete_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 provides clear operational guidance: it defaults to a dry run unless dry_run=False, requires calling get_tkc_available_versions and list_vm_classes first, and instructs polling get_tkc_cluster until the phase is running. It does not explicitly state when not to use it versus alternatives, but the create/read/update/delete sibling structure makes the intended use obvious.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description clearly discloses the destructive scope, irreversibility, default dry-run behavior, the requirement for both dry_run=False AND confirmed=True, the refusal while TKC clusters exist, and the expected return value. This gives the agent a full behavioral model beyond what annotations alone convey.

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

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

The description is compact and front-loaded with the [WRITE] signal, then delivers the return value, safety refusal, dry-run requirement, and alternative tool preference. Every sentence adds distinct value with 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 destructive tool with no output schema, this description is complete: it explains the return value, the default preview behavior, the confirmation flags, the blocking condition, and the safer alternative. Combined with the 100% schema coverage and sibling list, an agent has everything needed to call this tool correctly and safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter interplay by explaining that a dry run occurs unless both dry_run=False and confirmed=True are passed. It also clarifies that the preview is the default return. This goes beyond the schema's individual parameter descriptions, though it does not need to restate all parameter details.

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 vSphere Namespace and everything inside it.' It clearly distinguishes itself from update_namespace by saying 'prefer update_namespace to only change quotas,' and from delete_tkc_cluster by describing the prerequisite of deleting TKC clusters first. An agent can immediately understand the scope and uniqueness of this tool.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: use update_namespace instead when only quotas need changing, and use list_tkc_clusters plus delete_tkc_cluster when TKC clusters exist inside the namespace. It also specifies the required safety sequence before this tool will be allowed to act. This is strong routing and prerequisite information.

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 richly discloses behavior beyond annotations: it returns {name, namespace, status: 'deleting'}, defaults to a dry run unless dry_run=False AND confirmed=True, is irreversible, and is refused while workloads exist unless force=True. These details align with annotations (destructiveHint=true, readOnlyHint=false) and add significant operational context.

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

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

Every sentence carries essential information: the action, return value, safety guardrails, irreversibility, and the alternative tool. The structure breaks into clear labeled sections (WRITE, Returns, SAFETY) and wastes no words.

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

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

Given an absent output schema, the description provides the return shape and preview behavior. It covers safety conditions, dry-run semantics, irreversibility, and even the prerequisite for a related operation (delete_namespace). Nothing needed to invoke or decide on this tool 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 value by explaining the interaction between dry_run and confirmed ('dry run unless you pass dry_run=False AND confirmed=True') and that force skips the workload check. This clarifies parameter semantics beyond the schema definitions.

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

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

The description opens with a specific verb and resource: 'Delete a TKC cluster and all of its nodes.' It also differentiates from scale_tkc_cluster by noting it deletes the entire cluster rather than reducing node count, making the tool's scope unambiguous.

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

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

Explicit routing guidance is provided: 'use scale_tkc_cluster instead for fewer nodes' and 'Empty a namespace of TKC clusters before delete_namespace accepts it.' It also states when deletion is refused (if Deployments/StatefulSets run) unless force=True, giving clear conditions for proper use.

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 adds security-relevant behavioral context: the credential is a short-lived session token, it is higher-privileged, and using output_path keeps the credential out of agent context. These details go well beyond the structured annotations.

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

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

The description is reasonably compact and front-loads the core purpose before return format and security guidance. The historical aside about the sibling's docstring is slightly extra but does not undermine clarity.

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

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

Despite having no output schema, the description explicitly states the return shape in both invocation modes. Combined with full schema coverage and safety annotations, an agent has everything needed to call this tool correctly and safely.

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

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

Schema description coverage is 100%, so the schema documents namespace, target, and output_path. The description adds real semantic value by explaining the two return modes: inline kubeconfig vs. written file when output_path is given, and why output_path is preferred.

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 a kubeconfig for the Supervisor K8s API endpoint.' It clearly distinguishes this tool from get_tkc_kubeconfig, so an agent can select it correctly 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?

It gives explicit routing guidance: use this for Supervisor-level access and use get_tkc_kubeconfig instead for workloads inside a TKC cluster. It also advises preferring output_path for security, which covers an important usage decision.

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?

The description is extremely transparent about side effects, return shapes, and session-token handling, but it contradicts the annotations: it states output_path 'mkdir -p's and truncates' and can 'overwrite the user's own kubeconfig,' while annotations declare destructiveHint=false. Per rubric, this annotation contradiction forces a score of 1.

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 far longer than needed and repeats the truncation/overwrite warning in multiple places. It also includes meta-commentary about docstring history, sibling corrections, and marker conventions that an agent does not need to invoke the tool correctly.

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 fully covers return values, parameter side effects, prerequisites, alternatives, and security considerations. It provides enough context for an agent to call the tool correctly, apart from the annotation contradiction noted above.

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 value beyond the schema by explaining the behavior of output_path: omitting it returns the kubeconfig inline, while providing it writes a file and returns {cluster, written_to}.

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

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

The first sentence states a specific action and resource: 'Get a kubeconfig for one TKC cluster.' It also distinguishes itself from a sibling by naming get_supervisor_kubeconfig for Supervisor-level access, so an agent can tell them apart.

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

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

The description explicitly says to run list_tkc_clusters first for name/namespace, to use get_supervisor_kubeconfig instead for Supervisor-level access, and to prefer output_path for security. It also clarifies when nothing is written versus when output_path is supplied.

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.