Tools

The agent has seven tool 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 + Gemini)
Media	Load images for vision, attach images/audio for delivery	Agent
Skills	Validate skill directories	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 q15-exec 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.

Requires Q15_QDRANT_URL and Q15_GEMINI_API_KEY. See Embeddings & Search for details.

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_image — Deliver an image to the user (e.g., a generated chart or screenshot).
• attach_audio — Deliver an audio file to the user (e.g., TTS output).

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

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 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:

agent:
  tools:
    web_search:          # omit to disable
      brave_api_key_env: BRAVE_API_KEY
    embeddings:          # omit to disable
      qdrant_url_env: Q15_QDRANT_URL
      gemini_api_key_env: Q15_GEMINI_API_KEY
      model: gemini-embedding-2
      dimensions: 768

Files, exec, media, skills, and subagent tools are always available — they are core agent capabilities.