Kafka MCP

Overview Schema Source Related Servers Discussions Admin

delete_records

Delete the oldest messages from up to 1,000 Kafka partitions without removing the topic; preview affected offsets and consumer groups, then confirm the data loss.

Instructions

Delete the oldest messages of 1 to 1000 partitions in one call through items, without deleting the topic. Each item removes every message of one partition with an offset lower than before_offset; the message at before_offset becomes the first readable one. Alternatively give before_timestamp to cut at a moment, resolved per partition, and all_partitions to apply that moment to every partition of the topic in one item. Use it to purge test data, or a run of bad messages at the head of a partition, while keeping the topic, its configuration and its consumer groups. Truncating one partition is an items array of length one.

No message is deleted unless confirm is true and the item sets acknowledge_data_loss. The preview reports the partition's start and end offsets, how many messages would be removed, and every consumer group whose committed offset is below the cut, with how many messages it would lose without ever processing them. Such a group resumes from the new start offset.

Kafka cannot restore deleted records. One confirm covers the whole batch, and deletion is not atomic: partitions truncated before a later item failed stay truncated. Results follow items order, each carrying index with result or error. Compacted topics are not supported by every broker. Requires Kafka DELETE permission on the topic.

Input Schema

Name	Required	Description	Default
`items`	Yes	The partitions to truncate, 1 to 1000 of them. Truncating one partition is an array of length one. Two items naming the same topic and partition are refused before anything is deleted.
`confirm`	No	Optional. When false or omitted, nothing is deleted and the response shows how many messages each item would remove and which consumer groups have not read them yet. Must be true to delete. One confirm covers the whole batch.

Output Schema

Name	Required	Description	Default
`atomic`	Yes
`failed`	Yes
`applied`	Yes
`results`	Yes
`succeeded`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.2.7Oct 25, 2026

changedInput schema / properties / items / description

Previous value: -"The partitions to truncate, 1 to 100 of them. Truncating one partition is an array of length one. Two items naming the same topic and partition are refused before anything is deleted."New value: +"The partitions to truncate, 1 to 1000 of them. Truncating one partition is an array of length one. Two items naming the same topic and partition are refused before anything is deleted."

addedInput schema / properties / items / items / properties / all_partitions

Added value: +{
+  "description": "Optional. With before_timestamp, cut every partition of the topic at that moment; each partition gets its own resolved offset, reported in partitions. Partitions with nothing older are left alone.",
+  "type": "boolean"
+}

changedInput schema / properties / items / items / properties / before_offset / description

Previous value: -"Every message with an offset lower than this is deleted; the message at before_offset is kept and becomes the first readable one. Must be greater than the partition's current start offset and at most its end offset. Use the end offset to empty the partition."New value: +"Every message with an offset lower than this is deleted; the message at before_offset is kept and becomes the first readable one. Must be greater than the partition's current start offset and at most its end offset. Use the end offset to empty the partition. Give before_offset or before_timestamp, not both."

addedInput schema / properties / items / items / properties / before_timestamp

Added value: +{
+  "description": "Optional RFC3339 time. Every message written before it is deleted: the cut is resolved per partition to the first offset at or after this time, and the preview shows the offset it resolved to. Give before_offset or before_timestamp, not both.",
+  "type": [
+    "null",
+    "string"
+  ]
+}

changedInput schema / properties / items / items / properties / partition / description

Previous value: -"Partition to delete records from."New value: +"Partition to delete records from. Ignored with all_partitions."

changedInput schema / properties / items / items / required

Previous value: -[
-  "topic",
-  "partition",
-  "before_offset"
-]New value: +[
+  "topic"
+]

addedOutput schema / properties / results / items / properties / result / properties / all_partitions
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / results / items / properties / result / properties / partitions

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "affected_groups": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "committed_offset": {
+              "type": "integer"
+            },
+            "group": {
+              "type": "string"
+            },
+            "unprocessed_lost": {
+              "type": "integer"
+            }
+          },
+          "required": [
+            "group",
+            "committed_offset",
+            "unprocessed_lost"
+          ],
+          "type": "object"
+        },
+        "type": [
+          "null",
+          "array"
+        ]
+      },
+      "before_offset": {
+        "type": "integer"
+      },
+      "end_offset": {
+        "type": "integer"
+      },
+      "messages_deleted": {
+        "type": "integer"
+      },
+      "partition": {
+        "maximum": 2147483647,
+        "minimum": -2147483648,
+        "type": "integer"
+      },
+      "resulting_start_offset": {
+        "type": "integer"
+      },
+      "start_offset": {
+        "type": "integer"
+      }
+    },
+    "required": [
+      "partition",
+      "start_offset",
+      "end_offset",
+      "before_offset",
+      "messages_deleted",
+      "affected_groups"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

First observedv0.2.0Oct 7, 2026

TDQS

A4.7/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 thoroughly: two independent gates (confirm and acknowledge_data_loss), preview contents including per-consumer-group data-loss exposure, irreversibility ('Kafka cannot restore deleted records'), non-atomic batch failure semantics, result ordering, duplicate item refusal, compacted-topic caveat, and the required Kafka DELETE permission.

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?

Front-loads the operation and scope in the first sentence, then layers gating, preview, and failure semantics in short paragraphs that each carry distinct information. Length is justified by the destructive nature of the tool; nothing is padding.

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?

Output schema exists, yet the description still summarizes the preview payload (start/end offsets, message counts, affected consumer groups). Combined with permissions, irreversibility, and partial-failure behavior, an agent has everything needed to call this safely.

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 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning: one confirm covers the whole batch, all_partitions resolves a single moment per partition, and before_offset/before_timestamp are mutually exclusive. It does not add much to individual fields beyond what the schema already states.

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 precise verb and resource ('Delete the oldest messages of 1 to 1000 partitions') and immediately bounds the scope with 'without deleting the topic', which cleanly separates it from delete_topic in the sibling list. An agent knows exactly what operation this performs without opening 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 Guidelines4/5

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

Gives concrete motivating scenarios ('purge test data, or a run of bad messages at the head of a partition, while keeping the topic, its configuration and its consumer groups') and clarifies the single-partition case. It never names a sibling alternative explicitly, relying on the implicit 'without deleting the topic' contrast with delete_topic, so it falls short of a full when/when-not/alternatives statement.

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