rosbridge-mcp
rosbridge-mcp
rosbridge-mcp は、Model Context Protocol サーバーであり、AIエージェント(Claude Desktop、Cursor、VS Code、その他すべてのMCPクライアント)を、標準の rosbridge v2 プロトコル(WebSocket + JSON)を介して ROS 2 を実行するロボットに接続します。ロボットまたはROSマシン上で rosbridge_server を実行します。このMCPサーバーはネットワーク経由でそれに接続し、AIがトピックを観察し、ROSグラフとTFツリーを検査し、ロボットのカメラを通して見て、メッセージをパブリッシュし、サービスを呼び出し、ROS 2 アクションを駆動できるようにする11のツールを公開します。AIクライアントを実行するマシンにROSをインストールする必要はありません。
アーキテクチャ
+--------------------+ stdio (MCP) +----------------+ WebSocket/JSON +------------------+ DDS +---------+
| AI client | <-------------> | rosbridge-mcp | <----------------> | rosbridge_server | <-----> | ROS 2 |
| (Claude, Cursor, | | (this server) | rosbridge v2 | (on the robot) | | graph |
| VS Code, ...) | | | protocol | | | |
+--------------------+ +----------------+ +------------------+ +---------+Related MCP server: ROS2 MCP Server
クイックスタート(60秒)
pip install git+https://github.com/hieutachi/rosbridge-mcp.gitまたは、公開後:pip install rosbridge-mcp(PyPI — 近日公開予定)。
MCPクライアント設定に追加します(正確なファイルの場所については、以下のクライアント別ガイドを参照):
{
"mcpServers": {
"rosbridge": {
"command": "rosbridge-mcp",
"env": { "ROSBRIDGE_URL": "ws://<robot-ip>:9090" }
}
}
}次に、エージェントにこう尋ねてみてください:「ロボットにはどんなトピックがありますか?」
自分に合ったパスを選ぶ
自分に合ったガイドを選んでください。各ガイドは自己完結しているため、このREADMEの残りを最初に読む必要はありません:
あなたは... | ガイド |
Claude Desktop ユーザー — Claude からロボットと対話したい | |
Cursor または VS Code ユーザー — エディタ内でロボットツールを使用したい | |
ROS 初心者、ロボット未所持 — シミュレータまたは Docker ですべてを試す、ハードウェア不要 | |
実ロボットに接続する — LLM をハードウェアに近づける前の安全チェックリスト | |
開発者 — コントリビュート、ツールの追加、またはコードを理解したい |
ツール
合計11ツール。すべてのツールはJSONを返します。メッセージと引数のペイロードは、rosbridge が使用するのと同じ ROS メッセージの JSON 表現を使用します(フィールド名は .msg/.srv/.action 定義と一致します)。
ツール | 機能 | 変更の有無 |
| すべてのトピックとメッセージタイプ | なし |
| すべての実行中ノード | なし |
| すべての利用可能なサービス | なし |
| トピックからライブメッセージを収集 | なし |
| TF座標フレームツリーのスナップショット | なし |
| カメラフレームをbase64で1枚取得 | なし |
| 接続と読み取り専用状態 | なし |
| トピックにメッセージをパブリッシュ | あり |
| 任意のROSサービスを呼び出し | あり(読み取り専用では |
| ROS 2 アクションゴールを送信し、結果を待機 | あり |
| 実行中のアクションゴールをキャンセル | あり |
list_topics
すべてのトピックとそのメッセージタイプを一覧表示します。パラメータはありません。
{"topics": [
{"name": "/chatter", "type": "std_msgs/msg/String"},
{"name": "/cmd_vel", "type": "geometry_msgs/msg/Twist"},
{"name": "/scan", "type": "sensor_msgs/msg/LaserScan"}
]}list_nodes
すべての実行中ノードを一覧表示します。パラメータはありません。
{"nodes": ["/talker", "/listener", "/rosapi"]}list_services
すべての利用可能なサービスを一覧表示します。パラメータはありません。
{"services": ["/rosapi/topics", "/rosapi/nodes", "/reset_odometry"]}get_topic_snapshot
トピックにサブスクライブし、メッセージを収集し、サブスクライブを解除します。パラメータ:topic(必須)、count(デフォルト1)、timeout 秒(デフォルト5.0)、msg_type(オプション、通常はrosbridgeによって自動検出)。
入力:{"topic": "/chatter", "count": 2, "timeout": 3.0}
{"topic": "/chatter", "requested": 2, "received": 2,
"messages": [{"data": "Hello World: 41"}, {"data": "Hello World: 42"}],
"timed_out": false}トピックがサイレントの場合、received は requested より少なく、timed_out は true です。ツールがタイムアウトより長くハングすることはありません。
publish_message (変更あり)
トピックをアドバタイズし、1つのJSONメッセージをパブリッシュします。パラメータ:topic、msg_type(完全なROS 2 タイプ、例:geometry_msgs/msg/Twist)、message(タイプに一致するJSONオブジェクト)。
入力:
{"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist",
"message": {"linear": {"x": 0.1, "y": 0.0, "z": 0.0},
"angular": {"x": 0.0, "y": 0.0, "z": 0.2}}}出力:{"published": true, "topic": "/cmd_vel", "type": "geometry_msgs/msg/Twist"}
call_service (変更あり)
任意のROSサービスを呼び出します。パラメータ:service(必須)、args(JSONオブジェクト、デフォルト {})、timeout 秒(デフォルト10.0)。
入力:{"service": "/rosapi/topic_type", "args": {"topic": "/scan"}}
{"service": "/rosapi/topic_type", "success": true,
"values": {"type": "sensor_msgs/msg/LaserScan"}}失敗した場合、ツールは発生させる代わりに {"success": false, "error": "..."} を返します。
send_action_goal (変更あり)
ROS 2 アクションサーバー(ナビゲーション、アーム動作など)にゴールを送信します。パラメータ:action_name、action_type(/action/ を含む完全なタイプ、例:nav2_msgs/action/NavigateToPose)、goal(JSONオブジェクト、デフォルト {})、timeout 秒(デフォルト30、最大120に制限)、wait_for_result(デフォルト true)。
入力:{"action_name": "/fibonacci", "action_type": "test_msgs/action/Fibonacci", "goal": {"order": 5}}
{"action": "/fibonacci", "goal_id": "send_action_goal:7", "success": true,
"status": 4, "status_text": "succeeded",
"values": {"sequence": [0, 1, 1, 2, 3, 5]},
"last_feedback": {"partial_sequence": [0, 1, 1, 2, 3]}}wait_for_result: false の場合、ツールは即座に {"goal_id": ..., "result_pending": true} を返します。その goal_id を cancel_action_goal に渡すと、後でゴールを停止できます。ROS 2 アクションをサポートする rosbridge_suite のバージョンが必要です。古いrosbridgeでは、ツールはハングする代わりにアップグレードを促すエラーを返します。
cancel_action_goal (変更あり)
以前に送信したアクションゴールをキャンセルします。パラメータ:action_name、goal_id(send_action_goal から)。
出力:{"cancel_sent": true, "action": "/navigate_to_pose", "goal_id": "send_action_goal:7"}
get_tf_tree
/tf と /tf_static を短時間リッスンして、ロボットのTF(座標変換)ツリーのスナップショットを取得します。パラメータ:timeout 秒(デフォルト2.0、最大10に制限)。
{"frame_count": 3,
"frames": {
"base_link": {"parent": "odom", "translation": {"x": 1.0, "y": 0.0, "z": 0.0},
"rotation": {"x": 0, "y": 0, "z": 0, "w": 1}, "source": "dynamic"},
"laser": {"parent": "base_link", "...": "...", "source": "static"}},
"tree": {"odom": ["base_link"], "base_link": ["laser"]},
"roots": ["odom"]}get_camera_image
カメラトピックから1フレームをbase64として取得し、視覚対応モデルがロボットの見ているものを見られるようにします。パラメータ:topic(sensor_msgs/msg/CompressedImage トピック、例:/camera/image_raw/compressed を推奨)、timeout 秒(デフォルト5.0、最大30に制限)。
出力:{"topic": ..., "format": "jpeg", "data_base64": "...", "size_bytes": 51234}(生の Image トピックはさらに width/height/encoding を返します)。4MBを超えるフレームは返されません。ツールはメタデータと圧縮トピックを提案するエラーで応答します。
get_connection_status
接続状態と読み取り専用モードを報告します。パラメータはありません。
{"url": "ws://localhost:9090", "connected": true,
"connected_since_unix": 1786903978.1, "active_subscriptions": [],
"pending_service_calls": 0, "readonly": false}会話例
あなた: ロボットは今、何を見ていますか?
エージェント: (
list_topicsを呼び出し、sensor_msgs/msg/LaserScanタイプの/scanを検出し、get_topic_snapshotを{"topic": "/scan", "count": 1}で呼び出す) レーザースキャナーは360の距離測定値を報告しています。最も近い障害物は、左約90度の方向に約0.4メートルです。真正面のスペースは少なくとも2.5メートル以上空いています。あなた: わかりました、ゆっくり前進してください。
エージェント: (
publish_messageを{"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist", "message": {"linear": {"x": 0.1}, "angular": {"z": 0.0}}}で呼び出す) 0.1 m/s の前進速度コマンドをパブリッシュしました。停止するタイミングを教えてください。ゼロ速度をパブリッシュします。
ビジョンと身体化AIのために
読み取り専用ツールのうちの2つは、視覚言語モデルをロボットの物理的現実に根付かせるために特に存在します:
get_camera_imageは実際のカメラフレームをbase64として返します。視覚対応モデル(Claude、GPT-4o、またはVLAポリシーフロントエンド)は、何をすべきかを決定する前に文字通りロボットのカメラを通して見ることができます。get_tf_treeはモデルにロボットの空間的骨格を提供します。どのフレームが存在するか(map、odom、base_link、camera、gripper)と、それらが互いにどのように配置されているか。
get_topic_snapshot(LiDAR、オドメトリ、ジョイント状態)および send_action_goal(ナビゲーション、マニピュレーション)と組み合わせることで、これは視覚と行動のエージェントが必要とする観察→推論→行動のループを、プレーンなWebSocket経由で、モデル側にROSインストール不要でカバーします。両方の知覚ツールは読み取り専用モードで動作するため、「見るだけで触らない」エージェントを安全に実行できます。
設定
環境変数 | デフォルト | 説明 |
|
| rosbridgeサーバーのWebSocket URL |
|
| 変更ツールを拒否(安全性を参照) |
安全性
言語モデルに物理ロボットへの /cmd_vel のパブリッシュを許可することは、現実的なリスクです。ROSBRIDGE_MCP_READONLY=true を設定して読み取り専用モードで実行します。publish_message、send_action_goal、cancel_action_goal は拒否され、call_service は既知の読み取り専用 /rosapi イントロスペクションサービスの固定された許可リスト(topics、nodes、services、types、get_param、get_time、...)のみを許可し、リストにないもの(将来の未知の /rosapi サービスを含む)は拒否されます。読み取り専用の知覚ツール(get_topic_snapshot、get_tf_tree、get_camera_image)は引き続き機能します。実際のハードウェアでは、読み取り専用モードで開始することを強くお勧めします。詳細は 実ロボット安全チェックリスト と SECURITY.md の展開セキュリティモデルを参照してください。
プライバシーと法的情報
テレメトリなし、データ収集なし。 監査済み(2026-08):このパッケージが開く唯一のネットワーク接続は、設定した ROSBRIDGE_URL へのWebSocketです。分析、ホームコールバック、クラッシュレポート、隠れたHTTP呼び出しはなく、コードにはメッセージ内容のディスクへのログ記録は含まれていません。バンドルされたモックサーバーは 127.0.0.1 にのみバインドします。ツールによって返されるロボットデータは、排他的にMCPクライアントに送られます(MCPクライアントは選択したLLMにそれを転送します。その部分はお客様の管理下にあり、当社の管理下にはありません)。
ライセンスコンプライアンス。 すべてのランタイムおよび推移的依存関係は、このプロジェクトのMITライセンスと互換性のあるライセンスを保持しています。直接:fastmcp(Apache-2.0)、websockets(BSD-3-Clause)。主要な推移的:mcp(MIT)、pydantic(MIT)、starlette(BSD-3-Clause)、httpx(BSD-3-Clause)、anyio(MIT)、cryptography(Apache-2.0/BSD-3)。1つの推移的依存関係である certifi はMPL-2.0です。これはファイルレベルのコピーレフトであり、certifi自身のファイルの変更にのみ適用され、MITの使用と再配布と互換性があります。依存関係ツリーのどこにもGPL/AGPL/プロプライエタリコードはなく、このリポジトリ内のすべてのコードは、このプロジェクトのために書かれたオリジナル作品です。
FAQ
AIクライアントが実行されている場所にROSをインストールする必要がありますか? いいえ。Python 3.10+のみが必要です。ROSとrosbridgeはロボット上(またはDocker内、シミュレータ内)で実行されます。このサーバーはWebSocketを介してそれらと通信します。
ROS 1でも動作しますか?
rosbridge v2プロトコルは同じであるため、基本的な操作はROS 1の rosbridge_server でも動作します。ROS 1タイプ名(std_msgs/String)を使用してください。CIでテストされているのはROS 2のみです。
エージェントが接続できないと言っています。
rosbridgeが実行されていること(ros2 launch rosbridge_server rosbridge_websocket_launch.xml)、ROSBRIDGE_URLが正しいホスト/ポートを指していること、ポート9090が到達可能であること(ファイアウォール)を確認してください。docs/内の各ガイドにはトラブルシューティングセクションがあります。
ロボットやシミュレーターなしで試せますか?
はい — python -m rosbridge_mcp.mock_server 9090 を実行すると、ダミーのトピックを持つ偽のrosbridgeが起動し、ROSBRIDGE_URLを ws://localhost:9090 に設定します。
私のデータはどこかに送信されますか?
サーバーは設定した ROSBRIDGE_URL にのみ接続します。トピックデータはMCPクライアントに返され、そのクライアントが使用しているLLMに転送されます — センサーデータは適切に扱ってください。
ロードマップ
ステージごとの目標、成果物、および各ステージに必要なリソースを含む段階的計画: ROADMAP.md を参照。ハイライト:v0.2 アクションクライアント + TF + カメラスナップショット(v0.2.0で完了)、v0.3 HTTPトランスポート + Dockerイメージ + rosbridge認証/TLS、v0.4 マルチロボットフリート + MCPリソース(URDF/マップ)、v1.0 安定API + 公式MCPレジストリ登録 + Gazebo/Isaac Simの例。
このプロジェクトを支援する
rosbridge-mcpは、一人の開発者がパートタイムで、初期段階で構築・維持しています。現在存在するものは実際に動作し、テスト済みです:11のツール(トピック、サービス、ROS 2アクション、TF、カメラスナップショットをカバー)、43の自動テスト(コミットごとにCIで実行)、5つのユーザーパスに対するシナリオ別ドキュメント、読み取り専用セーフティモードとサービス許可リスト、監査済みのゼロテレメトリコードベース。
ロードマップ を実現するために必要なもの(正直に述べます):
v0.3(デプロイとセキュリティ): パートタイムの開発週数、Dockerイメージビルド用の小さなクラウドVMまたはセルフホステッドランナー、そして最も重要なのは、rosbridge認証/TLS層のセキュリティに詳しいレビュアー。
v0.4(フリート): 2台以上の同時実行ロボットまたはシミュレーターインスタンスへのアクセス、および実際のロボティクス研究室からの設計フィードバック(学術または産業パイロットパートナーを探しています)。
v1.0(安定性とエコシステム): 持続的なメンテナー時間(
週2日/四半期)、Isaac Sim検証用のRTXクラスGPUワークステーション1台(ロードマップ全体で主要なハードウェア要求)、およびオプションでハードウェアインザループCI用の低コストロボット($1~3k)。
あなたができる支援(難易度順):
リポジトリにスターを付ける — 可視性は初期プロジェクトに貢献者を引き寄せるのに本当に役立ちます。
自分のロボットやシミュレーターで試す — ROSディストリビューションとrosbridgeバージョンを添えてIssueを開いてください。互換性レポートは、これを堅牢にするための最も安価な方法です。
PRを投稿する — docs/development.md は10分でコードベースを説明しており、ロードマップの各項目はクレーム可能です。
スポンサーまたはパートナーになる — あなたの研究室や企業がシミュレーター時間、ハードウェア、GPUワークステーション、または資金提供された開発時間を提供できる場合、github.com/hieutachi までご連絡ください。
関連リソース
ロボティクスを始めるなら、Robotics RL & UAV ebook は著者による強化学習とUAVロボティクスをカバーした補助学習リソースです。
コントリビューション
コントリビューションを歓迎します! CONTRIBUTING.md と開発ガイド を参照してください。コミットには署名オフ(DCO)をお願いします。
ライセンス
MIT — LICENSE を参照。依存ライセンスは寛容で互換性があります:fastmcp(Apache-2.0)、websockets(BSD-3-Clause)。GPL/AGPLの依存関係はありません。
Tóm tắt tiếng Việt
rosbridge-mcp là một MCP server cầu nối giữa AI agent (Claude Desktop, Cursor, VS Code...) và robot chạy ROS 2 thông qua giao thức rosbridge (WebSocket + JSON). Không cần cài ROS trên máy chạy AI client.
Tài liệu được chia theo từng kịch bản — chọn đúng hướng dẫn cho bạn trong thư mục docs/:
Dùng Claude Desktop — cấu hình JSON từng bước trên Windows/macOS/Linux
Dùng Cursor / VS Code — cấu hình
mcp.jsontrong editorChưa có robot — chạy thử với Docker (
ros:humble+ rosbridge) hoặc TurtleBot3/Gazebo, hoặc mock server đi kèmCó robot thật — checklist an toàn: bật
ROSBRIDGE_MCP_READONLY=truetrước, đọc/odom,/scanđể hiểu robot rồi mới mở quyền publish/cmd_velDeveloper — kiến trúc code, cách thêm tool mới, chạy test với mock (không cần ROS)
11 tool: list_topics, list_nodes, list_services, get_topic_snapshot, publish_message, call_service, send_action_goal, cancel_action_goal, get_tf_tree, get_camera_image, get_connection_status. Bật ROSBRIDGE_MCP_READONLY=true để chặn mọi thao tác ghi (publish, action) khi làm việc với robot thật — các tool đọc (TF, camera, topic) vẫn hoạt động bình thường.
Tài liệu học kèm theo của tác giả: Robotics RL & UAV ebook — ebook về học tăng cường (reinforcement learning) và robot UAV.
Available Tools
11 toolscall_serviceA
Call any ROS service with JSON args and return the response values.
Rejected when ROSBRIDGE_MCP_READONLY is set, unless the service is on the fixed allowlist of known read-only /rosapi introspection services (topics, nodes, services, *_type, *_details, get_param, get_time, ...).
Args: service: Full service name, e.g. "/rosapi/topic_type" or "/reset_odometry". Discover names with list_services. args: JSON object matching the service request definition, e.g. {"topic": "/scan"} for /rosapi/topic_type. Default {}. timeout: Max seconds to wait for the response (default 10.0).
Returns {"service", "success": true, "values": {...}} on success, or {"service", "success": false, "error": "..."} on failure/timeout (with any related rosbridge status errors under "rosbridge_status").
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| service | Yes | ||
| timeout | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It explains readonly mode rejection, the return format (success vs failure with values/error/rosbridge_status), and that args are JSON. It does not explicitly flag potential side effects of calling a service, but given the generic nature, this is acceptable. The readonly note subtly suggests that some calls are destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written. The first sentence states the core purpose immediately, followed by a critical usage note, then a clean Args/Returns block. Every sentence adds unique value; no filler or repetition. Length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero annotations and zero schema-level descriptions, the tool description must stand alone. It covers: purpose, restricted-mode behavior, all three parameters (with defaults, format, examples), and the full return structure (success and failure cases). The presence of an output schema means return details are not required, but the description still enumerates them. Very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain parameters. It does: service name with example, args as JSON object with example defaults, timeout as seconds with default. This goes well beyond what the bare schema provides (which only lists types and defaults). No redundancy; all param info in description is additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb-resource pair: 'Call any ROS service with JSON args.' This precisely defines the action and target. It distinguishes from sibling tools (list_*, get_*, publish_message, send_action_goal) by focusing on service calling rather than introspection, publishing, or action management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool is rejected (readonly mode unless allowlisted) and suggests using list_services to discover service names. However, it does not directly compare against siblings like publish_message (which uses topics) or send_action_goal (actions), leaving the agent to infer the appropriate tool based on service vs topic vs action distinction. A clear 'Use this for calling services, not for topics or actions' would elevate to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cancel_action_goalA
Cancel a previously sent ROS 2 action goal.
Rejected when ROSBRIDGE_MCP_READONLY is set.
Args: action_name: The action the goal was sent to, e.g. "/navigate_to_pose". goal_id: The goal_id returned by send_action_goal.
Returns {"cancel_sent": true, "action", "goal_id"}. The cancellation outcome (status "canceled") is reported by the action server via the goal's result. Requires rosbridge_suite with ROS 2 action support; on an older rosbridge the tool returns an error advising an upgrade.
| Name | Required | Description | Default |
|---|---|---|---|
| goal_id | Yes | ||
| action_name | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description takes on the transparency burden. It discloses the cancellation request, the asynchronous nature of the outcome, and the return value. It also mentions version requirements. However, it does not cover edge cases like already-completed goals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the key purpose. It includes necessary details without redundancy. The structure is logical, though a slight trim could be possible without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no annotations, the description covers purpose, parameters, return value, and usage conditions. It is reasonably complete, though it could mention failure modes or prerequisites for the goal to be cancellable (e.g., goal must be active).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It does so effectively: action_name is described with an example, and goal_id is linked to the send_action_goal tool's return value. This adds significant meaning beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Cancel a previously sent ROS 2 action goal.' It uses a specific verb and resource, and distinguishes itself from sibling tools like send_action_goal, which is the complementary action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when the tool is rejected (when ROSBRIDGE_MCP_READONLY is set) and lists requirements (rosbridge_suite with action support). It provides context for use but does not explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_camera_imageA
Grab one frame from a camera topic, for vision-capable models.
Read-only — works in readonly mode. Subscribes to topic, waits for one sensor_msgs/msg/CompressedImage (preferred) or sensor_msgs/msg/Image (raw) message, and returns the frame as base64. This is the bridge for VLM / vision-language-action workflows: the model can literally look through the robot's camera before deciding how to act.
Args: topic: Camera topic, e.g. "/camera/image_raw/compressed". Prefer a compressed topic — raw images are large and may exceed the size limit below. timeout: Max seconds to wait for a frame (default 5.0, clamped to at most 30.0).
Returns {"topic", "format" (e.g. "jpeg"), "data_base64", "size_bytes"}, plus "width"/"height"/"encoding" for raw images. Frames larger than 4 MB are not returned: the tool responds with an error suggesting a CompressedImage topic instead (raw metadata is still included).
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | ||
| timeout | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses read-only nature, subscription behavior, message types (CompressedImage/Image), return format, size limit (4 MB), and error response behavior. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured with Args and Returns sections. Every sentence adds operational detail (size limits, raw image metadata, readonly mode), making it appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (subscription, timeout, size handling, output schema), the description covers all operational aspects including error conditions and return payload, making it complete. The output schema is described in prose, which is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions and 0% coverage, so the description fully compensates. It explains topic with an example and guidance, and timeout with default and max clamp. Additionally, it documents the return structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Grab one frame from a camera topic, for vision-capable models,' clearly stating the tool's function with a specific verb and resource. It distinguishes itself from sibling tools like get_topic_snapshot by emphasizing camera images and VLM workflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use: 'This is the bridge for VLM / vision-language-action workflows' and advises 'Prefer a compressed topic.' However, it does not explicitly name alternative tools or exclusionary criteria, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_connection_statusA
Report the current rosbridge connection status and readonly mode.
Takes no arguments. Returns {"url", "connected", "connected_since_unix", "active_subscriptions", "pending_service_calls", "readonly"}. The connection is opened lazily, so "connected" is false until another tool has been used. Check this first when other tools report errors.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the lazy connection behavior ('connected is false until another tool has been used') and lists the return fields. This adds significant behavioral context beyond a simple status check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and every sentence earns its place. The first sentence states the purpose, the second provides behavioral detail and usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, low complexity, and an output schema exists (though not shown), the description covers purpose, behavior (lazy connection), return fields, and usage guidance. It is fully complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds value by explaining the return fields and the lazy connection behavior, which goes beyond the empty schema. No parameter documentation is needed, but the description compensates by clarifying what the tool returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports the current rosbridge connection status and readonly mode. The verb 'report' and the resource 'connection status' are specific. It distinguishes from siblings like list_topics or publish_message, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit guidance: 'Check this first when other tools report errors.' This tells the agent when to use the tool. It also notes that the tool takes no arguments, which is helpful. While it doesn't explicitly state when not to use alternatives, the context of diagnostic ordering is valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_tf_treeA
Snapshot the robot's TF (coordinate transform) tree.
Subscribes briefly to /tf and /tf_static, merges every transform seen into a parent→child frame tree. Read-only — works in readonly mode. Useful for spatial reasoning: which frames exist (map, odom, base_link, camera, gripper, ...) and how they are connected.
Args: timeout: Seconds to listen for transforms (default 2.0, clamped to at most 10.0). Static transforms are latched and arrive immediately; dynamic ones need the robot to be publishing.
Returns {"frame_count", "frames": {child_frame: {"parent", "translation": {x,y,z}, "rotation": {x,y,z,w}, "source": "static"|"dynamic"}}, "tree": {parent: [children...]}, "roots": [frames with no parent seen]}. An empty tree usually means nothing publishes /tf on this robot (or the listen window was too short).
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It explains that the tool subscribes briefly to /tf and /tf_static, merges everything into a parent-child tree, and is read-only. It also notes that static transforms are latched while dynamic ones need publishing. This fairly comprehensively discloses behavior. It loses one point because it doesn't mention if it unsubscribes after the timeout or any potential blocking behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, a brief behavioral paragraph, a parameter section, and a detailed return value description. It is informative but not overly long. However, the return type description could be slightly more compact (e.g., the list of fields takes extra space). Still, every sentence earns its place. Minor deduction for lengthiness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite modest input schema (1 param, 0% coverage), the description is thorough. It explains the tool's behavior, the parameter semantics, the full return structure, and even includes a fallback ('empty tree means...'). The output schema exists and describes return fields, but the description adds context (e.g., what 'empty tree' means). The tool is simple (one param, one return), so the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only one parameter (timeout) with no description. The description adds significant meaning: the default is 2.0, it's clamped to at most 10.0, and it explains the semantics of listening duration in context of static vs dynamic transforms. This adds value beyond the schema. Baseline is 4 due to 0% schema coverage, and the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Snapshot' and a specific resource 'the robot's TF (coordinate transform) tree'. It clearly distinguishes itself from sibling tools like 'get_topic_snapshot', 'list_topics', and 'get_camera_image' by focusing on coordinate transforms and the robot's spatial structure, not just generic topics or images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: it says 'Useful for spatial reasoning: which frames exist... and how they are connected.' It implies when to use (when frame hierarchy is needed) and implicitly not to use for other sensor data. It does not name alternative tools but the sibling list and the purpose make it clear it's the only tree-snapshot tool. The mention of 'Read-only — works in readonly mode' is a usage hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_topic_snapshotA
Read live data from a topic: subscribe, collect up to count
messages (or until timeout seconds elapse), then unsubscribe.
Args: topic: Topic name including leading slash, e.g. "/scan" or "/odom". count: How many messages to collect (default 1, clamped to at most 100). Use more to observe a value changing over time. timeout: Max seconds to wait (default 5.0, clamped to at most 60.0). The tool never blocks longer than this, even on a silent topic. msg_type: Optional full message type, e.g. "sensor_msgs/msg/LaserScan". Usually omit it; rosbridge resolves the type of existing topics.
Returns {"topic", "requested", "received", "messages": [...], "timed_out", "timeout_s"}. If "timed_out" is true, nothing (or not enough) was published within the timeout — the topic may be silent, misspelled, or not exist. If the rosbridge connection drops mid-collection, the tool returns immediately with {"error", "connection_lost": true} instead of waiting out the timeout.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| topic | Yes | ||
| timeout | No | ||
| msg_type | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: subscribe-collect-unsubscribe lifecycle, clamping of count and timeout, never blocking longer than timeout, handling of connection loss, and return format including error fields. This exceeds the burden for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a header and parameter list, but it is slightly verbose in places (e.g., the return format could be prepended). However, every sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no annotations, and an output schema (though not provided in input, but the description lists return fields), the description is complete. It covers all parameters, behavior, edge cases, and return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description explains each parameter in detail: topic requires leading slash, count default and clamping, timeout behavior, and msg_type optionality. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Read live data from a topic: subscribe, collect up to `count` messages (or until `timeout` seconds elapse), then unsubscribe.' This uses a specific verb and resource, and distinctively separates it from siblings like list_topics, publish_message, and call_service.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance: 'Use more to observe a value changing over time' and explains when the tool may return empty (silent topic, misspelled, not exist). It does not explicitly compare to sibling tools, but the context is clear enough for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_nodesA
List all ROS nodes currently running on the robot.
Takes no arguments. Returns {"nodes": ["/talker", "/rosapi", ...]}. Useful to check whether an expected driver or controller is up.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states that the tool lists currently running nodes, returns a specific JSON structure, and takes no arguments. It does not mention potential side effects, permissions, or latency, but for a read-only list operation with no parameters, the given information is sufficient and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two complete sentences plus a short example. Every sentence provides value: the first states the purpose, the second details the return format and confirms no arguments, and the third adds a practical use case. Zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, a clear output schema, and a simple read-only purpose, the description is complete enough. It explains what the tool does, how to invoke it, what it returns, and when to use it. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since there are zero parameters and the schema has 100% coverage, the description adds clarity by explicitly stating 'Takes no arguments.' The baseline is 4 as per guidelines for 0 parameters, and no further parameter documentation is necessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'ROS nodes currently running on the robot'. It distinguishes from siblings like list_topics and list_services by specifying the resource type (nodes vs topics/services).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Takes no arguments' which clarifies invocation. It also provides a use case: 'Useful to check whether an expected driver or controller is up.' However, it does not explicitly state when NOT to use it or mention alternatives among the siblings, though the tool name itself is distinctive enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_servicesA
List all ROS services currently available on the robot.
Takes no arguments. Returns {"services": ["/reset_odometry", ...]}. Use before call_service to find the exact service name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It declares no arguments and specifies the return format (an object with a services array). While it doesn't explicitly state read-only behavior, listing services is inherently non-destructive. The example return value adds transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each essential: what it does, what it takes, and how to use it. No wasted words, front-loaded with the main purpose. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless tool with an output schema, the description covers purpose, usage, and return structure completely. The example service name and the hint to use before call_service provide full context for the agent to decide and invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameters (100% coverage by default). The description confirms 'Takes no arguments,' which adds no extra meaning but meets the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all ROS services currently available on the robot,' specifying both the verb (List) and the resource (ROS services). It effectively distinguishes from sibling tools like list_topics and list_nodes by naming the specific resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: 'Use before call_service to find the exact service name.' This tells the agent when to invoke this tool and hints at a workflow sequence, making the purpose and timing unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_topicsA
List all ROS topics currently known to the robot, with message types.
Takes no arguments. Returns {"topics": [{"name": "/scan", "type": "sensor_msgs/msg/LaserScan"}, ...]}. Call this first to discover what the robot exposes before subscribing or publishing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden of transparency. It explicitly states 'Takes no arguments' and describes the return format with an example, which is helpful for an AI. However, it does not mention side effects, rate limits, or access restrictions; a slight gap relative to a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, no wasted words. Each sentence contributes: the first explains the action, the second clarifies arguments and output, the third provides usage guidance. Perfectly front-loaded with the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple, parameter-less discovery tool with a nested output schema and the description already includes an example of the return format, nothing is missing. The context signals confirm zero parameters and 100% schema coverage, so the description is fully complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% description coverage (none needed), so baseline is 4. The description adds no parameter semantics (since none exist), but this is correct because there is nothing to add beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('all ROS topics') while distinguishing from sibling tools (e.g., list_nodes) by specifying the output includes message types. This fully clarifies the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use this tool ('Call this first to discover... before subscribing or publishing'), providing clear context. It does not explicitly exclude alternatives, but the guidance is strong enough for an AI to understand the primary use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
publish_messageA
Publish a JSON message to a ROS topic (advertises the topic first).
CAUTION: this can move a real robot. Rejected when ROSBRIDGE_MCP_READONLY is set. Prefer reading relevant sensor topics (e.g. /scan, /odom) before commanding motion, and publish zero velocity to stop.
Args: topic: Target topic, e.g. "/cmd_vel". msg_type: Full ROS 2 message type with the "/msg/" segment, e.g. "geometry_msgs/msg/Twist" or "std_msgs/msg/String". message: JSON object whose fields match the message definition, e.g. {"linear": {"x": 0.1, "y": 0.0, "z": 0.0}, "angular": {"x": 0.0, "y": 0.0, "z": 0.2}} for a Twist. Omitted fields default to zero/empty on the ROS side.
Returns {"published": true, "topic": ..., "type": ...} on success. The tool briefly waits for rosbridge 'status' errors after publishing; if rosbridge rejected the message (e.g. wrong msg_type), the result includes "rosbridge_warnings" — treat those as the publish having failed.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | ||
| message | Yes | ||
| msg_type | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It explains that the topic is advertised first, that the action is potentially destructive, that it waits briefly for rosbridge errors, and that failure results in rosbridge_warnings in the response. It also specifies the success return format. This is comprehensive and truthful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured: a core action sentence, a caution block, then Args and Returns sections. Every sentence serves a purpose. It is front-loaded with the essential information—the action and the safety warning—and no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 required parameters, nested objects, no schema descriptions, no provided output schema), the description is remarkably complete. It covers the purpose, usage precautions, parameter formats and defaults, behavioral notes (advertisement, error handling), and return values. The AI agent has all necessary information to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions for its three parameters. The description compensates fully with detailed Args: topic gets an example path, msg_type gets the required ROS 2 format with examples, and message gets a full JSON example plus the important note that omitted fields default to zero/empty. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Publish a JSON message to a ROS topic (advertises the topic first).' It immediately distinguishes this tool from its siblings, which are primarily read-only (list_topics, get_topic_snapshot, etc.), by emphasizing that it can move a real robot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage guidance: it warns that the tool can move a real robot, recommends reading sensor topics before commanding motion, advises publishing zero velocity to stop, and notes that it is rejected when ROSBRIDGE_MCP_READONLY is set. It could be more explicit about which sibling tools to use instead for reading (e.g., get_topic_snapshot), but the intent is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_action_goalA
Send a goal to a ROS 2 action server via rosbridge.
CAUTION: actions typically make the robot move (navigation, arm motion). Rejected when ROSBRIDGE_MCP_READONLY is set.
Args: action_name: Action name, e.g. "/navigate_to_pose". action_type: Full action type with the "/action/" segment, e.g. "nav2_msgs/action/NavigateToPose". goal: JSON object matching the action's goal definition. Default {}. timeout: Max seconds to wait for the result when wait_for_result is true (default 30.0, clamped to at most 120.0). wait_for_result: If true (default), block until the action finishes and return its result. If false, return the goal_id immediately — use cancel_action_goal with that id to stop the goal later.
Returns, when waiting: {"action", "goal_id", "success", "status", "status_text" (succeeded/aborted/canceled/...), "values" (result fields), "last_feedback" (most recent feedback values, or null)}. When not waiting: {"action", "goal_id", "result_pending": true}.
Requires rosbridge_suite with ROS 2 action support (ops send_action_goal / cancel_action_goal). Against an older rosbridge the tool detects the rejected operation (via rosbridge status errors, or timeout as fallback) and returns an error advising to upgrade rosbridge_suite on the robot.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| timeout | No | ||
| action_name | Yes | ||
| action_type | Yes | ||
| wait_for_result | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It thoroughly discloses: the tool causes robot movement, is blocked by READONLY mode, requires specific rosbridge_suite support, handles errors with older bridges, details return structures for both blocking and non-blocking modes, and explains timeout clamping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a brief purpose statement, a caution, parameter details with formatting, return value descriptions, and prerequisites. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description covers all essential aspects: purpose, parameters, return values, error scenarios, prerequisites, and practical usage notes. It is comprehensive and leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining each parameter: action_name with example, action_type with full type format, goal as JSON object, timeout with default and clamping, and wait_for_result with behavior implications.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The tool's purpose is clearly stated: 'Send a goal to a ROS 2 action server via rosbridge.' The caution about robot movement and the contrast with siblings like cancel_action_goal, call_service, and publish_message provide strong differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Some usage guidance is present: caution about robot movement, rejected when READONLY, and guidance on using cancel_action_goal when wait_for_result is false. However, there is no explicit comparison to sibling tools or advice on when to prefer this over other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
v0.2.0- First observed
call_service - First observed
cancel_action_goal - First observed
get_camera_image - First observed
get_connection_status - First observed
get_tf_tree - First observed
get_topic_snapshot - First observed
list_nodes - First observed
list_services - First observed
list_topics - First observed
publish_message - First observed
send_action_goal
TDQS
Scored across 11 tools
Each tool targets a distinct operation in the ROS ecosystem: listing resources, reading topic data, publishing, calling services, managing action goals, retrieving TF and camera data, and checking connection status. There is no overlap, and the descriptions clearly differentiate their purposes.
The tools follow a verb_noun pattern, but use a mix of verbs: 'list_' for discovery, 'get_' for retrieval, and 'publish_', 'call_', 'send_', 'cancel_' for actions. While all are descriptive and readable, the lack of a single unified prefix across all tools keeps it from being a perfect 5.
With 11 tools, the server is well-scoped for a ROS bridge interface. Each tool covers a distinct aspect of ROS interaction (topics, services, actions, TF, camera), and the number is neither too sparse nor overwhelming.
The tool surface covers core workflows: discovery, reading and writing topics, calling services, managing actions, and retrieving transforms and images. A minor gap is the lack of a dedicated tool to list available actions, but this can be partially achieved via list_services or documentation.
Maintenance
Related MCP Connectors
- alloyOAuthai.usealloy
Connect Claude, Cursor, Codex, and other AI tools to your robotics mission data.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Connect agents to 6DuckLearn memory, approvals, and runtime control.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables control of ROS/ROS2 robots through natural language commands by translating LLM instructions into ROS topics and services. Supports cross-platform WebSocket-based communication with existing robot systems without requiring code modifications.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI tools to interact with ROS2 robotics systems through natural language commands. Supports topic publishing/subscribing, service calls, message analysis, and auto-discovery of ROS2 interfaces for debugging and controlling robots.Mozilla Public 2.0
- AlicenseAqualityDmaintenanceEnables controlling robots in ROS environments through natural language, supporting topics, services, actions, and GUI tools.2436MIT
- AlicenseNot gradedqualityDmaintenanceEnables large language models to interact with ROS robots seamlessly, allowing natural language control, real-time sensor monitoring, and autonomous task execution without modifying existing robot code.Apache 2.0