TopicForge

Overview Schema Source Related Servers Discussions Admin

list_participants

List DDS participants on the bus, returning GUID, vendor, hostname, domain ID, and status, to inspect the ROS2 graph read-only.

Instructions

List DDS participants observed on the bus. Returns list[ParticipantInfo]: each entry carries guid, vendor (cyclone/fast/rti/rti_micro/opensplice/opendds/coredx/intercom/dust/mock/unknown) with vendor_source, optional name (announced EntityName QoS, e.g. lidar_driver), optional hostname, domain_id, is_observer and mode_effective (live/mock). Why vendor can be unknown: the vendor is read from the participant GUID prefix (vendor_source guid_prefix; none when unknown). Some vendors, e.g. Dust DDS and RTI Connext, do not put their vendor id there, and the Cyclone Python binding does not expose the RTPS header vendor id, so those participants are listed as unknown. is_observer is true for TopicForge's own read-only participant, which is listed like any other. Lifecycle fields: status (active/left), first_seen_ns / last_seen_ns (TopicForge's local clock), seen_count, announced_ns (DDS source timestamp of the announcement), and once left lost_ns + lost_time_source. lost_ns is an upper bound of when the participant died: exact after a clean shutdown, the lease expiry after a crash (the two cannot be told apart), so a crashed process died up to one lease before it (10 s Cyclone default, 20 s Fast DDS, 100 s RTI; the dead participant's lease, not ours). Cyclone tracks discovery continuously in the background, so these stay correct between calls; right after server start the call waits up to 3 s for discovery to warm up. Only the domain joined at startup is observed (see health_check dds_domain_id): a participant on another DDS domain is INVISIBLE here, so a missing participant may be on a different domain; domain_id does not switch domains (restart with TOPICFORGE_DDS_DOMAIN_ID). Works at the raw DDS layer beneath ROS, so it also sees non-ROS participants. Read-only by architecture: it cannot publish, modify QoS, or alter the bus. Raises an MCP error when no DDS module is active (install pip install topicforge[dds] and set TOPICFORGE_DDS_BACKEND=cyclone). The mock backend returns fixtures.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`domain_id`	No	Accepted 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.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.5.6Oct 5, 2026

TDQS

A4.4/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 behavioral burden and does so richly: read-only by architecture, raises an MCP error without a DDS module, waits up to 3 s for discovery warm-up, mock backend returns fixtures, and it discloses that `lost_ns` is only an upper bound with per-vendor lease timing. These are exactly the traits an agent cannot get from structured fields.

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?

Front-loaded with purpose and return type, then bolded sub-sections keep the dense material navigable. It is long, and the exhaustive vendor enum restates what the output schema already lists, but nearly every sentence carries substantive semantic information rather than 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, so return values needn't be explained, yet the description supplies the semantic layer the schema can't (why `vendor` can be `unknown`, what `is_observer` means, how lease expiry bounds `lost_ns`). Error conditions, domain limits, and warm-up behavior round out everything needed to invoke it correctly.

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 coverage is 100% and the schema already explains that `domain_id` is accepted only for compatibility. The description echoes this and adds a small diagnostic hint (a missing participant may be on another domain), but does not add format or syntax meaning beyond the schema, so the baseline of 3 applies.

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 and resource ('List DDS participants observed on the bus') and immediately names the return type (`list[ParticipantInfo]`). An agent can distinguish it from siblings like list_endpoints, list_topics, and participant_events from the first sentence alone.

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 clear context: it observes only the startup domain, participants on other domains are invisible, and it redirects to `health_check` for `dds_domain_id`. It also explains it operates beneath ROS so non-ROS participants appear. It stops short of explicitly contrasting with the closest sibling (participant_events for history vs. this for current state).

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

Deploy Server