Knowledge & search

A namespace endpoint’s main job is published knowledge: curated, ranked, searchable domain content managed by KnowledgeTheory. The query loop is always the same shape — list what’s visible, search for previews, then fetch the authoritative detail.

The tools

Tool	What it does	Treat the result as
`list_knowledge_bases`	lists the KBs visible on this route (name, display name, description, topics, access tier)	the menu
`search_docs`	finds units in one KB; returns title, summary, snippet, source_ref, citations, relevance	previews
`get_unit`	fetches the full authoritative body for a `unit_id`	the source of truth
`recall_units`	deterministic metadata + adjacency recall by id / source_ref / facet — no ranking	metadata, not the full body

On agent endpoints the compatibility tool is query_knowledge (same idea as search_docs, returns doc_id instead of unit_id). Confirm the real names by grounding first — describe_interface on a namespace route, server_instructions on an agent endpoint; the exposed surface is route-dependent.

Previews are not the answer

search_docs returns previews, not authoritative text. And recall_units returns deterministic metadata + adjacency, not the body. Don’t answer from either — find the right unit, then call get_unit and answer from its full authoritative body. Cite the unit_id so the answer is traceable.

The query loop, as a prompt

In the theorycloud namespace, call list_knowledge_bases and show me the visible KBs.
Then search the most relevant KB for "<my question>" and list the top 5 results as
previews (title · summary · relevance). Pick the best match, call get_unit on its unit_id,
and answer my question from the authoritative body. Cite the unit_id(s) you used.

Narrowing to one knowledge base

If you already know the KB, skip the menu:

Search the "<kb_name>" knowledge base in theorycloud for "<query>". Return the top matches
with their unit_ids and relevance, then get_unit the strongest one and summarize it.

Deterministic lookup (no ranking)

When you want a specific unit’s metadata or everything adjacent to one — not a ranked search — use recall_units. It returns deterministic metadata and adjacency; for the authoritative body, follow with get_unit:

In theorycloud, use recall_units to recall the metadata + adjacency for the unit with source_ref
"<ref>" (or unit_id "<id>") and anything it marks as related. Show titles and unit_ids; don't rank.
Then get_unit the one I actually want for its full body.

Contract packs

Some namespaces publish contract packs — curated, regulated-domain knowledge (financial products, API specifications, legal frameworks). They are knowledge bases with stricter access policies; you read them through the same tools:

List the knowledge bases in theorycloud and tell me which are contract packs. Then search
the "<pack_name>" pack for "<topic>" and get_unit the authoritative entry.

Good habits

Ground first. describe_interface tells you which KBs and tools this route actually exposes.
Search wide, read narrow. Many previews → one authoritative get_unit.
Cite unit ids. They make an answer checkable and re-fetchable.
Don’t widen scope by hand. Extra fields in a tool call don’t unlock more — access is route-resolved.

Want continuity, memory, and a named expert instead of raw knowledge? That’s an agent MCP. Want to see which agents a namespace offers? → Contactable agents.