Built-in Tools

Every noumen agent has access to six built-in tools. These are automatically registered in the ToolRegistry and available to the AI model during agent runs. All tools delegate file and shell access through VirtualFs and VirtualComputer — they never touch the host directly — so the isolation level is controlled entirely by which implementations you provide.

Tool reference

ReadFile

Reads a file and returns its contents with line numbers. Supports offset and limit parameters for reading specific line ranges.

// Parameters
{
  file_path: string;  // Path to read
  offset?: number;    // Starting line (1-based)
  limit?: number;     // Number of lines to return
}

WriteFile

Creates or overwrites a file. Parent directories are created automatically.

// Parameters
{
  file_path: string;  // Path to write
  content: string;    // File contents
}

EditFile

Performs exact string replacement within a file. The old_string must appear exactly once in the file.

// Parameters
{
  file_path: string;   // Path to edit
  old_string: string;  // Text to find (must be unique)
  new_string: string;  // Replacement text
}

Bash

Executes a shell command and returns stdout, stderr, and exit code.

// Parameters
{
  command: string;     // Shell command to run
  timeout?: number;    // Timeout in milliseconds
}

Glob

Finds files matching a glob pattern. Uses ripgrep for fast recursive search.

// Parameters
{
  pattern: string;  // Glob pattern (e.g., "**/*.ts")
  path?: string;    // Directory to search in
}

Grep

Searches file contents by regular expression. Uses ripgrep for speed.

// Parameters
{
  pattern: string;     // Regex pattern
  path?: string;       // Directory or file to search
  include?: string;    // File pattern filter (e.g., "*.ts")
}

How tools work

During an agent run, the model can request tool calls. The Thread's agent loop:

1. Sends available tool definitions to the model
2. Receives tool call requests from the model's response
3. Executes each tool via the ToolRegistry
4. Sends tool results back to the model
5. Repeats until the model produces a final text response

See Custom Tools for how to add your own tools.