Knowledge tool reference

Overview

The knowledge tool is one tool with actions. Instead of a separate tool for search, reading, listing and computing, a model gets one name, search_knowledge_base, and picks what it does with the action field. One description carries the rules once, and discover tells the model what exists before it guesses.

There is one tool behind every door. The SDKs, the HTTP API, the MCP server and agents in the app all call the same tool, so an answer cannot differ between them.

Where to call it

All doors need a project API key, made in the promptev app under the project’s API keys. The key reads only its own project.

From the SDKs

The action is the first argument and its fields follow. The list of actions is exported as KNOWLEDGE_ACTIONS.

pip install promptev

from promptev import PromptevClient, KNOWLEDGE_ACTIONS

client = PromptevClient(api_key="fk_...")   # a project API key

overview = client.search_knowledge_base("discover")
found = client.search_knowledge_base("search", query="how many days do customers have to ask for a refund", top_k=5)
for hit in found["hits"]:
    print(hit["document_name"], hit["score"])

# Async: await client.asearch_knowledge_base("search", query="how many days do customers have to ask for a refund")

npm install @promptev/client

import { PromptevClient, KNOWLEDGE_ACTIONS } from "@promptev/client";

const client = new PromptevClient({ apiKey: "fk_..." }); // a project API key

const overview = await client.searchKnowledgeBase("discover");
const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
for (const hit of found.hits) console.log(hit.document_name, hit.score);

Over HTTP

POST https://api.promptev.ai/api/v1/knowledge with a JSON body: action plus that action’s fields. The answer is the tool’s JSON. See the HTTP API reference and the command line page.

curl -X POST https://api.promptev.ai/api/v1/knowledge \
  -H "Authorization: Bearer fk_..." \
  -H "Content-Type: application/json" \
  -d '{"action": "search", "query": "how many days do customers have to ask for a refund", "top_k": 5}'

Over MCP

Every project has an MCP server. Its search_knowledge_base tool is this tool, with the same actions and fields, and its upload_document tool adds a file. Any MCP client can use it, such as Claude, n8n or Zapier. The model reads the tool’s description and sends the fields as JSON.

In agents

Agents you build in promptev use the knowledge base on their own. You do not call the tool for them: they pick the action, and the answer cites its sources.

Fields

Every field a caller may set. Only action is always required; each action checks its own required fields.

A search hit’s document_id is a system id. Content identifiers written inside documents, such as invoice numbers, belong in query, never in document_id.

The 13 actions

The order below is the order of KNOWLEDGE_ACTIONS. Examples show the SDK call; over HTTP and MCP the same fields go as JSON. Answers are shortened: ... marks left-out content, and // comments are explanations, not part of the answer.

discover

Needs: Always available

When to use it. First, whenever the agent does not already know what is in scope. One call returns the documents, what is inside each one and which actions are on, so later calls can use real sheet, column, section and field names.

answer = client.search_knowledge_base("discover")

const answer = await client.searchKnowledgeBase("discover");

{
  "success": true,
  "documents": [
    {"id": "...", "name": "costs.xlsx", "source_id": "finance",
     "kind": "spreadsheet",            // "spreadsheet" or "text", decided by MIME
     "document_type": "...", "mode": "hybrid", "failure_reason": null,
     "structure": {...}}               // sheets / sections + last_page / keys / chunks
  ],
  "count": 50, "has_more": true,
  "next_cursor": "...", "next_page": {"action": "discover", "cursor": "..."},
  "document_types": [...],             // census of the whole scope
  "fields_by_type": {...},             // extracted field names, types, counts
  "available_actions": {"search": "...", "compute": "... (OFF)", ...},
  "next_action": {"for a clause or a fact": {"action": "search", "query": "..."}, ...}
}

search

Needs: Always available

When to use it. Questions answered by reading text. To look up an ID, code, SKU or invoice number, send the bare identifier alone (for example "2525"), not the whole question.

answer = client.search_knowledge_base("search", query="annual leave carry over")

const answer = await client.searchKnowledgeBase("search", { query: "annual leave carry over" });

{
  "success": true,
  "hits": [
    {"document_id": "...", "document_name": "HR leave policy", "chunk_text": "...",
     "score": 0.83, "source_id": "hr", "chunk_idx": 4}
  ],
  "usage": {...},
  "hint": {"action": "compute", "reason": "aggregate question over a spreadsheet"}  // only on a mixed scope
}

get_doc

Needs: Always available

When to use it. Reading one whole document by its system id, taken from discover, list or a search hit. Never pass an invoice number or other content identifier here.

answer = client.search_knowledge_base("get_doc", document_id="3f2b8c1e-5a4d-4e8f-9b61-2c7d0a9e4f10")

const answer = await client.searchKnowledgeBase("get_doc", { document_id: "3f2b8c1e-5a4d-4e8f-9b61-2c7d0a9e4f10" });

{
  "success": true,
  "document": {
    "id": "...", "name": "...", "text": "...", "acl": [...], "status": "completed",
    ...,
    "failure_reason": null,      // one FAILURE_REASONS code, or null
    "failure_message": null      // the fixed sentence for that code
  }
}

get_docs

Needs: Always available

When to use it. Several whole documents at once, by id.

answer = client.search_knowledge_base("get_docs", document_ids=["3f2b8c1e-5a4d-4e8f-9b61-2c7d0a9e4f10", "8d1e7f02-6b3c-4a59-8e2d-1f0c9b7a6e35"])

const answer = await client.searchKnowledgeBase("get_docs", { document_ids: ["3f2b8c1e-5a4d-4e8f-9b61-2c7d0a9e4f10", "8d1e7f02-6b3c-4a59-8e2d-1f0c9b7a6e35"] });

{
  "success": true,
  "documents": [{...}, {...}],   // same per-document shape as get_doc
  "count": 2,
  "remaining_document_ids": ["..."],                               // only when the budget ran out
  "next_page": {"action": "get_docs", "document_ids": ["..."]}
}

get_chunks

Needs: Always available

When to use it. Walking one long document in order, a range at a time, or reading around a search hit by starting at its chunk_idx.

answer = client.search_knowledge_base("get_chunks", document_id="3f2b8c1e-5a4d-4e8f-9b61-2c7d0a9e4f10", start=4)

const answer = await client.searchKnowledgeBase("get_chunks", { document_id: "3f2b8c1e-5a4d-4e8f-9b61-2c7d0a9e4f10", start: 4 });

{
  "success": true,
  "document_id": "...", "total_chunks": 120, "start": 4, "end": 28,
  "chunks": [{"position": 4, "text": "...", "language": "en"}, ...],
  "has_more": true, "next_start": 29,
  "next_page": {"action": "get_chunks", "document_id": "...", "start": 29}
}

list

Needs: Always available

When to use it. Browsing documents without searching. Cheaper than discover: it does not fetch structure, fields or the census.

answer = client.search_knowledge_base("list", source_ids=["hr"], limit=20)

const answer = await client.searchKnowledgeBase("list", { source_ids: ["hr"], limit: 20 });

{
  "success": true,
  "documents": [{"id": "...", "name": "...", "source_id": "hr", "kind": "text",
                 "document_type": null, "mode": "hybrid", "failure_reason": null,
                 "status": "completed"}],
  "count": 20, "has_more": true,
  "next_cursor": "...", "next_page": {"action": "list", "cursor": "..."}
}

query_meta

Needs: On unless discover marks it (OFF)

When to use it. The structured fields a question names (dates, amounts, parties) and each document’s value for them. It does not filter or compare by value: read the values and compare them yourself.

answer = client.search_knowledge_base("query_meta", query="invoice amount and invoice date")

const answer = await client.searchKnowledgeBase("query_meta", { query: "invoice amount and invoice date" });

{
  "success": true,
  "question": "...",
  "resolved_fields": [...],
  "documents": [{"id": "...", "source_id": "...", "name": "...",
                 "document_type": "...", "structured_data": {...}, ...}],
  "count": 3
}

compute

Needs: Code execution on for the workspace (on by default)

When to use it. Any figure derived from spreadsheets (total, average, count, ranking, margin, comparison) and finding the exact row that matches one id or value. It runs over every row of the sheets in scope, not a sample.

answer = client.search_knowledge_base("compute", query="total amount by region in costs.xlsx")

const answer = await client.searchKnowledgeBase("compute", { query: "total amount by region in costs.xlsx" });

{
  "success": true,              // whether the generated code ran
  "result": ...,
  "code": "...", "stdout": "", "error": null,
  "execution_time": 0.41,
  "documents_used": ["..."],
  "provider_tokens": {"llm_input": 812, "llm_output": 164},
  "attempts": 1                 // 1 or 2 code-generation calls
}

map_reduce

Needs: On unless discover marks it (OFF)

When to use it. Asking the same question of every document in scope and getting one answer per document, for example "which contracts mention X", where search would return a handful of passages and miss the rest. Not for figures: that is compute.

answer = client.search_knowledge_base("map_reduce", query="Does this contract have an auto-renewal clause?")

const answer = await client.searchKnowledgeBase("map_reduce", { query: "Does this contract have an auto-renewal clause?" });

{
  "success": true,
  "results": [
    {"document_id": "...", "document_name": "...", "data": {...}},
    {"document_id": "...", "document_name": "...", "error": "..."}
  ],
  "processed": 24, "failed": 1, "considered": 25,
  "hint": {"action": "compute", "reason": "..."}   // only when some targets are spreadsheets
}

get_neighbors

Needs: Documents uploaded in graph mode (Context Graph)

When to use it. What is one step from a named thing, and which way each link points.

answer = client.search_knowledge_base("get_neighbors", entity="Acme Corp")

const answer = await client.searchKnowledgeBase("get_neighbors", { entity: "Acme Corp" });

{
  "success": true,
  "entity": {"id": "...", "name": "acme corp", "type": "ORG"},
  "neighbors": [{"id": "...", "name": "...", "type": "PERSON", "category": "MEMBERSHIP",
                 "label": "works_for", "evidence": "...", "direction": "incoming"}],
  "count": 7
}

traverse

Needs: Documents uploaded in graph mode (Context Graph)

When to use it. Everything within a few steps of a named thing.

answer = client.search_knowledge_base("traverse", entity="Acme Corp", depth=2, category="HIERARCHICAL")

const answer = await client.searchKnowledgeBase("traverse", { entity: "Acme Corp", depth: 2, category: "HIERARCHICAL" });

{
  "success": true,
  "entity": {"id": "...", "name": "...", "type": "ORG"},
  "paths": [{"target_id": "...", "target": "...", "target_type": "PERSON",
             "category": "HIERARCHICAL", "label": "reports_to", "evidence": "...", "hops": 2}],
  "count": 12
}

find_related

Needs: Documents uploaded in graph mode (Context Graph)

When to use it. Connections of a kind across the corpus, with no starting entity (an entity is refused; for how two named things connect, traverse from one). Also the way in when every name in an answer is masked: take a source_id or target_id from its result.

answer = client.search_knowledge_base("find_related", category="CREATION", entity_type="PRODUCT")

const answer = await client.searchKnowledgeBase("find_related", { category: "CREATION", entity_type: "PRODUCT" });

{
  "success": true,
  "relationships": [{"source_id": "...", "source": "...", "source_type": "ORG",
                     "target_id": "...", "target": "...", "target_type": "PRODUCT",
                     "category": "CREATION", "label": "makes", "evidence": "..."}],
  "count": 9
}

community_summary

Needs: Context Graph documents, and community summaries on

When to use it. The themes each source groups into, ranked against a question.

answer = client.search_knowledge_base("community_summary", query="supplier risk")

const answer = await client.searchKnowledgeBase("community_summary", { query: "supplier risk" });

{
  "success": true,
  "communities": [{"summary": "...", "entity_count": 14, "relationship_count": 22,
                   "hierarchy_level": 0, "relevance": 0.7121}],
  "count": 3
}

Refusals and off actions

Which actions can run depends on the workspace and on how its documents were uploaded:

An off action, if called anyway, returns a fixed sentence. The common refusals look like this:

// Aggregate question over a scope that is all spreadsheets (search, query_meta)
{"success": false,
 "error": "these documents are spreadsheets; searching their rows would answer from a sample. Use compute over the whole sheet.",
 "next_action": {"action": "compute", "query": "total spend by region",
                 "suggestion": {"frame_key": "...", "measure": "amount", "group_by": "region"}}}

// An action that is off for this workspace
{"success": false, "error": "compute is off: ..."}

// document_ids sent to an action that does not honour it
{"success": false, "error": "document_ids is not honored by get_doc ..."}

In the spreadsheet refusal, next_action.query is the question handed back, so the redirect is a call the model can make. suggestion is vocabulary, not code: frame_key is the name compute will give the newest sheet in scope, measure its first numeric column, group_by its first text column. Any of them can be null. A scope that mixes text and spreadsheets is still searched and only gets an extra hint.

Answers may also carry next_page or next_action: the next call, already filled in. The tool description tells the model to follow it rather than guess.

Over the HTTP API and the SDKs a refusal arrives as a 422 whose message is the error sentence; over MCP the whole answer, next_action included, is returned.

Permissions and scope

Every answer contains only what the caller may see. A project API key reads its whole project and nothing outside it. A person in the app, or an agent answering a person, sees only the documents that person’s access allows.

Only six actions honour document_ids (search, compute, get_docs, map_reduce, discover, list). The others refuse it rather than answer over the whole scope as if it had been honoured.

Who may see which document is set in the app when a source is added or a file is uploaded. See Settings.

Redaction

A project can have redaction rules, set in the app on the project’s Redaction page. They mask what the knowledge base returns, in every action: document text, passages, search hits, computed results and graph answers. A caller cannot turn them off, because they are not a field.

More

What a call costs

A knowledge call costs 1 credit. A search costs 1 more, or 5 more when the Context Graph is searched. From the SDKs and the HTTP API there is no extra API-call charge. Uploading costs 1 credit per page, slide or MB (minimum 1).

Why a document failed

A failed document carries failure_reason, one fixed code, with failure_message as its fixed sentence. A later successful upload clears both.

The provider and dimension codes matter most to a workspace on its own embedding model; see Settings. An unrecognised code reads as unknown rather than as no failure.