rosbridge-mcp
rosbridge-mcp
rosbridge-mcp — это сервер Model Context Protocol, который подключает AI-агентов (Claude Desktop, Cursor, VS Code и любые другие MCP-клиенты) к роботам, работающим под управлением ROS 2, через стандартный протокол rosbridge v2 (WebSocket + JSON). Вы запускаете rosbridge_server на своём роботе или ROS-машине; этот MCP-сервер подключается к нему по сети и предоставляет 11 инструментов, позволяющих AI наблюдать за топиками, исследовать граф ROS и дерево TF, видеть через камеру робота, публиковать сообщения, вызывать сервисы и управлять действиями ROS 2 — без необходимости установки ROS на машине, где работает AI-клиент.
Архитектура
+--------------------+ 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. Полезные нагрузки сообщений и аргументов используют то же JSON-представление ROS-сообщений, что и rosbridge (имена полей соответствуют определениям .msg/.srv/.action).
Инструмент | Что делает | Мутирующий? |
| Все топики + типы сообщений | нет |
| Все запущенные узлы | нет |
| Все доступные сервисы | нет |
| Собрать живые сообщения с топика | нет |
| Снимок дерева координатных преобразований TF | нет |
| Захватить один кадр с камеры в base64 | нет |
| Состояние подключения + режим только для чтения | нет |
| Опубликовать сообщение в топик | да |
| Вызвать любой 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 — инструмент никогда не зависает дольше 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, чтобы остановить цель позже. Требуется версия rosbridge_suite с поддержкой действий ROS 2; при старой версии 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 и /tf_static. Параметры: 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 МБ не возвращаются — инструмент отвечает метаданными и ошибкой с предложением использовать сжатый топик.
get_connection_status
Сообщить состояние подключения и режим только для чтения. Без параметров.
{"url": "ws://localhost:9090", "connected": true,
"connected_since_unix": 1786903978.1, "active_subscriptions": [],
"pending_service_calls": 0, "readonly": false}Пример диалога
Вы: Что сейчас видит робот?
Агент: (вызывает
list_topics, находит/scanтипаsensor_msgs/msg/LaserScan, затем вызывает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 м/с. Скажите, когда остановиться, и я опубликую нулевую скорость.
Для зрительного и воплощённого AI
Два инструмента только для чтения существуют специально для того, чтобы grounded vision-language модели в физической реальности робота:
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 на стороне модели. Оба инструмента восприятия работают в режиме только для чтения, поэтому вы можете безопасно запустить агента "смотри, но не трогай".
Конфигурация
Переменная окружения | По умолчанию | Описание |
|
| WebSocket-URL сервера rosbridge |
|
| Отклонять мутирующие инструменты (см. Безопасность) |
Безопасность
Позволять языковой модели публиковать /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): единственное сетевое соединение, которое когда-либо открывает этот пакет, — это WebSocket к ROSBRIDGE_URL, который вы настраиваете — нет аналитики, нет звонков домой, нет отчётов о сбоях, нет скрытых HTTP-вызовов, и код не содержит логирования содержимого сообщений на диск. Встроенный mock-сервер привязывается только к 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 — это уровень файла copyleft, который применяется только к модификациям собственных файлов certifi и совместим с использованием и распространением по MIT. В дереве зависимостей нет кода GPL/AGPL/проприетарного, и весь код в этом репозитории является оригинальной работой, написанной для этого проекта.
Часто задаваемые вопросы
Нужно ли устанавливать ROS там, где работает AI-клиент? Нет. Только 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 образ + аутентификация/TLS rosbridge, v0.4 многороботные флоты + MCP ресурсы (URDF/карта), v1.0 стабильный API + официальная регистрация в MCP реестре + примеры с Gazebo/Isaac Sim.
Поддержка проекта
rosbridge-mcp создаётся и поддерживается одним человеком, неполный рабочий день, на ранней стадии. Всё, что существует сегодня, реально и протестировано: 11 инструментов, охватывающих топики, сервисы, ROS 2 действия, TF и моментальные снимки камеры; 43 автоматических теста, работающих в CI при каждом коммите; документация для 5 сценариев использования; режим безопасности «только чтение» с белым списком сервисов; и аудированный код без телеметрии.
Что необходимо для реализации плана развития, честно говоря:
v0.3 (развёртывание и безопасность): несколько недель разработки неполный день, небольшое облачное VM или собственный раннер для сборки Docker образов и, что наиболее важно, рецензент, ориентированный на безопасность, для слоя аутентификации/TLS rosbridge.
v0.4 (флоты): доступ к 2+ одновременно работающим роботам или экземплярам симулятора, а также обратная связь по дизайну от реальной робототехнической лаборатории (ищу академического или промышленного пилотного партнёра).
v1.0 (стабильность и экосистема): постоянное время мейнтейнера (
2 дня/неделю в течение квартала), однаRTX-класс GPU рабочая станциядля валидации Isaac Sim — основной аппаратный запрос всего плана — и по желанию недорогой робот ($1–3k) для CI с аппаратурой в контуре.
Как вы можете помочь в порядке возрастания усилий:
Поставьте звезду репозиторию — видимость действительно помогает раннему проекту привлечь участников.
Попробуйте на своём роботе или симуляторе и откройте issue с вашей версией ROS + rosbridge — отчёты о совместимости — самый дешёвый способ сделать проект надёжным.
Внесите PR — docs/development.md объясняет структуру кода за 10 минут, и каждый пункт плана можно взять в работу.
Станьте спонсором или партнёром — если ваша лаборатория или компания может предоставить время симулятора, оборудование, 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 сервер, который соединяет AI-агента (Claude Desktop, Cursor, VS Code...) с роботом, работающим на ROS 2, через протокол rosbridge (WebSocket + JSON). Устанавливать ROS на машине с AI-клиентом не требуется.
Документация разделена по сценариям — выберите подходящее руководство в папке docs/:
Использование Claude Desktop — пошаговая настройка JSON на Windows/macOS/Linux
Использование Cursor / VS Code — настройка
mcp.jsonв редактореБез робота — попробуйте с Docker (
ros:humble+ rosbridge) или TurtleBot3/Gazebo, или встроенным mock-серверомС настоящим роботом — чек-лист безопасности: сначала включите
ROSBRIDGE_MCP_READONLY=true, прочитайте/odom,/scan, чтобы понять робота, затем откройте права на публикацию/cmd_velРазработчику — архитектура кода, как добавить новый инструмент, запуск тестов с mock (без 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 — электронная книга по обучению с подкреплением (reinforcement learning) и робототехнике БПЛА.
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