Skip to main content
Glama
Sign In
TopicForge

TopicForge

by yaniswav
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

list_nodes

Read-onlyIdempotent

Lists ROS 2 graph nodes (or mock graph) from one ros2 node list call, including namespaces, lifecycle status, and duplicate counts.

Instructions

ROS 2 graph only; on a DDS-only setup use list_participants. List the nodes on the ROS 2 graph (or the mock graph) from one ros2 node list call as a NodeListing: name, namespace, full_name, duplicate_count, lifecycle (managed node; state not read, lifecycle_note if unknown), by_namespace counts. duplicates lists full names used by several nodes (a per-node tool then answers for one of them, unidentified). Nodes starting with an underscore are hidden and a node on another ROS_DOMAIN_ID is invisible. Empty nodes when the graph has none. Use get_node_info for one node's interfaces. Raises an MCP error without a ros2 CLI. Cheap (two CLI calls). Duration: ROS lock, one call at a time, ends within 45 s; busy if held.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_nodes"
  }
}

Input Schema

NameRequiredDescriptionDefault

No arguments

Output Schema

NameRequiredDescriptionDefault
noteNoOne sentence of context, or `None`.
nodesYesNodes on the graph, one entry per distinct full name, sorted by name.
totalYesDistinct node names on the graph (no cap applies).
returnedYesLength of `nodes`.
truncatedYesTrue when `returned` is less than `total` because of a cap.
duplicatesYesFull names that appear more than once on the graph. Empty when every name is unique.
by_namespaceNoDistinct full names per namespace (`/` is the root), sorted by namespace.
lifecycle_noteNoWhy `lifecycle` could not be determined (service list failed), else `None`.
mode_effectiveYes`live` or `mock` (fixtures).
lifecycle_countNoNodes with `lifecycle` true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.9.0
    • changedOutput schema / $defs / NodeListItem / properties / lifecycle / description
      Previous value: -"True when the graph has `<full_name>/get_state` of type `lifecycle_msgs/srv/GetState` (a managed node). The state itself is never read."New value: +"True when the graph has `<full_name>/get_state` (`lifecycle_msgs/srv/GetState`). The state itself is never read."
  2. Changed8 schema fields changedv0.8.0
    • addedOutput schema / $defs / NodeListItem / properties / lifecycle
      Added value: +{
+  "description": "True when the graph has `<full_name>/get_state` of type `lifecycle_msgs/srv/GetState` (a managed node). The state itself is never read.",
+  "type": "boolean"
+}
    • removedOutput schema / description
      Removed value: -"Envelope returned by `list_nodes`."
    • addedOutput schema / properties / by_namespace
      Added value: +{
+  "additionalProperties": {
+    "type": "integer"
+  },
+  "description": "Distinct full names per namespace (`/` is the root), sorted by namespace.",
+  "type": "object"
+}
    • addedOutput schema / properties / lifecycle_count
      Added value: +{
+  "description": "Nodes with `lifecycle` true.",
+  "minimum": 0,
+  "type": "integer"
+}
    • addedOutput schema / properties / lifecycle_note
      Added value: +{
+  "description": "Why `lifecycle` could not be determined (service list failed), else `None`.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • removedOutput schema / properties / note / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • removedOutput schema / properties / note / default
      Removed value: -null
    • addedOutput schema / properties / note / type
      Added value: +[
+  "string",
+  "null"
+]
  3. Addedv0.7.1

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), but the description adds behavior they cannot express: hidden underscore-prefixed nodes, invisibility across `ROS_DOMAIN_ID`, an MCP error without the `ros2` CLI, and empty `nodes` on an empty graph. It also discloses cost and contention (two CLI calls, ROS lock, 45 s ceiling, `busy` when held) and the ambiguity of `duplicates` — unusually rich for a read-only list tool.

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 the scoping constraint and two sibling redirects, with cost/timing pushed to the end where it belongs. The one inefficiency is the enumeration of `NodeListing` fields (`name`, `namespace`, `full_name`, `duplicate_count`, `lifecycle`, `by_namespace`), which largely restates the output schema.

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?

For a zero-parameter list tool with an output schema and full annotations, everything an agent needs is present: when to pick it, what it will not see, failure mode, latency and lock contention, and the empty-graph result. Nothing material is left to inference.

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?

There are zero parameters, so the baseline is 4; there is no parameter semantics to add or omit. The description spends no words on inputs, which is correct here.

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 the nodes on the ROS 2 graph') and scopes it to a single `ros2 node list` call returning a `NodeListing`. It also disambiguates from siblings by naming `list_participants` for DDS-only setups and `get_node_info` for a single node's interfaces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit exclusion ('ROS 2 graph only; on a DDS-only setup use `list_participants`') plus an in-scope alternative (`get_node_info` for one node). The conditions that select between the three tools are stated outright rather than implied.

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