TopicForge

Overview Schema Source Related Servers Discussions Admin

inspect_tf

Read-onlyIdempotent

Rebuild the ROS 2 TF tree from /tf_static and /tf to diagnose broken lookups, reporting stale, disconnected, cyclic, or ambiguous frames plus paths and URDF gaps.

Instructions

ROS 2 graph only. Rebuild the TF tree from the transforms on /tf_static (latched) and /tf (listened to for window_s) and flag what breaks lookups. Returns a TfReport: frames (parent, kind static/dynamic/both, age_s, stale, observed_frequency_hz on wall time, sim_frequency_hz on stamps), roots, counts and findings {kind, frames, text}: stale (a frame trails the newest /tf stamp by more than stale_after_s), two_parents, disconnected (several roots), static_and_dynamic, cycle, no_path. Ages and rates use header stamps, so they hold on sim time (real_time_factor far from 1 means sim). Give source_frame and target_frame for the path between them. It also reads /robot_description and flags URDF links with no frame (declared_not_published). Empty frames when nothing is published (read note). The listening is capped (3000 messages): echo can drop messages at high rates, so the tree is exact but frequencies are approximate (truncated). Raises an MCP error without a ros2 CLI. Mock mode: a fixed 5 s capture of the demo robot with one stale frame. 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
`window_s`	No	Seconds to listen to `/tf`, 1..20, default 5.
`source_frame`	No	Frame name, e.g. `base_link`. Give `source_frame` and `target_frame` together to get the chain between them in `path`.
`target_frame`	No	See `source_frame`.
`stale_after_s`	No	A frame is stale past this many seconds of stamp time, default 2.

Output Schema

Name	Required	Description
`note`	No	One sentence of context, or `None`.
`path`	No	Frames from `source_frame` to `target_frame`.
`hints`	Yes
`roots`	Yes	Frames with no parent; one in a sound tree.
`frames`	Yes	Sorted by name.
`findings`	Yes	Empty when the tree is sound.
`window_s`	Yes
`path_note`	No	Why `path` is `None`, or context.
`truncated`	Yes	Messages were dropped or the cap was hit.
`urdf_note`	No
`frame_count`	Yes
`stale_count`	Yes
`urdf_source`	No
`reference_ns`	Yes	Newest `/tf` stamp: the clock for `age_s`.
`stamp_span_s`	Yes
`static_count`	Yes	Frames with a static transform.
`dynamic_count`	Yes	Frames with a dynamic transform.
`message_count`	Yes	Transforms captured, repeats included.
`mode_effective`	Yes	`live` or `mock` (fixtures).
`transform_count`	Yes	Distinct parent-child pairs.
`urdf_link_count`	No
`window_actual_s`	Yes
`real_time_factor`	Yes	Stamp time over wall time: about 1 on a real robot, other on sim.
`frames_not_in_urdf`	No	TF frames not in the URDF (`map`, `odom` are normal).
`declared_frames_missing`	No	URDF links with no TF frame.

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?

Annotations only cover the read-only/idempotent profile, and the description adds substantial operational context beyond that: MCP error without a `ros2` CLI, mock-mode behavior, 45 s duration bound, ROS-lock serialization with a `busy` retry, 3000-message listen cap with `truncated` flag, and wall-time vs stamp-time frequency caveats. It also discloses what empty results mean.

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 purpose before the report schema and operational caveats, and nearly every clause carries information. It is a dense wall of text, however, and the TfReport field enumeration partly duplicates the output schema, making it heavier than needed.

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, yet the description still names the finding kinds an agent must reason over (stale, two_parents, disconnected, cycle, no_path) and covers failure modes, time-base semantics, and mock behavior. Nothing needed for correct invocation or interpretation 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 baseline is 3. The description reinforces that `window_s` applies to `/tf` only (not latched `/tf_static`) and restates `stale_after_s` in stamp-time terms, but adds little that the schema does not already spell out.

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 ('Rebuild the TF tree from the transforms on /tf_static and /tf') plus its scope ('ROS 2 graph only'), which separates it from the topic/node/DDS inspection siblings. An agent immediately knows this is the transform-tree analysis tool rather than a generic graph lister.

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?

Clear context is given: use source_frame+target_frame to get the chain between them, read `note` when `frames` is empty, retry on `busy`. It lacks explicit when-not-to-use guidance or a named alternative, but no sibling overlaps with TF analysis, so the routing risk is low.

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

Deploy Server