Tool: look()

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/server.py
• pyproject.toml
• src/init.py
• LICENSE

The look() tool provides direct and precise control over the head positioning of the Reachy Mini robot. It is one of the seven core tools available in the MCP server, designed for scenarios where specific head orientation is required.

Unlike the more abstract show() tool, which expresses high-level emotions, look() offers granular control over the head's roll, pitch, yaw, and vertical position. This makes it suitable for tasks that require the robot to focus on a specific point or perform explicit head movements not covered by the predefined emotions.

Sources: README.md:14, src/server.py:35-43, 348-352

API Definition

The look() tool is exposed via the FastMCP server and can be called with five optional arguments to define the target head pose and movement duration.

Sources: src/server.py:345-359

Parameters

The function accepts floating-point values for orientation and timing. All angle values are in degrees. The input values are clamped to safe operational ranges to prevent mechanical strain.

Parameter	Type	Description	Safe Range	Default
roll	float	Tilt left/right. Positive = right ear to shoulder.	-45 to 45	0
pitch	float	Nod up/down. Positive = looking up.	-30 to 30	0
yaw	float	Turn left/right. Positive = looking right.	-90 to 90	0
z	float	Vertical offset. Positive = head higher.	-20 to 20	0
duration	float	Movement time in seconds.	0.1 to 5.0	1.0

Sources: README.md:14, src/server.py:354-365

Code Snippet

The look() tool is defined as a standard Python function decorated with @mcp.tool().

# File: src/server.py

@mcp.tool()
def look(
    roll: float = 0,
    pitch: float = 0,
    yaw: float = 0,
    z: float = 0,
    duration: float = 1.0
) -> str:
    """
    Direct head positioning in degrees.

    Use for precise control when express() doesn't fit.
    For most cases, prefer express() for cognitive simplicity.

    Args:
        roll: Tilt left/right (-45 to 45). Positive = right ear to shoulder
        pitch: Nod up/down (-30 to 30). Positive = looking up
        yaw: Turn left/right (-90 to 90). Positive = looking right
        z: Vertical offset (-20 to 20). Positive = head higher
        duration: Movement time in seconds (0.1 to 5.0)

    Returns:
        Confirmation
    """
    # Clamp values to safe ranges
    roll = max(-45, min(45, roll))
    pitch = max(-30, min(30, pitch))
    yaw = max(-90, min(90, yaw))
    z = max(-20, min(20, z))
    duration = max(0.1, min(5.0, duration))

    robot = get_robot()

    try:
        robot.goto_target(
            head=create_head_pose_array(z=z, roll=roll, pitch=pitch, yaw=yaw),
            duration=duration,
            method=get_interpolation_method("minjerk")
        )
        return f"Head positioned: roll={roll}°, pitch={pitch}°, yaw={yaw}°, z={z}"

    except Exception as e:
        return f"Movement failed: {e}"

Sources: src/server.py:345-388

Execution Flow

When the look() tool is called, it initiates a sequence of operations to translate the degree-based inputs into a physical robot movement.

The following diagram illustrates the internal logic of the look() function.

This diagram shows the process from receiving the tool call to returning a result.

1. Clamp Inputs: The roll, pitch, yaw, z, and duration values are clamped to their predefined safe ranges.
2. Get Robot Instance: The get_robot() helper ensures a connection to the ReachyMini instance is available, initializing it on the first call.
3. Create Pose Matrix: The create_head_pose_array() helper is called with the clamped z, roll, pitch, and yaw values to generate a 4x4 numpy transformation matrix required by the SDK.
4. Set Interpolation: The get_interpolation_method() helper is used to select the movement interpolation, which is hardcoded to minjerk for the look() tool.
5. Execute Movement: The robot.goto_target() method from the reachy-mini SDK is called with the head pose matrix, duration, and interpolation method.
6. Return Result: A success or failure message is constructed and returned to the caller.

Sources: src/server.py:367-388

Dependencies and Helper Functions

The look() function relies on several internal helpers and SDK functionalities to perform its task.

Sources: src/server.py

get_robot()

This function manages the connection to the robot. It uses lazy initialization, meaning it only connects to the Reachy Mini daemon on the first tool call that requires it. This avoids connection overhead if only non-robot tools are used.

Sources: src/server.py:180-201

create_head_pose_array()

This is a wrapper around the create_head_pose utility from the reachy_mini.utils module. It simplifies the process of creating the required 4x4 transformation matrix from simple degree-based roll, pitch, and yaw values.

Sources: src/server.py:211-224

get_interpolation_method()

This helper maps a string name (e.g., "minjerk") to an InterpolationTechnique enum from the SDK. The look() function consistently uses the "minjerk" method for smooth, jerk-minimized movements.

Sources: src/server.py:227-239, 381-385

Summary

The look() tool is a fundamental component for direct robotic control within the reachy-mini-mcp project. It provides a low-level, precise interface for head positioning, complementing the high-level, expressive show() tool. By taking simple degree-based inputs and handling the complexities of transformation matrices and SDK calls, it offers a powerful yet easy-to-use function for developers to make the robot perceive its environment in a directed manner.

Sources: README.md:14, src/server.py:348-352