kb_search
Read-only
Search a project's Knowledge Base for passages or whole files related to a natural-language query, with filters for collection, folder, skill, tags, and metadata.
Instructions
Search a project's Knowledge Base for passages or whole files related to a query. Use when the user asks what a client's files say about something, or a task needs a client's own files (such as their approved pricing or a template). The query is natural language, in the documents' language.
Filters, combined with AND: collection_id limits the search to one KB; folder to the files in a folder
and every folder below it; skill_id limits results to the files linked to that skill (a skill id from
find_skill or list_skills); tags to files carrying any of those tags (case doesn't matter; at most
20); metadata_filter to documents with those metadata values. folder is a folder's path, a result's
`path` without the file name ("/Templates", "/Templates/Pricing"; case doesn't matter), which matches
that folder in every KB of the project that has one (in one KB with collection_id), or a folder id
(a document's `parent_id` in kb_get_document), which is exactly one folder; a leading "/" makes it a
path. A folder that matches nothing is error "not_found" with reason
FOLDER_NOT_FOUND and `folder` set to it; a skill that doesn't exist or can't be used in this project
is reason SKILL_NOT_FOUND with `skill_id`. A filter that matches more than 2,000 files is refused
(reason FILTER_TOO_BROAD).
granularity "snippet" (the default) returns passages of up to 400 characters: max_results 1 to 20,
default 10. granularity "file" returns one result per file with the file's text in `content`, from
its start: max_results 1 to 10, default 5. `total_chars` is the file's full length and
`content_truncated` is true when `content` isn't the whole file; `content_next_cursor`, when set, is
the `cursor` from which kb_get_document returns the rest of that file. All files' text shares one
result-size budget, best match first, so a lower-ranked file can come with `content` null.
Each result names its file: `document_id`, `name`, `path` (its place in the KB's folders, e.g.
"/Templates/Pricing deck.pdf"), `collection` (the KB's name), `tags`, and `source_url` for a web page.
A long name or passage ends in "…"; a value too large to return (metadata, path, source_url) is null
and the result's `omitted_fields` names it with its size. `results_total` is how many results the
search returned (at most max_results, best first; more files may match); `results` holds the first
`count` of them that fit in one result. `filters` echoes the folder (a path written as "/A/B", or
the folder id), skill_id and tags as applied (normalised; null or [] when not set) and `files`, how
many files they allowed. `exhaustive` is true when every passage the filters allow was compared.
Returns only passages that came close to the query, nearest first, each with its source, `score`
(higher is closer) and `match`: "meaning" when the score reached the result's `min_score`, "words"
when the score is lower but the passage holds every word of the query (how exact names and codes are
found). An empty `results` means nothing in the searched files came close to the query.
Limit: the word rule looks only at the passages nearest in meaning, so a name or code can come back
empty when its passage is far in meaning from the rest of the query, or when the query mixes it with
words the passage doesn't hold. A code matches when written as in the document ("SKU-4417" finds
"SKU-4417", "SKU 4417" may not).Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project_id": "<project_id>",
"query": "<query>"
},
"name": "kb_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| query | Yes | ||
| folder | No | ||
| skill_id | No | ||
| project_id | Yes | ||
| granularity | No | snippet | |
| max_results | No | ||
| collection_id | No | ||
| metadata_filter | No |