TopicForge

Overview Schema Source Related Servers Discussions Admin

graph_diff

Read-onlyIdempotent

Snapshot a ROS 2 graph and compare it with a baseline to see what changed: node, topic, type, QoS, rate and count differences, plus what was added.

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. Read-only. Duration: ros2 CLI behind the ROS lock, one call at a time; ends within 45 s; busy error if the lock is held (retry).

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.

Addedv0.8.0Oct 21, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Beyond the read-only/no-destructive annotations, it discloses stateful snapshot storage and its 16-entry in-memory cap, first-call note behavior, MCP errors, mock mode behavior, and lock/duration semantics. These are concrete behavioral traits that materially help an agent invoke it correctly.

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 is front-loaded and most detail is useful, but the description is long and explains return fields like changes, added, and not_compared despite an output schema existing. 'Read-only' also largely repeats the annotations.

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 stateful diff tool with many edge cases, the description covers live vs bag modes, baseline selection, error conditions, snapshot retention, mock behavior, and timing constraints. With an output schema present, it does not need to explain every return value in depth.

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 carries the parameter semantics. The description mirrors bag_path and baseline meanings and adds first-call context, but it does not add much syntax or format detail beyond the schema.

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 names a specific operation (snapshot and compare), resource (ROS 2 graph), and output shape (GraphDiff). It distinguishes the tool from single-resource siblings by focusing on what changed between a current snapshot and a baseline.

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 clearly frames the use case as 'what changed since it last worked' and explains live vs bag_path plus baseline options. It also lists pair-wise limitations in not_compared, but it does not explicitly name sibling alternatives for non-diff tasks.

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

Deploy Server