Skip to content

Tool search

Purpose

Keep a large tool catalog out of every request. Tools are declared up front but advertised only when the model searches for them, so a fifty-tool agent pays for the handful it might use instead of every schema on every turn.

When to use

Use it when an agent declares enough tools that the catalog dominates the prompt or degrades tool selection — roughly past a few dozen — and most turns need only a few of them. Register a handful of tools with WithTools instead: search adds a model round trip and a keyword matcher between the model and a tool it could have called directly.

It is also not per-step tool pre-selection. The application cannot choose the subset for each request; the model discovers it. And it does not combine with WithToolChoice, which pins one tool.

How it works

WithDeferredTools[Deps, Output](tools ...tool.Tool[Deps]) declares tools that are valid and dispatchable but withheld from the advertised set. WithTools keeps registering eager tools. Every declared tool — eager or deferred — is validated at construction: names must be unique across both lists, and search_tools is reserved once anything is deferred.

When at least one tool is deferred, the runner synthesizes one search_tools tool and advertises it beside the eager tools. It takes {"query": string} and returns text: one line per match, name(arg1, arg2): description, best first, and a line saying the matches are available from now on. A search with no matches is a successful call — it spends no retry budget and says so. A malformed or empty query is a correctable *model.ModelRetry, fed back under the agent's tool retry budget (or ending the run at the tool stage when no budget is configured).

Matching is deterministic and stdlib-only. The query splits into lowercase alphanumeric tokens, breaking on separators and camel-case boundaries. Each token scores against a tool's name tokens (weight 3), its schema property names (weight 2), and its description words (weight 1); a tool's score is the sum over distinct query tokens. A token that only prefixes a catalog token scores one less than an exact hit, so calc still reaches calculator without outranking a real match. Matches rank by score, then by name, and stop at the limit — five by default, set with WithToolSearchLimit.

Reveal is derived from history, not stored. Before every request the runner scans the conversation for search_tools calls, re-runs the matcher on each call's arguments, and unions the results. The advertised set is the eager specs, then search_tools, then the revealed specs in declaration order — stable rather than discovery-ordered. Because the state is the history, a reveal survives the agent's output-correction rounds and a resumed run that carries the exchange; nothing is shared between concurrent runs.

A call to a deferred tool that has not been revealed fails the run at the tool stage with an error naming search_tools: the tool is declared, but the model could not have seen its schema. Once revealed, the call dispatches from the full declared set like any other tool. The search itself is an ordinary tool execution — it counts toward Result.ToolCalls and usage limits, emits the usual tool events, and honors the caller's context; there is no new run event.

Example

go run ./examples/tool-search runs offline against testmodel. It declares one eager tool and nine deferred ones, then scripts the model to search for the invoice tool and call it:

agent, err := golem.New[struct{}, string](client, decoder,
    golem.WithInstructions[struct{}, string]("Search for a tool before using one that is not listed."),
    golem.WithTools[struct{}, string](buildTool(eager)),
    golem.WithDeferredTools[struct{}, string](deferredTools...),
)

The first request advertises get_current_time and search_tools; after the search, get_invoice joins the set. The example prints the advertised count per request, the search result, and the answer.

API surface

  • golem.WithDeferredTools[Deps, Output](tools ...tool.Tool[Deps]) — declare tools that stay unadvertised until searched.
  • golem.WithToolSearchLimit[Deps, Output](limit int) — cap matches per search; zero uses the default of 5, negative is rejected at construction.
  • golem.WithTools[Deps, Output](tools ...tool.Tool[Deps]) — eager tools, advertised every request.

Gotchas

Search quality is keyword matching. A tool whose name, arguments, and description share no word with the query will not be found, and search is the only path to a hidden tool. Name tools for the task and write descriptions with the words a caller would use; a vague description hides the tool as effectively as not declaring it.

search_tools is reserved for agents that defer tools; a declared tool with that name fails construction. WithDeferredTools and WithToolChoice are mutually exclusive, and WithToolSearchLimit has no effect without deferred tools.

Revealing a tool changes the tool block, so providers that cache a request prefix miss the cache from the tool definitions onward on the turn a reveal lands. That is the documented cost of the local strategy; provider-native search is a separate, post-v1 capability. Decisions live in docs/adr/0033-tool-search.md.

Discovery lives in the history. A run that starts from a sanitized or truncated conversation begins with only the eager tools, and the model must search again. The limit caps one search, not the total number of revealed tools: repeated searches can reveal the whole catalog.