Built-in Tools

ra ships with built-in tools that give the agent the ability to interact with the filesystem, run shell commands, make HTTP requests, spawn parallel sub-agents, and communicate with the user. When memory is enabled, additional memory tools are registered. All tools are registered automatically when builtinTools is enabled (the default).

Tools are self-describing — each includes a detailed schema and description so the model knows when and how to use them. You can further guide tool usage through system prompts or middleware.

# ra.config.yml
builtinTools: true   # default

When ra runs as an MCP server, all built-in tools (except AskUserQuestion) are automatically exposed as MCP tools.

Filesystem

Read

Read the contents of a file. Returns content with line numbers prefixed (e.g. 1: first line).

Parameter	Type	Required	Description
path	string	yes	Absolute or relative path to the file
offset	number	no	Start reading from this line number (1-based)
limit	number	no	Maximum number of lines to return

{ "path": "src/index.ts", "offset": 10, "limit": 20 }

Write

Create or overwrite a file. Parent directories are created automatically.

Parameter	Type	Required	Description
path	string	yes	Path to the file to write
content	string	yes	Content to write

{ "path": "src/hello.ts", "content": "export const hello = 'world'" }

Edit

Replace the first occurrence of a string in a file. The match must be exact, including whitespace and indentation.

Parameter	Type	Required	Description
path	string	yes	Path to the file to update
old_string	string	yes	Exact string to find
new_string	string	yes	Replacement string

{
  "path": "src/config.ts",
  "old_string": "const PORT = 3000",
  "new_string": "const PORT = 8080"
}

AppendFile

Append content to the end of a file. Creates the file and parent directories if they don't exist. Does not add any separator — include a newline in the content if needed.

Parameter	Type	Required	Description
path	string	yes	Path to the file
content	string	yes	Content to append

LS

List files and directories at a path. Directories have a trailing /. Does not recurse into subdirectories.

Parameter	Type	Required	Description
path	string	yes	Directory to list

Grep

Search for a text pattern across files recursively. Returns matches in path:line:content format. Skips node_modules and .git.

Parameter	Type	Required	Description
path	string	yes	Directory to search in
pattern	string	yes	Text to search for (plain string, not regex)
include	string	no	Filename glob filter, e.g. "*.ts"

{ "path": "src", "pattern": "TODO", "include": "*.ts" }

Glob

Find files matching a glob pattern. Supports *, **, and ?.

Parameter	Type	Required	Description
path	string	yes	Directory to search in
pattern	string	yes	Glob pattern, e.g. "**/*.test.ts"

MoveFile

Move or rename a file or directory. Creates parent directories at the destination.

Parameter	Type	Required	Description
source	string	yes	Current path
destination	string	yes	New path

CopyFile

Copy a file or directory. Directories are copied recursively. Creates parent directories at the destination.

Parameter	Type	Required	Description
source	string	yes	Path to copy from
destination	string	yes	Path to copy to

DeleteFile

Delete a file or directory. Directories are deleted recursively. Irreversible.

Parameter	Type	Required	Description
path	string	yes	Path to delete

Shell

ra registers a platform-specific shell tool based on the OS it's running on. Only one is available at a time.

Bash macOS / Linux

Execute a bash command and return combined stdout/stderr output. The description includes the detected OS (macOS or Linux).

Parameter	Type	Required	Description
command	string	yes	Bash command to execute
cwd	string	no	Working directory
timeout	number	no	Timeout in milliseconds (default: 30000)

{ "command": "git status", "cwd": "/home/user/project" }

PowerShell Windows

Execute a PowerShell command and return the output. Runs with -NoProfile for fast startup.

Parameter	Type	Required	Description
command	string	yes	PowerShell command to execute
cwd	string	no	Working directory
timeout	number	no	Timeout in milliseconds (default: 30000)

{ "command": "Get-ChildItem -Recurse -Filter *.ts" }

Network

WebFetch

Make an HTTP request and return the response as JSON with status, headers, and body fields.

Parameter	Type	Required	Description
url	string	yes	URL to fetch
method	string	no	HTTP method (default: GET)
headers	object	no	Request headers as key-value pairs
body	string	no	Request body

{
  "url": "https://api.example.com/data",
  "method": "POST",
  "headers": { "Authorization": "Bearer token" },
  "body": "{\"key\": \"value\"}"
}

Agent Interaction

AskUserQuestion

Pause the agent loop and ask the user a question. The loop suspends until the user responds.

• REPL — the question is printed and the next input resumes the conversation
• CLI — the session ID is printed so the user can resume with --resume
• HTTP — an AskUserQuestion SSE event is emitted with the question and session ID

Parameter	Type	Required	Description
question	string	yes	Question to ask the user

This tool is not exposed via MCP since MCP clients manage their own user interaction.

TodoWrite

Track tasks with a checklist. The tool description dynamically updates to show remaining items and their indices, keeping the model aware of progress without needing to call list.

Actions:

Action	Parameters	Description
add	item (string)	Add an item to the checklist
check	index (number)	Mark an item as done (0-based)
uncheck	index (number)	Mark an item as not done
remove	index (number)	Remove an item
list	—	Show all items with status

{ "action": "add", "item": "Write tests" }
{ "action": "check", "index": 0 }
{ "action": "list" }

The dynamic description looks like:

Track tasks with a checklist. Actions: "add" (item text), "check"/"uncheck"/"remove" (by 0-based index), "list" (show all). Remaining (2/3): 1: Fix bug, 2: Deploy

Parallelization

Agent

Fork parallel copies of the agent to work on independent tasks simultaneously. Each fork inherits the parent's model, system prompt, tools, and thinking level — it's the same agent with a fresh conversation.

Parameter	Type	Required	Description
tasks	array	yes	Tasks to run in parallel
tasks[].task	string	yes	The task prompt for the fork

{
  "tasks": [
    { "task": "Read src/auth.ts and summarize the authentication flow" },
    { "task": "Find all TODO comments in the codebase" },
    { "task": "Check for unused exports in src/utils/" }
  ]
}

Returns { results, usage } where each result has task, status, result, iterations, and usage. Aggregate usage rolls up into the parent's token tracking automatically.

Only AskUserQuestion and Agent are excluded from forks — AskUserQuestion can't work from a background fork, and Agent nesting is depth-limited (default: 2) to prevent infinite recursion. All other tools (including memory) are inherited. Task failures don't affect siblings.

Forks honor the parent's maxIterations. Use maxConcurrency (default: 4) to control how many forks run in parallel.

MCP

When MCP clients are configured, all MCP tools are registered with server-prefixed names (github__search) to avoid conflicts. When mcp.lazySchemas is enabled (the default), schemas are additionally stripped — on the first call to each tool, ra returns the full schema as an error, and the model retries with correct parameters. See MCP for details.

Memory

When memory is enabled, three additional tools are registered.

memory_save

Save a fact to persistent memory for future conversations. Proactively saves user preferences, project decisions, corrections, and key context. To update an existing memory, the agent forgets the old version first, then saves the new one.

Parameter	Type	Required	Description
content	string	yes	Self-contained fact, e.g. "User prefers tabs over spaces"
tags	string	no	Category: preference, project, convention, team, or tooling

memory_search

Search persistent memories by keyword. Recent memories are automatically injected at conversation start — this tool is for targeted lookups beyond the recalled set.

Parameter	Type	Required	Description
query	string	yes	Full-text search keywords, e.g. "typescript tabs" or "deployment"
limit	number	no	Max results (default: 10)

memory_forget

Delete memories matching a search query. Used when the user corrects previous information, a fact becomes outdated, or before saving an updated version of an existing memory.

Parameter	Type	Required	Description
query	string	yes	Search keywords to match memories to delete
limit	number	no	Max memories to delete (default: 10)

Disabling built-in tools

To run ra without built-in tools (e.g., when using only MCP tools):

builtinTools: false

ra --no-builtin-tools

See also

• The Agent Loop — how tools are executed within the loop
• Middleware — beforeToolExecution and afterToolExecution hooks
• MCP — connecting external MCP tools