Tool Surface Design
When an action deserves its own tool instead of bash, how to write a description that raises selection accuracy, and how to scale past a few dozen tools without destroying the prompt cache.
Last updated
After this section you can
- Decide when an action deserves its own tool instead of going through bash, using reversibility as the test
- Write a tool description that raises selection accuracy, and keep examples and rival-tool instructions out of it
- Scale a large tool surface with tool search and deferred loading without destroying the prompt cache
Tool Surface Design
One bash tool can do almost anything, which is exactly why your harness can do almost nothing with it. Deciding which actions get their own tool is how you buy back the ability to gate, render, audit, and parallelise.
The model emits tool calls; your harness handles them. So the shape of the tool surface decides what the harness can see and therefore what it can do. A single bash tool gives it one opaque command string for every action — it cannot tell a read from a delete, so it must treat them alike. Promoting an action to its own tool gives the harness typed arguments it can intercept, approve, render, log, or run in parallel. That is the whole trade: breadth from bash, control from dedicated tools.