skip to content

In Koog, what does ToolRegistry do and what breaks if a tool is missing?

level: juniorimportance: must knowfreq 70%

answer

  1. the agent capability list
  2. builder with tool() and tools()
  3. feeds declarations, resolves calls back
  4. unregistered means invisible to the model

basics

~20 s

ToolRegistry is the single list of tools a Koog agent may call. Koog sends each registered tool's name, description and parameter schema with the prompt, then resolves incoming calls back to Kotlin. An unregistered tool is invisible and unresolvable.

solid answer

~40 s

You build one with the ToolRegistry { } builder: tool(MyTool) adds one tool instance, tools(MyToolSet().asTools()) adds a whole annotated set. It is passed to the agent as AIAgent(toolRegistry = ...). The registry does two jobs. Outbound, it is the source of the tool declarations Koog serializes into every model request: name, natural-language description, and the JSON schema derived from the parameters. Inbound, it maps a tool call the model returned back to the Kotlin implementation and invokes it. Registration is therefore not bookkeeping; it is what makes a tool exist for the model. If the model names something the registry does not hold, resolution fails with an explicit tool-not-found error rather than a silent no-op. Koog also ships built-ins such as SayToUser and ExitTool that go in the same registry.

go deeper

for a junior

Be able to say that ToolRegistry is where tools are registered, that it is passed to AIAgent, and that a tool the model was never told about will never be called.

for a middle

Explain both directions: declarations serialized out with the prompt, and call names resolved back to Kotlin. Name the builder entry points tool() and tools().

for a senior

Talk about failure modes you have hit: the forgotten registration that produces no error at all, and hallucinated tool names surfacing as resolution errors mid-run.

for a principal

Frame registration as a capability decision. What you register is what the model can reach, so the registry boundary is where blast radius is decided, not inside the tool.

## The object that defines what an agent can do Koog is JetBrains' Kotlin/JVM agent framework. An agent is an LLM loop plus a set of Kotlin functions the model may invoke, and ToolRegistry holds that set. In the registry means callable; out of it means non-existent as far as the model is concerned. ## Two directions of work Outbound, Koog walks the registry on every LLM request and serializes a declaration per tool: the tool name, its description, and a JSON schema built from its parameters. That text is the only documentation the model ever sees; your KDoc comments and Kotlin types are not sent, only what the descriptor carries. Inbound, when the model answers with a tool call, Koog looks the name up in the registry, deserializes the arguments into the tool's argument type, and runs the Kotlin code. The result is fed back into the conversation on the next turn. ## Building one The builder has two entry points. tool(...) registers a single object, typically a SimpleTool or Tool implementation. tools(...) registers a list, which is what asTools() returns for a class implementing ToolSet whose methods carry @Tool. A registry is an ordinary value: you can build different registries for different agents, or build one per run from configuration, and Koog also lets you combine a locally built registry with one produced from an MCP server. ## What a missing tool costs Two failure shapes matter. First, you implemented a tool but never added it: the model is never told it exists, so it will not call it, and you will watch the agent apologise that it cannot do the thing while your perfectly good function sits unused. This is the most common beginner bug and it produces no error at all, which is why it wastes time. Second, the model emits a name that is not in the registry, usually a plausible-looking hallucination or a stale name from earlier context. Koog cannot resolve it and surfaces an explicit error rather than pretending the call succeeded. ## Scope and lifetime The registry is per agent, fixed at construction. It is not a global service locator, and it does not perform permission checks; anything you register is callable by the model at any point in the run, so the decision about what to register is itself a security decision. Tools that touch money, files or production systems need their own guard inside the implementation, because putting them in the registry is exactly the act of handing them to the model. ## Built-ins Koog provides small ready-made tools such as SayToUser and ExitTool. They are added exactly like your own, which is the point: there is no separate mechanism for framework tools versus yours.

  • Can two agents in the same process share one ToolRegistry instance?
    Yes. A registry is an ordinary value passed to AIAgent(toolRegistry = ...), so several agents can take the same one. In practice you usually do not want that: the registry defines each agent's capability surface, and giving every agent every tool inflates the declarations sent on each request and makes tool selection noisier. Building a narrower registry per agent is the normal pattern.
  • How would you stop the model from calling any tool for one particular request?
    Set tool choice on the prompt parameters rather than emptying the registry. Koog exposes LLMParams.ToolChoice with Auto, None, Required and Named variants; ToolChoice.None tells the provider to answer with text only for that call. Rebuilding the agent with an empty registry would work too, but it throws the tools away for the whole run instead of one request.

saying these in an interview costs you the question

  • Thinking a tool works once implemented, without registering it
  • Believing Koog sends KDoc comments to the model
  • Assuming an unknown tool name is silently ignored
  • Treating the registry as a permission or auth layer
  • Thinking built-in tools are registered automatically

context

resolving links…