The loadout is a decision you make every turn

Lesson 1 of 5 in Tool Selection at Scale: Forty Tools, One Context.

You have already learned to design a tool contract and to test a set for overlap: can a stranger, reading only your names and descriptions, say without hesitation which tool handles a given request? That test is about the tools. This module is about the list — what happens when there are forty of them, from nine teams and a dozen MCP servers, and no amount of description polish makes the pile small.

Start by noticing an assumption almost every codebase makes without deciding to. Somewhere at startup, a registry is built. Every call thereafter sends the same array:

tools = registry.all()          # 41 contracts, every request, forever
response = model.create(messages=..., tools=tools)

Nothing in any provider’s API requires that. The tool list is a per-request parameter, the same as the messages. You may send a different one on every single turn of the same conversation. Once you see that, the design question changes from which tools does this agent have? to which tools is this agent holding right now? — its loadout.

Where the loadout gets chosen

Turn begins
Read the signals
Three are usually available before you call the model: the routed task or intent, the phase the run is in (what has already succeeded), and the principal on whose behalf the agent is acting.
Assemble the loadout
Plain code selecting from the registry. Deterministic, logged, and cheap — no model call, no embedding, no network hop.
Add the floor set
Tools that must never be filtered out: ask_human / escalate, and whatever discovery tool the agent uses to find more. Without a floor set, a filter bug leaves the agent mute rather than asking for help.
Model call with N tools, not all tools
The exposed set is now a value you can log. That log line is what makes every later selection bug falsifiable.
Execute — and re-check permission here
The loadout shaped what the model could see. It did not authorize anything. Authorization is enforced at the execution point, every time, regardless of how the tool got into the list.
Next turn — decide again

Three signals you can filter on before the model ever sees the list — and what each one costs you
Filter by	The signal	What it buys	How it fails
Task	A router’s intent label, or the endpoint the request arrived on	The biggest cut for the least machinery: a refund conversation never sees the eleven analytics tools	Inherits the router’s misclassification cascade — a mislabeled request gets a loadout with no correct move in it, and the model improvises
Run state	What has already succeeded this run — order resolved, invoice fetched, approval granted	Removes calls that cannot be valid yet, so the model stops proposing `issue_refund` before an order exists	Needs real state, not a guess from the transcript. If you infer phase by grepping messages, the loadout flickers
Principal	The user or agent identity the run acts for, and their role	A support agent never sees the finance tools, so the menu stops advertising things it will be refused	Tempting to mistake for security. Hiding a tool is not denying it — see the last lesson. Treat it as noise reduction that happens to align with permissions

Two costs of a dynamic loadout that nobody budgets for

It breaks prompt caching. Tool definitions sit near the front of the prompt, ahead of the conversation. Caching works on a shared prefix, so changing the tool array changes the prefix and invalidates the cached portion for that call — you pay full price on a turn you expected to be cheap. The practical consequence: filter on boundaries that rarely move (task, phase), not on something that jitters every turn. A loadout that changes on turns 2, 5 and 9 costs three cache misses; a loadout recomputed from a fuzzy score every turn costs all of them.

Tools that vanish leave footprints. Turn 3 called fetch_invoice; on turn 6 your filter drops it. The transcript still contains that tool call and its result, because you cannot rewrite history without breaking the call/result pairing the provider requires. The model can read the earlier call, infer the capability exists, and try again — now producing a call to a tool that is not in the list, which your dispatcher must reject cleanly rather than crash on. Filter forward, expect the ghost, and handle unknown-tool calls as a normal event with a useful error message the model can act on.

Worked scenario: the platform team with 41 tools

An internal developer-platform agent accumulated 41 tools over four quarters: deploys, log queries, incident lookups, cost reports, on-call schedules, three ticket systems. Nobody added a bad tool. Symptoms: median first-token latency crept up, the cost per request roughly doubled with no change in traffic, and — the complaint that got attention — asking for yesterday’s error rate sometimes triggered a deploy-status lookup first.

The fix was not a better prompt. Requests already arrived on four distinct surfaces (a Slack command, a PR comment hook, the incident channel, and a web console), and each surface had a knowable job. Four hand-written loadouts of 6–11 tools each, plus a floor set of two, replaced registry.all(). Selection mistakes dropped because most of the wrong answers were no longer on the menu, and the token cost of contracts fell by roughly three quarters — arithmetic, not magic. Note what was actually spent: an afternoon writing four lists in code. The team had been costing out an embedding-based retriever for the same problem.

Key terms: tool allowlist, prompt caching, tool overlap, context window

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