Skip to main content
Glama

run_kubectl

Executes kubectl commands against a target cluster for read and write operations. Use it for actions not covered by dedicated tools such as scaling, model deployment, or Helm.

Instructions

Execute a kubectl command on a cluster.

Use this only for operations not covered by dedicated tools. Prefer scale_deployment to scale pods, deploy_model for model deployments, and helm_upgrade or helm_uninstall for Helm operations.

Reads always pass: get, describe, logs, top, rollout (status, history), api-resources, api-versions, explain, cluster-info, config (view), version, wait, auth (can-i).

Writes (delete, apply, patch, scale, label, cordon, drain, exec, …) pass unless the organisation's tool policy turned them off (allow_writes on run_kubectl / kubectl_exec in the console's Tool Policy, open by default). The policy engine asks for confirmed=True, records the write in the audit log, and runs it WITHOUT verification — the catalogued action for the same change would carry a proof, so prefer it when one exists. When the organisation turned writes off, the engine refuses the write by name, whatever the caller.

Args: cluster_name: Target cluster. command: kubectl arguments as a list, without the 'kubectl' prefix. Example: ["get", "pods", "-n", "default"] gateway_id: Gateway UUID from list_clusters. Omit for single-gateway deployments; provide to disambiguate when multiple gateways share a cluster name. confirmed: Required for a write. Pass False (default) to receive the confirmation request with its preview, or the refusal.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cluster_name": "<cluster_name>",
      "command": "<command>"
    },
    "name": "run_kubectl"
  }
}

Input Schema

NameRequiredDescriptionDefault
commandYes
confirmedNo
gateway_idNo
cluster_nameYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.72.5
    • addedInput schema / properties / confirmed
      Added value: +{
      +  "default": false,
      +  "title": "Confirmed",
      +  "type": "boolean"
      +}
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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: it discloses that writes depend on the organisation's allow_writes policy, that the engine requires confirmed=True, that writes are recorded in an audit log, and critically that writes run WITHOUT verification unlike catalogued actions. It also states the refusal behavior when writes are disabled, which is exactly the failure mode an agent needs to anticipate.

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

Conciseness4/5

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

Front-loaded with purpose and routing before the policy detail, and the Args block is clean and scannable. The read/write policy paragraph is dense and somewhat repetitive about the tool policy mechanics, but each sentence adds behavioral information rather than filler.

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

Completeness4/5

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

For a high-blast-radius tool with no annotations and no output schema, the definition covers gating, confirmation, audit, and every parameter. The one gap is return-value shape: it never says what the tool hands back (raw kubectl stdout/stderr, structured output, or error envelope), which matters for an agent parsing results.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it does for all four parameters: command is specified as a list without the 'kubectl' prefix with a concrete example, gateway_id explains its source (list_clusters) and the single-vs-multi-gateway disambiguation rule, confirmed explains that passing False yields a preview/confirmation request or refusal, and cluster_name identifies the target.

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

Purpose5/5

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

States a specific verb and resource ('Execute a kubectl command on a cluster') and immediately distinguishes itself from dedicated siblings like scale_deployment, deploy_model, helm_upgrade, and helm_uninstall. An agent can tell exactly what class of operation this tool is for without inspecting the schema.

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

Usage Guidelines5/5

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

Explicit when-to-use ('only for operations not covered by dedicated tools') plus named alternatives with the conditions that select them (scaling, model deployment, Helm operations). It further partitions usage into always-allowed reads (get, describe, logs, top, rollout, …) versus policy-gated writes (delete, apply, patch, exec, …), which is actionable routing guidance.

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

Deploy Server

Other Tools