TopicForge

by yaniswav

Overview Schema Source Related Servers Discussions Admin

Python

Local

diagnose

Read-onlyIdempotent

Sweep the ROS 2 graph and DDS bus in one call to detect, rank, and explain issues with evidence and suggested fixes.

Instructions

Answer "is anything wrong": sweep the ROS 2 graph and DDS bus in one call and rank what is found as a Diagnosis. Checks, in order: environment, nodes, topics, dds (QoS pairs, restarts), tf (8 s window), logs (/rosout errors), responsiveness (parameter reads, node first, params_file diff); scope runs one group. findings are critical, warning or info, with evidence and suggested_fixes (QoS changes, else read-only commands); verdict is one line. A check that errors or runs out of budget_s is in checks_skipped, never a tool error, and the verdict then says it is not verified. A clean result does not prove data flows. Mock mode: fixtures. Duration: holds the ROS lock up to budget_s and ends within 45 s; other ROS tools get busy meanwhile, health_check stays free.

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": "diagnose"
  }
}

Input Schema

Name	Required	Description	Default
`node`	No	Node read first (6 s); a failed read is critical.
`scope`	No	`all`, or one group: `graph`, `tf`, `dds`, `logs`.	all
`budget_s`	No	Seconds for the sweep, 10..40, default 30.
`params_file`	No	With `node`: parameter `.yaml` to compare.

Output Schema

Name	Required	Description
`note`	No	One sentence of context, or `None`.
`verdict`	Yes	One line; never an all-clear after a skipped check.
`budget_s`	Yes
`findings`	Yes	Critical first; at most 50.
`elapsed_s`	Yes
`checks_run`	Yes
`info_count`	Yes
`warning_count`	Yes
`checks_skipped`	Yes	Not verified.
`critical_count`	Yes	Counts cover all findings, not the capped list.
`findings_total`	Yes
`mode_effective`	Yes	`live` or `mock` (fixtures).

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.10.0Nov 10, 2026

addedInput schema / properties / params_file

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "With `node`: parameter `.yaml` to compare."
+}

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

Previous value: -"From `detect_qos_mismatches`; text for a human, never applied."New value: +"QoS changes or read-only commands; text for a human, never applied."

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."

Addedv0.9.0Nov 3, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantial context beyond them: the sweep holds the ROS lock up to `budget_s` and ends within 45 s, other ROS tools return `busy` meanwhile, and a failing or budget-exhausted check lands in `checks_skipped` rather than surfacing as a tool error. The caveat that a clean result does not prove data flows, plus mock-mode fixtures, are genuinely important behavioral disclosures.

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 core question and the sweep are front-loaded, and the check list, severity semantics, error handling, and lock warning each earn their space. It is densely compressed with backticked shorthand, which is efficient but borders on cryptic in places (e.g., "(QoS pairs, restarts)").

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 complex, lock-holding diagnostic tool, everything an agent needs is present: scope options, budget behavior, severity and verdict semantics, skip-vs-error distinction, mock mode, and lock contention. With an output schema already defining `Diagnosis`, the description need not explain return values further.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds consequences the schema does not: `node` is read first and a failed read is critical, `params_file` produces a diff against that node, and `budget_s` exhaustion routes to `checks_skipped` with an unverified verdict. That is real added meaning above the per-parameter text.

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 the exact question the tool answers ("is anything wrong") and a specific verb+resource: sweep the ROS 2 graph and DDS bus in one call, returning a ranked `Diagnosis`. It enumerates the checks performed, which distinguishes it from narrower siblings like `detect_qos_mismatches` or `inspect_tf`.

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?

Clearly frames the use case as a whole-system triage sweep and explains that `scope` narrows to one group, implying the alternatives for focused checks. It also notes `health_check` stays available during a sweep, which is actionable guidance. It stops short of explicitly telling the agent when to prefer a sibling over a scoped run.

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

Deploy Server