> The agent's capabilities — file operations, shell execution, web search, embeddings, media, skills, and subagents.

The agent's tools fall into eight categories. Each is a capability the model can invoke during a
turn. Tools are wired by `q15-agent` and executed through the appropriate service boundary.

## Tool overview

| Tool           | What it does                                             | Execution boundary                                   |
| -------------- | -------------------------------------------------------- | ---------------------------------------------------- |
| **Files**      | Read, write, edit, and patch files                       | Agent (rooted to `/workspace`, `/memory`, `/skills`) |
| **Exec**       | Run shell commands through Nix                           | `q15-exec` (gRPC)                                    |
| **Web**        | Search the web and fetch pages                           | Agent → `q15-exec` → `q15-proxy`                     |
| **Embeddings** | Sync and search vector collections                       | Agent (Qdrant + the configured backend)              |
| **Media**      | Load images for vision, attach images/audio for delivery | Agent                                                |
| **Skills**     | Validate skill directories                               | Agent                                                |
| **Schedule**   | Create and manage jobs that run without you              | Agent                                                |
| **Subagent**   | Delegate work to isolated sub-agents                     | Agent (spawns independent model calls)               |

## Files

The agent can read, write, edit, and patch UTF-8 text files. All file operations are rooted to `/workspace`, `/memory`, and `/skills`. The agent cannot access paths outside these roots.

- **`read_file`** — Read a file with optional line-based pagination (`offset_lines`, `limit_lines`).
- **`write_file`** — Create or fully replace a file.
- **`edit_file`** — Perform one exact text replacement in an existing file.
- **`apply_patch`** — Apply a multi-file patch using the Codex patch envelope.

## Exec

Shell commands run through `q15-exec` over gRPC. The exec service uses Nix to provide packages on demand — any package from nixpkgs is available without rebuilding the container image.

- Commands specify optional `packages` (nix installables) for dependencies.
- Sessions can be long-running with `wait_seconds` and `keep_stdin_open`.
- All egress from exec routes through `q15-proxy`.

See [Architecture](/architecture/#inside-the-executor) for the full execution model.

## Web

Two web tools give the agent internet access:

- **`web_search`** — Search the web using Brave Search. Returns titles, URLs, and snippets.
- **`web_fetch`** — Fetch a known URL and convert readable HTML to markdown.

Both route through `q15-proxy`. If the proxy has a credential rule for the target host, credentials are injected at the network layer — the agent never sees them.

Web search requires `BRAVE_API_KEY` in the agent config. Omit the `web_search` block to disable it.

## Embeddings

When configured, the agent can build and search Qdrant-backed embedding collections over local content. This powers semantic recall from the library, zettelkasten, and memory.

- **`embed_sources`** — Manage typed embedding sources (add, remove, enable, disable).
- **`embed_sync`** — Index source content into Qdrant.
- **`embed_search`** — Run hybrid (dense + sparse), dense-only, or sparse-only search.
- **`embed_status`** — Report source state and collection health.
- **`embed_job`** — Inspect or cancel a running sync job.

Requires `Q15_QDRANT_URL` and a backend. The shipped stack uses the local `q15-tei` container through
the OpenAI-compatible provider, which needs no key; a hosted backend such as Gemini needs its API
key. See [Embeddings and search](/memory/#searching-your-own-files) for the configuration of both.

## Media

Media tools handle images and audio for vision-capable models and user-facing delivery:

- **`load_image`** — Register an image for the model to inspect with vision on the next turn.
- **`attach_media`** — Deliver a file to the user: an image, audio, a document, a video, a sticker, an
  animation, or a video note.

Media files must be under a shared runtime root (`/workspace`, `/memory`, `/skills` or `/media`).
The `/tmp` directory is not accessible for media delivery.

## Schedule

The schedule tool manages jobs that run without you:

- **`schedule_create`** — Add a one-shot or recurring job, on a UTC schedule, with its own turn
  budget and tool allow-list.
- **`schedule_list`**, **`schedule_update`**, **`schedule_delete`** — Inspect and manage them.

Scheduled jobs are optional: omit the `schedule` block in the config to disable the tool. A job's
own tool list is decided when the job is created, not by the config. See [Jobs](/jobs/).

## Skills

The skills tool validates skill directories:

- **`validate_skill`** — Parse a skill's `SKILL.md`, check metadata, and report errors and warnings.

Skills themselves are not tools — they are workflow packages the agent reads and follows. The skills tool is the mechanism for checking that a skill is well-formed.

See [Skills](/skills/) for the full skill system.

## Subagent

The agent can delegate work to isolated sub-agents running on configured models:

- **`subagent`** — Start a delegated sub-agent with a specific model, task, tools allowlist, and optional skill injection.
- **`subagent_read`** — Read events from a running sub-agent session.
- **`subagent_write`** — Send a follow-up message to a running sub-agent.
- **`subagent_list`** — List sub-agent sessions.
- **`subagent_kill`** — Cancel a running sub-agent session.

Subagents run independently from the main conversation. They receive sanitized context — only what the parent agent explicitly provides. This keeps the main session context clean and allows using cheaper models for delegated work.

## Optional tools

Web search and embeddings are optional. Omit their config blocks to disable them:

```yaml
agent:
  tools:
    web_search: # omit to disable
      brave_api_key_env: BRAVE_API_KEY
    embeddings: # omit to disable
      qdrant_url_env: Q15_QDRANT_URL
      provider: openai
      base_url_env: Q15_EMBEDDINGS_BASE_URL
      model: qwen3-embedding-0.6b
      dimensions: 1024
      batch_size: 128
```

Files, exec, media, skills, schedule and subagent tools are wired by the agent itself; only web
search, embeddings and schedule are gated on config blocks.
