KB Search
kb_searchSearch a governance knowledge base using natural-language queries, optional filters, and an in-force mode to return only currently applicable documents with ranked snippets.
Instructions
Full-text search across the KB.
Optional tier/category/status/type filters (status e.g. 'active', doc_type e.g. 'decision'). Returns ranked hits with snippets.
in_force: when true, HARD-filter to the in-force status class
(active/accepted/approved) AND the validity window (not expired, not
upcoming) before ranking, EXCLUDING superseded/deprecated/expired/
upcoming docs rather than only soft-downranking them. Composes with an
explicit status (both must hold). Use this when you want only guidance
that currently applies.
A doc past its valid_until date is EXCLUDED from every default search
result (not just in_force=True): an expired doc has no named successor
to outrank it, so left visible it could be the top hit and would govern.
Set include_expired=true to see it anyway; it then carries
freshness: "expired". A doc with a future valid_from ("upcoming")
stays visible in default search, flagged freshness: "upcoming"; only
in_force=true excludes it. validity_state is an audit-query facet:
one of "expired", "stale", or "expiring_within:N" (N days) to list
docs by validity condition; filtering for "expired" implies including
them regardless of include_expired. "stale" here matches only
recheck_by in the past -- narrower than the per-hit freshness: "stale" a hit can otherwise carry from verification age (see
KB_REVIEW_DUE_AFTER_DAYS); use kb_curate to list every document
currently showing freshness: "stale" for either reason.
abstain: when true, apply the signal gate. If the query matches no
discriminating column (title/tags/applies_when) it is treated as
out-of-scope and the search returns NO hits with abstained: true and an
abstain_reason, instead of surfacing a weak keyword match. A query with
a real signal retrieves normally. Distinguish abstained: true (no
governing rule) from an ordinary empty result (abstained: false).
verbose: False (default) returns a token-compact shape. Each hit is
{id, title, snippet} plus status only when a hit is NOT in-force
(superseded/deprecated), type when set, and freshness only when a
hit deviates (stale/expired/upcoming); the query echo, per-hit
path, and score are dropped (fetch a hit's full metadata with
kb_get(id); array order conveys rank). A compact hit additionally
carries in_force: false when the computed in-force predicate (the
single-sourced status + validity-window + not-inbox rule; never
stored in frontmatter) says the doc does NOT currently govern --
emitted deviation-only, so an in-force hit's compact shape is
unchanged. verbose=True restores the full legacy shape with query,
path, score, status, type, freshness, and the computed
in_force: bool on every hit, so a hit retrieved WITHOUT
in_force=true can still be checked for whether it may govern now.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tier | No | Optional tier filter such as T1, T2, T3, or T4. | |
| limit | No | Maximum number of results, clamped to 1..100. | |
| query | Yes | Natural-language search query. | |
| status | No | Optional frontmatter status filter. | |
| abstain | No | True returns an explicit abstention when the query has no KB signal. | |
| verbose | No | False returns the compact response; true includes all fields. | |
| category | No | Optional category filter within a tier. | |
| doc_type | No | Optional document type filter. | |
| in_force | No | True returns only currently governing documents. | |
| validity_state | No | Optional validity facet: expired, stale, or expiring_within:N. | |
| include_expired | No | True allows expired documents in search results. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||