Recall modes

Each turn, the model needs the few capabilities that matter now. Recall is how they arrive. Both modes go through the same search_capabilities contract; they differ in who runs the first search.

Eager recall

The host searches before the model does. Before each model call, rank the catalog against the last user message and append a synthetic search_capabilities call/result pair to the message list:

// appended after the user's message, in your framework's tool-call message shape
[
  { "role": "assistant", "content": [{ "type": "tool-call", "toolCallId": "<unique id>", "toolName": "search_capabilities", "input": { "query": "<last user message>" } }] },
  { "role": "tool", "content": [{ "type": "tool-result", "toolCallId": "<unique id>", "toolName": "search_capabilities", "output": { "tools": { "groups": [/* top-K hits */] }, "skills": [/* ... */] } }] }
]

The model wakes up with the top-K already in context, as if it had searched: no discovery round-trip for the common case. Recall fires only when the last message is a user turn; assistant messages and tool results never re-trigger it.

The per-language recipes are on Use the discovery tools (TypeScript, Python). Ratel Local's skill preload hook is the same idea for Claude Code: rank on every prompt, inject a pointer when one skill clearly wins.

On-demand search

The model searches itself. search_capabilities sits in the tool list every turn; the model calls it when the current toolset falls short, then follows with invoke_tool or get_skill_content. This is the progressive-disclosure funnel with no host involvement.

The two modes compose rather than compete. Eager recall covers the predictable case, and the capability tools stay in the list, so the model still searches on demand for the long tail.

Both preserve prompt caching

Providers cache the prompt as a prefix: tool definitions, system prompt, then messages. A cache hit needs that prefix byte-identical; changing anything invalidates the cache from that point on.

Both recall modes only append:

• The tool list stays the same three capability tools every turn, however large the catalog grows.
• Eager recall adds the synthetic pair after the last user message — a suffix append.
• On-demand search arrives as an ordinary model tool call and result — also a suffix.

Nothing upstream is rewritten, so the cached prefix keeps growing instead of busting.

The contrast is the top-K pre-filter (TypeScript, Python): putting each turn's hits into the tool list buys the framework's schema validation at the LLM boundary, but tool definitions sit at the top of the prompt, so a changed top-K invalidates the cache behind it. Both are legitimate; measure cached input tokens on your own traffic and pick.

Telemetry

Trace events and the ratel.origin span attribute record who ran each search: catalog.search from host code is "direct"; anything through the capability tools — including an eager-recall call to the search tool's execute — is "agent". See Telemetry.

Next steps