kb_query
Look up knowledge base entities by id, type, tags or source file, or ask typed fact questions to get matching fact rows and schema details.
Instructions
Read entities from the KB with exact filters, or ask typed fact questions. Use for lookup by id, type, tags or sourceFile, and for precise questions about modeled facts: predicate facts by name with named arguments (predicate + where), property facts of a subject (subjectKey + propertyKey), or the catalog of facts of one kind (factKind; 'predicate_schema' lists the predicates you can ask about with their argument names and constants). Typed answers return matching fact rows plus factQuery: the schema used, distinct counts, values that do exist when nothing matched, warnings about the question and the next call to make. Read-only. Tags filter by metadata tags only, not entity IDs.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Optional exact entity ID. Example: 'REQ-cli-gc'. If omitted, returns matching entities by other filters. | |
| args | No | Positional argument values for predicate when it has no schema; null matches any value. Example: ['admin', null, null, 'allow']. Prefer where. | |
| tags | No | Optional tag filter. Matches entities that contain any provided tag. Example: ['security','billing']. | |
| type | No | Optional entity type filter. Allowed: req, scenario, test, adr, flag, event, symbol, fact. Example: 'req'. | |
| limit | No | Optional max rows to return after filtering. Default: 100 when omitted. Example: 25. | |
| scope | No | Optional: 'current_requirements' keeps only facts a current (not superseded or retired) requirement requires. | |
| where | No | Named argument values for predicate, order-free, using the argument names from the predicate's schema. Example: {actor: 'admin', decision: 'allow'}. An unknown name returns a warning with the declared names; no match returns the values that do exist. | |
| offset | No | Optional zero-based pagination offset. Default: 0. Example: 50 to skip first 50 rows. | |
| distinct | No | Optional argument name to count distinct values of across the matching predicate facts, e.g. distinct: 'role' with predicate 'has_role' and where {user: 'alice'} answers how many roles alice has. | |
| factKind | No | Typed fact filter: list facts of one kind with their typed fields. 'predicate_schema' returns the catalog of askable predicates (argument names, constants, fact counts). Example: 'predicate_schema'. | |
| polarity | No | Optional polarity filter for predicate facts. Default: both. | |
| namespace | No | Optional predicate namespace when the same name exists in several. Default: any namespace. | |
| predicate | No | Typed fact filter: predicate name to ask about, e.g. 'has_role' or 'permission_rule'. Combine with where for named arguments. Returns every stored fact of that predicate with its arguments, polarity and allow/deny effect. | |
| sourceFile | No | Optional source-file substring filter. Example: 'src/auth/login.ts'. Uses KB source linkage, not file-system scanning. | |
| subjectKey | No | Typed fact filter: dotted subject key whose property facts to list, e.g. 'user.role_assignment'. Combine with propertyKey for one property. | |
| includeBody | No | With id only: also return the entity's authored Markdown body (the prose after its front matter) as body {id, path, text}, so a stale statement in it can be corrected; kb_upsert document.body replaces it. Default: false. | |
| propertyKey | No | Optional property key under subjectKey, e.g. 'max_roles'. Returns operator, value and unit of each fact. | |
| workspaceRoot | No | Optional absolute path of the workspace this call is about when it differs from the one the server started in, for example the git worktree you are working in. The server answers from that workspace's knowledge base when it is a worktree of the same repository or lies under the client's MCP roots; otherwise it answers from its own workspace and adds a workspace_mismatch diagnostic. Host hooks fill this in automatically where available. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| error | No | ||
| status | Yes | ||
| effects | Yes | ||
| operation | Yes | ||
| diagnostics | Yes | ||
| nextActions | Yes | ||
| kibiProtocol | Yes | ||
| resultVersion | Yes |