How do you decide which tools a Koog agent's ToolRegistry exposes as the set grows?

## Why the registry is a design artifact In Koog, ToolRegistry is the only thing that decides what an agent can do. That makes it three things at once: a cost centre, a correctness input, and a security boundary. Teams that treat it as a place to accumulate useful functions discover all three at the same time, usually in production. ## The per-turn tax Every registered tool contributes a name, a description and a parameter schema to every model request in the run. Twenty well-documented tools is a meaningful block of tokens paid on every single turn of a multi-step agent, and it is paid whether or not any of them are relevant to the current task. Because agent loops make several calls per user request, this is one of the few costs in an agent that multiplies rather than adds. It also competes with the conversation itself for context. ## The accuracy tax Selection quality degrades as tools multiply, especially when descriptions overlap. Two tools that both plausibly answer a question mean the model has to guess, and the failure is silent: a wrong-but-successful tool call. The first remedy is editorial, namely sharper descriptions that say when not to use a tool rather than only what it does. The second is structural: fewer tools in front of any one decision. Splitting a sprawling agent into several agents with narrow registries usually beats prompt-engineering a twenty-tool menu. ## The capability grant Registration is the moment you hand a capability to a model that will invoke it if a description sounds relevant. There is no per-call authorization layer in the registry itself, so tools that spend money, mutate production state or touch the filesystem need their own guards inside the implementation: argument validation, allowlists, quotas, and where appropriate a human approval step before the effect. The schema is a constraint on generation, not a guarantee about what arrives; assume any syntactically valid argument can appear, including one produced by an instruction injected into retrieved content. ## Imported tools deserve more scepticism Tools pulled from an MCP server arrive with names and descriptions written by someone else, on their release schedule. Two rules keep that manageable. Allowlist rather than merge wholesale, so the surface is a decision you made rather than whatever the server currently advertises. And control naming, because a foreign tool colliding with one of yours is a resolution problem you never want decided implicitly. ## Composition patterns that work Build registries as values, per agent and per run, rather than one shared singleton. Derive them from configuration when the surface varies by tenant or plan. Where a workflow has clearly separate phases, giving each its own agent and registry keeps each decision small. And keep descriptions under change control with a few regression prompts, since a reworded description silently changes routing. ## What tool choice does and does not solve LLMParams.ToolChoice, with its Auto, None, Required and Named variants, is the per-request lever: forbid tools for one call, force a tool when you know one is needed, or pin a specific one. It is genuinely useful for deterministic steps. It does not reduce the declarations sent, and forcing a call when the model should have answered or stopped creates its own failure mode, so it complements a scoped registry rather than replacing it.