TopicForge

Overview Schema Source Related Servers Discussions Admin

get_topic_info

Inspect a single ROS 2 topic to return its effective mode and live publisher QoS reliability and durability, helping diagnose latched topics and QoS mismatches. Read-only.

Instructions

ROS 2 graph only; on a DDS-only setup use list_endpoints. Return info for a single ROS 2 topic. topic must be a fully qualified name, e.g. /cmd_vel. Returns a TopicInfo with mode_effective (live or mock) and, in live mode, the publishers' qos_reliability (reliable / best_effort / mixed) and qos_durability (volatile / transient_local / mixed; transient_local marks a latched topic such as /tf_static). Raises an MCP error if the topic name is malformed, the topic is unknown to the active graph, or no ros2 CLI is available. Read-only; no side effects.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`topic`	Yes	Fully qualified ROS2 topic name starting with `/`, e.g. `/cmd_vel` or `/camera/image_raw`. Each `/`-separated segment must start with a letter or underscore and contain only letters, digits, and underscores; everything else (whitespace, quotes, shell metacharacters, `//`, trailing `/`) is rejected before reaching the `ros2` CLI.

Output Schema

TableJSON Schema

Name	Required	Description
`name`	Yes	Fully qualified topic name, e.g. `/cmd_vel`.
`qos_profile`	No	Effective DDS QoS profile for this topic when resolvable. `None` from the ROS2 CLI adapter or when the DDS module is inactive. The DDS module populates this on a best-effort basis (picks one representative endpoint if reader/writer QoS differ).
`message_type`	Yes	ROS2 message type, e.g. `geometry_msgs/msg/Twist`.
`reader_count`	No	DDS reader-endpoint count when the active backend can resolve endpoint-level info (Cyclone / Fast DDS). `None` from the ROS2 CLI adapter or when the DDS module is inactive.
`writer_count`	No	DDS writer-endpoint count when the active backend can resolve endpoint-level info. `None` from the ROS2 CLI adapter or when the DDS module is inactive.
`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`.
`qos_durability`	No	Durability announced by the topic's publishers: `volatile`, `transient_local` (late subscribers receive the last samples; typical of latched topics such as `/tf_static`), or `mixed` when publishers disagree. `null` when unknown, with the same rules as `qos_reliability`.
`publisher_count`	Yes	Publishers known to the graph.
`qos_reliability`	No	Reliability announced by the topic's publishers: `reliable`, `best_effort`, or `mixed` when publishers disagree. `null` when unknown: the topic has no publisher, or the value was not read (`list_topics` does not read QoS; `get_topic_info` does).
`subscriber_count`	Yes	Subscribers known to the graph.

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 provided, the description carries the full behavioral burden and does so: it discloses the live/mock mode distinction, the specific QoS fields returned, and the exact error conditions (malformed name, unknown topic, missing ros2 CLI). It also states 'Read-only; no side effects,' which is the safety profile an agent needs and is not contradicted by any annotation.

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 scope/routing constraint comes first, then the argument, then the return shape, then failure modes. Every clause adds information, though the detailed enumeration of TopicInfo fields partially duplicates the 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?

All inputs, routing, failure modes, and the read-only contract are covered for a single-argument lookup tool. With an output schema present, the return-value prose is a bonus rather than a necessity, so nothing an agent needs is missing.

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 fully-qualified-name rule and character restrictions are already documented in the input schema. The description restates the format with the same `/cmd_vel` example rather than adding syntax or resolution behavior beyond it, so the 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+resource ('Return info for a single ROS 2 topic') and names the boundary condition against a sibling ('ROS 2 graph only; on a DDS-only setup use `list_endpoints`'). An agent can distinguish it from topic_metrics or list_topics without opening the 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?

Explicitly names the alternative tool and the condition that selects it (DDS-only setups -> list_endpoints), which is strong routing guidance. It doesn't cover adjacent siblings like topic_metrics, and the 'single topic' scope is only implicit in 'Return info for a single ROS 2 topic', so it falls just short of fully explicit when/when-not coverage.

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

Deploy Server