> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Built-in tools

> Use built-in tools for web search, commands, machines, integrations, and more

Omnara includes built-in tools for common agent tasks. Add ordinary tools by name under `tools:` in the agent's config. Integration tools use names such as `int__engineering__post_message` and the credentials of that project [integration](/integrations/overview). Built-in tools default to `always_allow`, but you can [change the permission](/tools/permissions) for each one.

This page explains what each tool does and the inputs it accepts. To retrieve the current catalog programmatically, use [`GET /tool-catalog`](/tools/permissions#check-available-tools).

The tools are grouped by what they do:

| Group | Tools |
| - | - |
| Web | `web_search`, `web_fetch` |
| Questions | `ask_question` |
| Commands | `run_command` |
| Processes | `read_process`, `write_process`, `stop_process`, `list_processes` |
| Machines | `create_machine`, `delete_machine`, `list_machines`, `inspect_machine` |
| Files | `list_files`, `upload_file`, `download_file`, `read_file`, `search_files`, `write_file` |
| Integrations | Integration-specific tools; `list_interaction_handlers`, `set_interaction_handler` |
| Skills | `skill` |
| Tool loading | `tool_search` |

A red \* marks required inputs.

## Web

### `web_search`

Searches the public web and returns matching URLs, titles, and snippets.

| Input | Type | Notes |
| - | - | - |
| `query`\* | string | |
| `num_results` | integer | 1–20; default 5 |
| `recency` | enum | `day`, `week`, `month`, `year` |
| `domains` | string\[] | Restrict results to these domains |

### `web_fetch`

Fetches a public HTTP or HTTPS URL and returns readable content as Markdown or plain text. It cannot access `localhost` or private networks. To reach a service on an attached machine, use `run_command` with `curl`.

| Input | Type | Notes |
| - | - | - |
| `url`\* | string | |
| `format` | enum | `markdown` (default), `text` |
| `timeout_seconds` | integer | 1–120; default 30 |

## Questions

### `ask_question`

Asks a person one or more multiple-choice questions. The agent pauses until the resulting [interaction](/events/interactions) is answered. Omnara automatically adds an **Other** option for free-text responses.

| Input | Type | Notes |
| - | - | - |
| `questions`\* | array | Min 1. Each item requires `prompt` and `options`; each option requires `label`. `multiple` defaults to false. |

## Commands

### `run_command`

Runs a shell command on a [machine attached to the agent](/machines/overview#bindings-how-an-agent-holds-a-machine).

| Input | Type | Notes |
| - | - | - |
| `command`\* | string | |
| `machine_id` | string | Public ID (`mch_...`) of the [machine](#picking-a-machine) to use; omit when the agent has exactly one |
| `shell` | enum | `default`, `sh`, `bash`, `zsh`, `pwsh`, `powershell`, `cmd` |
| `cwd` | string | Overrides the binding's working directory |
| `wait_ms` | integer | 1–300000; how long to wait for early output or exit before returning |
| `io_mode` | enum | `pipe` (default) or `pty` |

Every command returns a `process_id` (`prc_…`). `wait_ms` controls how long `run_command` waits for the command to finish before returning. If it finishes in time, the result includes its output:

```json theme={null}
{
  "process_id": "prc_rwz3jehcyd5n6a2bfgik7mv4qt",
  "state": "exited",
  "command": "git log -1 --format=%H",
  "output": "8c41d2e9f0a3b7c6d5e4f3a2b1c0d9e8f7a6b5c4\n",
  "done": true,
  "exit_code": 0
}
```

If the command is still running after `wait_ms`, the tool returns `"state": "running"`. The agent can then read its output, send input, or stop it with the process tools below.

Set `run_command` to `always_ask` to require approval before execution. The prompt shows the command, machine, shell, and working directory.

### Picking a machine

`machine_id` chooses which attached machine runs the command:

* With one available machine, omit `machine_id`.
* With several, pass the public `machine_id` (`mch_...`) returned by `list_machines`.
* With none, attach a machine in the [config](/agents/configuration#machines) or use [`create_machine`](#create_machine).

If Omnara cannot choose a machine, the tool returns an error to the agent so it can inspect its machines and retry.

## Processes

Use these tools to follow or control commands that are still running. A process moves from `starting` to `running`, then ends as `exited`, `failed`, or `killed`.

### `read_process`

Reads process output from a byte cursor and can briefly wait for new output.

| Input | Type | Notes |
| - | - | - |
| `process_id`\* | string | |
| `cursor` | integer | ≥ 0; resume where the last read stopped |
| `max_bytes` | integer | 1–65536 (default 8192) |
| `wait_ms` | integer | 1–300000; returns as soon as output arrives or the process exits. |

### `write_process`

Sends input to a running process or closes its standard input.

| Input | Type | Notes |
| - | - | - |
| `process_id`\* | string | |
| `data` | string | Max 128 KiB per write |
| `close_stdin` | boolean | Pipe mode only |

### `stop_process`

Interrupts a process gracefully or terminates it. Repeating the call after the process has stopped is safe.

| Input | Type | Notes |
| - | - | - |
| `process_id`\* | string | |
| `mode`\* | enum | `interrupt` (SIGINT-style) or `terminate` |

### `list_processes`

No inputs. Returns the agent's active processes with their state, command label, and working directory.

### When machines misbehave

Agents remain observable when machine state changes:

* **The machine disconnects** — the agent can wait for it to reconnect or continue elsewhere. Retained output and process state remain available.
* **Output exceeds retention** — `read_process` returns `truncated: true` when older output has been dropped. For large output, write it to a file and read only what you need.
* **The machine is deleted** — its processes end and its binding is released.

## Machines

These tools let an agent inspect its BYO and pool-backed machines, and create or delete pool-backed machines. Its [config](/agents/configuration#machines) and [machine or pool grants](/machines/overview#who-may-use-a-machine) determine which machines it can use and how many pool-backed machines it can create.

### `create_machine`

Creates a machine from an available pool. Use `list_machines` to discover pools, then pass the selected `machine_pool_id`. You can omit the ID when only one pool is available. Pool names are for display; renaming a pool does not change which pool an ID selects. Optional `cpu` and `memory_mb` override the defaults where supported, within pool and project limits.

### `delete_machine`

Deletes a pool-backed machine. Requires `machine_id`.

### `list_machines` / `inspect_machine`

`list_machines` lists the agent's BYO and pool-backed machines, plus pools from its config that have an active project grant. Pools are included even when they have no machines yet. Each pool includes its `machine_pool_id`, `machine_pool_name`, and configured description. Pools also expose supported resource overrides, effective defaults, and CPU/memory limits.

`inspect_machine` shows whether a specific machine is ready to run commands; provide `machine_id` when the agent has more than one. Machine results include `cpu` and `memory_mb` when known, identify `source_kind` and `binding_kind`, and include `machine_pool_id` for pool-backed machines. Only pool bindings can be passed to `delete_machine`.

When `list_machines` returns `next_cursor`, pass it as `cursor` in the next call to continue listing. Pools are listed first, followed by machines. If `list_machines` is disabled, provide the agent with any needed pool IDs, supported resource overrides, and limits in its instructions.

## Files

`path` addresses files stored in Omnara, not files on an attached machine. `/artifacts` is the destination for creating an artifact, `/artifacts/<artifact_id>` identifies an existing artifact, and `/memory/<store-name>/<file-path>` identifies a file in an [attached memory store](/agents/configuration#memory-stores).

When compiling a config with enabled tools or MCP servers, Omnara adds missing `list_files`, `read_file`, and `search_files` entries to the compiled config, leaving the source unchanged. Attaching a memory store also adds these retrieval tools; a `read_write` attachment adds `write_file`. Explicit tool permissions and `enabled: false` settings take precedence. These tools do not require an attached machine. Integration-contributed tools are compiled with the config too.

### `list_files`

Lists matching files and directories without reading their contents.

| Input | Type | Notes |
| - | - | - |
| `pattern`\* | string | Path pattern under literal `/memory` or `/artifacts`; globs are allowed only below the root |
| `limit` | integer | 1–100; default 50 |
| `cursor` | string | `next_cursor` from the previous result; keep the same pattern |

Use `/artifacts/*` for the agent's artifacts, `/memory/*` for attached stores and their descriptions, or `/memory/**` to list paths across attached stores recursively. For example, `/memory/engineering/**/*.md` finds Markdown files across directories. `*` matches within a path segment, `**` spans directory levels, and `?` matches one character.

Artifact patterns such as `/artifacts/*.pdf` match filenames and return `/artifacts/<artifact_id>` paths for reading or downloading. An exact `/artifacts/<artifact_id>` selects one artifact; wildcards match filenames, not IDs, and a filename can match multiple artifacts. Artifacts are ordered newest first and include creation time and content type. Results include hidden entries. Continue with `next_cursor` until it is `null`; narrow the pattern if the listing exceeds its resource limit.

### `upload_file`

Use `upload_file` to copy a file from an attached machine into Omnara. Uploads to `/artifacts` create artifacts, making files such as generated PDFs, images, or reports available for the user to view or download. Set `path` to `/artifacts` or `/memory/<store-name>/<file-path>` and pass the regular machine file's relative, absolute, or `~`-relative path as `source`; provide `machine_id` when the agent has more than one machine.

Files may be up to 10 MiB. Artifacts must be non-empty; memory files may be empty. The upload process has a 30-second execution timeout.

On success, an artifact appears in the conversation and the durable tool result contains its `path`, `digest`, and a `media_ref` that clients can use to display or download it. The returned `path` can be passed directly to `download_file`; `source` and `destination` refer to paths on the selected machine. The artifact's contents are not added to later model context. To deliver artifacts through an integration, use its qualified posting tool, such as `int__engineering__post_message`, and follow its attachment schema.

A memory upload requires write access and returns its `path` and `digest`. Omit `expected_digest` to create a file, or pass its current digest to replace changed content. On conflict, read or download the latest file and reapply your changes before retrying. Uploading identical contents succeeds without changing the file, even with a stale digest. Artifacts do not accept `expected_digest`.

### `download_file`

Use `download_file` to copy a file stored in Omnara to an attached machine. Downloads support `/artifacts/<artifact_id>` and `/memory/<store-name>/<file-path>`; provide `machine_id` when the agent has more than one machine.

Set `path` to the stored file's path and `destination` to the exact machine file path. Relative and `~`-relative destinations are supported, the parent directory must already exist, and an existing destination is replaced atomically. Downloads return the file's `digest` on completion; use it when uploading an edited memory file.

The download process has a 120-second execution timeout.

### `read_file`

Reads a text or image file at `/artifacts/<artifact_id>` or `/memory/<store-name>/<file-path>`. Text must be UTF-8 without NUL bytes. Artifacts may be up to 48 MiB; memory files may be up to 10 MiB. Readability is determined from the file's bytes, regardless of its declared content type. PNG, JPEG, GIF, and WebP images are returned for the model to view, with `path`, `content_type`, `size_bytes`, and `digest` instead of paging fields; paging inputs are still validated but don't apply to images.

Memory images are preserved as immutable artifacts when read and appear in the agent's artifact listings.

| Input | Type | Notes |
| - | - | - |
| `path`\* | string | Exact artifact or memory file path |
| `offset_line` | integer | ≥ 1; default 1 |
| `limit_lines` | integer | 1–200; default 100 |
| `offset_char` | integer | ≥ 0; default 0 in character mode; counts Unicode code points |
| `limit_chars` | integer | 1–4096; default 512 in character mode |
| `expected_digest` | string | Optional digest precondition; use the first page's digest when continuing a memory read. Unnecessary for immutable artifacts. A mismatch returns a conflict; restart the read. |

Reading defaults to line mode. Supplying either character input selects character mode; do not combine line and character inputs. Each text response contains at most 4 KiB of file text, together with `size_bytes`, `content_type`, the whole-file `digest`, and `has_more`.

When `has_more` is true, continue using the returned `next_offset_line` or `next_offset_char`. A line longer than one page returns its first chunk and a character offset; switch to character mode to continue. Reading past the end returns empty content with `has_more: false`.

### `write_file`

Creates or edits a memory text file in a writable store attached with `read_write` access. Returns `path` and `digest`.

| Input | Type | Notes |
| - | - | - |
| `path`\* | string | Exact `/memory/<store-name>/<file-path>` destination |
| `content` | string | Text to create or replace the file with; empty text is allowed |
| `script` | string | GNU sed script using extended regex, at most 64 KiB; transforms an existing file |
| `append` | boolean | Append `content` exactly, without adding a newline; default false. Creates missing files. |
| `expected_digest` | string | Current digest when changing an existing file; omit to create |

Supply exactly one of `content` or `script`; `append` only applies to `content`. Text must be UTF-8 without NUL bytes, at most 10 MiB. Scripts cannot read other files, write files, or run commands, and run with resource limits. Concurrent edits cause a conflict; read the file again before retrying.

### `search_files`

Searches text in one artifact or in memory files matching a path or glob. Binary files may be skipped when searching with a glob.

| Input | Type | Notes |
| - | - | - |
| `path`\* | string | For artifacts, one exact `/artifacts/<artifact_id>` path. For memory, an exact file path or a glob such as `/memory/notes/**/*.md`. |
| `args`\* | string\[] | Ripgrep options and `-e` patterns; for example `["-i", "-C", "2", "-e", "deploy"]` |
| `limit` | integer | 1–100 entries across all files; default 20 |
| `offset_line` | integer | Starting line, default 1; only for exact-file content searches |

Supported options are `-e` (repeatable patterns), `-F` (literal), `-i` (ignore case), `-w` (whole word), `-x` (whole line), `-v` (invert), `-U` (multiline), `-l` (matching paths), `-c` (counts), and `-A`/`-B`/`-C` (0–5 context lines). Patterns total at most 1024 UTF-8 bytes. Other options and file operands are rejected.

Content results are a sequence of match and context records with paths, original line numbers, and bounded snippets. Context does not count toward `limit`; counts in `-c` results are not capped by it. Context may be cut off at the response limit. Narrow the query when truncated.

### Large tool results

For `web_fetch`, `web_search`, `skill`, MCP tools, and custom tools, results containing text or structured data trigger overflow handling when their serialized content exceeds 50 KiB. Omnara saves the oversized content as a text or JSON artifact and returns its `path`, a preview of up to 8 KiB, `size_bytes`, `content_type`, and `truncated: true`. Saved overflow artifacts are limited to 48 MiB.

The overflow marker's `truncated` field describes the shortened inline preview. In `web_fetch` metadata, `truncated` reports whether the upstream extractor shortened the fetched content; it can be `false` even when the overflow marker is `true`.

For example, a large `web_fetch` result provides an `/artifacts/<artifact_id>` path. The agent can search that path for a phrase with `search_files`, then read the surrounding lines with `read_file`. Visible overflow artifacts also appear as downloadable attachments in the conversation. Hidden results remain hidden.

Explicitly disabling both retrieval tools does not disable overflow handling. The agent still receives the preview and path, but cannot use these tools to retrieve the saved content.

Existing media references remain inline so their attachments remain available to the model and clients. Consequently, 50 KiB is an overflow threshold, not a hard limit on the rewritten result: many retained media references can still exceed it. Media-only results are not offloaded.

## Integration tools

Select [integration tools](/integrations/overview) by qualified name, such as
`int__engineering__post_message`. An integration owns its credentials and defines its
tools' argument schemas and conversation requirements. Credential access, live integration
state and ordinary permission govern
execution. Ordinary model output remains in Omnara.

Subscriptions control incoming forwarding independently of enabled tools. Manage
them from the integration's [Conversations list or subscriptions API](/integrations/overview#stop-forwarding).

### `list_interaction_handlers` / `set_interaction_handler`

Select these tools explicitly under `tools`, or use an integration launcher that supplies
an interaction handler and adds them, preserving explicit tool settings. They
are not global defaults.
`list_interaction_handlers` accepts `cursor` and `limit`, returning handler keys,
descriptions, eligible destinations and argument schemas. Its current selection is included
independently of pagination. No eligible handlers means an empty list.

`set_interaction_handler` takes a `handler` key and `args` matching its schema.
An integration may infer the destination from its agent state; in that case its
schema accepts empty arguments. Use `{"handler":null,"args":{}}` for dashboard only.
Pass `auto_select: false` to pin the choice, or `true` to enable automatic selection;
omitting it preserves the current mode. In automatic mode, the last eligible content input
admitted to a turn selects its handler, or clears the choice if none applies. Dashboard
and API messages therefore select dashboard-only delivery. Internal agent reports/messages
and ordinary cron instructions preserve selection. An explicit integration origin takes
precedence over that exception, including a scheduled integration thread's initial input.
Existing prompts keep their captured destination. Both tools report the current
automatic-selection mode.

## Subagents

These tools are added automatically when the config declares [`subagents`](/agents/configuration#subagents). Each subagent is an ordinary agent with a `parent_agent_id`.

### `spawn_agent`

Starts a subagent from a configured `subagents` key with a clean context. Requires `agent` (the key) and `task`; `name` is an optional display label. Returns immediately with the subagent's `agent_id`, which the other subagent tools take. The subagent's final answer arrives later as a message from it.

### `read_agent`

Reads a subagent's timeline by `agent_id` in the same shape as the [turns API](/api-reference/endpoints/events/list-turns). Without `turn_id` it returns the newest turns first, each with its opening events and latest event; `before_turn_sequence` pages older turns and `limit` defaults to 10. With `turn_id` it returns that turn's events, newest first; `before_sequence` pages older events and `limit` defaults to 20. Each result carries `next_before_turn_sequence` or `next_before_sequence` for the next page.

### `send_agent_message`

Delivers `message` to the subagent identified by `agent_id` as a steering input. The subagent reads it once its current model call and tool batch finish, so running work is not stopped, but any open question or permission request is canceled. Parents cannot answer a subagent's questions; those wait for a human. The reply arrives as a message from the subagent.

### `stop_agent`

Cancels the current work of the subagent identified by `agent_id` and leaves it idle, so `send_agent_message` can resume it later. With `archive: true` it also archives the subagent and its descendants, after which it can no longer be messaged.

### `list_agents`

Lists the agent's subagents with their `agent_id`, name, key, state, and last activity.

## Skills

### `skill`

Loads an attached skill. Requires its [skill](/tools/skills) `name`. The tool returns the skill's instructions and, when the agent has machines, installs its supporting files there.

## Tool loading

### `tool_search`

Added automatically when any tool is [deferred](/agents/configuration#deferred-tools). Searches deferred tools by name, description, and argument names, and loads the matches so the model can call them.

| Input | Type | Notes |
| - | - | - |
| `pattern`\* | string | Case-insensitive regular expression, at most 200 characters |
| `max_results` | integer | 1–50; default 5 |

> [!NOTE]
>
> Full inputs and defaults, live from your deployment: [Get tool catalog](/api-reference/endpoints/configs-and-profiles/get-tool-catalog).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.