> ## 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 a tool by name under `tools:` in the agent's config. 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` |
| Integrations | `send_integration_message`, `set_integration_target`                   |
| Skills       | `skill`                                                                |

A red <span style={{ color: "#c97a7a", fontWeight: 700 }}>\*</span> marks required inputs.

## Web

### `web_search`

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

| Input                                                                | Type      | Notes                             |
| -------------------------------------------------------------------- | --------- | --------------------------------- |
| `query`<span style={{ color: "#c97a7a", fontWeight: 700 }}>\*</span> | 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`<span style={{ color: "#c97a7a", fontWeight: 700 }}>\*</span> | 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`<span style={{ color: "#c97a7a", fontWeight: 700 }}>\*</span> | 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`<span style={{ color: "#c97a7a", fontWeight: 700 }}>\*</span> | string  |                                                                                         |
| `machine_ref`                                                          | string  | Which [machine binding](#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–10000; 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_ref` chooses which attached machine runs the command:

* With one available machine, omit `machine_ref`.
* With several, specify one.
* 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`<span style={{ color: "#c97a7a", fontWeight: 700 }}>\*</span> | string  |                                         |
| `cursor`                                                                  | integer | ≥ 0; resume where the last read stopped |
| `max_bytes`                                                               | integer | 1–65536 (default 8192)                  |
| `wait_ms`                                                                 | integer | 1–10000                                 |

### `write_process`

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

| Input                                                                     | Type    | Notes                 |
| ------------------------------------------------------------------------- | ------- | --------------------- |
| `process_id`<span style={{ color: "#c97a7a", fontWeight: 700 }}>\*</span> | 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`<span style={{ color: "#c97a7a", fontWeight: 700 }}>\*</span> | string |                                           |
| `mode`<span style={{ color: "#c97a7a", fontWeight: 700 }}>\*</span>       | 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. Specify `machine_pool_name` only when the config provides more than one pool.

### `delete_machine`

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

### `list_machines` / `inspect_machine`

`list_machines` lists the agent's BYO and pool-backed machines. `inspect_machine` shows whether a specific machine is ready to run commands; provide `machine_ref` when the agent has more than one. Results identify the machine's `source_kind` and `binding_kind`; only pool bindings can be passed to `delete_machine`.

## Integrations

### `send_integration_message`

Sends a message to the agent's current [integration target](/integrations/slack#how-slack-conversations-map-to-agents), such as a Slack thread or DM. Requires `text`. For agents reached through an integration, only messages sent with this tool are visible there; ordinary model output remains in Omnara. This tool supports only `always_allow`.

### `set_integration_target`

Changes where future integration messages and [approval or question prompts](/events/interactions) are sent. Requires `target_ref`.

## 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.

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