Skip to main content
Glama
yaniswav

TopicForge

by yaniswav
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

detect_qos_mismatches

Diagnose why DDS readers and writers on the same topic do not communicate by pairing every reader with every writer and reporting incompatible or risky QoS policies.

Instructions

Explain why DDS readers and writers on the same topic do not talk, and who will. Pairs every reader with every writer per topic and returns a MismatchScan: matched (pairs DDS will connect given the announced QoS; data flow is not observed), reports (incompatible or risky QoS pairs, each with participant names, requested vs offered values and the failed rule in details), not_matched (pairs DDS never matches: different partitions or type names; the QoS rules are NOT evaluated for them, so a partition split is not blamed on Reliability; latent_incompatible_policies lists the RxO policies that would ALSO be incompatible once the partition/type issue is fixed), hints (orphan topics with a near-identical name, i.e. probable typos, and type id notes), plus pairs_checked, topics_scanned, policies_checked and policies_unchecked. Checked: Partition (with * and ? wildcards), type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership, DestinationOrder, DataRepresentation, History (risky only, and only where announced: discovery does not carry it). Not checked: see policies_unchecked. An empty reports with a non-empty not_matched still means no data flows, and an all-empty result does not prove the bus healthy: discovery shows the QoS DECLARED, not runtime behavior (a reader logging 'deadline missed' with compatible QoS means the writer's real period exceeds the deadline, which TopicForge cannot observe). Pass topic to scope to one topic; omit to scan all. reports, matched and not_matched are capped at 200 entries each (truncated is true, the *_total fields keep the real counts, incompatible reports come first). A matched pair flagged late_joiner is a VOLATILE writer whose reader joined later on the same host: normal, not a fault. Read-only by architecture. Raises an MCP error when no DDS module is active; the mock backend returns fixtures.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
topicNoOptional DDS topic name to scope the scan to: a bare name such as `scan` or a ROS 2 mangled name such as `rt/scan`. Omit to scan all topics.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
hintsYesLeads that are not findings: orphan topics with near-identical names (typos), type id differences, pairs that could not be fully checked.
matchedNoPairs that will be matched by DDS given the announced QoS: same topic and type name, overlapping partitions, no incompatible RxO policy (a pair with only a `risky` History finding still counts). Actual data flow is not observed.
reportsYesPairs that share a partition and a type but have incompatible or risky QoS.
truncatedNoTrue when `reports`, `matched` or `not_matched` was cut to its cap (200 entries each, incompatible reports first): see the `*_total` fields. Narrow the scan with `topic`.
not_matchedYesPairs separated by partition or type name. No data flows between them. An empty `reports` with a non-empty `not_matched` does not mean the bus is healthy.
matched_totalNoMatched pairs before the size cap.
pairs_checkedYesSame-topic (reader, writer) pairs examined, including those reported in `not_matched`.
reports_totalNoReports before the size cap.
mode_effectiveYesRuntime 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`.
topics_scannedYesTopics that had at least one endpoint in scope.
policies_checkedYesPolicies compared on every pair.
not_matched_totalNoNot-matched pairs before the size cap.
policies_uncheckedYesPolicies and facts this scan does not cover, each with a one-line reason. A clean result says nothing about them.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.5.6

TDQS

A4.4/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full burden and does so thoroughly: read-only by architecture, raises an MCP error when no DDS module is active, mock backend returns fixtures, results capped at 200 with truncation flags, and explicit disclosure that discovery shows DECLARED QoS not runtime behavior. It also explains the late_joiner flag as normal rather than a fault.

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?

It is long and dense, but purpose is front-loaded in the first sentence and each subsequent sentence covers distinct output fields, caveats, or limits that a caller needs. The length is largely earned by the tool's complexity, though some field enumeration borders on restating 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?

Despite an output schema existing, the description goes further to explain what each field means and, critically, how to interpret ambiguous results (empty reports with non-empty not_matched still means no flow; all-empty does not prove health). Combined with error and mock-backend disclosure, nothing needed to invoke or interpret it correctly 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?

There is a single optional parameter and schema coverage is 100%, with the schema already documenting the bare vs ROS 2 mangled name formats and the omit-to-scan-all behavior. The description restates the scoping semantics but adds no syntax or meaning beyond what the schema provides, 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?

The opening sentence states a specific verb (explain why) and resource (DDS readers/writers on a topic), and frames it as a diagnostic question distinct from siblings like topic_metrics or list_endpoints. An agent can tell exactly what it gets back without opening a 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?

Gives clear context for use ('explain why readers and writers do not talk') and scoping instructions ('Pass `topic` to scope to one topic; omit to scan all'), plus a when-not-to-trust caveat about empty results. It stops short of naming alternative sibling tools or an explicit exclusion, so it is clear but not exhaustive.

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