check_references

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.