Kubernetes Tools MCP Server

get_pod_events

Retrieve events for a Kubernetes pod to diagnose issues. Use pod name and optional namespace, mirroring kubectl get events.

Instructions

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.timedelta]
        Time since the most recent occurrence of the event (if available).
    first_seen : Optional[datetime.timedelta]
        Time since the first occurrence combined into this record (if
        available).
    count : Optional[int]
        How many occurrences Kubernetes combined into this record: repeats
        of the same event on the same object are counted in one record
        rather than listed separately. The count covers first_seen to
        last_seen, not the object's lifetime - a record that stops repeating
        expires (after 1h by default), and a later repeat starts a new one.
        For a crash-looping container, count the "Created" or "Started"
        events to get restarts. "BackOff" is emitted repeatedly while the
        kubelet waits to restart, so its count is several times the number
        of restarts. count divided by (first_seen - last_seen) is the
        average rate over that window, not the current back-off.

        A record can lag behind what it counts. By default the kubelet
        writes at most one event update per object and event type
        ("Normal" or "Warning") every 5 minutes, once a burst of 25 is
        used up; occurrences in between are counted but only written with
        the next update, which then jumps by several at once. So count and
        last_seen describe the most recent *written* occurrence and can
        trail reality by several occurrences and tens of minutes. They lag
        together, so the rate above still holds, but last_seen is not the
        time of the last restart: for that, use the container status
        (last_state.finished_at, state.started_at from
        get_pod_container_statuses) or PodSummary.last_restart, which come
        from the kubelet's status rather than from events. "Pulled",
        "Created" and "Started" share one write budget, so their counts for
        the same restarts can differ by a few; don't compare counts across
        reasons.
    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.

Input Schema

TableJSON Schema

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

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.1.0Oct 4, 2026

addedOutput schema / $defs / EventSummary / properties / count

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Count"
+}

addedOutput schema / $defs / EventSummary / properties / first_seen

Added value: +{
+  "anyOf": [
+    {
+      "format": "duration",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "First Seen"
+}

First observedAug 15, 2025

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so unusually well: it discloses event coalescing, the 1h record expiry, the kubelet's one-write-per-5-minutes / burst-of-25 budget, the resulting lag between count and reality, and the two error types raised. These are exactly the behavioral traits an agent cannot infer from the schema.

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 purpose is front-loaded and the kubectl equivalent is a nice compression, but the count/last_seen explanation runs to several paragraphs of dense prose. Since an output schema exists for EventSummary, much of the field-by-field Returns block is duplicative, and the signal-to-length ratio suffers.

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?

For a two-parameter read tool with error semantics and an output schema, the description covers purpose, parameters, failure modes, and the non-obvious caveats about event counting and lag. An agent has everything needed to call it and to interpret the results correctly.

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 coverage is 0%, so the description must compensate, and it does: pod_name is identified as the required target pod and namespace as optional with a 'default' default. It stops short of format constraints (e.g. naming rules, cross-namespace behavior).

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+resource ('Get events for a specific Kubernetes pod') and anchors it to an exact kubectl equivalent, which removes any ambiguity about scope. It also implicitly separates itself from get_events and get_pod_container_statuses by naming the latter for restart-time needs.

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 gives one concrete routing rule: for the time of the last restart, use the container status / get_pod_container_statuses rather than event last_seen. However it never states when to prefer this tool over the sibling get_events, nor any preconditions beyond the Raises section.

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