How to offer only the tools a request needs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

# How to offer only the tools a request needs

This guide shows how to have a decision model leave out, before each turn, the groups of tools a request clearly does not need, so that a small model chooses among fewer tools. It assumes you have a decider agent file (see [How to ask a decision model](ask-a-decision-model.md)). The finished files are in `demos/decision-tools/`.

## Steps

1. Add a `toolRouting` block to the agent that answers you, with one group per family of tools. `when` is the statement the decider judges, `matcher` a regular expression on tool names:

   ```yaml
   toolRouting:
     decider: agent.decider.yaml   # relative to this file
     dropBelow: 0.2
     timeout: 5s
     groups:
       shell:
         when: Answering this request needs running shell commands (build, test, git, listing files).
         matcher: ^bash$
       files:
         when: Answering this request needs reading, writing or editing files of the project.
         matcher: ^(read_file|write_file|edit_file)$
       web:
         when: Answering this request needs fetching a web page or searching the web.
         matcher: ^fetch_content$
       plan:
         when: This request is a multi-step task that needs a plan or a task list.
         matcher: ^plan$
   ```

   The decider file only has to locate the model (`provider`, `model`, `baseUrl`, `fallback`).

2. Start the agent. The banner ends with the tool-routing column:

   ```
   … | tool routing: llmman/hf.co/LiquidAI/d1-3B-GGUF:Q4_K_M, 4 group(s), drop < 0.20
   ```

3. Ask a question. Before the turn, a `🧰` notice says which groups were left out:

   ```
   > explain what a goroutine is, in two sentences
   🧰 tools: dropped shell (0.04), web (0.08)
   ```

   ```
   > run go vet on this module and tell me the result
   🧰 tools: dropped web (0.08)
   🛠️  bash: go vet ./...
   ```

   `🧰 tools: all kept` means no group was under `dropBelow`.

## Variants

- **Drop more**: raise `dropBelow`. Each step up risks leaving out a tool the request needed, and the model then cannot do the task in that turn. Start low and watch the notices.
- **A tool that must always be there**: leave it out of every group. `ask_user`, `read_skill` and the MCP tools stay unless a group's `matcher` names them.
- **One tool, two groups**: a tool stays as long as one of its groups is kept (`read_file` in both `files` and `docs`, for example).
- **A decider that loads slowly**: past `timeout`, the turn shows `🧰 tool routing skipped: … context deadline exceeded` and every tool is offered.

## See also

- Every `toolRouting` key and notice: [Configuration reference](../reference/configuration.md#toolrouting)
- Why only a confident "no" removes a tool, and what it costs: [Decision models](../explanation/decision-models.md#tool-routing-only-removes-what-is-clearly-unneeded)