The ROS2 MCP Gateway exposes 3 tools for interacting with ROS2 systems. While tool names follow the verb_noun pattern (get_, service_call_, action_call_), the definitions have critical gaps: parameter descriptions are minimal, output schemas are completely undocumented, and error handling guidance is absent. All three tools lack documentation of what they return, making it impossible for LLMs to plan downstream operations or understand result structure. The input schemas are present with basic type information, but lack constraints, enums, or detailed parameter descriptions. No tool indicates whether it is idempotent, read-only, or has side effects beyond the Risk metadata. Descriptions are terse (10-30 words) and do not explain WHEN to use each tool or what happens on failure.

• Add comprehensive output schema documentation for each tool. Example for get_latest_topic_tool: 'Returns {"message": <parsed ROS2 message as JSON>, "timestamp": <ISO8601 string>, "topic": <string>}'. This enables LLM to extract and chain fields.
• Expand tool descriptions to 50-200 characters. Include WHEN to use it (get_latest_topic_tool for a single message snapshot; subscribe if continuous updates needed), WHAT it returns, and action consequences. Example: 'Retrieves the most recent message from a ROS2 topic and returns it as JSON. Use this for one-time reads; for continuous updates, use a subscription service instead.'
• Document the 'arguments' parameter structure for service_call_tool. Create a helper discovery tool (e.g., 'describe_ros_service') that accepts a service_name and returns required/optional argument fields and their types. This avoids hardcoding ROS2 IDL schemas in the tool description.
• Document action feedback streaming. Add a parameter 'wait_for_result' (boolean, default=false) and clarify in description whether feedback is streamed via multiple responses or accumulated into a single result. If using MCP's progressive result pattern (input_required loop), explain that clearly.
• Add parameter constraints as descriptions. Example for topic_name: 'The ROS2 topic name (e.g., /robot/status). Must start with / and contain only alphanumeric characters and underscores. Avoid spaces and special characters.'
• Implement error handling with actionable recovery messages. Example: 'Topic "/invalid topic" not found (invalid character: space). Available topics: /robot/status, /robot/pose. Did you mean: /robot_status?'