improve documentation of rai tool-calling or simplify internal ros communication

[boczekbartek]

Is your feature request related to a problem? Please describe.
rai currently has multiple levels of tools.

1. Generic tools that call ros2 topics/services/actions
2. Specialized tools (like nav2 tools or open-set detection tools) that implement their own node
3. Different types of tools attached to RaiNode are handled differently due to dedicated node spinning (rclpy.spin) implementation and to avoid deadlock. Tools that connect to topics are handled using different node to tools that call services and actions.

Describe the solution you'd like
Such dedicated implementations should be documented so that developer knows on which level a new tool should be implemented.

Describe alternatives you've considered

• Implement general solution so that tool type choice is not important from the higher level developer-facing API. This solution would be better but requires more time.
• a solution might be to use CallbackGroups and MultiThreadedExecutor: https://discourse.ros.org/t/how-to-use-callback-groups-in-ros2/25255

Additional context

Pseudo-code with high-level overview of the issue

# Node for topic subscription
class TopicSubNode(rclpy.node.Node):
    def __init__(self):
        self.subscriber = self.create_subscription(..., callback=self.callback)
    
    def callback(self,msg):
        # handle msg

def run_node_with_subscription():
    rclpy.init()

    node = TopicSubNode()
    rclpy.spin(node)

# Node for service calling 
class SrvClientNode(rclpy.node.Node):
    def __init__(self):
        ... 
        self.client = self.create_client("/some_service")

    def call_service(self):
        future = self.client.call_async(...)
        rclpy.spin_until_future_complete(self, future)

def run_srv_node():
    rclpy.init()
    node = SrvClientNode()
    # cannot spin here
    node.call_service()


# If 1 node handles service and topic - spin and spin_until_future_complete can deadlock / unexpected behavior