search_knowledge_base

Semantic search over the workspace's knowledge bases.

Role required: viewer.

Source: tool definition services/runtime/src/runtime/mcp/tools.py:515-540, handler services/runtime/src/runtime/mcp/tools.py:362-407, role check services/runtime/src/runtime/mcp/tools.py:367-370.

This tool has never been observed working end to end

The other four tools have been driven for real. This one has not. In the environment where the MCP server was validated the knowledge base service was switched off, so only its failure and validation paths were exercised: the refusals below have been seen, a successful search has not.

Everything on this page is read from source and is accurate as a description of the code. Nobody has watched it return a result.

Input

Property	Type	Required	Notes
`query`	string	yes	The search text
`workspace_id`	string	no	The workspace to act in. Optional if you belong to exactly one workspace, required otherwise
`kb_id`	string	no	Search one knowledge base instead of every one in the workspace
`top_k`	integer	no	Minimum 1, maximum 50, default 6

Source: services/runtime/src/runtime/mcp/tools.py:520-536, with the top_k bounds defined at services/runtime/src/runtime/mcp/tools.py:234-236.

query is checked before anything else runs, and an empty string counts as absent: the call is refused with query is required.

Source: services/runtime/src/runtime/mcp/tools.py:363-364.

The `top_k` bounds are enforced, not clamped

A value outside 1 to 50 is refused with a message naming the bound. It is not quietly rounded into range, and 0 is not read as "unspecified".

Source: services/runtime/src/runtime/mcp/tools.py:208-233 and services/runtime/src/runtime/mcp/tools.py:373-379.

What it searches

With no kb_id, it lists the workspace's knowledge bases and searches all of them, then merges the results, sorts them by score and returns the best top_k overall. With a kb_id, it searches that one only.

Source: services/runtime/src/runtime/mcp/tools.py:380-407.

Output

{
  "query": "the text you searched for",
  "results": [ ... ]
}

results is the merged, score-sorted list, cut to top_k.

Source: services/runtime/src/runtime/mcp/tools.py:406-407.

When the workspace has no knowledge base

Not an error. You get an empty result list and a note saying so:

{
  "query": "the text you searched for",
  "results": [],
  "note": "no knowledge base configured for this workspace"
}

Source: services/runtime/src/runtime/mcp/tools.py:385-390.

Failures

What happened	What you get
The knowledge base service cannot be reached	A tool error, `the knowledge base service is unreachable`
One knowledge base answers with an error	That one is skipped and logged, and the search continues with the others
Anything unanticipated	A tool error, `this tool call could not be completed`, with the real exception and its traceback in the server logs

Source: services/runtime/src/runtime/mcp/tools.py:398-405 for the first two and services/runtime/src/runtime/mcp/tools.py:566-574 for the third.

The generic refusal is deliberate. It is why a caller never sees a database error, and never sees the query text that produced one.

Note the shape of the second row: if every knowledge base in the workspace answers with an error, each one is skipped individually and the call still succeeds, returning an empty results list with no note. An empty result from this tool therefore does not distinguish "nothing matched" from "every knowledge base refused".

Source: services/runtime/src/runtime/mcp/tools.py:392-407.