TopicForge

Overview Schema Source Related Servers Discussions Admin

graph_diff

Read-onlyIdempotent

Compare a ROS 2 graph or bag snapshot with a baseline to report node, topic, type, QoS, rate, and count changes, answering what changed since it last worked.

Instructions

ROS 2 graph only. Answer "what changed since it last worked": snapshot the graph (or bag_path) and compare it with baseline, as a GraphDiff. changes are node, topic, type, qos, rate and count differences; added = present now, absent from the baseline. not_compared names what a pair cannot support: nodes and counts need live against live, rates bag against bag, writer QoS a DDS backend. /rosout and /parameter_events count noise is only tallied in builtin_changes_count. The first call stores a snapshot and says so in note. Snapshots stay in memory (16, lost on restart). Raises an MCP error for an unknown id, a bad bag path or without a ros2 CLI. Mock mode: the first call reports 3 changes, the next 0. 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": "graph_diff"
  }
}

Input Schema

Name	Required	Description	Default
`bag_path`	No	Snapshot this bag instead of the live graph.
`baseline`	No	`previous` (last snapshot), a `snap-N` id from `snapshot_ids`, or a bag path.	previous

Output Schema

Name	Required	Description
`note`	No	One sentence of context, or `None`.
`changes`	Yes
`current`	Yes
`baseline`	No	`null` without baseline.
`added_count`	Yes
`baseline_id`	No	`null` without baseline (`note`).
`snapshot_id`	Yes	Stored snapshot id.
`not_compared`	Yes	Skipped comparison and why.
`snapshot_ids`	Yes	Held ids, oldest first.
`changed_count`	Yes
`removed_count`	Yes
`mode_effective`	Yes	`live` or `mock` (fixtures).
`builtin_changes_count`	Yes	Count changes on `/rosout`, `/parameter_events`: not in `changes`.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.11.0Nov 12, 2026

addedOutput schema / $defs / GraphSnapshotRef / properties / taken_utc

Added value: +{
+  "description": "`taken_ns` as ISO 8601 UTC (a bag: when read).",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Addedv0.8.0Oct 21, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the annotations, it discloses in-memory snapshot retention (16, lost on restart), MCP error conditions for unknown ids, bad bag paths, missing CLI, a documented mock mode, and a single-call duration limit with a 'busy' state. It also explains `not_compared` and that builtin node count noise is only tallied in `builtin_changes_count`.

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?

The purpose and scope are front-loaded and every sentence carries information about outputs, errors, or constraints. The telegraphic clause style is dense and takes a careful read, but there is essentially no 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?

With an output schema present, the description need not explain return values, yet it still describes the change categories, `added`, `not_compared`, and the builtin count field. Errors, mock behavior, and concurrency limits are all covered, leaving no gap for a 2-parameter tool.

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: `baseline` accepts `previous`, a `snap-N` id from `snapshot_ids`, or a bag path, and the live-vs-bag pairing constraints tell the agent which combinations of `bag_path` and `baseline` are valid.

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 description opens with a concrete verb+resource and a framing question: snapshot the ROS 2 graph (or bag_path) and compare against a baseline producing a GraphDiff. It also scopes the tool with 'ROS 2 graph only', which separates it from the bag- and DDS-oriented siblings.

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 makes clear when the comparison is meaningful by listing what a pair cannot support (live-vs-live for nodes, bag-vs-bag for rates, DDS backend for writer QoS), and notes the first call only stores a snapshot. It does not name a sibling alternative explicitly, so it stops short of full when-to-use/when-not routing.

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

Deploy Server