TopicForge

Overview Schema Source Related Servers Discussions Admin

participant_events

Retrieve recent DDS participant lifecycle events (discovered/lost) to see who joined or left the bus and when they first appeared.

Instructions

Return DDS participant lifecycle events (discovered / lost) from a recent window, e.g. 'who was on the bus 5 minutes ago and left?' or 'when did this participant first appear?'. Returns list[ParticipantEvent]: each entry carries guid, event_type, vendor, timestamp_ns (wall-clock ns since epoch), time_source, observed_ns, optional name (the participant's announced DDS name), optional hostname, domain_id, and mode_effective (live/mock). time_source says what timestamp_ns is: dds_source_timestamp (the DDS timestamp of the announcement or dispose) or observed_local (when TopicForge noticed, weakest). observed_ns is when TopicForge noticed, always at or after a DDS-derived timestamp_ns. Crash caveat: a lost timestamp is an upper bound of the death. After a clean shutdown it is exact; after a crash it is when the lease expired, so the process died between timestamp_ns minus the dead participant's lease and timestamp_ns (10 s Cyclone default, 20 s Fast DDS, 100 s RTI), and the two cases cannot be told apart. A restarted node is a new participant: expect one lost and one discovered per restart, with different guids and the same name. Sorted newest-first. Capped at 200 events, silently (reduce lookback_seconds if you hit it). TopicForge only knows what happened since it started watching (see health_check.observer_started_ns). Backend caveats: Fast DDS captures arrivals and removals through listener callbacks; Cyclone tracks discovery in the background (a pass every 0.5 s, independent of tool calls), so restarts and crashes are recorded as they happen, but a participant cycle faster than the discovery reader's history depth between two passes can be missed; mock returns a fixture timeline. Right after server start the call waits up to 3 s for discovery to warm up. Read-only by architecture. Raises an MCP error when no DDS module is active (install pip install topicforge[dds] and set TOPICFORGE_DDS_BACKEND=cyclone|fast).

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.
`lookback_seconds`	No	Window (in seconds) over which to return events. Defaults to 300 (5 minutes). Range: 1..86400 (1 second to 24 hours). Larger windows may hit the 200-event cap: narrow the window or filter on `domain_id` when that happens.

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?

No annotations, so the description carries the full burden and does so richly: crash caveat with lease bounds per backend, restart semantics (one lost + one discovered per restart), 200-event silent cap, warm-up wait, backend-specific capture behavior, mock fixture mode, and the MCP error condition with required install/env settings.

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?

Long but dense and front-loaded: purpose first, then return shape, then semantics, then caveats. Nearly every sentence carries a unique fact, though the field-by-field enumeration of the return type overlaps with the existing output schema and could be trimmed.

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 output schema exists, return values needn't be explained, yet the description goes further with time_source semantics (dds_source_timestamp vs observed_local, weakest) and observed_ns ordering. Combined with crash/restart/backend caveats, an agent has everything needed to call and interpret 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 description coverage is 100%, so the schema already documents both parameters including the 200-event cap interaction with lookback_seconds and the domain_id compatibility note. The description's mention of reducing lookback_seconds largely repeats the schema, so baseline 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 ('Return DDS participant lifecycle events (`discovered`/`lost`)') with explicit scope (recent window). It is clearly distinguishable from siblings like list_participants (current snapshot) and health_check (observer metadata), which it cross-references.

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?

Provides concrete motivating questions ('who was on the bus 5 minutes ago and left?', 'when did this participant first appear?') that map directly to invocation. However, it never explicitly contrasts with the nearest sibling, list_participants, nor states when-not to use it.

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

Deploy Server