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

Annotations already declare readOnlyHint=true, so the '[READ]' tag is redundant and the safety profile is covered. The description adds the target-resolution behavior (config name, default fallback) but discloses nothing further about output shape, auth, or pagination, so it adds modest value beyond structured data.

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 action and the read tag, then a tight Args block. No wasted prose, though the bracketed '[READ]' restates the annotation rather than earning its place.

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

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

For a simple, single-param, no-output-schema discovery tool, the description tells the agent what it returns (API groups and versions) and how to direct the call via target. 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 0% and the schema only lists 'target' as a nullable string with null default. The description compensates by explaining that target is a k8s target name from config and that omitting it uses the default, which is genuine meaning beyond the raw schema.

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

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

States a specific verb and resource: 'List available API groups and their versions.' This uniquely identifies the resource (API discovery) among the many workload-specific siblings like pod_list and node_list. It could be sharper about how this differs in intent (discovery vs. resource enumeration), but the verb+resource is unambiguous.

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

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

Gives parameter-level usage ('omit to use the default') but no explicit when-to-use or when-not-to-use framing against alternatives. Since no sibling covers Kubernetes API discovery, the lack of exclusions is a minor gap, leaving usage implied rather than 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=true, and the '[READ]' prefix restates that, adding no new information. The description does add that the output is a 'friendly health summary' covering version and counts, but says nothing about failure modes or auth needs, which is acceptable but unremarkable given the low bar set by 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?

Front-loaded with the summary purpose in the first line, and the Args block is short. Slightly padded by the redundant '[READ]' marker and the docstring-style 'Args:' formatting, but nothing is wasted.

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

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

For a one-optional-param read tool with no output schema, the description does enough: it says what the summary contains and how to target the cluster. No return-format detail is needed since output structure is minimal and self-describing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: 'target' is identified as a k8s target name from config with an explicit default behavior when omitted. This compensates well for the single undocumented schema param.

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 resource (cluster) and the exact contents returned: server version plus node/ns counts. The word 'summary' distinguishes it from listing siblings such as node_list and namespace_list, which enumerate rather than aggregate.

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 only guidance is on the target parameter ('omit to use the default'). There is no statement of when to reach for this overview instead of node_list or namespace_list, so the when-to-use is left implied by the word 'summary'.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered, and the '[READ]' tag is largely redundant with that. The useful addition is clarifying the content is config data, not secrets, but nothing is said about missing-key behavior, error modes, or return shape beyond the payload description.

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

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

Front-loaded with the action and scope, followed by an Args block that maps cleanly to the three parameters. Efficient overall, with only mild redundancy in the '[READ]' prefix given the annotation.

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

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

For a simple read tool with no output schema, the description conveys what is returned (config keys and values) and how to address the resource. It is complete enough to invoke correctly, though it omits error/edge behavior for a non-existent configmap.

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

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

With 0% schema description coverage, the description must carry the params, and it does document all three: name (cross-referenced to configmap_list), namespace (omit for the target's default namespace), and target (k8s target name from config). This meaningfully compensates for the schema gap, though it stays fairly shallow.

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

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

The description states a specific verb+resource ('Return a configmap's data') and even scopes the payload ('keys + values — config, not secrets'), which distinguishes it from secret-list/get siblings. An agent can identify what this does without opening the schema.

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

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

It implies usage by cross-referencing configmap_list ('see configmap_list') for obtaining the name, and notes the namespace-omission behavior. However, it gives no explicit when-to-use vs alternatives (e.g., list vs get) or exclusions; the workflow is only inferred.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the '[READ]' prefix is redundant with that. The description does add useful context that it returns summary fields and can span all namespaces, but says nothing about volume, pagination, or truncation 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?

Front-loaded with the essential purpose and return fields, then a compact args block. Every line earns its place, though the '[READ]' prefix is mildly redundant with the annotation.

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

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

No output schema exists, and the description compensates by naming the returned fields. For a two-optional-param list tool with a readOnly annotation, this covers what an agent needs; only multi-namespace behavior edge cases are unstated.

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

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

Schema description coverage is 0%, so the description carries the entire load: it defines namespace semantics ('omit for all namespaces') and explains target as the k8s target name from config. Both parameters gain meaning the schema alone does not provide.

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

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

States a specific verb (List) and resource (configmaps), and even enumerates the returned fields (name, namespace, key count, age). It is clearly distinguishishable from configmap_get, though it doesn't explicitly name the sibling boundary.

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?

'omit for all namespaces' gives usable scoping guidance, but there is no explicit when-to-use-this-vs-configmap_get or when-not guidance. Usage is implied rather than 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=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered structurally. The description usefully adds the [WRITE][risk=medium] tag, the precise semantic effect (no new pods land), and the dry-run escape hatch. It does not state what happens to already-running pods, which is a minor remaining gap.

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

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

Front-loaded with the operation, the inverse, and the dry-run hint before the Args block, so the highest-value information comes first. The dry_run explanation is stated twice (prose and Args), which is mild 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 3-parameter mutation with no output schema, the description covers purpose, argument meaning, preview behavior, and the reverse operation. The only omission is whether existing pods on the node are affected, which matters for an agent judging impact.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it documents all three: name (with a pointer to node_list), dry_run (preview semantics), and target (k8s target name from config). Coverage is complete, though target's meaning stays slightly abstract.

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?

State a specific verb+resource ('Mark a node unschedulable') with an immediate parenthetical clarifying the effect ('no new pods land'), and it explicitly names its inverse sibling uncordon_node. An agent can distinguish this from drain_node and uncordon_node without reading any schema.

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

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

It names the reverse operation (uncordon_node) and gives a clear preview path ('Pass dry_run=True to preview without cordoning'). It stops short of stating when to prefer cordon over drain_node, so it lacks explicit exclusions, but the context for use is clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered; the description adds the dry-run preview behavior, a medium risk rating, and the inverse-tool mapping, which are not in the annotations. It omits what happens on re-creation/name conflict (the annotation says non-idempotent but the text never explains the failure mode) and permission requirements.

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

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

Front-loaded with the operation class, relationship, and the dry-run tip, then a compact Args block — every section is scannable. Minor waste: the dry_run preview is stated twice (once in prose, once in the Args block).

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

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

For a mutating create tool with no output schema, the description leaves the agent without the post-call picture: no statement of whether an existing namespace causes an error or a no-op, and no indication of what success returns. The dry-run coverage is good, but the conflict/return behavior is a real gap.

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

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

Schema coverage is 0%, and the description compensates by documenting all three parameters, notably 'target: k8s target name from config' which gives the schema's bare 'Target' field real meaning. 'name' and 'dry_run' definitions are adequate though thin ('dry_run' is repeated verbatim from the intro sentence).

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

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

Specific verb+resource ('Create a namespace') plus the explicit inverse relationship to delete_namespace, so an agent can immediately separate this from the destroy tool in the sibling list. It also carries a [WRITE] marker that signals the operation class up front.

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?

Tells the agent when to choose the non-destructive path ('Pass dry_run=True to preview without creating') and points at the inverse tool for the opposite operation. It stops short of stating prerequisites or when-not conditions (e.g. what to do if the namespace already exists, how to pick a target).

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the namespace-defaulting behavior ('omit for the target's default namespace'), which is genuine added context, but says nothing about error cases or the returned detail. Adequate but thin against the annotation baseline.

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

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

Front-loaded with the [READ] marker and one-line purpose, followed by a compact Args block. Every line earns its place; the only mild redundancy is the section header itself.

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

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

For a read-only, single-param-required get tool with no output schema, the description covers purpose, all parameters, and namespace defaulting — enough to invoke it correctly. The absence of any statement about what 'detail' is returned is the only gap.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning and it largely does: it names all three args and explains name (CronJob name), namespace (default fallback), and target (k8s target from config). 'Target' remains somewhat opaque, keeping this short of a 5.

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

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

States a specific verb and resource ('Return detail for a single cronjob by name'), and 'single' plus the [READ] tag distinguishes it from cronjob_list/job_list without opening the schema. It does not explicitly name job_get as the non-cronjob alternative, but the resource granularity is unambiguous.

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

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

Usage is implied: fetch one cronjob by name, cross-referencing cronjob_list for valid names. There is no explicit when-to-use/when-not framing versus cronjob_list or job_get, so the agent must infer the routing condition.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the '[READ]' tag is corroborating. The genuinely additive disclosure is the list of returned fields, useful because there is no output schema. No pagination or ordering behavior is mentioned, so it falls short of a 5.

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

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

Front-loaded [READ] marker, one-line purpose with return fields, then a tight Args block. No filler; every sentence earns its place.

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

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

For a simple two-optional-param list tool with readOnlyHint annotation, the definition covers what an agent needs. The absence of an output schema is partly offset by the enumerated return fields, though result volume or default behavior is unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: namespace (omit for all) and target (k8s target name from config) both get meaning. 'target' remains somewhat vague, keeping it out of 5 territory.

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

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

States a specific verb and resource ('List cronjobs') and even enumerates the fields returned (name, namespace, schedule, suspend, active, age). This clearly separates it from cronjob_get (single resource) and job_list (different resource).

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

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

It gives argument-level guidance ('omit for all namespaces', target name from config) but no explicit routing to alternatives such as cronjob_get for a single cronjob. Usage is implied rather than 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=true, and the "[READ]" tag is consistent with that rather than adding new information. The description does add useful behavioral detail about namespace resolution (omit to use the target's default namespace) and where to source names, but says nothing about failure modes, permissions, or the returned detail. Adequate against a lower annotation-era bar.

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?

Two front-loaded sentences plus a tight Args block with no padding; each parameter line earns its place. Slightly more verbose than strictly needed for the required-only name argument.

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

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

With no output schema and no annotations beyond readOnlyHint, the description should say at least roughly what detail is returned or how a missing daemonset is reported. It covers inputs well but leaves the return contract and failure semantics unstated.

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

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

Schema description coverage is 0%, so the description carries the whole burden, and it documents all three parameters: name format and where to find it, namespace defaulting behavior, and that target is a k8s target name from config. This meaningfully exceeds the bare schema, though it doesn't specify name casing/fully-qualified forms or error behavior for an unknown target.

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 ("Return detail for a single daemonset by name") and implicitly contrasts with the listing counterpart by pointing to daemonset_list for names. An agent can distinguish this from daemonset_list, deployment_get, or statefulset_get without opening any schema.

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

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

Usage is only implied: the description tells the agent to see daemonset_list for names and to omit namespace for the target's default, which hints at the read-a-single-object workflow. It never states when this tool is preferred over pod_describe, workload_readiness_rca, or rollout_status, nor what happens if the daemonset does not exist.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the returned column set, which is useful context absent from the output schema, but does not disclose pagination, auth requirements, or rate limits.

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

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

Extremely tight: one line for purpose and an Args section for the two parameters. The [READ] marker is front-loaded, and every sentence earns its place.

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

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

For a simple list tool with no output schema, the description supplies the returned fields and both parameter meanings. It does not mention pagination or label filtering, but those are not present in the schema either, so the core call is adequately specified.

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

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

Schema description coverage is 0%, so the description carries the full burden and documents both parameters: namespace (omit for all namespaces) and target (k8s target name from config). This adds meaning beyond the bare schema, though the target definition is somewhat terse.

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

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

States a specific verb (List) and resource (daemonsets), and enumerates the returned fields (name, namespace, desired/ready/available, age). This clearly distinguishes it from daemonset_get and other 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?

Usage is implied by the name and the [READ] marker, and the namespace arg notes 'omit for all namespaces'. However, there is no explicit guidance on when to choose daemonset_list over daemonset_get or other list siblings.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so safety is partly covered. The description adds value beyond them: the cascade behavior (deleting the deployment's pods), the 'no undo' irreversibility, and the dry_run preview path — all genuinely useful behavioral context.

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

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

Front-loaded with severity and risk labels, then the dry-run hint, then args. Efficient overall, though dry_run is stated twice (body and Args), a minor 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 delete with no output schema, the description covers risk, cascade scope, preview path, and all params. Minor gaps remain — no mention of graceful vs immediate deletion or confirmation requirements — but nothing critical for correct invocation is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does so: it documents all four params, including namespace default behavior ('omit for the target's default namespace'), dry_run semantics, and target being a config name. Brief but compensates for the total schema gap.

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

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

States a specific verb and resource ('Delete a deployment') and adds scope ('and its pods'), which distinguishes it from delete_pod in the sibling set. It does not name sibling alternatives directly, but the cascading-pods language is enough for an agent to tell it 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?

No when-to-use guidance or named alternatives despite many relevant siblings (delete_pod, rollout_undo_deployment, scale_deployment to zero). It only tells the agent how to preview via dry_run, not when this tool is the right choice over rolling back or scaling down.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds genuinely new information: the deletion cascades to pods, it is irreversible ('no undo'), and a dry-run preview exists. It stops short of stating permission/auth requirements, so it is strong but not exhaustive.

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

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

Front-loads the [WRITE][risk=high] marker and the irreversible warning before the dry-run escape hatch and the Args list. Every line earns its place; no filler.

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

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

For a destructive, no-output-schema mutation with four parameters, it covers the risk profile, cascade behavior, preview mechanism, and every parameter. Missing only operational detail such as required permissions or the shape of the delete response/confirmation.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden, and it documents all four: name, namespace (with the omit-for-default semantics), dry_run (preview behavior), and target (k8s target name from config). The name entry is merely a restatement, keeping it from a 5.

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

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

States a specific verb+resource ('Delete a job') plus a key side effect ('and its pods'), which cleanly distinguishes it from siblings like job_get, job_list, delete_pod, and delete_deployment. An agent can route to it without opening any schema.

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

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

Gives clear context for use (a destructive, irreversible delete) and explicitly offers the dry_run=True preview path. It does not name alternative tools or state when *not* to use it, but the resource-specific scope makes the routing unambiguous.

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

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

Annotations already declare destructiveHint=true, but the description goes far beyond them: 'no undo', the dry_run preview path, which namespaces are protected and why (DNS, pod networking), and the non-overridable credential self-revocation refusal. It even discloses that refusals fire on the dry_run path, preventing a false green preview.

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 [WRITE][risk=high] and the destructive scope, then preview mechanism, then refusal rules, then a clean Args block. Every sentence carries non-redundant operational information.

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

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

No output schema exists, yet the description still tells the agent what a preview would surface (a wouldDelete result) and enumerates the failure modes. For a high-risk mutation tool with four parameters, nothing material is missing.

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

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

Schema description coverage is 0%, so the description must carry semantics, and it does: dry_run is a preview switch, confirm acknowledges a protected control-plane namespace (and explicitly cannot override the SA refusal), target is a k8s target name from config. Only 'name' is left as the bare minimum, hence not a full 5.

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

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

States a specific verb and resource with scope in caps ('Delete a namespace and EVERYTHING in it') and a risk tag, so it is immediately distinguishable from delete_pod, delete_deployment, and delete_job. An agent knows exactly what this does without opening the schema.

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

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

Gives explicit conditional guidance: pass dry_run=True to preview, confirm=True is required only for control-plane namespaces, and the ServiceAccount namespace is refused outright with confirm not overriding it. It does not name sibling tools as alternatives, but the when-to-use and when-not rules are unusually 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?

Annotations already carry destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is partly covered. The description goes beyond them by tagging '[WRITE][risk=medium]' and clarifying that deletion is not permanent because a controller usually recreates the pod, which is real context an agent needs. It stops short of permission/auth or return-value details.

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

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

Front-loaded with the write/risk tag and core action, then a structured Args block. Every sentence earns its place; the only minor redundancy is dry_run appearing both in prose and the Args list, which is acceptable for scannability.

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

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

For a 4-parameter destructive tool with no output schema and 0% schema coverage, the description covers the action, the irreversibility caveat, the preview mechanism, and every parameter. It omits only permission requirements and return/pagination behavior, which are minor here.

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

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

Schema description coverage is 0%, so the description carries the full param burden, and it documents all four: name, namespace ('omit for the target's default namespace'), dry_run, and target ('k8s target name from config'). That meaningfully compensates for the empty schema, though the per-param text is terse.

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

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

States a specific verb and resource ('Delete a pod') and adds a distinguishing behavioral note ('No undo — a controller usually recreates it'). An agent can tell this apart from delete_job or delete_deployment 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?

The description gives a preview workflow ('Pass dry_run=True to preview without deleting') which is useful, but it offers no guidance on when to delete a pod versus alternatives like drain_node or rollout_restart_deployment, nor any prerequisite or exclusion conditions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: the namespace argument defaults to the target's default namespace when omitted, and target comes from config. It omits error behavior (e.g., not-found).

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

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

Front-loaded with the [READ] marker and purpose, followed by a compact arg list. Every line earns its place given the empty schema descriptions, though the Args block is somewhat mechanical.

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

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

With no output schema, the description should say more about what 'detail' is returned, but it only says 'Return detail.' Safety and parameters are adequately covered, so this is the main remaining gap for a read 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 coverage is 0%, so the description carries the param burden and does it well, documenting all three: name (deployment name, cross-referenced to deployment_list), namespace (defaulting behavior), and target (k8s target name from config). It genuinely adds meaning the bare schema lacks.

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

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

States a specific verb and resource with clear scope: 'Return detail for a single deployment by name.' The [READ] tag and the single-vs-list distinction make it identifiable, though it does not explicitly name deployment_list/delete_deployment as the alternatives an agent must choose between.

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

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

Usage is implied rather than stated: the reader infers you call this to inspect one deployment. It points to deployment_list only for name lookup, not as the routing alternative when the agent just wants a list. No when-not guidance or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, and the '[READ]' prefix reinforces it. Beyond that, the description discloses the return shape (name, namespace, desired/ready/available, age), which is genuinely useful behavioral context since there is 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?

Front-loaded with the read tag and core action, then a tight two-item args block. Every sentence earns its place 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?

Complete enough for a no-arg-required list tool: purpose, return fields, and both parameters are covered despite zero schema coverage and no output schema. Only pagination/sorting behavior, if any, is left unmentioned.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: 'namespace' including the omit-for-all-namespaces behavior, and 'target' as the k8s target name from config. Both are defined in terms the schema alone does not provide.

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

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

States a specific verb+resource ('List deployments') and even names the columns returned. It is distinguishable from deployment_get by the plural listing verb, though it never explicitly says how it differs from the singular sibling.

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

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

Usage is implied by the list semantics and the 'omit for all namespaces' hint, but there is no explicit when-to-use guidance nor any mention of the neighboring deployment_get for single-deployment inspection.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, yet the description adds substantial context beyond them: no full undo, cordon-is-reversible-but-evictions-are-not, and explicit skipping of DaemonSet-managed and mirror pods (matching kubectl drain). This is exactly the extra behavioral detail the annotations cannot convey.

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

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

Risk tag and IRREVERSIBILITY note are front-loaded before mechanics, then behavior, then a compact Args block. Every sentence (skipped pod types, reversibility split, dry_run) carries decision-relevant 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?

For a high-risk destructive operation with no output schema, the description covers the safety profile, the preview escape hatch (dry_run), reversibility boundaries, and workloads excluded from eviction. Nothing an agent needs before invoking this dangerous 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 0%, so the description must compensate, and it does: name points to node_list, dry_run explains the preview-without-draining behavior, and target is identified as the k8s target name from config. All three params gain meaning, though no format/enum detail is added for target.

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 compound action (cordon a node and evict its pods) with the resource named, and clearly distinguishes this from the reversible cordon_node/uncordon_node siblings by noting the eviction half is irreversible. An agent can tell drain_node apart from cordon_node and delete_pod without opening any schema.

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

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

Gives clear operational context: the cordon is reversible via uncordon_node while evictions are not, and dry_run=True previews without draining. It stops short of an explicit 'use this when... instead of...' routing statement, but the reversal/preview guidance effectively tells the agent when and how to use it safely.

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

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

Annotations already declare readOnlyHint=true, so the "[READ]" prefix adds nothing new. The description does add value by listing the fields the tool returns, partially compensating for the absent output schema, but it says nothing about permissions, cluster-connectivity requirements, or how the target/config mechanism behaves.

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 summary line is front-loaded and the two argument lines are terse and free of filler. Slightly redundant "[READ]" tag and an "Args:" block that mostly restates parameter names keep it from a 5.

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

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

For a simple read-only list tool with no output schema, the description usefully names the returned fields, which is the main thing an agent needs. However, with two parameters at 0% schema coverage and only a vague note on target, an agent still lacks enough to know where target values come from.

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

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

Schema description coverage is 0%, so the description carries the burden and does define both parameters: "omit for all namespaces" for namespace and "k8s target name from config" for target. The target explanation is thin — it never says how valid target names are discovered — so it only partially compensates for the schema gap.

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

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

The description gives a specific verb+resource ("List endpoints") and even enumerates the returned fields (name, namespace, ready addresses, ports, age), which clearly differentiates it from sibling *_list tools for different resources. It does not, however, explicitly contrast itself with nearby tools like service_list or pod_list.

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

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

The only usage instruction is "namespace: Namespace; omit for all namespaces," which is scoping rather than when-to-use guidance. There is no mention of when to prefer endpoints_list over service_list, pod_list, or the *_get variants, and no prerequisites or exclusions 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 only supply readOnlyHint=true. The description goes well beyond that by disclosing the return envelope, the meaning of the 'truncated' flag, and the correct remediation (re-run with a higher limit rather than reporting an incomplete set) — exactly the kind of behavior an agent cannot infer from structured fields.

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

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

Front-loaded with the verb and purpose, then the diagnostic use case, then the return contract, then Args. The truncation warning is the only multi-line passage and it earns its space by preventing a real failure mode; the '[READ]' tag is mildly redundant with readOnlyHint but harmless.

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

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

No output schema exists, yet the description supplies the return shape and the truncation semantics. For a 3-parameter, 0-required read tool with all arguments documented and the failure mode flagged, nothing an agent needs is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: namespace is defined including the meaningful default behavior ('omit for all namespaces'), limit is defined as a maximum count, and target is tied to a config source. All three parameters are accounted for.

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

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

States a specific verb and resource ('List recent events') and enumerates the fields returned (type, reason, object, message, age). No sibling tool in the 55-name list covers cluster events, so the resource itself cleanly disambiguates it from pod_describe or pod_logs.

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

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

Gives a clear diagnostic context ('why a pod is not starting', citing FailedScheduling) and the truncation re-run path. It never names an alternative (pod_describe, pod_health_rca, workload_readiness_rca) or states when-not to use it, so it stops short of a 5.

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

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

readOnlyHint=true already declares a safe read, so the bar is lower; the '[READ]' tag is redundant with the annotation. The description does add real behavioral value by explaining that omitting 'namespace' falls back to the target's default namespace, but it says nothing about errors or return 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?

Front-loads the '[READ]' marker and purpose, then a compact Args list covering every parameter. No filler; appropriately sized for a simple read tool.

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

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

With annotations covering the safety profile and no output schema, the description is nearly complete for a single-resource read: it names the resource, the returned content, and all parameter semantics. Only error/pagination behavior is unstated, which is minor here.

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

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

Schema description coverage is 0%, so the description must carry the full burden; it documents all three parameters meaningfully — 'name' cross-referenced to ingress_list, 'namespace' default behavior, and 'target' as a k8s target name from config. This compensates well for the empty schema.

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

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

States a specific verb and resource ('Return detail for a single ingress') and adds scope ('including path→backend rules'), which tells the agent what content to expect. The word 'single' implicitly contrasts with ingress_list, though no sibling is named explicitly for differentiation.

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

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

Usage is implied by the get-vs-list distinction and the parenthetical '(see ingress_list)' routes toward the sibling list tool, but there is no explicit when-to-use/when-not statement or prerequisite guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the [READ] tag and the namespace-omission behavior, but doesn't mention pagination, output volume, or any auth/rate-limit context. With annotations carrying the safety profile, this is adequate but shallow.

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

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

One short purpose line followed by a compact Args block. Every token earns its place; no repetition of schema structure, no filler.

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

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

For a zero-required-param, read-only list tool with no output schema, the description covers purpose, both params, and the returned fields. It's nearly complete; the only gap is the absence of pagination or result-size context typical of k8s listing tools with no server-side limit.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It documents both params: namespace (scope + omission behavior) and target (k8s config context). That's meaningful, but it doesn't cover format/type expectations or the default-null semantics — so it improves on the raw schema but doesn't fully compensate.

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

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

States a specific verb (List) and resource (ingresses), plus explicitly enumerates the fields returned (name, namespace, class, hosts, age). The [READ] tag reinforces the read-only nature and distinguishes it from ingress_get, which presumably fetches a single ingress.

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 namespace arg note ('omit for all namespaces') implies scoping behavior, which hints at when to use a filtered vs full listing. But there's no explicit guidance on when to prefer ingress_list over ingress_get, nor any statement of exclusions. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, and the [READ] prefix merely restates that safety profile rather than adding to it. Nothing is said about error behavior for missing jobs, permissions required, or response shape, and no new behavioral context is contributed beyond what the annotation already provides.

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

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

The purpose is front-loaded in one sentence, followed by a compact Args block with one line per parameter. Every line carries information; only the bracket tag is arguably redundant with the annotation.

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

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

For a read-only single-resource getter with no output schema, the description covers what the tool does and the meaning of each of its three inputs. Return-value details are not needed without an output schema, so the remaining gap is minor.

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

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

With schema coverage at 0%, the description carries the full burden and does document all three parameters: name with a pointer to job_list, namespace with its default-namespace semantics, and target as a config-sourced k8s target. This meaningfully compensates for the bare schema, though formats or accepted value shapes are not elaborated.

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?

"Return detail for a single job by name" gives a specific verb (return detail) and resource (job) with a scope qualifier (single, by name) that separates it from the plural job_list sibling. It stops short of naming job_list as the alternative, relying on a parenthetical pointer for names instead of an explicit contrast.

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

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

Usage is only implied: the agent can infer this tool is for inspecting one job rather than enumerating them, and the "(see job_list)" note hints at the discovery flow. There is no explicit when-to-use vs cronjob_get/pod_get guidance and no stated exclusions or prerequisites.

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

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

The readOnlyHint annotation already establishes this is a safe read, and the '[READ]' prefix merely repeats that. The description does add value by naming the columns returned, but says nothing about pagination, result limits, or ordering for large job lists.

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 action and returned fields, then a compact Args block. Nearly every line earns its place; the only minor waste is the redundant '[READ]' tag already covered by the annotation.

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 helpfully lists the returned fields, and with only two optional parameters both are documented. Missing only secondary details such as default ordering or behavior on an invalid target/namespace.

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

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

Schema coverage is 0%, so the description carries the load and does it reasonably: 'target' is explained as the k8s target name from config, and 'namespace' is explained with the omit-for-all behavior. Format expectations (e.g. exact namespace string) are still unspecified, keeping it below 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 ('List jobs') and even enumerates the returned fields (name, namespace, completions, succeeded/failed, age), which is more than a tautology. It does not explicitly distinguish itself from close siblings like job_get or cronjob_list, so it stops short of a 5.

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

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

Usage is only implied: 'omit for all namespaces' tells the agent how to broaden scope, which is useful. But there is no statement of when to prefer this over job_get or cronjob_list, and no prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with a [READ] tag. It adds value by disclosing the returned fields (name, phase, age), which matters since there is no output schema, but says nothing about scope across clusters, pagination, or filtering.

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

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

Front-loaded with the read tag and purpose, and the Args block is minimal with zero filler. Appropriately sized for a one-parameter list tool.

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

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

Since there is no output schema, listing the return fields (name, phase, age) is the right compensating detail, and the read-only nature is clear. Minor gaps remain around cluster scope and result size, but for a simple list operation this is largely complete.

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

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

Schema coverage is 0%, so the description carries the full burden for the single 'target' parameter, and it does explain it: 'k8s target name from config; omit to use the default.' That clarifies meaning and default behavior absent from the schema.

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

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

States a specific verb+resource ('List namespaces') and even enumerates the returned fields (name, phase, age), so the agent knows exactly what it produces. It doesn't explicitly distinguish itself from create_namespace/delete_namespace siblings, but the 'List' verb and [READ] tag make the intent obvious.

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

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

No explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The only guidance is embedded in the 'target' arg note (omit to use the default), which is parameter-level rather than usage-level.

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

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

readOnlyHint=true already establishes the safe-read profile, so the [READ] tag is redundant. The description does add value by naming the returned data (capacity, allocatable, conditions, taints), partially compensating for the absent output schema, but says nothing about errors, permissions, or behavior for missing nodes.

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

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

Front-loaded with the [READ] tag and a single-line purpose, followed by a clean Args block. No filler, though the [READ] tag duplicates the readOnlyHint annotation.

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

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

For a read-only single-node describe with no output schema, listing the key returned facets plus both parameters is nearly sufficient. It would be stronger with a note on behavior when the node/target does not exist.

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

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

Schema coverage is 0%, so the description carries the full burden. It documents both params concisely ('name: Node name', 'target: k8s target name from config') and cross-references node_list for valid names, but gives no format, default, or optionality detail for target.

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 (Describe) and resource (node) and enumerates the returned facets (capacity, allocatable, conditions, taints), which clearly separates it from node_list. Sibling differentiation is only implicit via the node_list cross-reference rather than stated explicitly.

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

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

Usage is implied – describe a single node's detailed state – but there is no explicit when-to-use, when-not, or comparison against node_list/node_top. The 'see node_list' pointer helps locate a name but is not guidance on choosing this tool.

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

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

readOnlyHint=true already covers the safety profile, and the description adds genuine context by naming the fields returned (name, status, roles, version, schedulable, age). It stops short of describing pagination or output format, but adds real value beyond the annotation.

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

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

Front-loaded [READ] + verb + resource + returned fields, followed by a compact Args note. Efficient, with the return columns parenthetically structured rather than padded.

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

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

For a one-param read tool with no output schema and readOnlyHint set, the description is complete enough: it covers purpose, returned fields, and the param's default behavior. Only minor absence of pagination/ordering details.

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

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

Schema coverage is 0% for the single target param, but the description compensates by defining it as a k8s target name from config and explaining that omitting it falls back to the default. This adds meaning the bare schema does not carry.

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

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

States a specific verb (List) and resource (cluster nodes), and even enumerates the returned columns (name, status, roles, version, schedulable, age). This clearly distinguishes it from siblings like node_describe, node_top, and cordon_node.

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

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

The [READ] tag and List framing imply a read-only enumeration, but the description gives no explicit when-to-use guidance versus node_describe or node_top. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the metrics-server dependency and the graceful degradation ('available: False' with a message), which 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?

Front-loads the [READ] tag and purpose, then the precondition, then the arg. Every sentence earns its place, though the docstring-style formatting is slightly heavier than needed for one parameter.

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

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

For a single-parameter read tool with annotations and no output schema, the description covers the precondition, fallback behavior, and parameter usage. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 0%, so the description carries the full burden for the single parameter. It does so adequately by explaining that 'target' is a k8s target name from config and that omitting it uses the default.

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

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

States a specific verb and resource ('CPU/memory usage per node') and implicitly contrasts with the sibling pod_top by scoping to nodes. An agent can tell exactly what data it returns without opening the schema.

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

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

Provides clear context that metrics-server is required and what happens otherwise, which is the key gating condition for use. It stops short of explicitly naming pod_top as the alternative for pod-level metrics or stating when not to use it.

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

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

readOnlyHint=true already establishes the safety profile, so the description only needs to add context. The [READ] tag and the enumeration of returned sections add modest value, but nothing about permissions, output volume, or truncation is disclosed.

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

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

Front-loaded with the purpose and the diagnostic use case, then a compact Args block. Every line earns its place, with only the bracketed [READ] marker being slightly redundant given the annotation.

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 listing the returned sections and the scenarios it serves, and all three params are addressed. It is adequate for a read-only single-resource tool, though multi-namespace or error behavior is unstated.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does add real meaning: namespace omission defaults to the target's namespace, name points at pod_list for discovery, and target is tied to config. "target" is still vague about how a multi-cluster target is chosen.

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 plus the payload it returns (status, conditions, container states, recent events), which is more concrete than most describe tools. It does not distinguish itself from the nearby pod_get or pod_health_rca siblings, so an agent still has to infer the boundary.

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 fastest single call to diagnose why a pod is not Ready (CrashLoopBackOff, ImagePullBackOff, scheduling failures)" gives a clear triggering situation and frames it against slower multi-call alternatives. It stops short of naming the competing tools (pod_get, pod_health_rca) or stating when not to use it.

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

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

readOnlyHint=true already declares the safety profile, so the '[READ]' tag is redundant. The description does add genuinely new behavioral context — omitting namespace falls back to the target's default namespace — but says nothing about what 'detail' is returned or its format.

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

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

The purpose is front-loaded in a single sentence, followed by a compact Args block that maps each parameter to its meaning. Little waste, though the bracketed '[READ]' prefix duplicates the annotation.

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

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

With no output schema and only readOnlyHint in annotations, the description should clarify what 'detail' means (raw manifest vs summarized fields). It covers inputs adequately but leaves the return contract unspecified for a detail-retrieval tool.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: it explains name (pod name, with a pod_list cross-reference), namespace (omit to use default), and target (k8s target from config) for all three parameters. It substantially compensates for the empty schema, though it gives no format or example values.

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 ('Return detail for a single pod by name') with clear singular scope, distinguishing it from the list-family siblings (pod_list, event_list). However, it does not differentiate from pod_describe, which is also a single-pod detail sibling, leaving ambiguity about which one an agent should pick.

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

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

Usage is only implied: it points to pod_list for name lookup and explains the namespace default. There is no explicit when-to-use guidance and no exclusion against pod_describe or pod_logs, so the agent must infer the choice.

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

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

readOnlyHint already covers safety, but the description adds real value beyond annotations: it discloses the worst-first ordering and that each finding cites the triggering reason string/restart count plus a concrete kubectl action. No mention of rate limits or permissions, but the output-shape disclosure is a meaningful addition.

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

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

Front-loaded with the [READ] tag and the scan scope, then the return shape, then args. Efficient overall, with only minor redundancy between 'Omit namespace to scan all' and the namespace arg line restating the same rule.

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

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

With no output schema, the description still explains the return shape (worst-first findings with reason strings and suggested actions), all three optional params, and the scoping behavior. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: namespace is explained with its omit-for-all behavior, label_selector gets a concrete example ("app=web"), and target is explained as a config name defaulting to the default. All three params are covered, though no format details for target values are given.

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

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

States a specific verb (scan) and resource (pods) plus the exact failure modes it targets (CrashLoopBackOff, image-pull failures, OOMKilled, unschedulable Pending, high restarts). This clearly separates it from pod_list, pod_describe, and workload_readiness_rca without opening any schema.

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

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

Tells the agent when to reach for it (diagnosing broken pods) and gives the scoping rule 'Omit namespace to scan all.' It does not explicitly name alternatives such as pod_describe or pod_logs or state when-not to use it, so it lands just short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered and the '[READ]' tag is redundant. The description adds real value beyond that by disclosing the returned fields and the namespace-scoping behavior, which matters since there is no output schema. It omits pagination/limit behavior for large clusters.

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 purpose, then usage, then args, so the important routing info comes first. Minor redundancy: the namespace omit-for-all rule is stated once in prose and again in the Args block, which slightly dilutes conciseness.

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

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

For a read-only list tool with annotations covering safety and no output schema, the description supplies purpose, alternative, params, and return columns. Remaining gaps are minor: no mention of result size/pagination or other relevant diagnostic siblings.

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

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

Schema description coverage is 0%, so the description must carry the full burden and does: it documents all three params, gives the label_selector syntax with an example ('app=web'), and explains the target default and the namespace omit-for-all semantics. Nothing 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?

States a specific verb and resource ('List pods') and even enumerates the returned columns (name, namespace, phase, ready, restarts, node, age). It explicitly differentiates itself from the sibling pod_get ('Use pod_get for full detail'), so an agent can route between them 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?

Gives explicit conditional guidance ('Omit namespace to list across all namespaces') and names the alternative for detail (pod_get). It lacks guidance against other nearby siblings like pod_describe or pod_health_rca, but the core when-to-use is clear.

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

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

readOnlyHint=true already declares the safety profile, and the description reinforces it with '[READ]'. It adds useful behavioral context beyond annotations: the default tail of 100 lines, the default-namespace fallback, and the container requirement for multi-container pods.

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 primary action is front-loaded in the first sentence, followed by an efficient Args list. No wasted prose, though the '[READ]' tag slightly duplicates the annotation.

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

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

For a read-only log-fetching tool with no output schema, the definition covers scope, defaults, and all parameters adequately. It could mention return format (timestamps, multi-container output) but nothing critical to 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?

With 0% schema description coverage, the description carries the full burden and documents all five parameters (name, namespace, tail_lines, container, target). The explanations for namespace default, tail_lines meaning, and container-conditional requirement add real meaning, though name and target are described only thinly.

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

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

The description gives a specific verb (Return) and resource (most recent log lines for a pod) with a default scope of 100 lines. It is clearly distinguishable from sibling read tools like pod_get or pod_describe, though it does not explicitly say so.

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

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

There is no guidance on when to use this tool versus alternatives such as pod_describe, pod_health_rca, or event_list, nor any exclusions or prerequisites. The only conditional hints ('omit for the target's default namespace', 'required only for multi-container pods') are parameter-level, not usage-level.

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

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

Annotations only declare readOnlyHint=true, so the description adds real value: it discloses the metrics-server dependency and the failure mode (returns available: False with a clear message). That is exactly the kind of context annotations cannot provide; it stops short of detailing return fields or rate limits.

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

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

Front-loaded with a bracketed read tag and the one-line purpose, followed by the failure behavior and a compact args block. Every sentence carries load and nothing is padded.

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

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

With no output schema, the description correctly notes the notable return case (available: False when metrics-server is absent). Combined with full parameter coverage and the readOnly annotation, an agent has enough to call it; only return-field detail and sibling routing are missing.

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

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

Schema description coverage is 0%, so the description must carry both parameters, and it does: namespace with its omit-semantics and target as the config target name. This meaningfully compensates for the empty schema, though 'target' is described a bit thinly.

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?

It states a specific verb+resource combination: per-pod CPU/memory usage. 'Per pod' implicitly distinguishes it from the sibling node_top, though it never names an alternative. The purpose is unmistakable to an agent.

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

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

The description gives a precondition (metrics-server required) and parameter context (omit namespace for all namespaces), which implies usage. But it never says when to choose this over pod_describe, pod_health_rca, or node_top, leaving comparison to inference.

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

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

Annotations declare readOnlyHint=true. The description's [READ] tag repeats this and adds default namespace behavior ('omit for target's default namespace') plus target config origin, but does not disclose error behavior, output format, or permissions. With annotations covering safety, this is adequate but not rich.

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?

Two-line description plus a compact Args list. It is front-loaded with the read marker and purpose; every line adds value.

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

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

No output schema exists, and the description does not describe what detail is returned or any error modes. Parameters and read-only nature are covered, but an agent lacks return-value context for a get 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 coverage is 0% and all three parameters are explained: name points to pvc_list as source, namespace explains default omission, and target explains config origin. This compensates well for the lack of schema descriptions, though the name format is still minimal.

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 ('Return detail') and resource ('single PVC by name'), and the [READ] marker reinforces scope. It is clearly distinct from pvc_list, which lists multiple PVCs.

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?

References pvc_list for name lookup, implying pvc_get is for retrieving one PVC's details. However, it gives no explicit when-to-use, when-not-to-use, or alternatives among other get tools; usage is only implied.

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

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

Annotations already declare readOnlyHint=true, and the '[READ]' tag merely repeats that. The description does add useful context by listing what each claim returns, but says nothing about pagination, volume of results, or auth/target resolution beyond the arg hint.

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

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

One front-loaded sentence with the verb, resource, and returned fields, followed by a terse Args block. No filler, though the '[READ]' tag is redundant with annotations.

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

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

For a read-only two-param list tool with no output schema, the description covers both parameters and enumerates the fields returned, which is sufficient for correct invocation. Minor gaps remain around result size/pagination but are not blocking.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: it explains namespace omission semantics and that target is the 'k8s target name from config'. Both params are covered, though no format/example for the target string is given.

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

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

States a specific verb+resource ('List persistent volume claims') and even enumerates the returned fields (name, status, capacity, class, age). It is clearly distinguishable from pv_list and storageclass_list by resource, though it does not explicitly call out the sibling boundary.

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?

'omit for all namespaces' gives a clear conditional for the namespace argument, which implies when to scope vs. not. However there is no explicit when-to-use vs. pvc_get or other storage listing alternatives, so usage is only implied.

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

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

The readOnlyHint=true annotation already covers the safety profile, so the "[READ]" prefix adds nothing. The description does add value by listing the returned columns and explaining the default-target behavior, but omits scope (all namespaces vs one) and pagination behavior for what could be a large cluster-wide listing.

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?

Two terse lines with the operation and return columns front-loaded; the Args stanza is compact and readable. The "[READ]" tag is redundant with the readOnlyHint annotation, a minor waste of the opening position.

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 one optional parameter, no output schema, and read-only annotations, the definition covers the essentials including return field names and the default-target fallback. Remaining gaps (namespace scope, pagination, sort order) are minor for a simple list tool.

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

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

Schema description coverage is 0% and the schema only offers a bare "Target" string with default null, so the description must compensate — and it does, explaining that target is a k8s target name from config and that omission falls back to the default. That is meaningfully more than the schema alone provides.

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

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

States a specific verb and resource ("List persistent volumes") and enumerates the columns returned (name, capacity, status, claim, class, age). It is distinguishable from sibling pvc_list/statefulset_list by explicit resource noun, though it never names an alternative to disambiguate against.

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

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

No when-to-use or when-not-to-use guidance and no named alternatives against ~50 sibling tools. The only procedural hint is "omit to use the default" for the target argument, which is parameter-level rather than task-level context.

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

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

The readOnlyHint annotation already declares the safe read profile, and the "[READ]" tag merely restates it. The description usefully discloses the return columns, but says nothing about pagination, result limits, or performance on large clusters.

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 verb and resource, followed by return fields, then a compact Args block. No filler, though the "[READ]" prefix is redundant with the annotation.

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

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

For a two-parameter read-only list with no output schema, the definition is nearly complete: it covers scoping behavior, the target selector, and the shape of returned rows. Only pagination/limit behavior is unaddressed.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so capably: namespace is explained ("omit for all namespaces") and target is glossed as "k8s target name from config". This meaningfully clarifies both parameters beyond the bare null-defaulted schema.

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

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

States a specific verb and resource ("List replicasets") and even enumerates the returned fields (name, namespace, desired/ready, age). It does not explicitly point to a sibling, but the resource name is distinctive enough against job_list/cronjob_list/deployment_list that confusion is unlikely.

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 one concrete usage rule ("omit namespace for all namespaces") and documents the target selector, which is helpful context. However, it gives no when-to-use framing versus the get/describe siblings and no indication of when listing is preferable.

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

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

The [READ] tag and readOnlyHint=true already establish the safe-read profile. The description adds the useful detail that revisions derive from replicasets, but says nothing about ordering, how many revisions are returned, or pagination, so it adds only moderate context beyond the annotation.

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

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

Front-loaded with the [READ] marker and purpose, then a tight Args list. No filler sentences; each line maps to a parameter.

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

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

A read tool with no output schema and three documented params is adequately covered for invocation, but the description omits anything about the returned revision structure or ordering, which the agent must guess. Adequate, not rich.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely does: name is the deployment name, namespace defaults to the target's default namespace, and target maps to the config entry. Only target's meaning ("k8s target name from config") remains somewhat thin.

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

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

States a specific verb+resource ("List a deployment's rollout revisions") and adds the source of those revisions ("from its replicasets"), which is a meaningful clarification. It does not explicitly distinguish itself from siblings like rollout_status or undo_list, so it stops short of a 5.

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

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

The description never says when to use this versus rollout_status, undo_list, or replicaset_list, nor does it state prerequisites or exclusions. Usage is only implied by the tool name, leaving the agent to infer routing.

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

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

Annotations declare destructiveHint=true and non-idempotent, giving the safety profile. Description adds the useful dry_run preview path and the inverse relationship, though it doesn't say what happens to in-flight pods or reversibility beyond the inverse tool. Adds real value beyond 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?

Front-loaded write/risk tag, purpose, inverse, and dry-run note, followed by a compact Args block. Every line earns its place with zero padding.

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

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

With no output schema and 0% schema coverage, the description must carry params and behavior; it does both reasonably well for a 4-param mutation tool. Minor gap: no explicit output/return info, though this is largely implied by the write semantics.

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

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

Schema coverage is 0%, so the description carries the full parameter burden. It documents all four params including namespace default behavior and dry_run semantics, which is essential given the schema has no descriptions. It's complete but terse; no syntax/format details for name or target.

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

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

Specific verb+resource ('Pause a deployment's rollout') with the inverse named explicitly (rollout_resume), which clearly distinguishes it from siblings like rollout_resume and rollout_restart_deployment.

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?

Names the inverse tool and gives the dry_run preview path, which is clear guidance for when to preview vs act. Doesn't explicitly state when-not-to-use or prerequisites, but the inverse and dry-run hints cover the main routing decisions.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so safety is partly covered. The description adds meaningful context beyond them: 'No clean undo' and the dry_run preview path, which is exactly the kind of operational guidance an agent needs before a mutating call.

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 action and risk tag, followed by the dry_run preview note and a compact args list. Every line is useful, though the Args block is a slightly mechanical enumeration.

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

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

For a mutation tool with annotations covering the safety profile and no output schema, the description supplies the remaining essentials: operation class, irreversibility, and a safe preview mechanism. Nothing critical 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 0%, so the description carries the full burden and does list all four parameters. It adds real meaning for namespace ('omit for the target's default namespace') and target ('k8s target name from config'), but name and dry_run are essentially restatements of the parameter names, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Trigger a rolling restart of a deployment'), which cleanly separates it from siblings like rollout_undo_deployment, rollout_pause, and scale_deployment. The [WRITE] tag signals the operation class immediately.

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

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

The description tells the agent how to preview safely (dry_run=True) and warns there is no clean undo, which implies caution. However, it never says when to choose this over adjacent tools such as rollout_undo_deployment or set_deployment_image, leaving the selection logic to inference.

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

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

Annotations already declare non-read-only and destructiveHint=true, so the safety profile is partly covered; the description adds a medium-risk classification and, more usefully, the dry_run preview mechanism, which is not expressed in annotations. It stops short of describing effects on in-flight pods or permissions needed, and the 'risk=medium' label sits somewhat awkwardly against destructiveHint=true.

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 operation class, risk, and the inverse relationship in sentence one, then preview semantics, then the args block. Slight repetition of dry_run between the summary and the args list is acceptable given the zero schema coverage.

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

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

For a 4-parameter mutation tool with no output schema, the description covers action, safety, the inverse alternative, and every parameter's meaning. Missing only the post-resume effect description and any permission prerequisites.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden and largely does: it explains name, namespace default ('omit for the target's default namespace'), dry_run behavior, and the origin of target ('k8s target name from config'). Only target's semantics beyond provenance remain thin.

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

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

States a specific verb+resource ('Resume a paused deployment's rollout') and immediately differentiates from a sibling by naming the inverse operation, rollout_pause. The [WRITE][risk=medium] tag adds operation class up front.

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

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

Gives the selecting condition (a paused rollout) and names rollback point to rollout_pause as the inverse. It also tells the agent how to safely trial the action via dry_run=True, but does not say when to prefer rollout_undo_deployment or other rollout_* siblings.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered, and the '[READ]' tag is somewhat redundant. However, the description goes beyond annotations by disclosing exactly what status fields are returned (desired/updated/available/unavailable + paused), which is genuinely useful given there is 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?

Front-loads the purpose with a clear result summary, then lists args compactly. The args section is somewhat duplicative of the schema, but with 0% schema coverage that repetition is justified rather than wasteful.

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

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

For a read-only status tool with no output schema and no annotation richness beyond readOnlyHint, the description supplies the returned fields and documents all three parameters, leaving little an agent needs missing. Only the alternative-tool routing is absent.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: name (deployment name), namespace (with the 'omit for default namespace' fallback behavior), and target (the k8s target name from config). This adds meaning beyond type-only schema fields.

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 (read) and resource (rollout status) and even enumerates the returned fields (desired/updated/available/unavailable + paused), which clearly separates it from rollout_history. It stops short of naming the sibling it is not, so it is not a full 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as rollout_history or deployment_get, which overlap with inspecting rollout state. Usage is only loosely implied by the '[READ] Rollout status' framing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further by warning there is 'No clean automatic inverse' and explaining the manual recovery path (re-deploy the intended image/revision). That irreversibility/recovery detail is genuinely additive beyond the structured hints.

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

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

The risk tag and rollback semantics are front-loaded in the first two lines, and the Args block is terse. The Args section duplicates schema fields, but that duplication is justified given 0% schema description coverage.

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

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

For a high-risk, non-idempotent mutation with no output schema, the description covers default behavior, dry-run preview, and the absence of an automatic inverse. It stops short of stating required permissions or failure modes, but the essentials for correct invocation are present.

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

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

Schema description coverage is 0%, so the description must carry the load, and it documents all five parameters including the non-obvious 'to_revision: 0 = previous' convention and the namespace omission default. 'target: k8s target name from config' is the thinnest entry, leaving a small gap, but overall it compensates well for the empty schema.

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

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

States a specific verb and resource ('Roll a deployment back to a prior revision') and advertises the default target revision. It does not, however, distinguish itself from nearby siblings such as undo_apply, undo_list, or rollout_restart_deployment, which an agent could plausibly confuse with this 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?

Gives implied usage context via 'Defaults to the immediately previous revision' and 'Pass dry_run=True to preview', which tells the agent when a preview is appropriate. There is no explicit when-not-to-use or pointer to alternative tools like rollout_history for inspecting revisions before choosing to_revision.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the safety profile is covered. The description adds genuine value beyond that: it discloses the return value ('previous_replicas so the change can be undone') and the dry_run preview semantics, including that previews record no undo. It doesn't discuss permissions or rollback caveats, but it meaningfully extends the annotations.

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

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

Front-loaded with the operation tag and core statement, then return/undo behavior, then a structured Args list. Efficient overall, though the dry_run behavior is stated twice (once in prose, once in Args), which is a minor 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 correctly discloses the return value (previous_replicas) and covers all parameters and the dry_run/undo semantics. For a medium-risk write tool this is close to complete; only permission requirements and confirmation of what happens to an in-flight scaling operation are absent.

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

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

Schema description coverage is 0%, so the description must carry the param burden, and it documents all five via an Args block. It adds real meaning the schema lacks, e.g., namespace 'omit for the target's default namespace' and target 'k8s target name from config'. Values are terse but sufficient for correct invocation.

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

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

States a specific verb+resource ('Scale a deployment to replicas'), and the [WRITE][risk=medium] tag immediately signals the operation class. The resource is unambiguous enough to distinguish it from the sibling scale_statefulset, and the inverse relationship ('restore previous count') clarifies its place in the write operations.

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

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

Gives clear context on when to use dry_run=True (preview without changing anything, no undo recorded) and notes the inverse operation for reverting. It stops short of explicitly naming an alternative tool (e.g., rollout_undo_deployment or scale_statefulset) or stating when NOT to use it, but the operational 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?

Annotations already mark it destructive, non-idempotent, non-read-only; the description adds real value beyond them by disclosing the inverse operation ('restore previous count'), the risk level, and that a preview records no undo entry. It stops short of stating permission requirements or the effect on running pods, but the safety-relevant context is solid.

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 action and risk tag, then the dry_run caveat, then a clean Args list. Minor redundancy: 'Pass dry_run=True to preview without scaling' is restated in the per-arg line for dry_run.

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

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

No output schema exists, so return values need not be explained, and annotations cover the destructive profile. The description adds undo and dry_run semantics plus all parameter meanings, leaving only minor gaps such as auth requirements and workload impact.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it documents all five params: name, replicas, namespace ('omit for the target's default namespace'), dry_run, and target ('k8s target name from config'). The namespace default and target meaning go beyond the bare schema, though 'target' is still somewhat circular.

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 resource ('statefulset') with the scaling target ('to ``replicas``'), plus a '[WRITE][risk=medium]' tag. The named resource inherently separates it from the sibling scale_deployment, so an agent can route correctly without opening either schema.

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

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

Explicitly describes the preview path ('Pass dry_run=True to preview without scaling') and notes the inverse/undo relationship. It does not name a sibling alternative or state when-not-to-use conditions, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds the genuinely useful behavioral fact that secret values are never returned and are redacted to key names. It also implies access is gated by kubeconfig authorization. It does not cover pagination or error behavior, but the added context goes beyond the annotation.

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

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

Front-loads the read-only redaction constraint in the first line, then the usage guidance, then a compact Args block. No sentence is redundant for a two-parameter tool.

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

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

With no output schema, the description fully specifies what is returned (names, types, key names; values redacted) and how each parameter behaves, which is everything an agent needs to call and interpret this tool.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: namespace is documented with the default behavior (omit for all namespaces) and target is defined as a k8s target name from config. Only the accepted target-name values remain unspecified.

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

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

States a specific verb and resource (list secrets) and immediately bounds the scope: only names, types, and key NAMES are returned. This distinguishes it from sibling readers like configmap_get or pod_describe without needing to name them.

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

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

Explicitly tells the agent when to use it: to discover which secrets and keys exist, then mount/reference them through the authorized workload. That is a clear usage context, though it never names an alternative tool or an exclusion condition the way a 5 would.

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

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

The readOnlyHint annotation already declares the safety profile, and the "[READ]" tag merely restates it. The description does add value by disclosing the returned fields (name, namespace, type, cluster IP, ports), which matters because there is no output schema. It says nothing about error behavior, scope limits, or result ordering.

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

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

Two short clauses plus an args block, with the purpose and scope stated first and no filler. Every line earns its place and the structure is easy to scan.

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

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

With no output schema, the description usefully names the returned fields, the annotations cover read-only safety, and both parameters are documented. Missing only minor operational detail such as behavior on invalid namespace or empty results, which is acceptable for a simple list 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 coverage is 0% and the schema supplies only bare titles, so the description carries the full burden and mostly meets it: it explains that namespace can be omitted to span all namespaces, and that target is a k8s target name from config. The target explanation is a little thin (which config, what values), but both parameters are meaningfully addressed.

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 services") and enumerates the fields returned (name, namespace, type, cluster IP, ports), which lets an agent distinguish it from the many other *_list siblings such as pod_list, deployment_list, and endpoints_list. It stops short of explicitly naming an alternative or contrasting sibling, so it is clear but not maximally differentiated.

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

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

There is no when-to-use/when-not guidance and no named alternative, even though the sibling set contains many overlapping list tools. The only usage hint, "omit for all namespaces," is parameter-level rather than tool-selection guidance. An agent must infer the intended context from the tool name alone.

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 the destructive and non-idempotent profile, but the description adds genuine value beyond them: it discloses that the return includes previous_image enabling undo, that dry_run previews without mutation, and that no undo record is created for a preview. These are meaningful behavioral traits not captured by the annotations.

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

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

Front-loads the operation type and risk tag, then behavior, then a clean Args list. Well organized with little waste, though the [WRITE][risk=medium] prefix slightly duplicates what the annotations already convey.

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

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

For a mutation tool with no output schema, the description supplies the key return contract (previous_image) and safety behavior (dry_run, no undo on preview). Combined with annotations covering the safety profile, an agent has enough to invoke it correctly; only the precise rollback mechanism is left implicit.

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

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

Schema description coverage is 0%, so the description must carry the load, and it documents all six parameters in the Args block with useful detail: image format example ('nginx:1.27'), container scoping within the pod template, namespace defaulting, and target origin from config. It doesn't clarify the interaction between name/namespace/target beyond defaults, but coverage is substantially better than the empty schema.

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

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

States a specific verb and resource ('Update a deployment container's image') that clearly differentiates it from siblings like scale_deployment, rollout_restart_deployment, and rollout_undo_deployment. The [WRITE][risk=medium] tag scopes the operation type immediately.

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

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

The description implies usage via the 'Inverse: restore previous' framing and the dry_run preview path, and points to deployment_get for the container name. However, it never explicitly states when to prefer this tool over related mutation siblings such as rollout_restart_deployment or rollout_undo_deployment, leaving routing partly to inference.

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

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

Annotations declare readOnlyHint=true and the '[READ]' prefix is consistent with that, so the safety profile is covered. The description adds small behavioral context (namespace defaults to the target's default namespace, target comes from config) but says nothing about error behavior or what a missing resource yields.

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 single-sentence summary followed by a compact Args block; nothing is padded. The Args lines slightly restate schema property names, but each carries added meaning (source of the name, defaulting behavior), so nearly every token earns its place.

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

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

For a simple read tool with no output schema, the description covers selection, parameters, and defaulting adequately. It stops short of indicating what 'detail' is returned (spec/status shape), which is the one gap given there is no output schema to fall back on.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does document all three: name (with a pointer to statefulset_list), namespace (omit for default), and target (k8s target name from config). It adds real semantics beyond the bare schema titles, though it doesn't clarify required vs optional — which the schema already handles.

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 ('Return detail') and resource ('a single statefulset by name'), and the '[READ]' tag plus the singular scope cleanly distinguishes it from the sibling statefulset_list. An agent can identify the tool's job without opening the schema.

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

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

It points to statefulset_list for name lookup and explains that namespace can be omitted to use the target's default, which is useful context. However, it never states when to prefer this over pod_describe / *_get siblings or what happens if the statefulset doesn't exist; usage is implied rather than spelled out.

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

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

readOnlyHint=true is already declared by annotations, so the safety profile is covered; the description's real contribution is disclosing the returned fields (name, namespace, desired/ready/current, age), which matters because there is no output schema. It still says nothing about pagination or volume limits on large clusters, which keeps it short of a 5.

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

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

Two compact blocks, purpose first, then a tight Args list. No sentence is wasted; the '[READ]' tag is mildly redundant with the annotation but costs almost nothing.

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

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

For a simple two-optional-parameter list tool with no output schema and no required params, the description covers the scope semantics and the return shape adequately. Minor gaps remain around pagination/ordering and what 'target' values are acceptable.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does document both parameters: namespace ('omit for all namespaces') and target ('k8s target name from config'). The target explanation is thin about what values are valid, but both params get meaning that the bare schema lacks.

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

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

The description gives a specific verb and resource ('List statefulsets') and enumerates the returned columns (name, namespace, desired/ready/current, age). It is clear enough to distinguish list from the statefulset_get sibling, but it never explicitly names that alternative, so it stops short of full sibling differentiation.

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

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

Usage is only implied: the '[READ]' tag and 'List' verb signal a read-only enumeration, and 'omit for all namespaces' hints at the scoping choice. There is no explicit when-to-use vs when-to-use-something-else guidance (e.g., use statefulset_get for a single object).

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, and the '[READ]' tag is consistent with it. The description adds value by enumerating the fields returned, but says nothing about pagination, result volume, or whether it queries all clusters.

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?

Two short lines, front-loaded with the read tag and the resource, followed only by the one piece of arg guidance that matters. No filler sentences.

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

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

For a single-parameter, read-only list tool with no output schema, the description covers purpose, returned fields, and the sole parameter's default behavior. 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 0% — the 'target' property has only a title and a null default, no description. The description compensates by explaining that target is a k8s target name from config and that omitting it falls back to the default, which is genuine information absent from the schema.

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

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

States a specific verb ('List') and resource ('storage classes') and even previews the returned fields (name, provisioner, reclaim policy, default). The resource name alone disambiguates it from every sibling list/get tool, though it never explicitly contrasts itself with a sibling.

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

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

Usage is implied by the resource name and the '[READ]' prefix, and the Args note tells the caller how to select a cluster target. There is no explicit when-to-use statement, no mention of alternatives, and no prerequisites (e.g., cluster-scoped resource, RBAC needs).

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

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

Annotations already declare write (readOnlyHint false), destructiveHint true, and non-idempotent. The description adds the [WRITE][risk=medium] tags, the inverse relationship, and the dry_run preview capability, which is useful behavioral context beyond annotations; it stops short of permission or side-effect detail.

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?

Compact and front-loaded: write/risk tag, purpose, inverse, dry-run note, then a parameter list. The only redundancy is dry_run appearing twice, which is conventional for an Args block.

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

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

For a write tool with no output schema and full annotation coverage, the description gives an agent enough to invoke it correctly: purpose, inverse, dry-run preview, and each parameter. It omits permissions and the exact effect on already-schedulable nodes, but those are minor gaps.

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

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

Schema coverage is 0%, so the description carries the burden. It explains all three parameters: name (with a pointer to node_list), dry_run (preview behavior), and target (k8s target name from config). The target definition is thin, but overall it compensates for the empty schema.

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

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

States a specific verb and resource ('Mark a node schedulable again') and explicitly names the sibling it inverts ('Inverse: cordon_node'), so an agent can distinguish it from cordon_node and drain_node without opening schemas.

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

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

Provides clear context: use to reverse a cordon, with dry_run for preview. It does not state when not to use or list alternatives beyond the inverse relationship, but routing is implied by the inverse label.

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 cover the safety profile (destructive, non-idempotent, not read-only), and the description adds value beyond them: the inverse runs through its own governed/audited tool with its own risk tier, dry_run previews it, and a token can only be applied once. The [WRITE][risk=medium] label and single-use constraint are meaningful behavioral disclosures.

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

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

Front-loads the [WRITE][risk=medium] tag and the core action, then follows with useful behavioral notes and an Args section. It is slightly longer than necessary (some prose could be tightened), but every element earns its place.

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

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

For a mutation tool with no output schema, the description explains the dispatch mechanism, audit behavior, single-use constraint, and preview option. It does not spell out the concrete effect (which depends on the dynamic inverse tool), but that is inherent to this indirection pattern.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does: undo_id is sourced from undo_list, dry_run previews the inverse without executing, and target is passed through only when the inverse accepts one. All three parameters are given meaning the schema does not provide.

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

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

States a specific verb and resource ('Apply a recorded undo by dispatching its inverse tool') and distinguishes itself from undo_list by sourcing the undo_id there. An agent can tell it apart from the sibling undo_list and the rollout_undo_deployment tools without opening a schema.

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

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

Clearly says how to obtain the undo_id (from undo_list or an _undo_id in a write result) and when to use dry_run=True to preview. It lacks an explicit 'when not to use' or a direct comparison to rollout_undo_deployment, but the triggering context is well established.

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 supply readOnlyHint=true; the description goes well beyond that by disclosing the return shape, that truncation is *measured* via an extra-row fetch, and that effectVerified=false means the reversed change is only PROBABLE, with a caution to check live state and not over-report. This is meaningful operational context the annotations cannot carry.

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 purpose and the sibling handoff, then structured paragraphs for return value and the effectVerified caveat. Every sentence carries information, though the emphasis on truncation being 'measured, not guessed from a length coincidence' is slightly verbose for the value it adds.

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 supplies the return JSON shape, the meaning of every field an agent must act on (returned, limit, truncated, effectVerified), and the follow-up behavior for truncation. Nothing needed to call or interpret it correctly is missing.

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

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

Schema description coverage is 0% and no param has an enum, so the description must compensate, and it does fully: limit is documented as default 50 / capped at 500, and target is documented as ignored with the reason (host-local undo state, kept for CLI uniformity).

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

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

States a specific verb and resource ('List recorded, not-yet-applied undo tokens') plus ordering ('most recent first'). The [READ] tag and the reference to undo_apply make it clearly distinguishable from the sibling that actually applies tokens.

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

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

Explicitly routes the agent: 'Use the undoId with undo_apply.' and tells it to re-run with a higher limit when truncated rather than reporting a partial list as complete. It lacks an explicit 'when not to use this' condition, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description goes further by disclosing result ordering (worst-first), what each finding contains (measured ready/desired ratio or failing condition reason), and that an actionable kubectl command is attached. It stops short of noting cost, pagination, or cluster-connectivity requirements.

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?

Purpose is front-loaded in the first sentence, return behavior second, arguments last, with a [READ] marker for instant scanning. The args block is necessary precisely because the schema has no descriptions.

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

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

With no output schema, the description correctly explains the return shape (worst-first findings with ratio/condition and a kubectl action) and documents both parameters. It is essentially complete for a two-param read-only diagnostic tool, missing only environment or operand notes.

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

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

Schema description coverage is 0%, so the description carries the burden and does so: it defines 'namespace' as a scope with 'omit for all namespaces' and explains that 'target' is a k8s target name from config defaulting to the configured default. Both parameters gain clear semantics the bare anyOf/null schema lacks.

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

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

The description names a specific verb (Scan) and enumerates the exact resource kinds (Deployments/StatefulSets/DaemonSets) plus the failure modes it detects (ready-vs-desired shortfalls, zero-ready outages, rollout-stuck). This scope alone distinguishes it from narrower siblings like rollout_status or pod_health_rca.

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

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

Usage is implied by the listed conditions - an agent can infer it should reach for this when workloads seem under-ready - but there is no explicit when-to-use framing and no mention of alternatives such as pod_health_rca or rollout_status. The 'omit...' sentences are parameter defaults, not routing guidance.

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