Skip to main content
Glama
yaniswav

TopicForge

by yaniswav
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

list_endpoints

Inspect all DDS writers and readers on the bus, with topics, types, QoS, and participant details, to detect orphaned endpoints and understand the ROS2 graph configuration.

Instructions

List every DDS endpoint (writer and reader) announced on the bus, one EndpointInfo per endpoint with role, topic, type_name, type_id, the owning participant_guid joined with its participant_name, and a structured qos (reliability, durability, history, deadline, liveliness kind and lease, ownership kind and strength, partitions, latency budget, destination order, data representation). Use it instead of parsing peek_dds_samples output and joining GUID prefixes. Spotting orphans: by_topic rolls the endpoints up per topic with writer_count, reader_count and orphan ("no_reader" = a writer nobody subscribes to, "no_writer" = a reader nobody publishes to), plus the union of partitions. Reading qos: a duration of None (deadline_ns, liveliness_lease_ns, latency_budget_ns) means infinite or not set; a policy field of None means the endpoint did not announce it. Ownership: among EXCLUSIVE writers the live one with the highest ownership_strength delivers to a reader; which writer currently owns an instance is reader-side runtime state TopicForge cannot observe. Departed endpoints: when a participant leaves, its endpoints are remembered (last 200, 1 h) and shown in by_topic as departed_writers / departed_readers (participant name and gone_ns), so a topic that lost its only writer is explained in one call; they are listed in endpoints only with include_departed. Topic filter: rt/scan and scan match each other (exact name first; note says which form matched), and a filter that matches nothing returns a note with the closest known topics. announced_ns is the discovery announcement's source timestamp on the announcing side's clock, which can differ from this host's clock. This lists discovery facts, not data flow: it shows which endpoints exist and how they are configured, not whether samples move. activity is always None (see activity_note): TopicForge holds no reader on user topics and cannot tell a silent or hung writer from a healthy one. Pair it with detect_qos_mismatches to see which pairs cannot match. TopicForge's own observer participant is excluded unless include_observer is true. Output is capped at 500 endpoints (truncated, total_discovered); by_topic still covers all matches. Read-only. Raises an MCP error when no DDS module is active. Mock mode returns a fixture matching the other mock DDS tools.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
topicNoOnly endpoints on this DDS topic name: a bare name such as `scan` or a ROS 2 mangled name such as `rt/scan` (exact name first, then the alternate form). Omit to list every topic.
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.
include_departedNoAlso list endpoints whose participant left the bus (flagged with `gone_ns`). Defaults to false; `by_topic` reports them as `departed_writers` / `departed_readers` either way.
include_observerNoInclude TopicForge's own observer participant's endpoints. Defaults to false.
participant_guidNoOnly endpoints owned by this participant, as the guid reported by `list_participants` or by an earlier `list_endpoints`. Omit for all participants.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
noteNoHint when a `topic` filter matched nothing: names the closest known topics.
by_topicYesRoll-up over every matching endpoint.
returnedYesLength of `endpoints`.
domain_idYesDDS domain observed.
endpointsYesMatching endpoints, capped (see `truncated`).
truncatedYesTrue when matching endpoints exceeded the cap.
snapshot_nsYesWall-clock time of the snapshot, ns since epoch.
observer_guidNoGUID of TopicForge's own participant, `None` in mock.
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`.
total_discoveredYesEndpoints in the discovery cache before any filter.
departed_endpointsNoDeparted endpoints (their participant left) matching the filters. They are in `endpoints` only with `include_departed`; `by_topic` always carries them as `departed_writers` / `departed_readers`.
excluded_observer_endpointsNoEndpoints of TopicForge's own observer participant left out of `endpoints` (they are counted in `total_discovered`). Explains `total_discovered` vs `returned` together with the filters.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.5.6

TDQS

A4.6/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 thoroughly: read-only, raises an MCP error when no DDS module is active, mock mode returns a fixture, output capped at 500 endpoints with `truncated`/`total_discovered`, departed endpoints retained (last 200, 1 h), `activity` is always None and why, observer participant excluded unless `include_observer`, and how `None` duration/policy fields should be read. These are exactly the non-obvious traits 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?

It is long, but the bold-labeled sections (Spotting orphans, Reading qos, Ownership, Departed endpoints, Topic filter, This lists discovery facts) make it scannable and the core purpose is front-loaded in the first sentence. Nearly every sentence conveys a non-obvious behavior, though the volume is close to the upper bound of what is proportionate.

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-value documentation is not strictly required, yet the description still maps the fields, semantics of `None`, and the `by_topic` roll-up. Combined with the failure mode, cap behavior, and observer exclusion, an agent has everything needed to call and interpret this tool correctly.

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 the baseline is 3, but the description adds real meaning: the topic-matching rule (`rt/scan` and `scan` match each other, exact name first, with a `note` indicating which form matched, and a closest-known-topics note on no match), the fact that `domain_id` does not switch domains, and that participant_guid composes from list_participants output. It goes beyond what the schema states.

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?

The opening sentence gives a specific verb and resource ('List every DDS endpoint (writer and reader) announced on the bus') and enumerates the per-endpoint payload (role, topic, type_name, participant_guid joined with participant_name, structured qos). It explicitly separates itself from sibling `peek_dds_samples` by saying to use this 'instead of parsing `peek_dds_samples` output and joining GUID prefixes.' An agent can distinguish it from list_participants/list_topics without opening any schema.

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?

It names an explicit alternative and the reason to prefer this tool ('instead of parsing `peek_dds_samples` output'), and points to a complementary tool ('Pair it with `detect_qos_mismatches` to see which pairs cannot match'). It also explains when the orphan and departed-endpoint views matter. There is no explicit 'do not use this when X' exclusions against other siblings, so it stops short of 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