Tools

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

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