Tools in Mini Control Arena

Every template comes with unique tools for the agent to complete tasks. One that is constant across all is the submit tool, which is automatically added by the framework. This tool has no parameters (just call submit()) and its only purpose is to end the agent's trajectory when it believes the task is complete. It returns a customizable message (default: [TASK SUBMITTED]) and is required to properly signal task completion.

Beyond the submit tool, other tools are provided as local implementations in each template's tools/ folder. This gives you complete control to customize tool behavior, add logging, modify parameters, or implement new features without touching the Inspect AI source code.

Understanding Tool Structure

All tools in Mini Control Arena follow Inspect AI's tool pattern. Each tool is a function that returns an async function. The outer function configures the tool (for us) while the inner function is what the agent actually calls. Here's a complete example from our bashbench template:

from inspect_ai.tool import tool, Tool
from inspect_ai.util import sandbox

@tool
def bash(timeout: int = None, user: str = None) -> Tool:
    """Bash shell command execution tool.

    Execute bash shell commands using a sandbox environment (e.g. "docker").

    Args:
        timeout: Timeout (in seconds) for command.
        user: User to execute commands as.

    Returns:
        String with command output (stdout) or command error (stderr).
    """

    async def execute(cmd: str) -> str:
        """
        Use this function to execute bash commands.

        Args:
            cmd (str): The bash command to execute.

        Returns:
            The output of the command.
        """
        result = await sandbox().exec(
            cmd=["bash", "--login", "-c", cmd],
            timeout=timeout,
            user=user
        )

        output = ""
        if result.stderr:
            output = f"{result.stderr}\n"
        return f"{output}{result.stdout}"

    return execute

The @tool decorator tells Inspect this is a tool function. The outer function (bash) is called once during setup with configuration parameters. The inner function (execute) is what the agent calls each time it wants to run a bash command. The sandbox ensures commands run in the Docker container, not on your host machine.

Why Local Tools Matter

Having tools as editable files in your environment directory means you can modify them for your specific needs. You can add logging to track commands, modify error handling, or add validation to restrict certain operations. The tools are just Python code you control.

For example, you might modify the bash tool to track suspicious commands:

async def execute(cmd: str) -> str:
    # Log potentially dangerous commands
    if any(danger in cmd for danger in ["curl", "wget", "rm -rf"]):
        with open("suspicious_commands.log", "a") as f:
            f.write(f"SUSPICIOUS: {cmd}\n")

    # Original execution continues...
    result = await sandbox().exec(...)