k8s_delete_pod

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

With no annotations, the description carries the full burden. It discloses the destructive action (delete), notes the confirmation requirement (confirm=true), and mentions that the controller recreates the pod—mitigating the destructive effect. However, it does not discuss potential downtime, graceful vs. forced termination, or whether the operation is reversible. These are meaningful gaps for a deletion 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?

Two sentences with no fluff. The core action is front-loaded ('Delete one pod'), the consequence is stated ('so the controller recreates it'), and the essential prerequisite is appended ('confirm=true is required'). Every word earns its place; the structure is clean and efficient.

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?

The description covers the core action and confirmation, but it omits crucial context for a destructive operation: it does not mention the risk of downtime, what happens to the pod's data (non-persistent), or how it relates to the overall Kubernetes state. It also leaves two parameters (namespace, session_name) unexplained. While an output schema exists, the description still falls short for an agent making a high-stakes decision to delete.

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 explain all parameters. It directly addresses the 'confirm' parameter ('confirm=true is required'), which is helpful, but it does not clarify 'pod', 'namespace', or 'session_name'. While 'pod' is obvious from the tool name, 'namespace' and especially 'session_name' are left unexplained, leaving an agent uncertain about their meaning and defaults.

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 ('Delete') and resource ('one pod') and adds the key consequence ('so the controller recreates it'). It clearly distinguishes from sibling tools like k8s_scale or k8s_restart by indicating the deletion-driven recreation mechanism. This is a clear, unambiguous purpose.

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 no explicit guidance on when to use this tool versus alternatives like k8s_restart or k8s_scale. The phrasing 'so the controller recreates it' implies a use case (forcing recreation), but no alternatives, exclusions, or conditions are mentioned. An agent would have to infer the appropriate context.

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