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

With no annotations, the description carries the full burden. It does disclose useful behavior: scope is limited to passed files, some findings are informational when a resource may legitimately live elsewhere, and selector mismatches are flagged invalid. It does not cover severity model beyond that, or whether it fails or reports when nothing is 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 tool's core action and the check range (K8S2001-K8S2017), then a dense list of detected cases. The enumeration is long but each item is a distinct, actionable check; only the closing scope sentence could be tighter.

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?

An output schema exists, so return shape needn't be explained. The description covers what is checked and the scoping caveat well, but for a tool in a crowded linting family it leaves the crucial selection question, when to prefer this over lint_manifests or rbac_review, unanswered.

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 single required 'path' param is undocumented in the schema, so the description must supply meaning. It partially does by implying path may be a directory ('Pass a directory to check a whole app'), but never states whether a single file is also accepted or what formats are expected.

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?

Names a specific operation (cross-resource reference checks) and enumerates the concrete failure classes it detects (selector/label mismatch, dangling Service/Ingress/HPA targets, missing ConfigMap keys, duplicate objects). This distinguishes it from a plain linter, but it never names or contrasts with siblings like lint_manifests or rbac_review, leaving the boundary to inference.

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: 'Pass a directory to check a whole app' and 'Only the files you pass are considered' give scope hints, but there is no explicit when-to-use vs. lint_manifests or rbac_review, and no prerequisites or preconditions are described.

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?

With no annotations supplied, the description carries the full burden and does a solid job: it discloses a meaningful privacy constraint that the agent (and user) needs — env values, ConfigMap/Secret data, and command arguments are never printed. It doesn't explicitly state read-only/non-mutating behavior or error behavior (e.g., what happens when the kind/name isn't found), which keeps it from 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?

Dense but front-loaded: the core purpose opens the sentence and the parenthetical enumerations are informative rather than filler. The long embedded list of posture dimensions is slightly wall-of-text, but every clause carries information and the trailing privacy and parameter sentences are short.

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?

An output schema exists, so the return shape need not be explained, and the description correctly focuses on scope and on the one behavior an agent can't infer (redacted secret/env/args data). The unexplained required `path` parameter is the remaining gap for a four-parameter tool with zero schema descriptions.

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

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

Schema coverage is 0%, so the description must compensate and it only partly does: it clarifies `kind` ('e.g. Deployment' — a Kind, not a filename), `name` (metadata.name), and `namespace` (disambiguator for duplicate names). The required `path` parameter is never explained at all, leaving the agent to guess whether it is a file, a directory, or a manifest root.

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?

Names a specific verb and scope ('Explain one object in plain English') and then enumerates exactly what the explanation covers: security posture, dependencies, inbound traffic, and lint findings. An agent can tell this is a single-object deep dive rather than a repo-wide scan like lint_manifests or check_references.

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

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

Usage is only implied by the enumeration of contents; there is no explicit statement of when to pick this over lint_manifests, check_references, or rbac_review, which overlap on lint findings, references, and security posture. The only concrete guidance is 'pass `namespace` if the name exists in several', which is parameter advice rather than tool selection guidance.

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

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

With no annotations, the description must carry the behavioral burden. 'Summarize' implies a read-only analysis pass, and the description usefully discloses accepted input shapes (multi-document YAML, helm template output, directories), but says nothing about side effects, failure behavior on malformed YAML, or whether any cluster/auth access is needed.

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 capability, then input semantics, then the next step. The mid-sentence enumeration is long but each item maps to a distinct thing the agent gets back, so it earns its space; only slight tightening would improve it.

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?

An output schema exists, so return values needn't be spelled out, and the description lists enough content to make selection easy while covering the one ambiguous input. Remaining gap is behavioral: no note on invalid/non-Kubernetes YAML or on scope limits of the summary.

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 single parameter has no description, so the description is the only source of meaning. It specifies that `path` accepts a YAML file, a multi-document file, helm template output, or a directory of files — meaningful detail the bare string schema does not convey.

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

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

States a specific verb (Summarize) and resource (Kubernetes manifests), then enumerates exactly what the summary covers: objects by kind/namespace, workloads with replicas/images/ports, Services with selectors, Ingress routes, host-network workloads. The closing 'Start here, then lint_manifests' positions it against the closest 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?

Gives an explicit workflow position ('Start here') and names the follow-up tool (lint_manifests), which is genuine when-to-use guidance. It does not state when to skip this tool or jump straight to check_references/rbac_review, so it stops 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?

With no annotations supplied, the description carries the full behavioral burden and does so: "Nothing is applied to any cluster" declares the read-only, non-mutating nature, and the secret rule explicitly states only name and length are surfaced, never the value — a privacy trait no schema could convey. It also describes the finding shape (rule ID, severity, file:line, concrete fix) and the in-file suppression syntax, which are behavioral details beyond the input schema.

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

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

The core purpose and the alternative-tool routing are front-loaded, and the suppression and non-mutation notes are short and standalone. The middle rule enumeration is a long, comma-spliced run-on that is dense to parse, though every clause does convey actual rule coverage rather than 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?

An output schema exists, so return-value formatting is covered, and the description adds the semantic layer (severity, file:line, fix) plus suppression and safety context. Completeness is only slightly undercut by the unexplained `path` parameter, which is the one thing an agent must get right to invoke it.

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

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

The single `path` parameter has 0% schema description coverage, so the description must compensate but only implicitly implies it points at manifests. It never states whether path is a file, directory, glob, or repo root, nor whether recursion applies — a meaningful gap for a linting tool. Baseline is lowered accordingly, though the rule enumeration gives some indirect sense of what is scanned.

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

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

Opens with a specific verb+resource ("Lint Kubernetes manifests") and then enumerates the concrete rule families K8S1001-K8S1040 it covers, from resource limits to deprecated apiVersions. It also explicitly distinguishes itself from siblings by naming check_references for cross-object checks and rbac_review for RBAC, so an agent can separate it from those 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?

Gives clear routing guidance: cross-object checks belong to check_references and RBAC to rbac_review, which is the main disambiguation an agent needs. It also documents the suppression mechanism (`# kubelint-ignore: K8S1004`). It stops short of covering when to prefer values_review, render_helm, or suggest_fixes, so the routing is partial rather than exhaustive.

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?

No annotations are supplied, so the description carries the full burden, and it does disclose what the analysis looks for and that it enumerates roles and subject bindings. However it never states that the operation is read-only/static, whether a live cluster or credentials are needed, or what happens on an invalid path — meaningful gaps for a file-consuming review tool.

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

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

Front-loaded with purpose, then a compact rule list, then the secondary listing behavior — no filler sentences. The enumerated security checks are dense but each one maps to real detection content, though the run-on comma list is harder to scan than a short bulleted form would be.

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?

An output schema exists, so return-value explanation is not required, and the detection scope is well covered. What is missing is context an agent needs to call it correctly: what `path` points at, whether cluster access is required, and how it differs operationally from the sibling review tools.

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

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

There is a single required parameter, `path`, with 0% schema description coverage, so the description must define it — but it never mentions the parameter at all. It is unclear whether `path` is a file, a directory of YAML manifests, or a Helm-rendered output root.

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 ("Review RBAC") followed by a concrete enumeration of the eleven rule families checked (wildcard verbs, cluster-admin bindings, secret reads, escalate/bind/impersonate, pods/exec, nodes/proxy, anonymous/default-SA bindings). It also states the secondary output (listing Roles/ClusterRoles and their subjects), which clearly separates it from generic siblings like lint_manifests or check_references.

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: an agent can infer it should call this when auditing RBAC manifests. There is no explicit when-to-use statement, no guidance on when to prefer lint_manifests or check_references instead, and no stated prerequisites (e.g. whether the path must be a manifest directory or a live-cluster kubeconfig).

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?

With no annotations supplied, the description carries the full burden and does so well: local subprocess execution, 60 s timeout, no cluster contact, output linted in memory and never written to disk, a hard allow_exec gate, and a clear failure when helm is absent. These are exactly the traits an agent needs before authorizing a local exec.

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?

Dense but front-loaded: 'OPT-IN' and the core action lead, followed by safety and failure details. Parenthetical asides are frequent but each carries real information; no sentence is 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?

For a local-exec tool with an output schema (so return values need not be described), the description covers the safety gate, timeout, side-effect profile, and failure mode. The remaining gap is the semantics of namespace and release_name, which matter for templating results.

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

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

Schema description coverage is 0% across five parameters, so the description must compensate. It explains values_file (optional values YAML inside --dir) and allow_exec (the exec gate) and implies chart_dir, but says nothing about namespace or release_name (defaulting to "release"), leaving two parameters undocumented in both places.

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: it runs the local `helm template` on a chart directory and lints the rendered output in memory. The parenthetical clarifies execution scope (argument list, 60 s timeout, no cluster contact). It does not differentiate itself from siblings such as lint_manifests or values_review, so an agent must 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?

Gives explicit activation guidance: it is OPT-IN and refuses unless allow_exec=true, which should only be set when the user asked to render a chart. That is a clear use condition. It stops short of naming alternatives (e.g., lint_manifests for already-rendered manifests), so the routing 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?

With no annotations, the description carries the full burden and does well: it declares the output is text-only and 'never written', that patches are re-parsed and re-linted in memory to confirm correctness, and that only safe mechanical changes are applied. It does not say what happens when no auto-fixable issues exist (empty diff?) or whether the file must already lint cleanly.

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

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

The core action is front-loaded in the first clause, and the enumerated fix list is dense but each item earns its place by defining the tool's scope. Slightly long sentences with parenthetical examples add bulk but little waste.

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

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

An output schema exists, so return-value shape need not be explained. Given a single-parameter tool with no annotations, the description still covers the mutation-safety profile, the validation step, and the human-decision fallback, which is enough 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 'path' is undocumented in the schema, so the description must compensate. Its phrase 'for ONE manifest file' does add meaning by narrowing the parameter to a single file path rather than a directory or glob, but it says nothing about accepted path formats or relative vs absolute roots.

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 precise verb and resource ('Show a unified diff ... of the safe mechanical fixes for ONE manifest file') and enumerates exactly which fix classes it covers (privileged/hostNetwork/hostPID/hostIPC, allowPrivilegeEscalation, apiVersion renames). This makes it easy to tell apart from lint_manifests, which reports issues rather than proposing a patch, even though the sibling is not named 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?

Scope guidance is present and useful: 'ONE manifest file' and 'Everything else is listed as needing a human decision' set boundaries for what the tool will and will not do. However, there is no explicit guidance on when to reach for this versus lint_manifests or explain_resource, so the agent must infer the 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?

With no annotations, the description carries the burden and does reasonably well: it discloses the exact check categories, notes that credential values are redacted and only key name and length are reported (an important privacy behavior an agent could not infer), and frames the operation as a review rather than a mutation. It stops short of explicitly stating read-only semantics or any failure behavior on unreadable/invalid files.

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, then a compact checklist of checks, then the sibling-routing sentence. Dense but every clause carries information; the parenthetical about redaction is slightly heavy but justified by its privacy significance.

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-parameter read-style reviewer with an output schema available, the description covers what is checked, how credentials are handled, and when to use alternatives instead. The remaining gap is the meaning/format of `path`, which is the only thing an agent could get wrong when calling it.

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 single parameter `path` is undocumented in the schema. The description only implies it via 'Review a Helm values.yaml' — it never says whether path is a file, a chart directory, or how relative paths are resolved, so it adds only marginal meaning beyond the schema.

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

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

States a specific verb and resource ('Review a Helm values.yaml') and enumerates the exact rule set it applies (K8S4001-K8S4007: latest/untagged images, empty resources, committed credentials, empty securityContext, LoadBalancer/NodePort services, replicaCount 1, privileged/runAsUser 0). It also explicitly contrasts itself with render_helm and lint_manifests, so an agent can distinguish it from siblings 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?

Gives an explicit routing rule: this tool reviews chart inputs, while render_helm or `helm template` output plus lint_manifests should be used to review what the chart actually produces. Both the when-to-use and the named alternatives with their selecting condition are present.

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