Built-in Tools

Every noumen agent has access to a set of built-in tools registered in the ToolRegistry. The nine core tools (ReadFile, WriteFile, EditFile, Bash, Glob, Grep, WebFetch, NotebookEdit, AskUser) are always available. Additional tools are enabled through Agent options — subagents, tasks, plan mode, worktrees, LSP, web search, and skills each add their own tools when enabled.

All tools delegate file and shell access through the sandbox (VirtualFs and VirtualComputer), so isolation is controlled entirely by which sandbox you provide.

Tool reference

File I/O

Search

Execution

Web

Agent & Interaction

Task Management

Planning & Worktrees

Code Intelligence

Enabling optional tools

Core tools (ReadFile, WriteFile, EditFile, Bash, Glob, Grep, WebFetch, NotebookEdit, AskUser) are always registered. Other tools require enabling their feature in Agent options:

const code = new Agent({
  provider,
  sandbox,
  options: {
    enableSubagents: true,    // adds Agent tool
    enableTasks: true,        // adds TaskCreate, TaskList, TaskGet, TaskUpdate
    enablePlanMode: true,     // adds EnterPlanMode, ExitPlanMode
    enableWorktrees: true,    // adds EnterWorktree, ExitWorktree
    lsp: { ... },             // adds LSP tool (pass Record<string, LspServerConfig>)
    skills: [...],            // adds Skill tool when skills are configured
    webSearch: { ... },       // configures the WebSearch tool backend
    toolSearch: true,         // adds ToolSearch for on-demand tool discovery
    streamingToolExecution: true, // execute tools as they arrive during model streaming
  },
});

These flags are opt-in rather than on by default for two reasons: each additional tool increases the token cost of every request, and exposing a capability means the model may use it even when a simpler approach would suffice. See each feature's docs page for specifics.

Tool search

When toolSearch is enabled, tools marked as deferred (MCP tools by default, plus any tool with shouldDefer: true) are hidden from the model's tool definitions. Instead, a ToolSearch tool is added that lets the model discover and load deferred tools on demand. This fundamentally changes how the agent sees its tool set — tools it would normally use directly become invisible until explicitly searched for — so it's off by default.

Streaming tool execution

When streamingToolExecution is enabled, the agent begins executing concurrency-safe tools as soon as their arguments finish streaming from the model, rather than waiting for the model's entire response to complete. This can reduce latency when the model requests multiple independent tool calls in a single turn. It's off by default because it changes execution ordering: tools may start running while the model is still generating, which can be surprising if you rely on observing the full model response before side-effects occur.

File state cache (read-before-edit)

The file state cache tracks which files the model has read and enforces that it must read a file before editing it. When enabled, EditFile and WriteFile will reject edits to files the model hasn't seen via ReadFile, preventing hallucinated edits on unseen content.

options: {
  fileStateCache: {
    enabled: true,
    maxEntries: 100,                  // max cached file entries (default)
    maxBytes: 25 * 1024 * 1024,      // 25 MB total cache size (default)
  },
}

The cache is an LRU store that records file contents and modification times at the point of each read. This is opt-in because it introduces a hard constraint on tool execution order — the model must explicitly read every file it wants to edit, which can cause edit attempts to fail if the model skips the read step. Without this option, edits proceed unconditionally.

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

Read-only tools marked with isConcurrencySafe can run in parallel within a single turn. The orchestration layer automatically partitions tool calls into concurrent and serial batches.

See Custom Tools for how to add your own tools.