---
paths:
  - "fast_tools.py"
  - "agent.py"
---

# Fast Tools — Extension Guide

To add a new fast tool:

1. In `fast_tools.py`, subclass `FastTool` and implement:
   - `name` (str property) — unique identifier, used in logs
   - `matches(message: str) -> bool` — regex or logic; keep it cheap, runs on every message
   - `run(message: str) -> str` — async fetch; return a short context block or `""` on failure; never raise

2. In `agent.py`, add an instance to the `_fast_tool_runner` list (module level, after env vars are defined).

3. The router will automatically force medium tier when `matches()` returns true — no router changes needed.

## Constraints
- `run()` must return in under 15s — it runs in the pre-flight gather that blocks routing.
- Return `""` or a `[tool error: ...]` string on failure — never raise exceptions.
- Keep returned context under ~1000 chars — larger contexts slow down `qwen3:4b` streaming significantly.
- The deepagents container has no direct external internet. Use SearXNG (`host.docker.internal:11437`) or internal services.