rosbridge-mcp
rosbridge-mcp
rosbridge-mcp es un servidor del Model Context Protocol que conecta agentes de IA (Claude Desktop, Cursor, VS Code y cualquier otro cliente MCP) a robots que ejecutan ROS 2, a través del protocolo estándar rosbridge v2 (WebSocket + JSON). Ejecutas rosbridge_server en tu robot o máquina ROS; este servidor MCP se conecta a él a través de la red y expone 11 herramientas que permiten a la IA observar tópicos, inspeccionar el grafo ROS y el árbol TF, ver a través de la cámara del robot, publicar mensajes, llamar servicios y ejecutar acciones de ROS 2 — sin necesidad de instalar ROS en la máquina donde se ejecuta el cliente de IA.
Arquitectura
+--------------------+ 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
Inicio rápido (60 segundos)
pip install git+https://github.com/hieutachi/rosbridge-mcp.gitO, una vez publicado: pip install rosbridge-mcp (PyPI — próximamente).
Añádelo a la configuración de tu cliente MCP (consulta las guías específicas para cada cliente más abajo para conocer las ubicaciones exactas de los archivos):
{
"mcpServers": {
"rosbridge": {
"command": "rosbridge-mcp",
"env": { "ROSBRIDGE_URL": "ws://<robot-ip>:9090" }
}
}
}Luego pregúntale a tu agente: "¿Qué tópicos tiene el robot?"
Elige tu ruta
Elige la guía que se adapte a ti — cada una es autocontenida, no necesitas leer el resto de este README primero:
Eres... | Guía |
Un usuario de Claude Desktop — quieres hablar con tu robot desde Claude | |
Un usuario de Cursor o VS Code — quieres herramientas robóticas dentro de tu editor | |
Nuevo en ROS, sin robot aún — pruébalo todo con un simulador o Docker, sin hardware | |
Conectando un robot real — lista de verificación de seguridad antes de dejar que un LLM se acerque al hardware | |
Un desarrollador — quieres contribuir, añadir herramientas o entender el código |
Herramientas
11 herramientas en total. Todas las herramientas devuelven JSON. Las cargas útiles de mensajes y argumentos utilizan la misma representación JSON de mensajes ROS que usa rosbridge (los nombres de campo coinciden con las definiciones .msg/.srv/.action).
Herramienta | Qué hace | ¿Mutante? |
| Todos los tópicos + tipos de mensaje | no |
| Todos los nodos en ejecución | no |
| Todos los servicios disponibles | no |
| Recoge mensajes en vivo de un tópico | no |
| Instantánea del árbol de marcos de coordenadas TF | no |
| Captura un fotograma de cámara como base64 | no |
| Estado de la conexión + modo de solo lectura | no |
| Publica un mensaje en un tópico | sí |
| Llama a cualquier servicio ROS | sí (solo lectura permite una lista blanca de lecturas de |
| Envía un objetivo de acción ROS 2, espera el resultado | sí |
| Cancela un objetivo de acción en curso | sí |
list_topics
Lista todos los tópicos con sus tipos de mensaje. Sin parámetros.
{"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
Lista todos los nodos en ejecución. Sin parámetros.
{"nodes": ["/talker", "/listener", "/rosapi"]}list_services
Lista todos los servicios disponibles. Sin parámetros.
{"services": ["/rosapi/topics", "/rosapi/nodes", "/reset_odometry"]}get_topic_snapshot
Se suscribe a un tópico, recoge mensajes, se desuscribe. Parámetros: topic (obligatorio), count (por defecto 1), timeout segundos (por defecto 5.0), msg_type (opcional, normalmente detectado automáticamente por rosbridge).
Entrada: {"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}Si el tópico está en silencio, received es menor que requested y timed_out es true — la herramienta nunca se cuelga más tiempo del indicado en timeout.
publish_message (mutante)
Anuncia un tópico y publica un mensaje JSON. Parámetros: topic, msg_type (tipo completo de ROS 2, ej. geometry_msgs/msg/Twist), message (objeto JSON que coincide con el tipo).
Entrada:
{"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}}}Salida: {"published": true, "topic": "/cmd_vel", "type": "geometry_msgs/msg/Twist"}
call_service (mutante)
Llama a cualquier servicio ROS. Parámetros: service (obligatorio), args (objeto JSON, por defecto {}), timeout segundos (por defecto 10.0).
Entrada: {"service": "/rosapi/topic_type", "args": {"topic": "/scan"}}
{"service": "/rosapi/topic_type", "success": true,
"values": {"type": "sensor_msgs/msg/LaserScan"}}En caso de fallo, la herramienta devuelve {"success": false, "error": "..."} en lugar de lanzar una excepción.
send_action_goal (mutante)
Envía un objetivo a un servidor de acciones ROS 2 (navegación, movimiento de brazo, ...). Parámetros: action_name, action_type (tipo completo con /action/, ej. nav2_msgs/action/NavigateToPose), goal (objeto JSON, por defecto {}), timeout segundos (por defecto 30, limitado a ≤ 120), wait_for_result (por defecto true).
Entrada: {"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]}}Con wait_for_result: false la herramienta devuelve {"goal_id": ..., "result_pending": true} inmediatamente — pasa ese goal_id a cancel_action_goal para detener el objetivo más tarde. Requiere una versión de rosbridge_suite con soporte para acciones de ROS 2; contra un rosbridge más antiguo, la herramienta devuelve un error recomendando una actualización en lugar de colgarse.
cancel_action_goal (mutante)
Cancela un objetivo de acción previamente enviado. Parámetros: action_name, goal_id (de send_action_goal).
Salida: {"cancel_sent": true, "action": "/navigate_to_pose", "goal_id": "send_action_goal:7"}
get_tf_tree
Toma una instantánea del árbol TF (transformación de coordenadas) del robot escuchando brevemente /tf y /tf_static. Parámetros: timeout segundos (por defecto 2.0, limitado a ≤ 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
Captura un fotograma de un tópico de cámara como base64, para que los modelos con capacidad de visión puedan ver lo que ve el robot. Parámetros: topic (preferiblemente un tópico sensor_msgs/msg/CompressedImage, ej. /camera/image_raw/compressed), timeout segundos (por defecto 5.0, limitado a ≤ 30).
Salida: {"topic": ..., "format": "jpeg", "data_base64": "...", "size_bytes": 51234} (los tópicos Image sin procesar adicionalmente devuelven width/height/encoding). Los fotogramas de más de 4 MB no se devuelven — la herramienta responde con metadatos más un error sugiriendo un tópico comprimido.
get_connection_status
Informa del estado de la conexión y del modo de solo lectura. Sin parámetros.
{"url": "ws://localhost:9090", "connected": true,
"connected_since_unix": 1786903978.1, "active_subscriptions": [],
"pending_service_calls": 0, "readonly": false}Ejemplo de conversación
Tú: ¿Qué está viendo el robot ahora mismo?
Agente: (llama a
list_topics, encuentra/scande tiposensor_msgs/msg/LaserScan, luego llama aget_topic_snapshotcon{"topic": "/scan", "count": 1}) El escáner láser reporta 360 lecturas de rango. El obstáculo más cercano está a unos 0.4 m aproximadamente a 90° a la izquierda; el espacio directamente al frente está despejado durante al menos 2.5 m.Tú: Bien, avanza lentamente un momento.
Agente: (llama a
publish_messagecon{"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist", "message": {"linear": {"x": 0.1}, "angular": {"z": 0.0}}}) Publicado un comando de velocidad hacia adelante de 0.1 m/s. Dime cuándo parar y publicaré velocidad cero.
Para visión e IA corpórea
Dos de las herramientas de solo lectura existen específicamente para fundamentar los modelos de lenguaje visual en la realidad física del robot:
get_camera_imagedevuelve un fotograma real de la cámara como base64 — un modelo con capacidad de visión (Claude, GPT-4o, o un front-end de política VLA) puede literalmente mirar a través de la cámara del robot antes de decidir qué hacer.get_tf_treeproporciona al modelo el esqueleto espacial del robot — qué marcos existen (map, odom, base_link, camera, gripper) y cómo están posicionados entre sí.
Combinado con get_topic_snapshot (lidar, odometría, estados de articulaciones) y send_action_goal (navegación, manipulación), esto cubre el bucle observar → razonar → actuar que los agentes de visión y acción necesitan, a través de un WebSocket simple, sin instalación de ROS en el lado del modelo. Ambas herramientas de percepción funcionan en modo de solo lectura, por lo que puedes ejecutar un agente de "mira pero no toques" de forma segura.
Configuración
Variable de entorno | Por defecto | Descripción |
|
| URL WebSocket del servidor rosbridge |
|
| Rechazar herramientas mutantes (ver Seguridad) |
Seguridad
Permitir que un modelo de lenguaje publique /cmd_vel en un robot físico es un riesgo real. Establece ROSBRIDGE_MCP_READONLY=true para ejecutar en modo de solo lectura: publish_message, send_action_goal y cancel_action_goal son rechazados, y call_service solo permite una lista blanca fija de servicios de introspección de /rosapi de solo lectura conocidos (topics, nodes, services, types, get_param, get_time, ...) — cualquier cosa que no esté en la lista, incluidos servicios futuros desconocidos de /rosapi, es rechazada. Las herramientas de percepción de solo lectura (get_topic_snapshot, get_tf_tree, get_camera_image) siguen funcionando. Recomendamos encarecidamente comenzar en modo de solo lectura con hardware real — consulta la lista de verificación de seguridad completa para robots reales y el modelo de seguridad de despliegue en SECURITY.md.
Privacidad y aspectos legales
Sin telemetría, sin recopilación de datos. Auditado (2026-08): la única conexión de red que este paquete abre alguna vez es el WebSocket hacia la ROSBRIDGE_URL que configures — no hay análisis, ni llamadas a casa, ni informes de fallos, ni llamadas HTTP ocultas, y el código no contiene registro del contenido de los mensajes en disco. El servidor simulado incluido se vincula solo a 127.0.0.1. Los datos del robot devueltos por las herramientas van exclusivamente a tu cliente MCP (que los reenvía al LLM que hayas elegido — esa parte está bajo tu control, no bajo el nuestro).
Cumplimiento de licencias. Todas las dependencias de tiempo de ejecución y transitivas tienen licencias compatibles con la licencia MIT de este proyecto — directas: fastmcp (Apache-2.0), websockets (BSD-3-Clause); transitivas clave: mcp (MIT), pydantic (MIT), starlette (BSD-3-Clause), httpx (BSD-3-Clause), anyio (MIT), cryptography (Apache-2.0/BSD-3). Una dependencia transitiva, certifi, es MPL-2.0 — un copyleft a nivel de archivo que solo se aplica a modificaciones de los propios archivos de certifi y es compatible con el uso y redistribución MIT. No hay código GPL/AGPL/propietario en ningún lugar del árbol de dependencias, y todo el código en este repositorio es trabajo original escrito para este proyecto.
Preguntas frecuentes
¿Necesito tener ROS instalado donde se ejecuta el cliente de IA? No. Solo Python 3.10+. ROS y rosbridge se ejecutan en el robot (o en Docker, o en un simulador); este servidor se comunica con ellos a través de WebSocket.
¿Funciona con ROS 1?
El protocolo rosbridge v2 es el mismo, por lo que las operaciones básicas también funcionan contra un rosbridge_server de ROS 1 — usa nombres de tipo de ROS 1 (std_msgs/String). Solo ROS 2 se prueba en CI.
El agente indica que no puede conectarse.
Verifique que rosbridge esté en ejecución (ros2 launch rosbridge_server rosbridge_websocket_launch.xml), que ROSBRIDGE_URL apunte al host/puerto correcto y que el puerto 9090 sea accesible (firewall). Cada guía en docs/ tiene una sección de solución de problemas.
¿Puedo probarlo sin ningún robot o simulador?
Sí — python -m rosbridge_mcp.mock_server 9090 inicia un rosbridge falso con temas precargados, luego configure ROSBRIDGE_URL en ws://localhost:9090.
¿Se envían mis datos a algún lugar?
El servidor solo se conecta a la ROSBRIDGE_URL que usted configure. Los datos de los temas se devuelven a su cliente MCP, que los reenvía al LLM que usted utilice — trate los datos de los sensores en consecuencia.
Hoja de ruta
Plan por etapas con objetivos, entregables y recursos necesarios para cada etapa: consulte ROADMAP.md. Lo más destacado: v0.2 cliente de acciones + TF + capturas de cámara (completado en v0.2.0), v0.3 transporte HTTP + imagen Docker + autenticación/TLS de rosbridge, v0.4 flotas multirobot + recursos MCP (URDF/mapa), v1.0 API estable + listado en el registro oficial de MCP + ejemplos de Gazebo/Isaac Sim.
Apoye este proyecto
rosbridge-mcp es construido y mantenido por una persona, a tiempo parcial, en su etapa inicial. Lo que existe hoy es real y probado: 11 herramientas que cubren temas, servicios, acciones de ROS 2, TF y capturas de cámara; 43 pruebas automatizadas que se ejecutan en CI en cada commit; documentación por escenario para 5 perfiles de usuario; un modo de seguridad de solo lectura con una lista blanca de servicios; y una base de código auditada sin telemetría.
Lo que la hoja de ruta necesita para hacerse realidad, expuesto honestamente:
v0.3 (despliegue y seguridad): semanas de desarrollo a tiempo parcial, una pequeña VM en la nube o un runner autoalojado para la compilación de imágenes Docker y, lo más importante, un revisor orientado a la seguridad para la capa de autenticación/TLS de rosbridge.
v0.4 (flotas): acceso a 2 o más instancias de robots o simuladores en ejecución simultánea, y comentarios de diseño de un laboratorio de robótica real (buscando un socio piloto académico o industrial).
v1.0 (estabilidad y ecosistema): tiempo sostenido de mantenimiento (
2 días/semana durante un trimestre), unaestación de trabajo GPU clase RTXpara la validación con Isaac Sim — la principal solicitud de hardware de toda la hoja de ruta — y, opcionalmente, un robot de bajo costo ($1–3k) para CI hardware-in-the-loop.
Cómo puede ayudar, en orden creciente de esfuerzo:
Dé una estrella al repositorio — la visibilidad ayuda genuinamente a que un proyecto temprano obtenga contribuyentes.
Pruébelo en su robot o simulador y abra un issue con su distribución de ROS y versión de rosbridge — los informes de compatibilidad son la forma más barata de hacerlo robusto.
Contribuya con un PR — docs/development.md explica la base de código en 10 minutos, y cada elemento de la hoja de ruta es reclamable.
Patrocine o asóciese — si su laboratorio o empresa puede ofrecer tiempo de simulador, hardware, una estación de trabajo GPU o tiempo de desarrollo financiado, póngase en contacto a través de github.com/hieutachi.
Recursos relacionados
Si se está iniciando en la robótica, el libro electrónico Robotics RL & UAV es un recurso de aprendizaje complementario del autor que cubre el aprendizaje por refuerzo y la robótica UAV.
Contribuciones
¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md y la guía de desarrollo. Firme sus commits (DCO).
Licencia
MIT — consulte LICENSE. Las licencias de las dependencias son permisivas y compatibles: fastmcp (Apache-2.0), websockets (BSD-3-Clause). Sin dependencias GPL/AGPL.
Tóm tắt tiếng Việt
rosbridge-mcp là một MCP server cầu nối giữa AI agent (Claude Desktop, Cursor, VS Code...) và robot chạy ROS 2 thông qua giao thức rosbridge (WebSocket + JSON). Không cần cài ROS trên máy chạy AI client.
Tài liệu được chia theo từng kịch bản — chọn đúng hướng dẫn cho bạn trong thư mục docs/:
Dùng Claude Desktop — cấu hình JSON từng bước trên Windows/macOS/Linux
Dùng Cursor / VS Code — cấu hình
mcp.jsontrong editorChưa có robot — chạy thử với Docker (
ros:humble+ rosbridge) hoặc TurtleBot3/Gazebo, hoặc mock server đi kèmCó robot thật — checklist an toàn: bật
ROSBRIDGE_MCP_READONLY=truetrước, đọc/odom,/scanđể hiểu robot rồi mới mở quyền publish/cmd_velDeveloper — kiến trúc code, cách thêm tool mới, chạy test với mock (không cần ROS)
11 tool: list_topics, list_nodes, list_services, get_topic_snapshot, publish_message, call_service, send_action_goal, cancel_action_goal, get_tf_tree, get_camera_image, get_connection_status. Bật ROSBRIDGE_MCP_READONLY=true để chặn mọi thao tác ghi (publish, action) khi làm việc với robot thật — các tool đọc (TF, camera, topic) vẫn hoạt động bình thường.
Tài liệu học kèm theo của tác giả: Robotics RL & UAV ebook — ebook về học tăng cường (reinforcement learning) và robot UAV.
Available Tools
11 toolscall_serviceA
Call any ROS service with JSON args and return the response values.
Rejected when ROSBRIDGE_MCP_READONLY is set, unless the service is on the fixed allowlist of known read-only /rosapi introspection services (topics, nodes, services, *_type, *_details, get_param, get_time, ...).
Args: service: Full service name, e.g. "/rosapi/topic_type" or "/reset_odometry". Discover names with list_services. args: JSON object matching the service request definition, e.g. {"topic": "/scan"} for /rosapi/topic_type. Default {}. timeout: Max seconds to wait for the response (default 10.0).
Returns {"service", "success": true, "values": {...}} on success, or {"service", "success": false, "error": "..."} on failure/timeout (with any related rosbridge status errors under "rosbridge_status").
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| service | Yes | ||
| timeout | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It explains readonly mode rejection, the return format (success vs failure with values/error/rosbridge_status), and that args are JSON. It does not explicitly flag potential side effects of calling a service, but given the generic nature, this is acceptable. The readonly note subtly suggests that some calls are destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written. The first sentence states the core purpose immediately, followed by a critical usage note, then a clean Args/Returns block. Every sentence adds unique value; no filler or repetition. Length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero annotations and zero schema-level descriptions, the tool description must stand alone. It covers: purpose, restricted-mode behavior, all three parameters (with defaults, format, examples), and the full return structure (success and failure cases). The presence of an output schema means return details are not required, but the description still enumerates them. Very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain parameters. It does: service name with example, args as JSON object with example defaults, timeout as seconds with default. This goes well beyond what the bare schema provides (which only lists types and defaults). No redundancy; all param info in description is additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb-resource pair: 'Call any ROS service with JSON args.' This precisely defines the action and target. It distinguishes from sibling tools (list_*, get_*, publish_message, send_action_goal) by focusing on service calling rather than introspection, publishing, or action management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool is rejected (readonly mode unless allowlisted) and suggests using list_services to discover service names. However, it does not directly compare against siblings like publish_message (which uses topics) or send_action_goal (actions), leaving the agent to infer the appropriate tool based on service vs topic vs action distinction. A clear 'Use this for calling services, not for topics or actions' would elevate to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cancel_action_goalA
Cancel a previously sent ROS 2 action goal.
Rejected when ROSBRIDGE_MCP_READONLY is set.
Args: action_name: The action the goal was sent to, e.g. "/navigate_to_pose". goal_id: The goal_id returned by send_action_goal.
Returns {"cancel_sent": true, "action", "goal_id"}. The cancellation outcome (status "canceled") is reported by the action server via the goal's result. Requires rosbridge_suite with ROS 2 action support; on an older rosbridge the tool returns an error advising an upgrade.
| Name | Required | Description | Default |
|---|---|---|---|
| goal_id | Yes | ||
| action_name | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description takes on the transparency burden. It discloses the cancellation request, the asynchronous nature of the outcome, and the return value. It also mentions version requirements. However, it does not cover edge cases like already-completed goals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the key purpose. It includes necessary details without redundancy. The structure is logical, though a slight trim could be possible without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no annotations, the description covers purpose, parameters, return value, and usage conditions. It is reasonably complete, though it could mention failure modes or prerequisites for the goal to be cancellable (e.g., goal must be active).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It does so effectively: action_name is described with an example, and goal_id is linked to the send_action_goal tool's return value. This adds significant meaning beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Cancel a previously sent ROS 2 action goal.' It uses a specific verb and resource, and distinguishes itself from sibling tools like send_action_goal, which is the complementary action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when the tool is rejected (when ROSBRIDGE_MCP_READONLY is set) and lists requirements (rosbridge_suite with action support). It provides context for use but does not explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_camera_imageA
Grab one frame from a camera topic, for vision-capable models.
Read-only — works in readonly mode. Subscribes to topic, waits for one sensor_msgs/msg/CompressedImage (preferred) or sensor_msgs/msg/Image (raw) message, and returns the frame as base64. This is the bridge for VLM / vision-language-action workflows: the model can literally look through the robot's camera before deciding how to act.
Args: topic: Camera topic, e.g. "/camera/image_raw/compressed". Prefer a compressed topic — raw images are large and may exceed the size limit below. timeout: Max seconds to wait for a frame (default 5.0, clamped to at most 30.0).
Returns {"topic", "format" (e.g. "jpeg"), "data_base64", "size_bytes"}, plus "width"/"height"/"encoding" for raw images. Frames larger than 4 MB are not returned: the tool responds with an error suggesting a CompressedImage topic instead (raw metadata is still included).
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | ||
| timeout | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses read-only nature, subscription behavior, message types (CompressedImage/Image), return format, size limit (4 MB), and error response behavior. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured with Args and Returns sections. Every sentence adds operational detail (size limits, raw image metadata, readonly mode), making it appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (subscription, timeout, size handling, output schema), the description covers all operational aspects including error conditions and return payload, making it complete. The output schema is described in prose, which is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions and 0% coverage, so the description fully compensates. It explains topic with an example and guidance, and timeout with default and max clamp. Additionally, it documents the return structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Grab one frame from a camera topic, for vision-capable models,' clearly stating the tool's function with a specific verb and resource. It distinguishes itself from sibling tools like get_topic_snapshot by emphasizing camera images and VLM workflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use: 'This is the bridge for VLM / vision-language-action workflows' and advises 'Prefer a compressed topic.' However, it does not explicitly name alternative tools or exclusionary criteria, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_connection_statusA
Report the current rosbridge connection status and readonly mode.
Takes no arguments. Returns {"url", "connected", "connected_since_unix", "active_subscriptions", "pending_service_calls", "readonly"}. The connection is opened lazily, so "connected" is false until another tool has been used. Check this first when other tools report errors.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the lazy connection behavior ('connected is false until another tool has been used') and lists the return fields. This adds significant behavioral context beyond a simple status check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and every sentence earns its place. The first sentence states the purpose, the second provides behavioral detail and usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, low complexity, and an output schema exists (though not shown), the description covers purpose, behavior (lazy connection), return fields, and usage guidance. It is fully complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds value by explaining the return fields and the lazy connection behavior, which goes beyond the empty schema. No parameter documentation is needed, but the description compensates by clarifying what the tool returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports the current rosbridge connection status and readonly mode. The verb 'report' and the resource 'connection status' are specific. It distinguishes from siblings like list_topics or publish_message, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit guidance: 'Check this first when other tools report errors.' This tells the agent when to use the tool. It also notes that the tool takes no arguments, which is helpful. While it doesn't explicitly state when not to use alternatives, the context of diagnostic ordering is valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_tf_treeA
Snapshot the robot's TF (coordinate transform) tree.
Subscribes briefly to /tf and /tf_static, merges every transform seen into a parent→child frame tree. Read-only — works in readonly mode. Useful for spatial reasoning: which frames exist (map, odom, base_link, camera, gripper, ...) and how they are connected.
Args: timeout: Seconds to listen for transforms (default 2.0, clamped to at most 10.0). Static transforms are latched and arrive immediately; dynamic ones need the robot to be publishing.
Returns {"frame_count", "frames": {child_frame: {"parent", "translation": {x,y,z}, "rotation": {x,y,z,w}, "source": "static"|"dynamic"}}, "tree": {parent: [children...]}, "roots": [frames with no parent seen]}. An empty tree usually means nothing publishes /tf on this robot (or the listen window was too short).
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It explains that the tool subscribes briefly to /tf and /tf_static, merges everything into a parent-child tree, and is read-only. It also notes that static transforms are latched while dynamic ones need publishing. This fairly comprehensively discloses behavior. It loses one point because it doesn't mention if it unsubscribes after the timeout or any potential blocking behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, a brief behavioral paragraph, a parameter section, and a detailed return value description. It is informative but not overly long. However, the return type description could be slightly more compact (e.g., the list of fields takes extra space). Still, every sentence earns its place. Minor deduction for lengthiness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite modest input schema (1 param, 0% coverage), the description is thorough. It explains the tool's behavior, the parameter semantics, the full return structure, and even includes a fallback ('empty tree means...'). The output schema exists and describes return fields, but the description adds context (e.g., what 'empty tree' means). The tool is simple (one param, one return), so the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only one parameter (timeout) with no description. The description adds significant meaning: the default is 2.0, it's clamped to at most 10.0, and it explains the semantics of listening duration in context of static vs dynamic transforms. This adds value beyond the schema. Baseline is 4 due to 0% schema coverage, and the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Snapshot' and a specific resource 'the robot's TF (coordinate transform) tree'. It clearly distinguishes itself from sibling tools like 'get_topic_snapshot', 'list_topics', and 'get_camera_image' by focusing on coordinate transforms and the robot's spatial structure, not just generic topics or images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: it says 'Useful for spatial reasoning: which frames exist... and how they are connected.' It implies when to use (when frame hierarchy is needed) and implicitly not to use for other sensor data. It does not name alternative tools but the sibling list and the purpose make it clear it's the only tree-snapshot tool. The mention of 'Read-only — works in readonly mode' is a usage hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_topic_snapshotA
Read live data from a topic: subscribe, collect up to count
messages (or until timeout seconds elapse), then unsubscribe.
Args: topic: Topic name including leading slash, e.g. "/scan" or "/odom". count: How many messages to collect (default 1, clamped to at most 100). Use more to observe a value changing over time. timeout: Max seconds to wait (default 5.0, clamped to at most 60.0). The tool never blocks longer than this, even on a silent topic. msg_type: Optional full message type, e.g. "sensor_msgs/msg/LaserScan". Usually omit it; rosbridge resolves the type of existing topics.
Returns {"topic", "requested", "received", "messages": [...], "timed_out", "timeout_s"}. If "timed_out" is true, nothing (or not enough) was published within the timeout — the topic may be silent, misspelled, or not exist. If the rosbridge connection drops mid-collection, the tool returns immediately with {"error", "connection_lost": true} instead of waiting out the timeout.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| topic | Yes | ||
| timeout | No | ||
| msg_type | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: subscribe-collect-unsubscribe lifecycle, clamping of count and timeout, never blocking longer than timeout, handling of connection loss, and return format including error fields. This exceeds the burden for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a header and parameter list, but it is slightly verbose in places (e.g., the return format could be prepended). However, every sentence is informative and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no annotations, and an output schema (though not provided in input, but the description lists return fields), the description is complete. It covers all parameters, behavior, edge cases, and return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description explains each parameter in detail: topic requires leading slash, count default and clamping, timeout behavior, and msg_type optionality. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Read live data from a topic: subscribe, collect up to `count` messages (or until `timeout` seconds elapse), then unsubscribe.' This uses a specific verb and resource, and distinctively separates it from siblings like list_topics, publish_message, and call_service.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance: 'Use more to observe a value changing over time' and explains when the tool may return empty (silent topic, misspelled, not exist). It does not explicitly compare to sibling tools, but the context is clear enough for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_nodesA
List all ROS nodes currently running on the robot.
Takes no arguments. Returns {"nodes": ["/talker", "/rosapi", ...]}. Useful to check whether an expected driver or controller is up.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states that the tool lists currently running nodes, returns a specific JSON structure, and takes no arguments. It does not mention potential side effects, permissions, or latency, but for a read-only list operation with no parameters, the given information is sufficient and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two complete sentences plus a short example. Every sentence provides value: the first states the purpose, the second details the return format and confirms no arguments, and the third adds a practical use case. Zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, a clear output schema, and a simple read-only purpose, the description is complete enough. It explains what the tool does, how to invoke it, what it returns, and when to use it. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since there are zero parameters and the schema has 100% coverage, the description adds clarity by explicitly stating 'Takes no arguments.' The baseline is 4 as per guidelines for 0 parameters, and no further parameter documentation is necessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'ROS nodes currently running on the robot'. It distinguishes from siblings like list_topics and list_services by specifying the resource type (nodes vs topics/services).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Takes no arguments' which clarifies invocation. It also provides a use case: 'Useful to check whether an expected driver or controller is up.' However, it does not explicitly state when NOT to use it or mention alternatives among the siblings, though the tool name itself is distinctive enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_servicesA
List all ROS services currently available on the robot.
Takes no arguments. Returns {"services": ["/reset_odometry", ...]}. Use before call_service to find the exact service name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It declares no arguments and specifies the return format (an object with a services array). While it doesn't explicitly state read-only behavior, listing services is inherently non-destructive. The example return value adds transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each essential: what it does, what it takes, and how to use it. No wasted words, front-loaded with the main purpose. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless tool with an output schema, the description covers purpose, usage, and return structure completely. The example service name and the hint to use before call_service provide full context for the agent to decide and invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameters (100% coverage by default). The description confirms 'Takes no arguments,' which adds no extra meaning but meets the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all ROS services currently available on the robot,' specifying both the verb (List) and the resource (ROS services). It effectively distinguishes from sibling tools like list_topics and list_nodes by naming the specific resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: 'Use before call_service to find the exact service name.' This tells the agent when to invoke this tool and hints at a workflow sequence, making the purpose and timing unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_topicsA
List all ROS topics currently known to the robot, with message types.
Takes no arguments. Returns {"topics": [{"name": "/scan", "type": "sensor_msgs/msg/LaserScan"}, ...]}. Call this first to discover what the robot exposes before subscribing or publishing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden of transparency. It explicitly states 'Takes no arguments' and describes the return format with an example, which is helpful for an AI. However, it does not mention side effects, rate limits, or access restrictions; a slight gap relative to a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, no wasted words. Each sentence contributes: the first explains the action, the second clarifies arguments and output, the third provides usage guidance. Perfectly front-loaded with the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple, parameter-less discovery tool with a nested output schema and the description already includes an example of the return format, nothing is missing. The context signals confirm zero parameters and 100% schema coverage, so the description is fully complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% description coverage (none needed), so baseline is 4. The description adds no parameter semantics (since none exist), but this is correct because there is nothing to add beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('all ROS topics') while distinguishing from sibling tools (e.g., list_nodes) by specifying the output includes message types. This fully clarifies the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use this tool ('Call this first to discover... before subscribing or publishing'), providing clear context. It does not explicitly exclude alternatives, but the guidance is strong enough for an AI to understand the primary use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
publish_messageA
Publish a JSON message to a ROS topic (advertises the topic first).
CAUTION: this can move a real robot. Rejected when ROSBRIDGE_MCP_READONLY is set. Prefer reading relevant sensor topics (e.g. /scan, /odom) before commanding motion, and publish zero velocity to stop.
Args: topic: Target topic, e.g. "/cmd_vel". msg_type: Full ROS 2 message type with the "/msg/" segment, e.g. "geometry_msgs/msg/Twist" or "std_msgs/msg/String". message: JSON object whose fields match the message definition, e.g. {"linear": {"x": 0.1, "y": 0.0, "z": 0.0}, "angular": {"x": 0.0, "y": 0.0, "z": 0.2}} for a Twist. Omitted fields default to zero/empty on the ROS side.
Returns {"published": true, "topic": ..., "type": ...} on success. The tool briefly waits for rosbridge 'status' errors after publishing; if rosbridge rejected the message (e.g. wrong msg_type), the result includes "rosbridge_warnings" — treat those as the publish having failed.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | ||
| message | Yes | ||
| msg_type | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It explains that the topic is advertised first, that the action is potentially destructive, that it waits briefly for rosbridge errors, and that failure results in rosbridge_warnings in the response. It also specifies the success return format. This is comprehensive and truthful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured: a core action sentence, a caution block, then Args and Returns sections. Every sentence serves a purpose. It is front-loaded with the essential information—the action and the safety warning—and no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 required parameters, nested objects, no schema descriptions, no provided output schema), the description is remarkably complete. It covers the purpose, usage precautions, parameter formats and defaults, behavioral notes (advertisement, error handling), and return values. The AI agent has all necessary information to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions for its three parameters. The description compensates fully with detailed Args: topic gets an example path, msg_type gets the required ROS 2 format with examples, and message gets a full JSON example plus the important note that omitted fields default to zero/empty. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Publish a JSON message to a ROS topic (advertises the topic first).' It immediately distinguishes this tool from its siblings, which are primarily read-only (list_topics, get_topic_snapshot, etc.), by emphasizing that it can move a real robot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage guidance: it warns that the tool can move a real robot, recommends reading sensor topics before commanding motion, advises publishing zero velocity to stop, and notes that it is rejected when ROSBRIDGE_MCP_READONLY is set. It could be more explicit about which sibling tools to use instead for reading (e.g., get_topic_snapshot), but the intent is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_action_goalA
Send a goal to a ROS 2 action server via rosbridge.
CAUTION: actions typically make the robot move (navigation, arm motion). Rejected when ROSBRIDGE_MCP_READONLY is set.
Args: action_name: Action name, e.g. "/navigate_to_pose". action_type: Full action type with the "/action/" segment, e.g. "nav2_msgs/action/NavigateToPose". goal: JSON object matching the action's goal definition. Default {}. timeout: Max seconds to wait for the result when wait_for_result is true (default 30.0, clamped to at most 120.0). wait_for_result: If true (default), block until the action finishes and return its result. If false, return the goal_id immediately — use cancel_action_goal with that id to stop the goal later.
Returns, when waiting: {"action", "goal_id", "success", "status", "status_text" (succeeded/aborted/canceled/...), "values" (result fields), "last_feedback" (most recent feedback values, or null)}. When not waiting: {"action", "goal_id", "result_pending": true}.
Requires rosbridge_suite with ROS 2 action support (ops send_action_goal / cancel_action_goal). Against an older rosbridge the tool detects the rejected operation (via rosbridge status errors, or timeout as fallback) and returns an error advising to upgrade rosbridge_suite on the robot.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | ||
| timeout | No | ||
| action_name | Yes | ||
| action_type | Yes | ||
| wait_for_result | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It thoroughly discloses: the tool causes robot movement, is blocked by READONLY mode, requires specific rosbridge_suite support, handles errors with older bridges, details return structures for both blocking and non-blocking modes, and explains timeout clamping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a brief purpose statement, a caution, parameter details with formatting, return value descriptions, and prerequisites. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description covers all essential aspects: purpose, parameters, return values, error scenarios, prerequisites, and practical usage notes. It is comprehensive and leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining each parameter: action_name with example, action_type with full type format, goal as JSON object, timeout with default and clamping, and wait_for_result with behavior implications.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The tool's purpose is clearly stated: 'Send a goal to a ROS 2 action server via rosbridge.' The caution about robot movement and the contrast with siblings like cancel_action_goal, call_service, and publish_message provide strong differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Some usage guidance is present: caution about robot movement, rejected when READONLY, and guidance on using cancel_action_goal when wait_for_result is false. However, there is no explicit comparison to sibling tools or advice on when to prefer this over other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
v0.2.0- First observed
call_service - First observed
cancel_action_goal - First observed
get_camera_image - First observed
get_connection_status - First observed
get_tf_tree - First observed
get_topic_snapshot - First observed
list_nodes - First observed
list_services - First observed
list_topics - First observed
publish_message - First observed
send_action_goal
TDQS
Scored across 11 tools
Each tool targets a distinct operation in the ROS ecosystem: listing resources, reading topic data, publishing, calling services, managing action goals, retrieving TF and camera data, and checking connection status. There is no overlap, and the descriptions clearly differentiate their purposes.
The tools follow a verb_noun pattern, but use a mix of verbs: 'list_' for discovery, 'get_' for retrieval, and 'publish_', 'call_', 'send_', 'cancel_' for actions. While all are descriptive and readable, the lack of a single unified prefix across all tools keeps it from being a perfect 5.
With 11 tools, the server is well-scoped for a ROS bridge interface. Each tool covers a distinct aspect of ROS interaction (topics, services, actions, TF, camera), and the number is neither too sparse nor overwhelming.
The tool surface covers core workflows: discovery, reading and writing topics, calling services, managing actions, and retrieving transforms and images. A minor gap is the lack of a dedicated tool to list available actions, but this can be partially achieved via list_services or documentation.
Maintenance
Related MCP Connectors
- alloyOAuthai.usealloy
Connect Claude, Cursor, Codex, and other AI tools to your robotics mission data.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Connect agents to 6DuckLearn memory, approvals, and runtime control.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables control of ROS/ROS2 robots through natural language commands by translating LLM instructions into ROS topics and services. Supports cross-platform WebSocket-based communication with existing robot systems without requiring code modifications.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI tools to interact with ROS2 robotics systems through natural language commands. Supports topic publishing/subscribing, service calls, message analysis, and auto-discovery of ROS2 interfaces for debugging and controlling robots.Mozilla Public 2.0
- AlicenseAqualityDmaintenanceEnables controlling robots in ROS environments through natural language, supporting topics, services, actions, and GUI tools.2436MIT
- AlicenseNot gradedqualityDmaintenanceEnables large language models to interact with ROS robots seamlessly, allowing natural language control, real-time sensor monitoring, and autonomous task execution without modifying existing robot code.Apache 2.0