What can you do with this server?

Read-only Kubernetes monitoring/ops MCP server that lets agents inspect a cluster with kubectl-style summaries, logs, events, and object details, plus safe capture/replay testing options. * List kubectl-like summaries for namespaces, nodes, pods, deployments, replica sets, services, configmaps, statefulsets, cronjobs, jobs, and PVCs. * Retrieve deeper details such as pod specs, per-container statuses, full ConfigMap contents, and events. * Fetch logs for pods, jobs, and cronjobs, with options like tail, since_seconds, and previous-instance logs. * Run via MCP over stdio or streamable HTTP, or call the tools directly in Python agents. * Includes print_* helpers for easy debugging output. * Redacts secret-shaped values from tool output by default. * Supports mock mode and captured cluster snapshots for deterministic replay without a live cluster.

Which integrations are available for this server?

Enables chat interactions with Kubernetes clusters via GitHub Copilot, allowing users to query cluster status, inspect resources, and retrieve logs through natural language conversation supported by custom instruction files. Provides a collection of Kubernetes tools for querying and monitoring cluster resources, including namespaces, nodes, pods, deployments, and services. Enables agents to retrieve logs, inspect pod specifications, and check container statuses to support monitoring and root cause analysis use cases. Provides mock tools that can simulate interactions with a Kubernetes cluster running OpenTelemetry Demo, useful for testing agents against realistic but static data without requiring a live cluster.

How do I use Kubernetes Tools MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Kubernetes Tools MCP Server show me the status of pods in the default namespace" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Kubernetes Tools MCP Server

by BenedatLLC

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Kubernetes Tools

Unit Tests

This package provides a collection of Kubernetes functions to be used by Agents. They can be passed directly to an agent as tools or placed behind an MCP server (included). Some use cases include:

Chat with your kubernetes cluster via GitHub CoPilot or Cursor.
Build agents to monitor your cluster or perform root cause analysis.
Vibe-code a custom chat UI.
Use in non-agentic automations.
Snapshot a live cluster to a file and replay it as a test fixture, with no cluster needed — see Capturing and replaying a cluster.

Methodology

Our goal is to focus on quality over quantity -- providing well-documented and strongly typed tools. We believe that this is a critical in enabling agents to make effective use of tools, beyond simple demos.

These are built on top of the kubernetes Python API (https://github.com/kubernetes-client/python). There are three styles of tools provided here:

There are tools that mimic the output of kubectl commands (e.g. get_pod_summaries, which is equivalent to kubectl get pods). Strongly-typed Pydantic models are used for the return values of these tools.
There are tools that return strongly typed Pydantic models that attempt to match the associated Kubernetes client types (see https://github.com/kubernetes-client/python/tree/master/kubernetes/docs). Lesser used fields may be omitted from these models. An example of this case is get_pod_container_statuses.
In some cases we simply call to_dict() on the class returned by the API (defined in https://github.com/kubernetes-client/python/tree/master/kubernetes/client/models). The return type is dict[str,Any], but we document the fields in the function's docstring. get_pod_spec is an example of this type of tool.

Currently, the priority is on functions that do not modify the state of the cluster. We want to focus first on the monitoring / RCA use cases. When we do add tools to address other use cases, they will be kept separate from the read-only tools so you can still build "safe" agents.

Related MCP server: kubeview-mcp

Installation

Via pip:

pip install k8stools

Via uv:

uv add k8stools

This installs three commands: k8s-mcp-server (the MCP server), k8s-mcp-client (a client for manual testing), and k8s-capture-state (snapshot a cluster to a replayable file).

Current tools

These are the tools we define:

get_namespaces - get a list of namespaces, like kubectl get namespace
get_node_summaries - get a list of nodes, like kubectl get nodes -o wide (includes capacity/allocatable/conditions/taints/labels)
get_pod_summaries - get a list of pods, like kubectl get pods -o wide
get_pod_container_statuses - return the status for each of the container in a pod
get_pod_events - return the events for a pod
get_pod_spec - retrieves the spec for a given pod
get_logs_for_pod_and_container - retrieves logs from a pod and container (supports tail, since_seconds, and previous)
get_deployment_summaries - get a list of deployments, like kubectl get deployments
get_replicaset_summaries - get a deployment's replica sets with their revision numbers and images. A deployment's replica sets are its change history: use this to see when a workload last changed and what the change was.
get_service_summaries - get a list of services, like kubectl get services (includes selector/labels/annotations)
get_configmap_summaries - get a list of ConfigMaps, like kubectl get configmaps
get_configmap - retrieve the full contents of a single ConfigMap
get_statefulset_summaries - get a list of StatefulSets, like kubectl get statefulsets
get_cronjob_summaries - get a list of CronJobs, like kubectl get cronjobs
get_job_summaries - get a list of Jobs, like kubectl get jobs
get_logs_for_job - retrieve logs from a Job's most-recent pod
get_logs_for_cronjob - retrieve logs from a CronJob's most-recent run
get_pvc_summaries - get a list of PersistentVolumeClaims, like kubectl get pvc (resolves mounting pods)
get_events - list cluster/namespace-wide events with server-side filtering

We also define a set of associated "print_" functions that are helpful in debugging:

print_namespaces
print_node_summaries
print_pod_summaries
print_pod_container_statuses
print_pod_events
print_pod_spec
print_deployment_summaries
print_service_summaries
print_configmap_summaries
print_configmap
print_statefulset_summaries
print_cronjob_summaries
print_job_summaries
print_pvc_summaries
print_events

Using the tools

Directly use in an agent

The core tools are in k8stools.k8s_tools. Here's an example usage in an agent:

from pydantic_ai.agent import Agent
from k8stools.k8s_tools import TOOLS

agent = Agent(
        model="openai:gpt-4.1",
        system_prompt=SYSTEM_PROMPT,
        tools=TOOLS
)

result = agent.run_sync("What is the status of the pods in my cluster?")
print(result.output)

Using via MCP

The script k8s-mcp-server provides an MCP server for the same set of tools. Here are the command line arguments for the server:

usage: k8s-mcp-server [-h] [--transport {streamable-http,stdio}] [--host HOST] [--port PORT]
                      [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug] [--mock]
                      [--state-file FILE] [--state-time {advancing,frozen}] [--no-redact]

Run the MCP server.

options:
  -h, --help            show this help message and exit
  --transport {streamable-http,stdio}
                        Transport to use for MCP server [default: stdio]
  --host HOST           Hostname for HTTP service [default: 127.0.0.1]
  --port PORT           Port for HTTP service [default: 8000]
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Log level [default: INFO]
  --debug               Enable debug mode [default: False]
  --mock                Run mock versions of the tools that don't need a cluster
  --state-file FILE     Serve a captured cluster snapshot from FILE (implies --mock)
  --state-time {advancing,frozen}
                        Replay clock for a captured snapshot [default: advancing]
  --no-redact           Disable secret redaction of tool output (on by default)

Use MCP with the stdio transport

The stdio transport is best for use with local Coding Agents, like GitHub CoPilot or Cursor. It is the default, so you can run the k8s-mcp-server script without arguments. Here's an example mcp.json configuration:

{
   "servers": {
      "k8stools-stdio": {
         "command": "${workspaceFolder}/.venv/bin/k8s-mcp-server",
         "args": [
         ],
         "envFile": "${workspaceFolder}/.envrc"
      }
   }
}

This assumes the following:

The Python virtual environment is expected to be in .venv under the root of your VSCode workspace
You have installed the k8stools package into your workspace
The environment file .envrc contains any variables you need defined. In particular, you may need to set KUBECONFIG to point to your kubectl config file.

Use MCP with the streamable HTTP transport

The streamable http transport is enabled with the command line option --transport=streamable-http. It will start an HTTP server which listens on the specified address and port (defaulting to 127.0.0.1 and 8000, respectively). This transport is best for cases where you want remote access to your MCP server.

Here's a short example that starts the server and then does a sanity test using curl to get the tool information:

# start the server
 $ k8s-mcp-server --transport=streamable-http
[07/21/25 19:55:13] INFO     Starting with 18 tools on transport streamable-http          mcp_server.py:59
INFO:     Started server process [6649]
INFO:     Waiting for application startup.
INFO     StreamableHTTP session manager started         streamable_http_manager.py:111
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

# Now, open another terminal window and test it
$ curl -v \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{
           "jsonrpc": "2.0",
           "id": 1,
           "method": "tools/list",
           "params": {}
         }' \
     http://127.0.0.1:8000/mcp
*   Trying 127.0.0.1:8000...
* Connected to 127.0.0.1 (127.0.0.1) port 8000
> POST /mcp HTTP/1.1
> Host: 127.0.0.1:8000
> User-Agent: curl/8.7.1
> Content-Type: application/json
> Accept: application/json, text/event-stream
> Content-Length: 120
>
* upload completely sent off: 120 bytes
< HTTP/1.1 200 OK
< date: Tue, 22 Jul 2025 02:56:25 GMT
< server: uvicorn
< cache-control: no-cache, no-transform
< connection: keep-alive
< content-type: text/event-stream
< x-accel-buffering: no
< Transfer-Encoding: chunked
<
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"tools":[.... long text elided ...]}}

Mock tools

When building agents, it can be helpful to test them against mock versions that do not go against a real cluster, but return realistic values. The module k8stools.mock_tools does just that. The data values were captured when running against a real Minikube instance running the Open Telemetry Demo application. When running the MCP server, this may be enabled by using the --mock command line option.

The mock serves a capture — a JSON snapshot of one cluster — rather than a set of per-tool canned answers, so the tools agree with each other: a pod that is not in the capture does not exist for any tool, and one that is has consistent statuses, events, spec and logs. You can snapshot your own cluster the same way — see Capturing and replaying a cluster.

Capturing and replaying a cluster

k8s-capture-state snapshots a live cluster into a single JSON file, and the MCP server replays that file as if it were the cluster. A whole scenario — a crash loop, a full volume, a bad rollout — becomes a fixture you can re-run, commit, or attach to an issue, with no cluster needed to reproduce it.

# Snapshot the current cluster (respects KUBECONFIG)
k8s-capture-state -o incident-1234.json

# Replay it
k8s-mcp-server --state-file incident-1234.json

`k8s-capture-state` options

usage: k8s-capture-state [-h] [--namespace NS [NS ...]] [-o FILE] [--no-logs]
                         [--max-log-lines MAX_LOG_LINES] [--no-previous-logs]
                         [--no-redact]
                         [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]

options:
  -h, --help            show this help message and exit
  --namespace NS [NS ...]
                        Namespace(s) to capture namespaced resources from
                        [default: all]. Namespaces and nodes are always
                        captured in full.
  -o FILE, --output FILE
                        Output file [default: k8s-state-<timestamp>.json]
  --no-logs             Skip container logs
  --max-log-lines MAX_LOG_LINES
                        Log lines to capture per container [default: 1000]
  --no-previous-logs    Skip the previous-instance logs of restarted containers
  --no-redact           Disable secret redaction of captured values (redaction
                        is on by default; can also be disabled with
                        K8STOOLS_REDACT=0)
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Log level [default: INFO]

It finishes with a summary of what it got:

$ k8s-capture-state --namespace default -o incident-1234.json
Captured 27 pod(s), 31 container(s).
  logs captured:          31
  previous logs captured: 31
  values redacted:        4
Wrote incident-1234.json (1,435,335 bytes, redacted).

What gets captured

Everything the tools can read, so that every tool answers on replay:


Cluster-wide	namespaces, nodes
Per namespace	deployments, replica sets, services, statefulsets, cronjobs, jobs, PVCs, events
ConfigMaps	summary and full contents, so `get_configmap` works too
Per pod	summary, labels, container statuses, spec, and per-container logs

--namespace restricts only the namespaced resources; namespaces and nodes are always captured in full so the cluster still makes sense.

Logs dominate the file size — expect a few MB for a few dozen pods (the 27-pod capture above was 1.4 MB with only 50 lines per container; a 38-pod one at 200 lines was 3.3 MB). Use --max-log-lines to trade size against history, or --no-logs for a structure-only snapshot. Captures compress about 10x, and can be written and read gzipped — see Compression, and what to check in.

Compression, and what to check in

A name ending in .gz is written gzipped, and captures are read back compressed or not either way — detection is by content, so a capture still loads after being renamed:

k8s-capture-state -o incident-1234.json.gz     # 3.3 MB -> 364 KB
k8s-mcp-server --state-file incident-1234.json.gz

For a fixture you check into git, use plain .json anyway. Git already stores blobs compressed, so you do not pay the uncompressed size — and it deltas successive versions of a text file against each other, which it cannot do for a gzip blob. Measured on two captures of the same 38-pod cluster:

	first commit	updating the fixture later
`.json` (3.3 MB)	404 KB	+61 KB
`.json.gz` (364 KB)	388 KB	+358 KB

The two cost about the same once, but every re-capture of a .gz adds a whole fresh blob, so the repo grows roughly 6x faster. Captures are also indented rather than compact for the same reason — it gives git something to delta. This is also why you probably do not need git-lfs here: LFS stores every version whole, which gives up exactly the delta compression that makes these files cheap.

Reach for .gz when the file travels on its own — attached to an issue, dropped in object storage, or simply too large to keep expanded in a working tree.

Previous-instance logs

The capture includes the previous-instance logs of every restarted container — what get_logs_for_pod_and_container(..., previous=True) returns. For a crash-looping container the current instance's logs are usually empty or post-restart, and the stack trace or OOM message that explains the crash lives in the previous instance, so a capture without them would be missing the evidence that matters most.

They roughly double the log payload for a cluster where a lot is restarting — which is exactly the cluster worth capturing. --no-previous-logs skips them. The summary reports how many could not be read (the previous instance may have been garbage-collected), because a crash-loop capture that lost them looks identical to one that never had any.

Replay clock

Every age in a capture is stored relative to the moment of capture, so the intervals between resources survive replay exactly: a deployment aged 8 days whose newest replica set is aged 7h34m still says "upgraded 7h34m ago" whenever it is replayed.

By default those ages advance in real time from when the server starts, which is what makes an interactive session feel like a live cluster. For an automated test suite pass --state-time frozen:

k8s-mcp-server --state-file incident-1234.json --state-time frozen

which pins every age at its captured value, so repeated runs are identical and a long session cannot see ages drift between its first tool call and its last. (--state-time requires --state-file; it is rejected rather than ignored, since a suite that believed it had frozen the clock and had not would be flaky with no visible cause.)

Replaying from Python

For a test suite, skip the server and load the capture directly. MockState has the same query methods as the tools:

from pathlib import Path
from k8stools.mock_state import MockState

state = MockState.from_file(Path("incident-1234.json"), frozen=True)

pods = state.get_pod_summaries("default")
logs = state.get_logs_for_pod_and_container("ad-647b4947cc-s5mpm", "default",
                                            previous=True)

Or point the mock_tools module at it, so anything already calling k8stools.mock_tools serves your capture instead of the built-in one:

from k8stools import mock_tools

mock_tools.load_mock_state(Path("incident-1234.json"), frozen=True)
agent = Agent(model="openai:gpt-4.1", tools=mock_tools.TOOLS)

Captures and secrets

k8s-capture-state applies the same redaction pass as the MCP server, on by default, opt out with --no-redact or K8STOOLS_REDACT=0. This matters because a capture file is far more portable than cluster access — it gets committed to git, attached to issues, and passed around long after anyone remembers which cluster it came from. Redaction is one-way: replaying a redacted capture with --no-redact restores nothing, so a scenario that genuinely needs real values has to be re-captured.

Secret redaction

Some read-only resources can carry secret-shaped values even though they are not Kubernetes Secret objects — ConfigMap data and the env blocks in a pod spec are the common cases. When you run the k8stools MCP server directly against an agent (with no wrapping service to scrub output), those values would otherwise flow straight into the model's context.

To prevent that, the MCP server applies a redaction pass to every tool's output. It is on by default and can be disabled with --no-redact or by setting K8STOOLS_REDACT=0. Redaction matches two ways, replacing each match with a visible [REDACTED] marker so the agent can tell "hidden" from "absent". We never provide a reader for Kubernetes Secret objects.

By value shape — AWS access keys, JWT / bearer tokens, PEM private-key blocks.
By key / env-var name — the name contains key, secret, token, password, passwd, credential or cred as a whole word. Names are split on separators and camelCase, so AWS_SECRET_ACCESS_KEY, apiKey and x-auth-token all match while VALKEY_ADDR does not.
A field named exactly key is exempt: in the Kubernetes API that is always a map entry, a taint, a label selector or a projected-volume item, never a credential. This matters more than it sounds — on a real 38-pod cluster it was 130 of 139 redactions, none of them secrets: toleration keys such as node.kubernetes.io/not-ready, the filename ca.crt, and secretKeyRef.key. That last is worth stating plainly: a reference to a secret is not a secret. The value lives in the Secret object and is resolved by the kubelet, never appearing in tool output, so redacting the pointer hides which key feeds an env var and protects nothing. The exemption does not apply to env-var names, where a variable someone named KEY plausibly does hold one.

If you call the tool functions directly in Python (rather than through the MCP server), you get raw, un-redacted values; you can apply the same pass yourself via k8stools.redaction.redact_object.

Available Tools

9 tools

get_deployment_summariesA

Retrieves a list of DeploymentSummary objects for deployments in a given namespace or all namespaces.
Similar to `kubectl get deployements`.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list deployments from. If None, lists deployments from all namespaces.

Returns
-------
list of DeploymentSummary
    A list of DeploymentSummary objects, each providing a summary of a deployment's status with the following fields:

    name : str
        Name of the deployment.
    namespace : str
        Namespace in which the deployment is running.
    total_replicas : int
        Total number of replicas desired for this deployment.
    ready_replicas : int
        Number of replicas that are currently ready.
    up_to_date_replicas : int
        Number of replicas that are up to date.
    available_replicas : int
        Number of replicas that are available.
    age : datetime.timedelta
        Age of the deployment (current time minus creation timestamp).

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list deployments fails.

ParametersJSON Schema

Name	Required	Description	Default
`namespace`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden and does so well by disclosing behavioral traits: it specifies the kubectl-like behavior, lists potential errors (K8sConfigError, K8sApiError), and describes the return format. It does not mention rate limits or auth needs, but covers key operational aspects.

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

Conciseness5/5

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

The description is appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by organized sections (Parameters, Returns, Raises) that add necessary detail without redundancy. Every sentence earns its place by providing essential information.

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

Completeness5/5

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

Given the tool's complexity (1 parameter, no annotations, but with an output schema), the description is complete enough. It explains the purpose, parameter usage, return values in detail (though the output schema covers this, the description adds clarity), and error conditions, leaving no significant gaps for an AI agent.

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

Parameters4/5

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

The description adds significant meaning beyond the input schema, which has 0% coverage. It explains the 'namespace' parameter's purpose (to list deployments from a specific namespace or all namespaces), default behavior (None for all namespaces), and semantics, compensating fully for the schema's lack of descriptions.

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?

The description clearly states the verb 'retrieves' and resource 'list of DeploymentSummary objects for deployments', specifying it works 'in a given namespace or all namespaces'. It distinguishes from siblings by focusing on deployments rather than pods, nodes, services, etc., and explicitly mentions the kubectl analogy for context.

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

Usage Guidelines4/5

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

The description provides clear context for when to use this tool (to get deployment summaries) and implies when not to use it (e.g., for pod or service summaries, as indicated by sibling tool names). However, it does not explicitly name alternatives or state exclusions, such as when to use get_pod_summaries instead.

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

get_logs_for_pod_and_containerB

Retrieves logs from a Kubernetes pod and container.

Args:
    namespace (str): The namespace of the pod.
    pod_name (str): The name of the pod.
    container_name (str, optional): The name of the container within the pod.
                                    If None, defaults to the first container.

Returns:
    str, optional: Log content if any found for this pod/container, or None otherwise

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to fetch logs fails or an unexpected error occurs.

ParametersJSON Schema

Name	Required	Default
`pod_name`	Yes
`namespace`	No	default
`container_name`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.4/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses behavioral traits: it retrieves logs, returns a string or None if no logs found, and raises specific errors (K8sConfigError, K8sApiError). However, it lacks details on permissions needed, rate limits, log format, or whether it's read-only/destructive (though 'retrieves' implies read-only). The error information is valuable but not comprehensive.

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?

The description is appropriately sized and front-loaded with the purpose in the first sentence. The Args and Returns sections are structured clearly, but the 'Raises' section could be integrated more concisely. Overall, it's efficient with minimal waste, though minor improvements in flow are possible.

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?

Given the tool's moderate complexity (3 parameters, no annotations, but with output schema), the description is fairly complete. It covers parameters, return values, and errors. The output schema exists, so it doesn't need to explain return values in detail. However, it lacks context on log scope (e.g., time range, tailing) and permissions, which would enhance completeness.

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

Parameters4/5

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

The description adds significant meaning beyond the input schema, which has 0% schema description coverage. It explains each parameter's purpose: namespace, pod_name, and container_name (with default behavior). This compensates well for the schema's lack of descriptions, though it doesn't detail format constraints (e.g., namespace/pod naming rules).

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

Purpose4/5

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

The description clearly states the tool's purpose: 'Retrieves logs from a Kubernetes pod and container.' This is a specific verb+resource combination that distinguishes it from sibling tools like get_pod_summaries or get_pod_events. However, it doesn't explicitly differentiate from all siblings (e.g., get_pod_container_statuses might overlap in context).

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like get_pod_events (which might provide event logs) or clarify if this is for real-time vs. historical logs. The only implied usage is from the purpose statement, but no explicit when/when-not or alternative recommendations are given.

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

get_namespacesA

Return a summary of the namespaces for this Kubernetes cluster, similar to that returned by kubectl get namespace.

Parameters
----------
None
    This function does not take any parameters.

Returns
-------
list of NamespaceSummary
    List of namespace summary objects. Each NamespaceSummary has the following fields:

    name : str
        Name of the namespace.
    status : str
        Status phase of the namespace.
    age : datetime.timedelta
        Age of the namespace (current time minus creation timestamp).
Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list namespaces fails.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations provided, the description carries full burden and does well by disclosing the return format (list of NamespaceSummary objects with specific fields), error conditions (K8sConfigError, K8sApiError), and behavioral aspects like what happens on API failure. It doesn't mention rate limits, authentication needs, or pagination behavior, but provides substantial operational context.

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

Conciseness5/5

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

The description is well-structured with clear sections (Parameters, Returns, Raises), front-loaded with the core purpose, and every sentence earns its place by providing essential information about behavior, output format, and error conditions without redundancy.

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

Completeness5/5

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

Given the tool has no parameters, has an output schema (implied by the detailed Returns section), and no annotations, the description provides complete context: clear purpose, detailed return format with field descriptions, specific error conditions, and operational behavior. Nothing essential appears missing for this type of read-only listing tool.

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

Parameters4/5

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

With 0 parameters and 100% schema coverage, the baseline would be 4. The description explicitly states 'This function does not take any parameters' in the Parameters section, which adds clarity beyond what the empty schema alone conveys, confirming this is a parameterless operation.

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?

The description clearly states the tool's purpose with specific verb ('Return') and resource ('summary of the namespaces for this Kubernetes cluster'), and distinguishes it from siblings by specifying it returns namespace summaries rather than deployments, pods, services, etc. The kubectl analogy provides helpful context.

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

Usage Guidelines3/5

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

The description implies usage context through the kubectl analogy and by specifying what it returns (namespace summaries), but doesn't explicitly state when to use this tool versus alternatives like get_pod_summaries or get_service_summaries. No explicit when-not-to-use guidance or prerequisite information is provided.

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

get_node_summariesA

Return a summary of the nodes for this Kubernetes cluster, similar to that returned by kubectl get nodes -o wide.

Parameters
----------
None
    This function does not take any parameters.

Returns
-------
list of NodeSummary
    List of node summary objects. Each NodeSummary has the following fields:

    name : str
        Name of the node.
    status : str
        Status of the node (Ready, NotReady, etc.).
    roles : list[str]
        List of roles for the node (e.g., ['control-plane', 'master']).
    age : datetime.timedelta
        Age of the node (current time minus creation timestamp).
    version : str
        Kubernetes version running on the node.
    internal_ip : Optional[str]
        Internal IP address of the node.
    external_ip : Optional[str]
        External IP address of the node (if available).
    os_image : Optional[str]
        Operating system image running on the node.
    kernel_version : Optional[str]
        Kernel version of the node.
    container_runtime : Optional[str]
        Container runtime version on the node.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list nodes fails.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations provided, the description carries full burden and does well by disclosing behavioral traits: it specifies the return format (list of NodeSummary with detailed fields), mentions exceptions (K8sConfigError, K8sApiError), and implies read-only behavior through 'Return a summary'. It doesn't cover rate limits or auth needs, but adds significant context beyond basic purpose.

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

Conciseness5/5

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

The description is well-structured with clear sections (Parameters, Returns, Raises), front-loaded purpose, and no wasted sentences. Every part adds value: the kubectl comparison sets context, the parameter note is essential, and the return details are comprehensive but necessary.

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

Completeness5/5

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

Given 0 parameters, no annotations, but a detailed output schema in the description, the description is complete. It covers purpose, usage hint, parameter semantics, return format, and exceptions, making it fully adequate for this tool's complexity without redundancy.

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

Parameters4/5

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

The description explicitly states 'This function does not take any parameters', which adds clarity beyond the empty input schema. With 0 parameters and 100% schema coverage, the baseline is 4, and this confirmation earns it without needing further compensation.

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?

The description clearly states the verb ('Return a summary') and resource ('nodes for this Kubernetes cluster'), and explicitly distinguishes it from siblings by comparing to `kubectl get nodes -o wide`, which helps differentiate from other node-related tools like get_pod_summaries or get_service_summaries.

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

Usage Guidelines4/5

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

The description provides clear context by mentioning it's similar to `kubectl get nodes -o wide`, which implies usage for high-level node overviews. However, it doesn't explicitly state when to use this versus alternatives like get_pod_summaries or get_deployment_summaries, nor does it mention exclusions or prerequisites.

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

get_pod_container_statusesA

Get the status for all containers in a specified Kubernetes pod.

Parameters
----------
pod_name : str
    Name of the pod to retrieve container statuses for.
namespace : str, optional
    Namespace of the pod (default is "default").

Returns
-------
list of ContainerStatus
    List of container status objects for the specified pod. Each ContainerStatus has the following fields:

    pod_name : str
        Name of the pod.
    namespace : str
        Namespace of the pod.
    container_name : str
        Name of the container.
    image : str
        Image name.
    ready : bool
        Whether the container is currently passing its readiness check.
        The value will change as readiness probes keep executing.
    restart_count : int
        Number of times the container has restarted.
    started : Optional[bool]
        Started indicates whether the container has finished its postStart
        lifecycle hook and passed its startup probe.
    stop_signal : Optional[str]
        Stop signal for the container.
    state : Optional[ContainerState]
        Current state of the container.
    last_state : Optional[ContainerState]
        Last state of the container.
    volume_mounts : list[VolumeMountStatus]
        Status of volume mounts for the container
    resource_requests : dict[str, str]
        Describes the minimum amount of compute resources required. If Requests
        is omitted for a container, it defaults to Limits if that is explicitly specified,
        otherwise to an implementation-defined value. Requests cannot exceed Limits. 
    resource_limits : dict[str, str]
        Describes the maximum amount of compute resources allowed.
    allocated_resources : dict[str, str]
        Compute resources allocated for this container by the node.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to read the pod fails.

ParametersJSON Schema

Name	Required	Description	Default
`pod_name`	Yes
`namespace`	No		default

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden and does well by disclosing behavioral traits: it's a read operation (implied by 'Get'), specifies error conditions (K8sConfigError, K8sApiError), and details the return structure. It doesn't mention rate limits or authentication needs, but covers key operational aspects.

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

Conciseness3/5

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

The description is appropriately sized but not optimally front-loaded: the purpose is clear upfront, but the detailed return values (which could be in an output schema) make it lengthy. Every sentence adds value (e.g., error explanations), but structure could be tighter by focusing more on usage context.

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

Completeness5/5

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

Given the tool's moderate complexity (2 parameters, no annotations, but with an output schema), the description is complete: it explains purpose, parameters, returns (with detailed field descriptions), and errors. The output schema existence means return values are well-documented, making this description thorough for agent use.

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

Parameters4/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. It adds meaning by explaining parameters: pod_name is 'Name of the pod to retrieve container statuses for' and namespace is 'Namespace of the pod (default is "default")'. This clarifies usage beyond the bare schema, though it doesn't detail format constraints (e.g., Kubernetes naming rules).

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?

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('status for all containers in a specified Kubernetes pod'), distinguishing it from siblings like get_pod_summaries (general pod info) or get_logs_for_pod_and_container (logs rather than status). It precisely defines what the tool retrieves.

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

Usage Guidelines3/5

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

The description implies usage by specifying the target (Kubernetes pod containers) but does not explicitly state when to use this tool versus alternatives like get_pod_summaries or get_pod_spec. It provides context (e.g., for monitoring container health) but lacks explicit guidance on tool selection or exclusions.

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

get_pod_eventsA

Get events for a specific Kubernetes pod. This is equivalent to the kubectl command:
`kubectl get events -n NAMESPACE --field-selector involvedObject.name=POD_NAME,involvedObject.kind=Pod`

Parameters
----------
pod_name : str
    Name of the pod to retrieve events for.
namespace : str, optional
    Namespace of the pod (default is "default").

Returns
-------
list of EventSummary
    List of events associated with the specified pod. Each EventSummary has the following fields:

    last_seen : Optional[datetime.datetime]
        Timestamp of the last occurrence of the event (if available).
    type : str
        Type of the event.
    reason : str
        Reason for the event.
    object : str
        The object this event applies to.
    message : str
        Message describing the event.
Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list events fails.

ParametersJSON Schema

Name	Required	Description	Default
`pod_name`	Yes
`namespace`	No		default

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden and does well by detailing the kubectl equivalent (clarifying the query logic), listing return fields with types, and specifying error conditions (K8sConfigError, K8sApiError). It doesn't cover rate limits or auth needs, but gives solid operational context.

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

Conciseness5/5

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

Well-structured with clear sections (description, parameters, returns, raises), front-loaded purpose, and no wasted sentences. Each part adds value, such as the kubectl analogy and detailed return field explanations.

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

Completeness5/5

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

Given the tool's moderate complexity (2 params, no annotations), the description is highly complete: it explains the action, parameters, return structure (with output schema details), and error cases. The output schema is present, so no need to redundantly explain returns.

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 fully. It explicitly documents both parameters (pod_name, namespace), including the namespace default value ('default') and their purposes, adding crucial meaning beyond the bare schema.

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?

The description clearly states the specific action ('Get events for a specific Kubernetes pod') and resource ('pod'), distinguishing it from siblings like get_pod_summaries or get_logs_for_pod_and_container by focusing exclusively on events. The kubectl command analogy reinforces the precise scope.

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

Usage Guidelines4/5

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

It implicitly suggests usage when needing pod events, but lacks explicit guidance on when to choose this over alternatives like get_pod_summaries (which might include event data) or get_logs_for_pod_and_container (for logs vs. events). No exclusions or prerequisites are mentioned.

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

get_pod_specA

Retrieves the spec for a given pod in a specific namespace.

Args:
    pod_name (str): The name of the pod.
    namespace (str): The namespace the pod belongs to (defaults to "default").

Returns
-------
dict[str, Any]
    The pod's spec object, containing its desired state. It is converted
    from a V1PodSpec to a dictionary. Key fields include:

    containers : list of kubernetes.client.V1Container
        List of containers belonging to the pod. Each container defines its image,
        ports, environment variables, resource requests/limits, etc.
    init_containers : list of kubernetes.client.V1Container, optional
        List of initialization containers belonging to the pod.
    volumes : list of kubernetes.client.V1Volume, optional
        List of volumes mounted in the pod and the sources available for
        the containers.
    node_selector : dict, optional
        A selector which must be true for the pod to fit on a node.
        Keys and values are strings.
    restart_policy : str
        Restart policy for all containers within the pod.
        Common values are "Always", "OnFailure", "Never".
    service_account_name : str, optional
        Service account name in the namespace that the pod will use to
        access the Kubernetes API.
    dns_policy : str
        DNS policy for the pod. Common values are "ClusterFirst", "Default".
    priority_class_name : str, optional
        If specified, indicates the pod's priority_class via its name.
    node_name : str, optional
        NodeName is a request to schedule this pod onto a specific node.

Raises
------
K8SConfigError
    If unable to initialize the K8S API
K8sApiError
    If the pod is not found, configuration fails, or any other API error occurs.

ParametersJSON Schema

Name	Required	Description	Default
`pod_name`	Yes
`namespace`	No		default

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden and does so well by detailing return values, key fields, and error conditions (K8SConfigError, K8sApiError). It explains that the spec is converted from V1PodSpec to a dictionary and lists common values for fields like restart_policy and dns_policy, adding valuable behavioral context beyond basic functionality.

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?

The description is appropriately sized and front-loaded with the core purpose, followed by structured sections for Args, Returns, and Raises. Every sentence adds value, such as detailing return fields and errors, though the Returns section is somewhat lengthy but necessary for clarity.

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

Completeness5/5

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

Given the tool's complexity (retrieving detailed pod specs) and the presence of an output schema (implied by the detailed Returns section), the description is complete enough. It covers purpose, parameters, return semantics with key fields, and error handling, providing all necessary context for an AI agent to use the tool effectively without redundancy.

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

Parameters4/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, which it does by explaining both parameters: pod_name as 'the name of the pod' and namespace as 'the namespace the pod belongs to (defaults to "default")'. This adds clear meaning beyond the schema's titles, though it doesn't elaborate on format constraints or examples.

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?

The description clearly states the verb 'retrieves' and the resource 'spec for a given pod in a specific namespace', making the purpose specific and unambiguous. It distinguishes this tool from siblings like get_pod_summaries or get_pod_events by focusing on the detailed spec object rather than summaries or events.

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

Usage Guidelines3/5

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

The description implies usage by specifying it retrieves a pod's spec, but it does not explicitly state when to use this tool versus alternatives like get_pod_summaries for high-level info or get_pod_container_statuses for container states. No explicit exclusions or prerequisites are provided, leaving usage context inferred rather than guided.

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

get_pod_summariesA

Retrieves a list of PodSummary objects for pods in a given namespace or all namespaces.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list pods from. If None, lists pods from all namespaces.

Returns
-------
list of PodSummary
    A list of PodSummary objects, each providing a summary of a pod's status with the following fields:

    name : str
        Name of the pod.
    namespace : str
        Namespace in which the pod is running.
    total_containers : int
        Total number of containers in the pod.
    ready_containers : int
        Number of containers currently in ready state.
    restarts : int
        Total number of restarts for all containers in the pod.
    last_restart : Optional[datetime.timedelta]
        Time since the container last restart (None if never restarted).
    age : datetime.timedelta
        Age of the pod (current time minus creation timestamp).
    ip : Optional[str]
        Pod IP address (None if not assigned).
    node : Optional[str]
        Name of the node where the pod is running (None if not scheduled).
Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list pods fails.

ParametersJSON Schema

Name	Required	Description	Default
`namespace`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations provided, the description carries full burden and does well by disclosing behavioral traits: it specifies the return type (list of PodSummary), documents potential exceptions (K8sConfigError, K8sApiError), and describes error conditions. However, it doesn't mention rate limits, authentication needs, or side effects like caching.

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

Conciseness5/5

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

The description is well-structured with clear sections (Parameters, Returns, Raises), front-loaded with the core purpose, and every sentence earns its place by providing essential information without redundancy. It's appropriately sized for a tool with one parameter and detailed return documentation.

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

Completeness5/5

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

Given the tool's moderate complexity, no annotations, and the presence of a detailed output schema (which the description references), the description is complete: it covers purpose, parameter semantics, return structure, and error conditions. The output schema handles return value details, so the description appropriately focuses on higher-level context.

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

Parameters4/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. It fully documents the single parameter 'namespace', explaining its optional nature, default value (None), and semantic meaning ('specific namespace to list pods from' vs 'all namespaces'). This adds significant value beyond the bare schema.

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?

The description clearly states the verb 'Retrieves' and resource 'list of PodSummary objects for pods', specifying it works 'in a given namespace or all namespaces'. It distinguishes from siblings like get_pod_container_statuses (container-level details) and get_pod_events (event logs) by focusing on summary-level pod status.

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

Usage Guidelines4/5

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

The description provides clear context by specifying it retrieves summaries for pods in a namespace or all namespaces, but does not explicitly state when to use this tool versus alternatives like get_pod_container_statuses or get_pod_events. The namespace parameter guidance implies usage but lacks explicit sibling comparison.

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

get_service_summariesA

Retrieves a list of ServiceSummary objects for services in a given namespace or all namespaces. Similar to kubectl get services.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list services from. If None, lists services from all namespaces.

Returns
-------
list of ServiceSummary
    A list of ServiceSummary objects, each providing a summary of a service's status with the following fields:

    name : str
        Name of the service.
    namespace : str
        Namespace in which the service is running.
    type : str
        Type of the service (ClusterIP, NodePort, LoadBalancer, ExternalName).
    cluster_ip : Optional[str]
        Cluster IP address assigned to the service (None for ExternalName services).
    external_ip : Optional[str]
        External IP address if applicable (for LoadBalancer services).
    ports : list[PortInfo]
        List of ports (and their protocols) exposed by the service.
    age : datetime.timedelta
        Age of the service (current time minus creation timestamp).

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list services fails.

ParametersJSON Schema

Name	Required	Description	Default
`namespace`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

With no annotations provided, the description carries full burden and does well by detailing return values, error conditions (K8sConfigError, K8sApiError), and the kubectl analogy for context. It lacks explicit rate limits or auth requirements, but covers key behavioral aspects adequately.

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

Conciseness5/5

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

The description is well-structured with clear sections (Parameters, Returns, Raises), front-loaded purpose, and no wasted sentences. Each part adds value, making it efficient and easy to parse.

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

Completeness5/5

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

Given the tool's moderate complexity, no annotations, and an output schema present, the description is complete: it covers purpose, parameters, returns in detail (including field explanations), error cases, and contextual analogy, leaving no significant gaps for agent understanding.

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 fully. It does so by clearly explaining the namespace parameter's purpose, default behavior (None lists all namespaces), and effect, adding essential meaning beyond the bare schema.

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?

The description clearly states the specific action ('Retrieves a list of ServiceSummary objects') and resource ('services in a given namespace or all namespaces'), with explicit differentiation from siblings through the kubectl analogy and focus on services rather than deployments, pods, nodes, etc.

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

Usage Guidelines4/5

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

The description provides clear context for when to use this tool (to get service summaries, with namespace filtering) and implicitly distinguishes it from siblings by focusing on services, but does not explicitly state when to use alternatives like get_deployment_summaries or get_pod_summaries for other resource types.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

9 tool updatesAug 15, 2025
- First observedget_deployment_summaries
- First observedget_logs_for_pod_and_container
- First observedget_namespaces
- First observedget_node_summaries
- First observedget_pod_container_statuses
- First observedget_pod_events
- First observedget_pod_spec
- First observedget_pod_summaries
- First observedget_service_summaries

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-04-18 09:10 across 9 tools

Disambiguation5/5

Each tool has a clearly distinct purpose targeting specific Kubernetes resources and operations. The tools are well-differentiated by resource type (deployments, pods, services, nodes, namespaces) and action type (summaries, logs, events, specs), with no overlapping functionality that would cause confusion.

Naming Consistency5/5

All tools follow a consistent 'verb_noun' pattern with snake_case throughout. The naming convention is perfectly uniform with 'get_' prefix for all retrieval operations followed by specific resource identifiers, making the tool set highly predictable and readable.

Tool Count5/5

With 9 tools, this server is well-scoped for Kubernetes operations. Each tool earns its place by covering essential read-only operations for core Kubernetes resources (pods, deployments, services, nodes, namespaces), providing comprehensive monitoring capabilities without being overwhelming.

Completeness3/5

For a Kubernetes monitoring/read-only server, the coverage is good but has notable gaps. While it provides excellent read operations for core resources, there are no tools for creating, updating, or deleting resources, and missing operations like scaling deployments or executing commands in pods limit agent capabilities for full Kubernetes management.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Reddit Discussion

Related Servers

Related MCP Connectors

Cortex C
io.cortex.mcp
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Developer Tools Monitoring Observability
312
Google GKE A
com.googleapis.container
The Google GKE MCP server is a managed Model Context Protocol server that provides AI applications with tools to manage Google Kubernetes Engine (GKE) clusters and Kubernetes resources. It exposes a structured, discoverable interface that allows AI agents to interact with GKE and Kubernetes APIs, enabling them to inspect cluster configurations, retrieve Kubernetes resource YAMLs, monitor operations like cluster upgrades, diagnose issues, and optimize costs—all without needing to parse text output or use complex kubectl commands.
Cloud Platforms Virtualization Observability
232
mcp A
com.googleapis.container
Provides read access to your GKE and Kubernetes resources.
Cloud Platforms Virtualization Monitoring
232
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21

Related MCP Servers

Kubernetes Monitor
Observability Shell Access
vlttnv
A
license
Not graded
quality
D
maintenance
A read-only MCP server for Kubernetes that allows querying cluster information and diagnosing issues through natural language interfaces like Claude.
Updated 2 years ago (2025-03-15 14:25 UTC)
8
MIT
kubeview-mcp
Cloud Platforms Monitoring Code Execution
mikhae1
A
license
A
quality
B
maintenance
Read-only MCP server for safe Kubernetes inspection, diagnosis, and debugging. Supports Kubernetes core, Helm, Argo Workflows, and Argo CD.
Updated 15 days ago (2026-09-02 09:25 UTC)
2
191 npm
5
MIT
k8s-readonly-mcp
Cloud Platforms Monitoring
ziyuyu23
A
license
A
quality
C
maintenance
A read-only MCP server for inspecting Kubernetes clusters, allowing LLMs to list resources, describe pods, and read logs without mutation.
Updated 2 months ago (2026-07-21 17:44 UTC)
5
MIT
kubeaid-mcp
Cloud Platforms Command Line Monitoring
1Shubham7
A
license
A
quality
C
maintenance
Exposes a Kubernetes cluster to MCP-compatible AI clients, enabling read-only and optional write operations on cluster resources like pods, deployments, and namespaces through natural language.
Updated 2 months ago (2026-07-04 11:08 UTC)
9
1
MIT

Kubernetes Tools

Methodology

Installation

Current tools

Using the tools

Directly use in an agent

Using via MCP

Use MCP with the stdio transport

Use MCP with the streamable HTTP transport

Mock tools

Capturing and replaying a cluster

k8s-capture-state options

What gets captured

Compression, and what to check in

Previous-instance logs

Replay clock

Replaying from Python

Captures and secrets

Secret redaction

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

`k8s-capture-state` options