Kubernetes Tools MCP Server

get_deployment_summaries

Retrieve deployment summaries from Kubernetes clusters to monitor replica status and availability across namespaces.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`namespace`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedAug 15, 2025

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.