TopicForge

Overview Schema Source Related Servers Discussions Admin

detect_qos_mismatches

Read-onlyIdempotent

Detect why DDS readers and writers on a topic fail to communicate by pairing every reader with every writer and reporting incompatible QoS policies, unmatched partitions, and suggested fixes.

Instructions

Explain why DDS readers and writers on a topic do not talk, and who will. Pairs every reader with every writer per topic and returns a MismatchScan: summary (one line, read it first), matched (pairs DDS will connect given the announced QoS; data flow is not observed), reports (incompatible or risky QoS pairs, 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, and latent_incompatible_policies lists what would also break once fixed), hints (probable typos in orphan topic names, type id notes), plus pairs_checked, topics_scanned, policies_checked and policies_unchecked. Checked: Partition (* and ? wildcards), type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership, DestinationOrder, DataRepresentation, History (risky only, where announced). 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 'deadline missed' log with compatible QoS means the writer's real period exceeds the deadline, which TopicForge cannot see). Pass topic to scope the scan. The lists are capped at 200 each (truncated; *_total keep the counts). A late_joiner match is a VOLATILE writer whose reader joined later on the same host: normal. Reports and partition splits carry suggested_fixes: text for a human, never applied by TopicForge; verify_with names the call that confirms the repair. Read-only by architecture. Raises an MCP error when no DDS module is active; mock returns fixtures. Duration: DDS 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": "detect_qos_mismatches"
  }
}

Input Schema

Name	Required	Description	Default
`topic`	No	Optional DDS topic to scope the scan to: `scan` or `rt/scan`. Omit to scan all topics.

Output Schema

Name	Required	Description
`note`	No	One sentence of context, or `None`.
`hints`	Yes	Leads that are not findings: probable typos, type id notes, incomplete checks.
`matched`	No	Pairs DDS will connect given the announced QoS (data flow is not observed).
`reports`	Yes	Pairs sharing partition and type with incompatible or risky QoS.
`summary`	No	One-line reading of the scan: counts of incompatible, not matched and matched pairs.
`truncated`	No	True when `reports`, `matched` or `not_matched` hit the 200-entry cap (see `*_total`); narrow with `topic`.
`not_matched`	Yes	Pairs DDS never matches (partition or type name). Non-empty with empty `reports` is NOT all-clear: no data flows.
`matched_total`	No	Matched pairs before the size cap.
`pairs_checked`	Yes	Same-topic (reader, writer) pairs examined.
`reports_total`	No	Reports before the size cap.
`mode_effective`	Yes	`live` or `mock` (fixtures).
`topics_scanned`	Yes	Topics that had at least one endpoint in scope.
`policies_checked`	Yes	Policies compared on every pair.
`not_matched_total`	No	Not-matched pairs before the size cap.
`policies_unchecked`	Yes	What the scan does not cover, each with a reason; a clean result says nothing about them.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.10.0Nov 10, 2026

addedOutput schema / $defs / MismatchReport / properties / topic / description
```
Added value: +"DDS name: `rt/scan` is the ROS topic `/scan`."
```
addedOutput schema / $defs / NotMatchedPair / properties / topic / description
```
Added value: +"DDS name: `rt/scan` is the ROS topic `/scan`."
```

changedOutput schema / $defs / SuggestedFix / properties / target / description

Previous value: -"Which node or side to change, writer or reader."New value: +"The node or side concerned, writer or reader."

changedOutput schema / $defs / SuggestedFix / properties / text / description

Previous value: -"The exact command, YAML or XML to apply."New value: +"The exact command, YAML or XML."

changedOutput schema / $defs / SuggestedFix / properties / tradeoff / description

Previous value: -"What is lost by applying it."New value: +"What applying it loses, or what a read-only command shows."

changedOutput schema / $defs / SuggestedFix / properties / verify_with / description

Previous value: -"The TopicForge tool to run again to confirm the repair."New value: +"The TopicForge tool to run again to confirm."

Changed3 schema fields changedv0.9.0Nov 3, 2026

changedOutput schema / $defs / MatchedPair / properties / late_joiner / description

Previous value: -"True for a VOLATILE writer whose reader joined over 1 s later on the same host: earlier samples are not delivered. Normal."New value: +"True for a VOLATILE writer whose same-host reader joined over 1 s later: earlier samples are lost. Normal."

changedOutput schema / $defs / NotMatchedPair / properties / suggested_fixes / description

Previous value: -"Fixes proposed as text for a human to apply; TopicForge never applies them. Only for a `partition` split, and only on the first pair of identical splits on a topic. Empty when it proposes none for this finding."New value: +"Text fixes for a human, never applied. Only for a `partition` split, on the first of identical splits per topic."

changedOutput schema / properties / not_matched / description

Previous value: -"Pairs DDS never matches (partition or type name). Non-empty with empty `reports` is NOT all-clear: no data flows between them."New value: +"Pairs DDS never matches (partition or type name). Non-empty with empty `reports` is NOT all-clear: no data flows."

Changed6 schema fields changedv0.8.1Oct 27, 2026

addedOutput schema / $defs / MatchedPair / properties / reader_node
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
addedOutput schema / $defs / MatchedPair / properties / writer_node
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```

addedOutput schema / $defs / MismatchReport / properties / reader_node

Added value: +{
+  "description": "ROS 2 node (`ros_discovery_info`); `None` if not announced.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / $defs / MismatchReport / properties / writer_node

Added value: +{
+  "description": "ROS 2 node (`ros_discovery_info`); `None` if not announced.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / $defs / NotMatchedPair / properties / reader_node
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
addedOutput schema / $defs / NotMatchedPair / properties / writer_node
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```

Changed53 schema fields changedv0.8.0Oct 21, 2026
- removedOutput schema / $defs / MatchedPair / properties / late_joiner / default
```
Removed value: -false
```
- removedOutput schema / $defs / MatchedPair / properties / late_joiner_note / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MatchedPair / properties / late_joiner_note / default
```
Removed value: -null
```
- addedOutput schema / $defs / MatchedPair / properties / late_joiner_note / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MatchedPair / properties / reader_participant_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MatchedPair / properties / reader_participant_name / default
```
Removed value: -null
```
- addedOutput schema / $defs / MatchedPair / properties / reader_participant_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MatchedPair / properties / type_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MatchedPair / properties / type_name / default
```
Removed value: -null
```
- addedOutput schema / $defs / MatchedPair / properties / type_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MatchedPair / properties / writer_participant_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MatchedPair / properties / writer_participant_name / default
```
Removed value: -null
```
- addedOutput schema / $defs / MatchedPair / properties / writer_participant_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MismatchReport / properties / reader_guid / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MismatchReport / properties / reader_guid / default
```
Removed value: -null
```
- addedOutput schema / $defs / MismatchReport / properties / reader_guid / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MismatchReport / properties / reader_participant_guid / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MismatchReport / properties / reader_participant_guid / default
```
Removed value: -null
```
- addedOutput schema / $defs / MismatchReport / properties / reader_participant_guid / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MismatchReport / properties / reader_participant_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MismatchReport / properties / reader_participant_name / default
```
Removed value: -null
```
- addedOutput schema / $defs / MismatchReport / properties / reader_participant_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MismatchReport / properties / reader_type_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MismatchReport / properties / reader_type_name / default
```
Removed value: -null
```
- addedOutput schema / $defs / MismatchReport / properties / reader_type_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MismatchReport / properties / writer_guid / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MismatchReport / properties / writer_guid / default
```
Removed value: -null
```
- addedOutput schema / $defs / MismatchReport / properties / writer_guid / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MismatchReport / properties / writer_participant_guid / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MismatchReport / properties / writer_participant_guid / default
```
Removed value: -null
```
- addedOutput schema / $defs / MismatchReport / properties / writer_participant_guid / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MismatchReport / properties / writer_participant_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MismatchReport / properties / writer_participant_name / default
```
Removed value: -null
```
- addedOutput schema / $defs / MismatchReport / properties / writer_participant_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / MismatchReport / properties / writer_type_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / MismatchReport / properties / writer_type_name / default
```
Removed value: -null
```
- addedOutput schema / $defs / MismatchReport / properties / writer_type_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / NotMatchedPair / properties / reader_participant_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / NotMatchedPair / properties / reader_participant_name / default
```
Removed value: -null
```
- addedOutput schema / $defs / NotMatchedPair / properties / reader_participant_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / $defs / NotMatchedPair / properties / writer_participant_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / $defs / NotMatchedPair / properties / writer_participant_name / default
```
Removed value: -null
```
- addedOutput schema / $defs / NotMatchedPair / properties / writer_participant_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / matched_total / default
```
Removed value: -0
```
- removedOutput schema / properties / not_matched_total / default
```
Removed value: -0
```
- 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"
+]
```
- removedOutput schema / properties / reports_total / default
```
Removed value: -0
```
- removedOutput schema / properties / summary / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- removedOutput schema / properties / summary / default
```
Removed value: -null
```
- addedOutput schema / properties / summary / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / truncated / default
```
Removed value: -false
```

Changed110 schema fields changedv0.7.1Oct 14, 2026

changedInput schema / properties / topic / description

Previous value: -"Optional 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."New value: +"Optional DDS topic to scope the scan to: `scan` or `rt/scan`. Omit to scan all topics."

removedInput schema / properties / topic / title
```
Removed value: -"Topic"
```

removedInput schema / title

Removed value: -"detect_qos_mismatchesArguments"

removedOutput schema / $defs / MatchedPair / description

Removed value: -"A reader and a writer that DDS will connect given their announced QoS."

changedOutput schema / $defs / MatchedPair / properties / late_joiner / description

Previous value: -"True when the writer is VOLATILE and the reader was announced more than 1 s after it, both on the same host: samples published before the reader joined are not delivered to it. Normal for a VOLATILE writer, not a fault."New value: +"True for a VOLATILE writer whose reader joined over 1 s later on the same host: earlier samples are not delivered. Normal."

removedOutput schema / $defs / MatchedPair / properties / late_joiner / title
```
Removed value: -"Late Joiner"
```
removedOutput schema / $defs / MatchedPair / properties / late_joiner_note / title
```
Removed value: -"Late Joiner Note"
```
removedOutput schema / $defs / MatchedPair / properties / reader_guid / description
```
Removed value: -"GUID of the reader endpoint."
```
removedOutput schema / $defs / MatchedPair / properties / reader_guid / title
```
Removed value: -"Reader Guid"
```
removedOutput schema / $defs / MatchedPair / properties / reader_participant_guid / description
```
Removed value: -"GUID of the reader's participant."
```
removedOutput schema / $defs / MatchedPair / properties / reader_participant_guid / title
```
Removed value: -"Reader Participant Guid"
```
removedOutput schema / $defs / MatchedPair / properties / reader_participant_name / description
```
Removed value: -"Announced name of the reader's participant."
```
removedOutput schema / $defs / MatchedPair / properties / reader_participant_name / title
```
Removed value: -"Reader Participant Name"
```
removedOutput schema / $defs / MatchedPair / properties / topic / description
```
Removed value: -"Topic name both endpoints use."
```
removedOutput schema / $defs / MatchedPair / properties / topic / title
```
Removed value: -"Topic"
```
removedOutput schema / $defs / MatchedPair / properties / type_name / description
```
Removed value: -"Type name both announced."
```
removedOutput schema / $defs / MatchedPair / properties / type_name / title
```
Removed value: -"Type Name"
```
removedOutput schema / $defs / MatchedPair / properties / writer_guid / description
```
Removed value: -"GUID of the writer endpoint."
```
removedOutput schema / $defs / MatchedPair / properties / writer_guid / title
```
Removed value: -"Writer Guid"
```
removedOutput schema / $defs / MatchedPair / properties / writer_participant_guid / description
```
Removed value: -"GUID of the writer's participant."
```
removedOutput schema / $defs / MatchedPair / properties / writer_participant_guid / title
```
Removed value: -"Writer Participant Guid"
```
removedOutput schema / $defs / MatchedPair / properties / writer_participant_name / description
```
Removed value: -"Announced name of the writer's participant."
```
removedOutput schema / $defs / MatchedPair / properties / writer_participant_name / title
```
Removed value: -"Writer Participant Name"
```
removedOutput schema / $defs / MatchedPair / title
```
Removed value: -"MatchedPair"
```

removedOutput schema / $defs / MismatchReport / description

Removed value: -"A single reader/writer QoS incompatibility detected on a topic.\n\nOnly pairs that share a partition and a type name are reported here: those\nseparated by partition or type are `NotMatchedPair`s in the same scan."

changedOutput schema / $defs / MismatchReport / properties / details / description

Previous value: -"Requested and offered value and the failed rule, one entry per policy."New value: +"Requested and offered value and the failed rule, per policy."

removedOutput schema / $defs / MismatchReport / properties / details / title
```
Removed value: -"Details"
```

changedOutput schema / $defs / MismatchReport / properties / incompatible_policies / description

Previous value: -"Names of the QoS policies that block communication or risk degradation: see `details` for the compared values."New value: +"Blocking or risky policies; values in `details`."

removedOutput schema / $defs / MismatchReport / properties / incompatible_policies / title
```
Removed value: -"Incompatible Policies"
```

removedOutput schema / $defs / MismatchReport / properties / mode_effective

Removed value: -{
-  "description": "Runtime 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`.",
-  "enum": [
-    "mock",
-    "live"
-  ],
-  "title": "Mode Effective",
-  "type": "string"
-}

removedOutput schema / $defs / MismatchReport / properties / reader_guid / description
```
Removed value: -"GUID of the reader endpoint involved in the mismatch, if known."
```
removedOutput schema / $defs / MismatchReport / properties / reader_guid / title
```
Removed value: -"Reader Guid"
```
removedOutput schema / $defs / MismatchReport / properties / reader_participant_guid / description
```
Removed value: -"GUID of the participant that owns the reader, if known."
```
removedOutput schema / $defs / MismatchReport / properties / reader_participant_guid / title
```
Removed value: -"Reader Participant Guid"
```
removedOutput schema / $defs / MismatchReport / properties / reader_participant_name / description
```
Removed value: -"Announced name of the reader's participant, if it set one."
```
removedOutput schema / $defs / MismatchReport / properties / reader_participant_name / title
```
Removed value: -"Reader Participant Name"
```
removedOutput schema / $defs / MismatchReport / properties / reader_type_name / description
```
Removed value: -"Type name the reader announced."
```
removedOutput schema / $defs / MismatchReport / properties / reader_type_name / title
```
Removed value: -"Reader Type Name"
```

changedOutput schema / $defs / MismatchReport / properties / severity / description

Previous value: -"`incompatible` means communication is definitely blocked; `risky` means it may degrade but is not strictly blocked by the DDS spec (History only). Useful for an LLM to triage user-facing advice."New value: +"`incompatible` (blocked) or `risky` (may degrade; History only)."

removedOutput schema / $defs / MismatchReport / properties / severity / title
```
Removed value: -"Severity"
```

addedOutput schema / $defs / MismatchReport / properties / suggested_fixes

Added value: +{
+  "description": "Fixes as text for a human to apply, never applied; empty when none.",
+  "items": {
+    "$ref": "#/$defs/SuggestedFix"
+  },
+  "type": "array"
+}

removedOutput schema / $defs / MismatchReport / properties / topic / description
```
Removed value: -"Topic name where the mismatch was detected."
```
removedOutput schema / $defs / MismatchReport / properties / topic / title
```
Removed value: -"Topic"
```

changedOutput schema / $defs / MismatchReport / properties / unchecked / description

Previous value: -"Policies that could not be compared for this pair because one side did not announce a value."New value: +"Policies not compared because one side announced no value."

removedOutput schema / $defs / MismatchReport / properties / unchecked / title
```
Removed value: -"Unchecked"
```
removedOutput schema / $defs / MismatchReport / properties / writer_guid / description
```
Removed value: -"GUID of the writer endpoint involved in the mismatch, if known."
```
removedOutput schema / $defs / MismatchReport / properties / writer_guid / title
```
Removed value: -"Writer Guid"
```
removedOutput schema / $defs / MismatchReport / properties / writer_participant_guid / description
```
Removed value: -"GUID of the participant that owns the writer, if known."
```
removedOutput schema / $defs / MismatchReport / properties / writer_participant_guid / title
```
Removed value: -"Writer Participant Guid"
```
removedOutput schema / $defs / MismatchReport / properties / writer_participant_name / description
```
Removed value: -"Announced name of the writer's participant, if it set one."
```
removedOutput schema / $defs / MismatchReport / properties / writer_participant_name / title
```
Removed value: -"Writer Participant Name"
```
removedOutput schema / $defs / MismatchReport / properties / writer_type_name / description
```
Removed value: -"Type name the writer announced."
```
removedOutput schema / $defs / MismatchReport / properties / writer_type_name / title
```
Removed value: -"Writer Type Name"
```

changedOutput schema / $defs / MismatchReport / required

Previous value: -[
-  "topic",
-  "incompatible_policies",
-  "severity",
-  "mode_effective"
-]New value: +[
+  "topic",
+  "incompatible_policies",
+  "severity"
+]

removedOutput schema / $defs / MismatchReport / title
```
Removed value: -"MismatchReport"
```

removedOutput schema / $defs / NotMatchedPair / description

Removed value: -"A reader and a writer on one topic that DDS will not match, whatever their QoS."

removedOutput schema / $defs / NotMatchedPair / properties / detail / title
```
Removed value: -"Detail"
```

changedOutput schema / $defs / NotMatchedPair / properties / latent_incompatible_policies / description

Previous value: -"RxO policies that would ALSO be incompatible once the partition / type issue is fixed (same shape as `MismatchReport.details`). Empty when the QoS of the two endpoints would be compatible, or could not be compared."New value: +"RxO policies that would ALSO be incompatible once the partition or type is fixed (shape of `MismatchReport.details`)."

removedOutput schema / $defs / NotMatchedPair / properties / latent_incompatible_policies / title
```
Removed value: -"Latent Incompatible Policies"
```
removedOutput schema / $defs / NotMatchedPair / properties / reader_guid / description
```
Removed value: -"GUID of the reader endpoint."
```
removedOutput schema / $defs / NotMatchedPair / properties / reader_guid / title
```
Removed value: -"Reader Guid"
```
removedOutput schema / $defs / NotMatchedPair / properties / reader_participant_guid / description
```
Removed value: -"GUID of the reader's participant."
```
removedOutput schema / $defs / NotMatchedPair / properties / reader_participant_guid / title
```
Removed value: -"Reader Participant Guid"
```
removedOutput schema / $defs / NotMatchedPair / properties / reader_participant_name / description
```
Removed value: -"Announced name of the reader's participant."
```
removedOutput schema / $defs / NotMatchedPair / properties / reader_participant_name / title
```
Removed value: -"Reader Participant Name"
```

changedOutput schema / $defs / NotMatchedPair / properties / reason / description

Previous value: -"`partition`: no reader partition matches a writer partition. `type_name`: the endpoints announced different type names. The RxO QoS rules are not evaluated for such a pair."New value: +"`partition` (none in common) or `type_name` (different types); QoS rules are not evaluated."

removedOutput schema / $defs / NotMatchedPair / properties / reason / title
```
Removed value: -"Reason"
```

addedOutput schema / $defs / NotMatchedPair / properties / suggested_fixes

Added value: +{
+  "description": "Fixes proposed as text for a human to apply; TopicForge never applies them. Only for a `partition` split, and only on the first pair of identical splits on a topic. Empty when it proposes none for this finding.",
+  "items": {
+    "$ref": "#/$defs/SuggestedFix"
+  },
+  "type": "array"
+}

removedOutput schema / $defs / NotMatchedPair / properties / topic / description
```
Removed value: -"Topic name both endpoints use."
```
removedOutput schema / $defs / NotMatchedPair / properties / topic / title
```
Removed value: -"Topic"
```
removedOutput schema / $defs / NotMatchedPair / properties / writer_guid / description
```
Removed value: -"GUID of the writer endpoint."
```
removedOutput schema / $defs / NotMatchedPair / properties / writer_guid / title
```
Removed value: -"Writer Guid"
```
removedOutput schema / $defs / NotMatchedPair / properties / writer_participant_guid / description
```
Removed value: -"GUID of the writer's participant."
```
removedOutput schema / $defs / NotMatchedPair / properties / writer_participant_guid / title
```
Removed value: -"Writer Participant Guid"
```
removedOutput schema / $defs / NotMatchedPair / properties / writer_participant_name / description
```
Removed value: -"Announced name of the writer's participant."
```
removedOutput schema / $defs / NotMatchedPair / properties / writer_participant_name / title
```
Removed value: -"Writer Participant Name"
```
removedOutput schema / $defs / NotMatchedPair / title
```
Removed value: -"NotMatchedPair"
```

removedOutput schema / $defs / PolicyMismatch / description

Removed value: -"One QoS policy of a reader/writer pair, with the values that were compared."

removedOutput schema / $defs / PolicyMismatch / properties / offered / description
```
Removed value: -"What the writer offers, same format as `requested`."
```
removedOutput schema / $defs / PolicyMismatch / properties / offered / title
```
Removed value: -"Offered"
```

changedOutput schema / $defs / PolicyMismatch / properties / policy / description

Previous value: -"Policy name: `Reliability`, `Durability`, `Deadline`, `Liveliness`, `LatencyBudget`, `Ownership`, `DestinationOrder`, `DataRepresentation` or `History`."New value: +"Policy name, e.g. `Reliability`, `Deadline`, `Ownership`, `History`."

removedOutput schema / $defs / PolicyMismatch / properties / policy / title
```
Removed value: -"Policy"
```

changedOutput schema / $defs / PolicyMismatch / properties / requested / description

Previous value: -"What the reader requests, human-readable: `\"RELIABLE\"`, `\"100 ms\"`, `\"infinite\"`."New value: +"What the reader requests, e.g. `\"RELIABLE\"`, `\"100 ms\"`."

removedOutput schema / $defs / PolicyMismatch / properties / requested / title
```
Removed value: -"Requested"
```
removedOutput schema / $defs / PolicyMismatch / properties / rule / title
```
Removed value: -"Rule"
```
removedOutput schema / $defs / PolicyMismatch / title
```
Removed value: -"PolicyMismatch"
```

addedOutput schema / $defs / SuggestedFix

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "description": "Form of `text`: a CLI command, a ROS 2 QoS override, a DDS profile or a launch parameter.",
+      "enum": [
+        "cli",
+        "qos_override",
+        "dds_profile",
+        "launch_param"
+      ],
+      "type": "string"
+    },
+    "target": {
+      "description": "Which node or side to change, writer or reader.",
+      "type": "string"
+    },
+    "text": {
+      "description": "The exact command, YAML or XML to apply.",
+      "type": "string"
+    },
+    "tradeoff": {
+      "description": "What is lost by applying it.",
+      "type": "string"
+    },
+    "verify_with": {
+      "description": "The TopicForge tool to run again to confirm the repair.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind",
+    "target",
+    "text",
+    "tradeoff",
+    "verify_with"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / hints / description

Previous value: -"Leads that are not findings: orphan topics with near-identical names (typos), type id differences, pairs that could not be fully checked."New value: +"Leads that are not findings: probable typos, type id notes, incomplete checks."

removedOutput schema / properties / hints / title
```
Removed value: -"Hints"
```

changedOutput schema / properties / matched / description

Previous value: -"Pairs 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."New value: +"Pairs DDS will connect given the announced QoS (data flow is not observed)."

removedOutput schema / properties / matched / title
```
Removed value: -"Matched"
```
removedOutput schema / properties / matched_total / title
```
Removed value: -"Matched Total"
```

changedOutput schema / properties / mode_effective / description

Previous value: -"Runtime 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`."New value: +"`live` or `mock` (fixtures)."

removedOutput schema / properties / mode_effective / title
```
Removed value: -"Mode Effective"
```

changedOutput schema / properties / not_matched / description

Previous value: -"Pairs 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."New value: +"Pairs DDS never matches (partition or type name). Non-empty with empty `reports` is NOT all-clear: no data flows between them."

removedOutput schema / properties / not_matched / title
```
Removed value: -"Not Matched"
```
removedOutput schema / properties / not_matched_total / title
```
Removed value: -"Not Matched Total"
```

addedOutput schema / properties / note

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "One sentence of context, or `None`."
+}

changedOutput schema / properties / pairs_checked / description

Previous value: -"Same-topic (reader, writer) pairs examined, including those reported in `not_matched`."New value: +"Same-topic (reader, writer) pairs examined."

removedOutput schema / properties / pairs_checked / title
```
Removed value: -"Pairs Checked"
```
removedOutput schema / properties / policies_checked / title
```
Removed value: -"Policies Checked"
```

changedOutput schema / properties / policies_unchecked / description

Previous value: -"Policies and facts this scan does not cover, each with a one-line reason. A clean result says nothing about them."New value: +"What the scan does not cover, each with a reason; a clean result says nothing about them."

removedOutput schema / properties / policies_unchecked / title
```
Removed value: -"Policies Unchecked"
```

changedOutput schema / properties / reports / description

Previous value: -"Pairs that share a partition and a type but have incompatible or risky QoS."New value: +"Pairs sharing partition and type with incompatible or risky QoS."

removedOutput schema / properties / reports / title
```
Removed value: -"Reports"
```
removedOutput schema / properties / reports_total / title
```
Removed value: -"Reports Total"
```

addedOutput schema / properties / summary

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "One-line reading of the scan: counts of incompatible, not matched and matched pairs."
+}

removedOutput schema / properties / topics_scanned / title
```
Removed value: -"Topics Scanned"
```

changedOutput schema / properties / truncated / description

Previous value: -"True 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`."New value: +"True when `reports`, `matched` or `not_matched` hit the 200-entry cap (see `*_total`); narrow with `topic`."

removedOutput schema / properties / truncated / title
```
Removed value: -"Truncated"
```

First observedv0.5.6Oct 5, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Goes far beyond the annotations: it discloses that it raises an MCP error when no DDS module is active, that it takes a DDS lock one call at a time and returns `busy` if held, the 45 s bound, and the 200-item cap per list with `truncated`/`*_total`. It also scopes the epistemic limit ('discovery shows the QoS DECLARED, not runtime behavior') and clarifies that `late_joiner` is normal, which prevents misreading a match as 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?

Front-loaded with the purpose, then organized by return field, checked policies, caveats, and limits — each block earns its place. It is dense and long, and since an output schema exists, enumerating every field (`summary`, `matched`, `reports`, `not_matched`, `hints`, counters) is partly redundant, which keeps it from a 5.

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 single-parameter scan with heavy output, it covers everything an agent needs: error behavior, concurrency/duration, truncation, the distinction between `matched` and `not_matched`, the wildcard policy coverage, and the warning that suggested_fixes are advisory and never applied. 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.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one optional parameter, and the schema already documents it at 100% coverage including the `scan`/`rt/scan` example. The description adds only the scoping intent ('Pass topic to scope the scan'), which is essentially a restatement of the schema. Baseline 3 applies when the schema carries the semantics.

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?

Opens with a specific verb and outcome: 'Explain why DDS readers and writers on a topic do not talk, and who will.' That distinguishes it from generic diagnostics siblings like diagnose or health_check by naming the exact resource (reader/writer QoS pairs) and the mechanism (pairing every reader with every writer per topic).

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 conditions for invocation and for interpreting results: '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.' It also states how to scope via 'Pass topic to scope the scan.' It stops short of naming an alternative sibling to use instead for runtime-behavior questions, so 4 rather than 5.

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

Deploy Server