lint_manifests

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.