TopicForge

Overview Schema Source Related Servers Discussions Admin

peek_dds_samples

Read recent samples directly from a raw DDS topic without ROS 2. Returns topic, count, samples, and notes; user-defined payloads are not decoded.

Instructions

Peek recent samples on a raw DDS topic. Unlike sample_messages (which uses the ros2 CLI), this reads the DDS layer directly and works without ROS 2. Returns a SampleResult {topic, count, samples, mode_effective, note}, the same shape as sample_messages. count defaults to 5 and is silently clamped to 50. Topic categories: (a) The 3 builtin discovery topics (DCPSParticipant, DCPSSubscription, DCPSPublication) return structured discovery payloads: on Cyclone the CURRENT discovery state (one record per live participant or endpoint), not a stream of recent events (use participant_events for history). DCPSPublication and DCPSSubscription are the raw writers and readers behind list_endpoints. The topic may be given as /scan, scan or rt/scan: all three resolve to the same topic. (b) User-defined topics: payload decoding is DISABLED on every backend. The call returns count 0, samples empty and a note saying so; that does NOT mean the topic is silent. Use list_endpoints for the topic's presence, writers, readers and QoS. A user topic that is not announced on the bus raises an error. Right after server start the call waits up to 3 s for discovery to warm up. Read-only by architecture: it cannot publish. Raises an MCP error when no DDS module is active or the topic is not announced on the bus.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`count`	No	Maximum number of recent messages to return. Defaults to 5; silently clamped to 50 (the hard cap that keeps tool output bounded; read it from `health_check.max_sample_count`). Negative values raise an error. The returned `SampleResult.count` reflects the actual number of samples produced: it can be lower than the request (empty topic, timeout, mock fixture shorter than requested).
`topic`	Yes	DDS topic name. Bare DDS names such as `scan` are valid, as are ROS 2 mangled names such as `rt/scan` and the builtin discovery topics `DCPSParticipant`, `DCPSSubscription`, `DCPSPublication`. Letters, digits, `_`, `/` and `::` are allowed; anything else is rejected.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	No	Why `samples` is empty or limited, when the cause is not obvious (for example payload decoding is disabled for DDS user topics). `None` when there is nothing to add.
`count`	Yes	Number of samples actually returned. May be 0 (no publisher active in live mode, or empty mock fixture), less than the requested count (topic yielded fewer messages within the timeout), or capped by the the silent maximum of 50: request `count > 50` and you will receive at most 50 without warning.
`topic`	Yes	Topic the samples were taken from, echoed from the request.
`samples`	Yes	The sampled messages, ordered as received from the backend.
`mode_effective`	Yes	Runtime mode the adapter served this response in: `live` (real ROS2 introspection) or `mock` (deterministic fixtures). Lets a caller tell a real graph from a demo one without calling `health_check`.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.5.6Oct 5, 2026

TDQS

A4.8/5.0

Behavior5/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 and does so richly: read-only by architecture (cannot publish), raises an MCP error in two specific situations, 3 s discovery warm-up, silent clamping of count, and payload decoding disabled on user topics returning count 0 with a note. This is exactly the behavioral context an agent needs.

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?

Dense and front-loaded – the core distinction from `sample_messages` comes first, then topic categories, then failure modes. It is long, but nearly every sentence carries operational information; minor redundancy exists in restating the `SampleResult` shape that the output schema already covers.

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-param tool with no annotations, the description covers selection rationale, topic-name handling, per-category return semantics, limits, and error conditions. With an output schema present, the brief restatement of the return shape is not a gap.

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 baseline is 3, but the description adds real meaning: the three accepted topic name forms (`/scan`, `scan`, `rt/scan`) resolve to the same topic, and the builtin discovery topics have distinct return semantics. It also explains the clamping behavior for count, though that is largely mirrored in the 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?

States a specific verb+resource ('peek recent samples on a raw DDS topic') and immediately differentiates from the sibling `sample_messages`, explaining that this reads the DDS layer directly and works without ROS 2. An agent can tell it apart from the other sampling/list tools without opening a schema.

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

Usage Guidelines5/5

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

Explicitly routes the agent: use `participant_events` for discovery history, `list_endpoints` for a user topic's presence/writers/readers/QoS, and `sample_messages` if you need the ros2 CLI. It also states the failure conditions (no DDS module, unannounced topic) and the warm-up wait.

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

Deploy Server