Kafka MCP

Overview Schema Source Related Servers Discussions Admin

sample_messages

Sample up to 500 topics in one call to summarize value formats, field paths, schemas, value sizes, and offset ranges, then design a search_messages predicate against recent data.

Instructions

Sample the newest messages of 1 to 500 topics in one call through items, and summarize value formats, field paths, key usage, the schemas values were written with, raw value sizes (value_bytes min/p50/max), and sampled offset ranges. Use this to design a search_messages predicate, and to find the schema to produce against.

Avro, Protobuf and JSON Schema values carrying a Schema Registry id, and topics with a configured format, are decoded, so their field paths are reported like JSON. value_formats.undecodable counts values that named a schema but could not be decoded; decode_error on each message says why.

Results follow items order, each carrying index with result or error. Sampling one topic is an items array of length one. The sample describes recent data only, and keys must not be used to guess partitions.

Input Schema

Name	Required	Description	Default
`items`	Yes	The topics to sample, 1 to 500 of them. Sampling one topic is an array of length one. Results follow this order and a topic that cannot be sampled is reported against its own item.

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.2.7Oct 25, 2026

changedInput schema / properties / items / description

Previous value: -"The topics to sample, 1 to 20 of them. Sampling one topic is an array of length one. Results follow this order and a topic that cannot be sampled is reported against its own item."New value: +"The topics to sample, 1 to 500 of them. Sampling one topic is an array of length one. Results follow this order and a topic that cannot be sampled is reported against its own item."

changedInput schema / properties / items / items / properties / max_value_bytes / description

Previous value: -"Optional maximum value bytes to return per message. Defaults to 512."New value: +"Optional maximum value bytes to return per message. Defaults to 512, at most 1048576."

changedInput schema / properties / items / items / properties / sample_size / description

Previous value: -"Optional number of messages to read in total, spread across partitions. Defaults to 20."New value: +"Optional number of messages to read in total, spread across partitions. Defaults to 20, at most 1000."

addedOutput schema / properties / results / items / properties / result / properties / value_bytes

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "max": {
+      "type": "integer"
+    },
+    "min": {
+      "type": "integer"
+    },
+    "p50": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "min",
+    "p50",
+    "max"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / results / items / properties / result / required

Previous value: -[
-  "topic",
-  "messages",
-  "sampled_ranges",
-  "value_formats",
-  "json_fields",
-  "key_stats",
-  "key_in_value",
-  "schemas"
-]New value: +[
+  "topic",
+  "messages",
+  "sampled_ranges",
+  "value_formats",
+  "json_fields",
+  "key_stats",
+  "key_in_value",
+  "schemas",
+  "value_bytes"
+]

First observedv0.2.0Oct 7, 2026

TDQS

A4.2/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full behavioral burden. It discloses decoding of Avro, Protobuf and JSON Schema values, how undecodable values are counted, per-message decode_error meaning, ordered results/errors, and the recency limitation; it does not explicitly discuss permissions or read-only side effects, but the sampling nature is clear.

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 front-loaded with the core purpose and follows with decoding semantics and result-order caveats. It is dense but every sentence contributes; only the long facet list in the first sentence slightly reduces crispness.

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 an output schema and full input-schema coverage, the description supplies the missing behavioral context an agent needs: decoding/error semantics, recency limits, result ordering, and the key-handling caveat. No essential invocation guidance appears missing.

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

Parameters3/5

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

Schema description coverage is 100%, so baseline is 3. The description reinforces that items holds 1 to 500 topics and that sampling one topic is a length-one array, and it explains result order/error reporting, but it adds little beyond the schema's own descriptions for partitions, sample_size, and max_value_bytes.

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, and batch scope: 'Sample the newest messages of 1 to 500 topics in one call through items.' It also enumerates the summary facets returned and distinguishes the tool from search_messages by casting it as a predicate-design and schema-discovery step.

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?

Explicitly names search_messages as the downstream use case and says to use this to 'find the schema to produce against,' giving clear usage context. It also warns that the sample is recent-only and keys must not be used to guess partitions, though it does not state explicit when-not conditions versus get_message or get_schema.

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