K3 — search is a tool call: shipped, one wiring gap left

[davidmckayv]

Rewritten 2026-08-24. K3's design question has been answered, and largely built. The original
issue argued for a decision that has since been made and shipped, so it is replaced with what is
actually left rather than left standing as though nothing had happened.

K3. Follows K1 (answer from a live system) and K2 (as me, not as the deployment). Fuller version
in Notion under Architecture, same title.

The design, and where it landed

The question was whether retrieval should be a bolted-on pipeline or a tool call like any other. It
is a tool call, and the reason is the constraint OpenBot lives under: it is a template an enterprise
deploys, not a hosted product we run, so the deployment picks its own model. Anything that only works
on one vendor's API is not an answer for us.

Two halves came out of that, and both are built.

Selection, shipped. server/src/plugins/selection.ts narrows a Bot's tools per run to those its
matching skills declare, because a model picks the right tool reliably out of about ten and
unreliably out of thirty. It is model-agnostic by construction: a separate pass, not a vendor feature.
Skills declare tools in the tenant package (#157), and the offer is always the intersection with what
the Bot was actually granted, so a declaration confers nothing.

Retrieval over the tools, shipped. Google Drive is a connected plugin with four governed tools:
search_files, list_recent_files, get_file_metadata, read_file_content. Searching goes through
the same gateway as every other tool call: resolve, decide, audit, act. Access is per-person OAuth, so
two people asking the same question get answers from their own files, which is the permission property
that motivated putting retrieval over the tools rather than beside them.

The vector store and ingestion pipeline that predated this were removed. See #59.

What is left

Nothing in the original design. #227 closes the last wiring gap: a package can say which skills each
coworker gets, so Knowledge boots paired with its document skills rather than with none.

What was deliberately not decided here

Drive search is keyword search over a person's own files, not ranked semantic retrieval over an
indexed corpus. K3 did not answer whether we want the latter, and this issue should not be read as
having asked for it. If it is wanted, it is a project of its own, and its hard part is not ranking but
keeping an index in step with who may see what, which is the problem the per-person connector avoids
entirely.

[Hotragn]

I would like to take step 1, skills declaring their tools, since you have it as the keystone and
nothing downstream is buildable without it. Reading around it first turned up two things worth having
before anybody starts.

Step 5 is already done

Namespace tool names by vendor now — google_drive_*, slack_*. Renaming later breaks grants.

The name a model sees is already namespaced, and has been. plugins/store.ts:149:

export const toolNameFor = (ref: string) => `mcp__${ref.replace("/", "__")}`;

listForAgent hands that to the runtime rather than the vendor's own name
(store.ts:961), so a Drive search reaches the model as mcp__google_drive__search, and
refFromToolName (:151) is the inverse used on the way back in. Grants are keyed on
<serverId>/<toolName> independently of it.

So there is no rename to get in before, and no grant to break. Worth striking off the list rather than
leaving as a thing somebody schedules.

The catalogue read is a full table scan, which the 1,000-tool target makes load-bearing

listForAgent narrows to what the Bot holds — but in this process, not in the query
(store.ts:951-956):

const toolRows =
  toolRefs.length === 0
    ? []
    : await database.select().from(mcpTools).orderBy(asc(mcpTools.name));
const grantedTools = toolRows
  .filter((row) => toolRefs.includes(`${row.serverId}/${row.name}`))

Every mcp_tools row in the deployment is selected on every run of every Bot, then filtered with a
linear includes per row. At today's sizes that is invisible. At the design target in this issue it is
1,000 rows across the wire and 1,000 × |grants| comparisons, per run, to build a list that is usually
a handful of tools — and it happens before retrieval, so it is under whatever pass one costs rather
than instead of it.

It is a small change (inArray on the composite, or on serverId with the name check kept) and I am
not proposing it here, because it is not step 1 and it should not ride along inside it. Flagging it
because "the catalogue is already narrowed to what this Bot has been granted before retrieval runs" is
a load-bearing sentence in your governance rule, and today that narrowing is done after the read
rather than by it. Happy to send it separately, before or after, whichever you prefer.

What I would build for step 1, so you can redirect cheaply

The invariant I am taking as fixed, from schema/plugins.ts:180-188:

Writing one adds no capability at all: it can only ask a Bot to use what that Bot was already
granted.

So allowedTools is a retrieval hint and never a grant. A skill naming a tool the Bot does not
hold must select the skill and load nothing, not quietly widen what the Bot can call. The intersection
with plugin_grants stays the boundary, and I would put a test on exactly that rather than leave it
as a property of how the code happens to be written today.

Shape, unless you would rather otherwise:

• A skill_tools join table — (skillId, ref) — rather than a text[] on skills. It mirrors
  plugin_grants's own (kind, ref, agentId) shape, indexes for the pass-two query, and a text[]
  of refs is the shape allowed_groups is documented as a channel access control but is never enforced #82 and fix: State what decides channel access, and what allowed_groups is waiting on #92 just finished being unhappy about elsewhere.
• Refs, not tool names. <serverId>/<toolName>, the same key grants use, so a skill and a grant
  are comparable without either side parsing a display name.
• A ref naming a tool that does not exist is refused on save, so a typo is an error where it was
  written rather than a skill that silently selects nothing. A ref naming a tool that exists but that
  a given Bot lacks is not an error — that is the ordinary case, and it is the intersection above.
• Editing them on the existing skill screens, and left out of the / menu, which is a person picking
  an instruction rather than a capability.

Two things I would leave alone in this PR: pass-two selection itself, and anything about tiers. Step 1
only.

One caveat you should have from me up front: I have no local PostgreSQL, so integration tests here run
first in CI, and I say so on the PR rather than implying a suite I watched. That has been fine on
#109 and #113, and it is also how I missed the @types/bun resolution on #121 — so if you want a
live-database run before it reaches you, say so and I will get one up first.

[Hotragn]

Sent the catalogue read as #184, the one I flagged above and said I would keep out of step 1.

It turned out knownToolRefs in the same file already narrowed the way I was proposing, with the
reasoning written above it — so this is the run-time half catching up with the save-time half rather
than a new idiom. Narrowed by server rather than by exact pair, for the reason in the PR.

Worth knowing for whoever picks up steps 3 and 4: this sits underneath selection, so it is paid before
the narrowing, which is why it seemed worth doing before a prefilter rather than after.

(Edited: the function name was eaten by my own shell quoting the first time round.)