Tool granularity

Why does giving an assistant fewer, broader actions often beat giving it many precise ones?

You are wiring an assistant up to a calendar. You could give it one tool, manage_event, taking an action and some fields. Or you could give it seven: create, move, cancel, invite, uninvite, set reminder, change room. The second feels obviously better — each one is unambiguous, each schema is tight, nothing is overloaded. It is what good API design taught us.

And yet the assistants that work best in practice often have the smaller list. That is worth explaining rather than asserting, because "fewer tools" is not a principle so much as a symptom of something else being true.

Ask first what a tool actually costs. Not to run — to exist. Every tool the client exposes puts its name, its description and its whole input schema into the model's context before any work begins. Fifty tools is fifty schemas, and a meaningful share of the window is now a menu. That is a real cost, though the least interesting one, because context windows keep growing.

The second cost is subtler and does not shrink. The model must choose. With seven similar tools it is doing a discrimination task, and the difficulty of that task grows with how similar the options are, not merely with how many there are. Two tools whose descriptions differ in one clause are harder to choose between than ten that are plainly distinct. So the count is a poor proxy; the real quantity is how much overlap there is in the action surface.

Now the third cost, the decisive one. Suppose the assistant must move an event and notify the attendees. With narrow tools that is two calls, and between them sits a model turn: the first result becomes context for the second, and the model must decide, unaided, to make the second call at all. Each hop is another place the sequence can be abandoned, duplicated, or continued under a wrong assumption. With one broader tool, that coordination happens inside ordinary code — deterministic, tested, and free.

Does that suggest a general principle? I think it does, and it is not about counting tools at all: put the branching where it is cheapest and most reliable. A branch that a program can decide should be decided by the program. A branch that genuinely requires judgement about the user's intent is exactly what the model is for. Tool granularity is really the question of where you draw that line, and the fewer-tools result follows because designers habitually draw it too far toward the model.

But now push against it, because the argument is not one-sided. What do narrow tools buy? Precision of permission, mainly. A single manage_event tool that can also delete cannot be granted to someone who should only be able to create. An approval prompt for it can only say "manage an event", which tells the user nothing about what is about to happen. An audit line records the tool name and leaves the reader to parse arguments to learn what occurred. Each of those problems is real, and each gets worse the broader the tool.

So the two forces are visible now, and they pull in opposite directions on the same design. Coordination cost pushes toward fewer, broader tools; authorisation, confirmation and auditing push toward narrower ones. Where they meet is not a number. It is a shape: group operations that share a risk class and a permission, and separate ones that do not, whatever their functional similarity.

That reframing dissolves most of the awkward cases. Should reading and writing be one tool? Almost never — different risk, different permission — even though they touch the same object. Should moving an event and notifying its attendees be one tool? Very likely yes, because they carry the same consequence and nobody would grant one and refuse the other.

One honest caveat. It is widely observed that model reliability degrades as the tool list grows, but the thresholds people quote are specific to a model, a prompt, and how distinguishable the tools are — and they move with every model release. Treat "fewer tools works better" as a direction to lean, not a number to hit.

Two corrections.

The first: "broader" must not mean "vaguer". A tool that takes an action string and a free-form payload has not consolidated anything — it has moved the schema out of the schema, where neither the validator nor the model can see it. The consolidation that works keeps every argument declared and typed; it merges operations, not specifications. If merging two tools makes the schema unstateable, they should not have been merged.

The second: bundling changes what a confirmation prompt can honestly say. If a broad tool can take a destructive path under some argument, the user approving it is approving the worst case, and most users do not read that far. The fix is usually not to split the tool but to keep the destructive path out of it entirely — a separate, narrow, deliberately awkward tool for deletion, and a broad one for everything reversible.

Notice how both corrections point the same way as the earlier reframing: the boundary that matters is consequence, not function.

• How tool annotations such as read-only or destructive hints let one tool carry a risk signal that a client can act on.
• How the same argument plays out for sub-agents, which are effectively very broad tools with judgement inside them.

Every term the collection defines is gathered in the glossary.