Skip to main content
Glama
hieutachi

rosbridge-mcp

by hieutachi

rosbridge-mcp

CI 许可证: MIT Python 3.10+

rosbridge-mcp 是一个模型上下文协议服务器,它通过标准的 rosbridge v2 协议(WebSocket + JSON),将 AI 代理(Claude Desktop、Cursor、VS Code 以及任何其他 MCP 客户端)连接到运行 ROS 2 的机器人。您在机器人或 ROS 机器上运行 rosbridge_server;此 MCP 服务器通过网络连接到它,并公开了 11 个工具,让 AI 可以观察话题、检查 ROS 图和 TF 树、通过机器人摄像头查看、发布消息、调用服务以及驱动 ROS 2 动作——在运行 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 与您的机器人交谈

docs/claude-desktop.md

Cursor 或 VS Code 用户——希望在编辑器中使用机器人工具

docs/cursor-vscode.md

ROS 新手,尚无机器人——尝试模拟器或 Docker,无需硬件

docs/simulator-quickstart.md

连接真实机器人——在让 LLM 靠近硬件前的安全清单

docs/real-robot-safety.md

开发者——希望贡献、添加工具或理解代码

docs/development.md

工具

共 11 个工具。所有工具均返回 JSON。消息和参数负载使用与 rosbridge 相同的 ROS 消息 JSON 表示形式(字段名称与 .msg/.srv/.action 定义匹配)。

工具

功能

可更改?

list_topics

所有话题 + 消息类型

否

list_nodes

所有运行中的节点

否

list_services

所有可用的服务

否

get_topic_snapshot

从话题收集实时消息

否

get_tf_tree

抓取 TF 坐标变换树的快照

否

get_camera_image

获取一帧摄像头图像,编码为 base64

否

get_connection_status

连接状态 + 只读状态

否

publish_message

向话题发布消息

是

call_service

调用任何 ROS 服务

是(只读模式下允许使用 /rosapi 读取的允许列表)

send_action_goal

发送 ROS 2 动作目标,等待结果

是

cancel_action_goal

取消正在执行的动作目标

是

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——该工具永远不会阻塞超过 timeout 时间。

publish_message (可更改)

通告一个话题并发布一条 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

从摄像头话题获取一帧图像,编码为 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)。超过 4 MB 的帧不会返回——该工具会返回元数据以及一条建议使用压缩话题的错误消息。

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 个距离读数。最近的障碍物大约在 0.4 米外,位于左侧约 90° 方向;正前方至少 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

其中两个只读工具专门用于将视觉语言模型锚定在机器人的物理现实中:

  • get_camera_image 将真实的摄像头帧作为 base64 返回——具有视觉能力的模型(Claude、GPT-4o 或 VLA 策略前端)在决定做什么之前,可以直观地通过机器人的摄像头观察。

  • get_tf_tree 为模型提供机器人的空间骨架——存在哪些坐标系(map、odom、base_link、camera、gripper)以及它们之间的相对位置关系。

结合 get_topic_snapshot(激光雷达、里程计、关节状态)和 send_action_goal(导航、操作),这覆盖了视觉和动作代理所需的观察→推理→行动循环,通过简单的 WebSocket 实现,模型端无需安装 ROS。两个感知工具均在只读模式下工作,因此您可以安全地运行“只看不碰”的代理。

配置

环境变量

默认值

描述

ROSBRIDGE_URL

ws://localhost:9090

rosbridge 服务器的 WebSocket URL

ROSBRIDGE_MCP_READONLY

false

拒绝可更改工具(参见安全说明)

安全

让语言模型向实体机器人发布 /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 客户端(该客户端会将其转发给您选择的 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)。一个传递依赖项 certifi 是 MPL-2.0——这是一种文件级别的版权左派许可证,仅适用于对 certifi 自身文件的修改,并且与 MIT 的使用和重新分发兼容。依赖树中没有任何 GPL/AGPL/专有代码,并且此仓库中的所有代码均为此项目编写的原创作品。

常见问题

我需要在运行 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。

Agent 提示无法连接。 请检查 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–3k)用于硬件在环 CI。

您可以按以下方式提供帮助(按投入精力递增排序):

  1. 为仓库加星 — 知名度确实有助于早期项目吸引贡献者。

  2. 在您的机器人或模拟器上试用,并提交一个包含您的 ROS 发行版和 rosbridge 版本的问题 — 兼容性报告是提升鲁棒性最经济的方式。

  3. 贡献 PR — docs/development.md 可在 10 分钟内解释代码库,每个路线图项目都可认领。

  4. 赞助或合作 — 如果您的实验室或公司可以提供模拟器时间、硬件、GPU 工作站或资助开发时间,请通过 github.com/hieutachi 联系。

相关资源

如果您正在进入机器人领域,Robotics RL & UAV ebook 是作者提供的配套学习资源,涵盖强化学习和无人机机器人技术。

贡献

欢迎贡献!请参见 CONTRIBUTING.md 和开发指南。请确保签署您的提交(DCO)。

许可证

MIT — 请参见 LICENSE。依赖项许可证宽松且兼容:fastmcp(Apache-2.0),websockets(BSD-3-Clause)。无 GPL/AGPL 依赖。


越南语摘要

rosbridge-mcp 是一个 MCP 服务器,通过 rosbridge 协议(WebSocket + JSON)在 AI agent(Claude Desktop、Cursor、VS Code 等)和运行 ROS 2 的机器人之间建立桥梁。无需在运行 AI 客户端的机器上安装 ROS。

文档按场景划分 — 在 docs/ 目录中为您选择正确的指南:

  • 使用 Claude Desktop — Windows/macOS/Linux 上的逐步 JSON 配置

  • 使用 Cursor / VS Code — 在编辑器中配置 mcp.json

  • 还没有机器人 — 使用 Docker(ros:humble + rosbridge)或 TurtleBot3/Gazebo 试用,或使用附带的模拟服务器

  • 有真实机器人 — 安全检查清单:先启用 ROSBRIDGE_MCP_READONLY=true,读取 /odom、/scan 以了解机器人,然后才开放发布 /cmd_vel 的权限

  • 开发者 — 代码架构、添加新工具的方法、使用模拟(无需 ROS)运行测试

11 个工具: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。在处理真实机器人时,启用 ROSBRIDGE_MCP_READONLY=true 以阻止所有写入操作(发布、动作)——读取工具(TF、摄像头、话题)仍可正常使用。

作者提供的配套学习资源:Robotics RL & UAV ebook — 关于强化学习和无人机机器人的电子书。

Available Tools

11 tools
call_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").

ParametersJSON Schema
NameRequiredDescriptionDefault
argsNo
serviceYes
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
goal_idYes
action_nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYes
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNo
topicYes
timeoutNo
msg_typeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYes
messageYes
msg_typeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
goalNo
timeoutNo
action_nameYes
action_typeYes
wait_for_resultNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior5/5

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

No annotations are provided, so the description carries 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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 11 tool updatesv0.2.0
    • First observedcall_service
    • First observedcancel_action_goal
    • First observedget_camera_image
    • First observedget_connection_status
    • First observedget_tf_tree
    • First observedget_topic_snapshot
    • First observedlist_nodes
    • First observedlist_services
    • First observedlist_topics
    • First observedpublish_message
    • First observedsend_action_goal

TDQS

A4.5/5.0

Scored across 11 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/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.

Completeness4/5

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

ActivitySlowing
ResponsivenessResponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables 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
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables 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
  • A
    license
    A
    quality
    D
    maintenance
    Enables controlling robots in ROS environments through natural language, supporting topics, services, actions, and GUI tools.
    24
    36
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables 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