k8s_triage

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

Discloses read-only nature ('fans out several kubectl get calls only — never mutates the cluster, idempotent'), permission requirements, and error behavior ('Forbidden/absent are skipped rather than aborting'). No annotations provided, but description carries full burden effectively.

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?

Concise and well-structured: star emoji + bold header, bullet list of returns, behavioral paragraph, usage guidance, and parameter details. Every sentence adds value; no fluff.

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

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

Given 3 optional parameters and no output schema, description adequately explains what the tool returns (four categories) and how to use it. All necessary context (permissions, idempotency, error handling) is included.

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 covers all 3 parameters with descriptions (100% coverage). Description's Args section adds default values, format constraints (e.g., '1h', '30m'), and clarifies namespace scoping. Adds value beyond 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?

Description starts with 'Start here for cluster diagnostics' and lists specific outputs (problem pods, warning events, unhealthy nodes, stale deployments). It distinguishes itself from siblings by stating it's the first tool for broad questions, then deeper with k8s_describe/k8s_logs/k8s_events.

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

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

Explicit guidance: 'Use this as the FIRST tool for broad questions... then dig deeper with k8s_describe / k8s_logs / k8s_events.' Also states read-only and cluster-wide read access needed, with graceful handling of forbidden sub-queries.

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