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

# Tools & permissions

> Control which tools an agent can use and which calls require approval

Tools let an agent search the web, run commands, call external services, and more. An agent can use only the tools listed in its current [config](/agents/configuration). Changing that set requires an explicit [config update](/events/sending-input#change-the-config-mid-conversation), so you can always see exactly what the agent has access to.

Omnara has exactly three kinds of tools, distinguished by *who executes them*:

| Kind | Executed by | Declared as | Default permission |
| - | - | - | - |
| **Built-in** | Omnara | A name from the [built-in set](/tools/built-in), e.g. `web_search` | `always_allow` |
| **MCP** | A [Model Context Protocol](https://modelcontextprotocol.io) server you point at | An entry under `mcp:`, exposed as `mcp__{server}__{tool}` | `always_ask` |
| **Custom** | **Your own system**, via the API | `type: custom` with a description and input schema | `always_allow` |

## Permission modes

Each tool has one of three permission modes. For MCP tools, you can set a default for the server and override it for individual tools:

| Mode | What happens on each call |
| - | - |
| `always_allow` | Runs immediately. No human involved. |
| `always_ask` | The call pauses in `awaiting_permission` and a **permission [interaction](/events/interactions)** opens. A human approves or denies; the agent continues either way, knowing the outcome. |
| `always_deny` | The call is refused and the model is told so. Useful for explicitly fencing off one tool from a server that's otherwise allowed. |

```yaml theme={null}
tools:
  web_search: {}               # built-in, default always_allow
  run_command:
    permission:
      mode: always_ask         # every command needs approval
mcp:
  linear:
    url: https://mcp.linear.app/mcp
    permission:
      mode: always_ask         # server-wide default
    tools:
      get_issue:
        permission:
          mode: always_allow   # reads are fine
      delete_issue:
        permission:
          mode: always_deny    # never, even with approval
```

A permission mode applies to every call. Changing it requires creating a new config and [updating the agent](/events/sending-input#change-the-config-mid-conversation).

> [!NOTE]
>
> Provider tools such as `int__engineering__post_message` use the ordinary permission modes.
> They use the named project [integration](/integrations/overview) and its provider credentials.
> Approval prompts show the destination alongside the action. Interaction
> handlers are independent: an agent can request approval through a handler without
> having that integration's sending tools.

## What an `always_ask` call looks like

When an agent calls a tool with `always_ask`, its turn pauses and a permission interaction opens. Until someone approves or denies it, the tool call has state `awaiting_permission`. [Approvals & questions](/events/interactions) shows the form and how to respond.

## Check available tools

`GET /tool-catalog` lists the built-in tools available in your deployment, including each tool's description, default permission, and supported modes:

```bash theme={null}
curl "$OMNARA_API/tool-catalog" -H "Authorization: Bearer $OMNARA_TOKEN"
```

The response also includes the supported modes and defaults for custom and MCP tools in `custom_tool_permissions` and `mcp_tool_permissions`. Use it to build or validate configs against your deployment's current tool catalog.

## Next

> **[Built-in tools](/tools/built-in)**
>
> Available tools, with inputs and defaults

> **[Custom tools](/tools/custom)**
>
> Declare a tool, execute it in your system, post the result back

> **[MCP servers](/tools/mcp)**
>
> Connect third-party tool servers, including the OAuth flow

> **[Skills](/tools/skills)**
>
> Versioned instruction packages agents load on demand


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