TopicForge

Overview Schema Source Related Servers Discussions Admin

detect_qos_mismatches

Read-onlyIdempotent

Diagnose why DDS readers and writers on a topic don't communicate: pairs every reader with every writer, reports incompatible or risky QoS values, unmatched partitions and type names, plus 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 binding behind the DDS lock, one call at a time; ends within 45 s; busy error if the lock is held (retry).

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 between them.
`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.

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?

Adds plenty beyond annotations: read-only by architecture, raises an MCP error without an active DDS module, runs under a DDS lock with a 45 s bound and `busy` retry, caps lists at 200 with `truncated`/`*_total`, and flags that discovery shows declared QoS rather than runtime behaviour. It also explains that `late_joiner` matches are normal and that suggested fixes are text only.

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 and the returned scan fields, then the caveats and error/latency notes. It is dense and long, and some content (read-only, return shape) duplicates annotations or the output schema, but nearly every sentence carries operational value.

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?

Complete for a scan tool with an output schema: it covers scoping, truncation, lock/duration behaviour, error conditions, and the important false-negative caveat about empty results. Nothing an agent needs to invoke 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?

Only one parameter, and the schema already documents `topic` at 100% coverage, including the omit-to-scan-all behaviour. The description repeats this rather than adding syntax or format details, 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?

Names a specific verb and resource: explains why DDS readers and writers on a topic cannot communicate and reports who can. It clearly differs from siblings like get_topic_info or list_endpoints by describing a pairwise QoS compatibility scan with a named return type.

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?

Says to pass `topic` to scope the scan, and that omitting it scans all topics. It also points at `verify_with` for confirming repairs and warns that an empty `reports` still means no data flows. It does not explicitly state when to prefer a sibling such as get_topic_info, but the context is clear.

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

Deploy Server