retrieve_knowledge

Runs a semantic search (RAG) over a project's indexed knowledge. Returns an answer (when post-processing is enabled) and source citations with relevance scores. Use it to ground responses in the actual content of a DEON project.

Tool name: retrieve_knowledge

Prerequisites

The project must have been analysed — by the user the API token belongs to, under that user's currently selected tenant. Knowledge is scoped to (user, tenant, project), not to the project alone; see Scoping. knowledge_status reports that precondition directly.

Parameters

Parameter	Type	Required	Default	Description
projectId	string	Yes	—	Project (map) id to scope the search to.
query	string	Yes	—	Natural-language question or search query.
keywords	string[]	No	—	Optional keywords to bias the hybrid search.
maxResults	number	No	—	Maximum citations to return. Positive integer, max 50.
postProcess	boolean	No	—	When true, an LLM composes a final answer from the retrieved context.
itemIds	string[]	No	—	Restrict the search to these item ids.

Returns

{
  "answer": "The launch is planned for the first week of September, pending the security review.",
  "citations": [
    {
      "id": "11aa22bb-...",
      "index": 1,
      "relevance": 0.91,
      "chunk": "Launch: week 36, blocked on security review sign-off",
      "projectId": "a1b2c3d4-..."
    }
  ],
  "costInEuros": 0.0021
}

With postProcess enabled, answer is an LLM-composed answer over the retrieved context. Without it, answer is the raw concatenation of the retrieved chunks and no model is called, so costInEuros is 0 — in that case prefer the citations, which carry the same content already split by source.

When nothing is found

A retrieval that matches nothing is not an error: citations is empty and answer is the canned "I'm sorry, I don't have enough information to answer that question." That happens both when the project is not indexed for you and when the query simply has no match, so the result then also carries:

Property	Type	Description
indexed	boolean	Whether any content is indexed for you in this project. false means the project was never analysed by you, or was analysed under a different tenant.
importedItemCount	number	How many source elements are indexed for you in this project.
hint	string	Present only when indexed is false — what to do about it.

These three fields are absent when the retrieval found citations. Call knowledge_status for the full picture, including which of the two causes applies.

Scoping

Indexed knowledge is stored per user and per tenant, as stamped when the project was analysed. A retrieval only sees rows that match both: the user who owns the API token, and that user's currently selected tenant. So a project analysed by a colleague, or analysed while a different tenant was selected, returns no citations even though the project itself is readable. Re-run the analysis as the token's user to make it retrievable.

Example

"According to the project, when are we launching?"

{
  "projectId": "a1b2c3d4-...",
  "query": "When is the launch planned?",
  "maxResults": 5,
  "postProcess": true
}