Skip to main content
Glama
yaniswav

TopicForge

by yaniswav
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

topic_metrics

Compute temporal metrics for a DDS topic over a recent time window. Get frequency, sequence gaps, and latency percentiles to inspect ROS2 graph health.

Instructions

Return temporal metrics (frequency, sequence gaps, latency percentiles) for a DDS topic over a recent time window. Returns a TopicMetrics payload carrying status, samples_observed, frequency_hz_observed, frequency_hz_declared, sequence_gaps_count, latency_ns_p50/p95/p99, and boolean availability flags. Read status first: unsupported_user_topic means the topic is a user topic, whose payload is not decoded, so there are no metrics: every number is null or 0 and none of it is a measurement. no_samples_yet means a builtin topic with nothing buffered in the window. ok means metrics were computed. Limits: the buffer is filled only when peek_dds_samples runs on the topic, so frequency_hz_observed reflects how often it was called, not the real publish rate: treat it as a coarse presence signal. frequency_hz_declared is declared, not measured: 1 / deadline of the shortest QoS Deadline a writer on the topic announced in discovery, null when none announced one. Read-only by architecture. Raises an MCP error when no DDS module is active or window_seconds is out of range (1..3600). Right after server start the call waits up to 3 s for discovery to warm up.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
topicYesDDS 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.
domain_idNoAccepted for compatibility (0..232). TopicForge observes the domain it joined at startup (TOPICFORGE_DDS_DOMAIN_ID); this argument does not switch domains, and the response `domain_id` says which one was observed.
window_secondsNoWindow in seconds over which to compute metrics (1..3600). Defaults to 60 seconds. Smaller windows reflect more recent state; larger windows smooth transient anomalies.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
topicYesTopic the metrics were computed for.
statusNoHow to read the numbers. `unsupported_user_topic`: the topic is a user topic, whose payload is not decoded, so no metric exists and the null fields are not a measurement. `no_samples_yet`: a supported topic with nothing buffered in the window. `ok`: metrics computed from buffered samples.ok
latency_ns_p50NoMedian publish-to-receive latency in nanoseconds, computed only when the sample type exposes a publish timestamp (typically via `header.stamp` on `Header`-stamped messages). `None` when `latency_available=False`.
latency_ns_p95No95th-percentile publish-to-receive latency (ns).
latency_ns_p99No99th-percentile publish-to-receive latency (ns).
mode_effectiveYesRuntime 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`.
window_secondsYesRequested window in seconds (1..3600). Echoed back from the tool call so the LLM can correlate the request.
samples_observedYesNumber of samples in the buffer matching `topic` within the window. `0` means TopicForge has not seen any sample on this topic recently: it does NOT mean the topic has no publisher, only that no `peek_dds_samples` call captured one in the window.
latency_availableNoTrue when at least one sample in the window carried both a publish timestamp and a receive timestamp. The percentile fields are `None` when this is False.
sequence_gaps_countNoNumber of missing sequence numbers detected in the buffered samples. `0` either means no gaps observed OR the sample type did not expose a sequence number (check `sequence_numbers_available` to disambiguate).
frequency_hz_declaredNoDeclared, not measured: `1 / deadline` for the shortest QoS Deadline period announced by a writer on this topic in discovery. `None` when no writer announced a finite Deadline or the topic is not announced. It is the rate the application promised, not the rate observed.
frequency_hz_observedNo`samples_observed / window_seconds_actual`. `None` when fewer than 2 samples were observed (a single sample does not define a frequency).
window_seconds_actualYesActual elapsed seconds within the window. May be smaller than `window_seconds` when the adapter buffered samples for less time than the requested window (e.g., the server just started). `0.0` when `samples_observed=0`.
sequence_numbers_availableNoTrue when the adapter successfully extracted sequence numbers from at least one sample. Sequence number support depends on the message type: `Header`-stamped messages with a `seq` field expose it; primitives like `std_msgs/String` do not.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.5.6

TDQS

A4.5/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 it does so thoroughly: status semantics and their meaning for the numbers, the observability limitation of frequency_hz_observed, the declared-vs-measured distinction for frequency_hz_declared, the read-only architecture, the MCP error conditions (no DDS module, out-of-range window), and the 3 s discovery warm-up delay. This is exactly the behavioral context an agent needs to avoid misinterpreting results.

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-loaded with purpose, then progressively adds interpretation rules (status), limits, error conditions, and startup caveats using bold markers for scannability. Despite its length, every sentence carries distinct decision-relevant information with no filler.

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?

An output schema exists, yet the description still names the payload fields and, more importantly, explains how to interpret them (status branches, null/0 caveats, declared-vs-measured). For a single-resource compute tool with three fully-documented params, this is complete.

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 all three parameters are already fully documented in the schema (including the domain_id no-op explanation and window_seconds range). The description adds only the error condition for an out-of-range window, so the schema does the heavy lifting and a baseline 3 is appropriate.

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 (Return) and resource (temporal metrics: frequency, sequence gaps, latency percentiles) scoped to a DDS topic over a time window. The named metric set distinguishes it from siblings like peek_dds_samples or get_topic_info, which don't compute derived temporal metrics.

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?

Explains the operational context clearly: the buffer is populated only when peek_dds_samples runs, so the metric is a coarse presence signal. It also tells the agent to read `status` first and enumerates the branches. It stops short of an explicit when-to-use-this-vs-X directive against siblings, so it's a strong 4 rather than a 5.

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

Deploy Server

Other Tools