How many tools is too many?

Lesson 4 of 5 in Tools and Tool Use: The Contract Between Model and World.

Every tool you add has two costs before it does anything useful. It occupies context — the full contract rides along on every model call, whether the tool is used or not. And it adds a branch to every routing decision the model makes for the rest of the session.

The second cost is the one that bites. Models handle many tools better than they handle overlapping tools. Give a model get_user, fetch_customer, and lookup_account — three wrappers over the same records, added by three teams in three quarters — and watch it dither: it alternates between them across turns, calls two of them back-to-back for one question, or picks whichever name most resembles the user’s phrasing. Each tool works; the set is broken, because no description answers the only question the model has: when this one and not that one?

Symptom: the model alternates between similar tools across turns

Classic overlap. Two contracts both plausibly match the request, so sampling splits between them turn by turn. Fix the boundary, not the model: merge the tools, or make each description name the other (“for X use tool_b instead”).

Symptom: a tool you built is never called

Usually not a model problem — a shadowing problem. A broader, better-named neighbour absorbs every request the ignored tool was built for. Check whether its description ever wins the “when this one?” contest against the neighbour, and carve out its territory explicitly.

Symptom: quality degraded when you added ten more tools

Nothing is “wrong” with any one of them — the routing decision got harder and the context got heavier for every call, including ones that need no tool at all. Prune, merge, or expose different tool subsets to different tasks rather than shipping the full drawer everywhere.

Symptom: the model uses the right tool with a neighbour’s arguments

Sibling tools with near-identical parameter lists blur together — the model has seen both schemas in context and cross-pollinates them. Distinct names and visibly different parameter shapes keep the contracts separable in the model’s working memory.

The strongest version of the fix is a design principle: build tools around workflows, not endpoints. The classic anti-pattern is auto-generating one tool per REST endpoint — forty near-identical contracts, each doing one-fortieth of a job. The model then has to reconstruct your API’s call-ordering conventions from names alone. A handful of task-shaped tools — resolve_customer, get_order_history, issue_refund — each wrapping several endpoint calls behind one contract, routes better, costs less context, and fails less often than the full mirror of your API surface.

There is no magic maximum — it depends on the model and how distinct the contracts are. The test that matters is not a number; it is: can a stranger, reading only your names and descriptions, say without hesitation which tool handles a given request? If two tools tie, the model will too. (Where the tools also differ in privilege, the same overlap becomes a security problem — the least privilege module picks that thread up.)

Should this become a new tool?

Interactive decision tree — outcomes:

  • Extend the existing tool

    One tool with an extra enum value or optional parameter keeps the routing decision unchanged. New tools are for new jobs, not new options on old jobs.

  • Stop — resolve the overlap first

    If you cannot state the boundary in one sentence, the model certainly cannot infer it from two competing descriptions. Merge the tools, or redraw both descriptions so each names when to use the other.

  • Add it — with a boundary-drawing description

    Crisp territory, task-shaped scope. Ship it with the “use when… not when…” sentence you just wrote as the opening of its description.

  • Reshape it around the workflow

    One tool per endpoint forces the model to re-derive your API choreography from names. Wrap the chain of calls behind a single task-shaped contract and let your code handle the sequencing.

Key terms: tool overlap, context window, tool contract, least privilege

Interactive checkpoint quiz (2 questions) — open this page in a browser to take it.