Kibi

Overview Schema Source Related Servers Discussions Admin

kb_search

Read-onlyIdempotent

Ask the knowledge base a question or search it to retrieve governing requirements, linked facts, ADRs, scenarios, and tests before changing behavior; low-confidence queries abstain.

Instructions

Ask the KB a question or search it. Default intent-v1 ranking accepts questions, host-agent semantic facets and changed-code source locations, returns evidence, abstains below its confidence threshold and adds an answer layer: the current requirements that govern the topic, what must stay true (linked facts), why (ADRs) and what verifies it (scenarios, tests). A weak answer may add queryAnalysis.hints from a search-hints plugin: requirements the question may mean, to re-ask with. Use before changing behavior, then kb_query for exact follow-up. No mutation side effects.

Input Schema

Name	Required	Description
`type`	No	Optional entity type filter to narrow discovery. Example: 'req'.
`hints`	No	Intent-v1 only, first page only. When true (default) and the project activates a kibi.search-hints.v1 plugin, a weak or abstained answer adds queryAnalysis.hints: requirements the question may mean, to re-ask with. Hints never change results or the answer layer.
`limit`	No	Optional max rows to return after ranking. Default: 10; raise it or page with offset when the answer layer is not enough.
`query`	Yes	Free-text query for metadata and markdown body discovery. Example: 'OAuth login flow'.
`answer`	No	Intent-v1 only, first page only. When true (default) the result includes an answer layer: current governing requirements with their linked facts, scenarios, tests and ADRs, superseded requirements listed separately, and observation facts labelled as notes. Bounded in size; discovery, not proof.
`fields`	No	Optional result detail. 'summary' returns identifying metadata plus the match snippet for discovery. Use 'full' to include complete entity bodies, or follow up with kb_query for the exact entities you need.
`offset`	No	Optional zero-based pagination offset. Default: 0.
`minScore`	No	Intent-v1 acceptance threshold between 0 and 1. Low-confidence queries abstain instead of returning misleading matches.
`rankingMode`	No	Optional deterministic ranking mode. Default intent-v1: question-aware ranking with semantic facets, source-aware evidence, graph boosts, superseded demotion and abstention. Use legacy for the older lexical ranking.
`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.
`semanticFacets`	No	Optional host-agent semantic interpretation. Kibi uses these strings as deterministic aliases/facets; ranking never calls a model.
`sourceLocations`	No	Optional changed-code locations. Results are matched to source-linked symbols/entities and include source evidence.

Output Schema

Name	Required	Description	Default
`data`	Yes
`error`	No
`status`	Yes
`effects`	Yes
`operation`	Yes
`diagnostics`	Yes
`nextActions`	Yes
`kibiProtocol`	Yes
`resultVersion`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.1.6Nov 1, 2026

addedInput schema / properties / hints

Added value: +{
+  "description": "Intent-v1 only, first page only. When true (default) and the project activates a kibi.search-hints.v1 plugin, a weak or abstained answer adds queryAnalysis.hints: requirements the question may mean, to re-ask with. Hints never change results or the answer layer.",
+  "type": "boolean"
+}

changedInput schema / properties / semanticFacets / description

Previous value: -"Optional host-agent semantic interpretation. Kibi uses these strings as deterministic aliases/facets; it does not call a model itself."New value: +"Optional host-agent semantic interpretation. Kibi uses these strings as deterministic aliases/facets; ranking never calls a model."

First observedv0.1.0Oct 17, 2026

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real behavioral context: abstention below a confidence threshold, an answer layer with superseded requirements and observation facts, bounded size ('discovery, not proof'), and that hints never change results. The closing 'No mutation side effects' merely restates the annotations, and much of the hints/answer prose describes output fields the output schema likely already documents.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in sentence one, but the remainder is dense jargon ('queryAnalysis.hints', 'host-agent semantic facets', 'superseded demotion') packed into long clauses. Several phrases describe return-value mechanics rather than tool selection, which dilutes a description that could be tighter for an agent scanning candidates.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter tool with nested objects and an output schema, the description conveys the overall model (question-answering search, abstention, answer layer, follow-up with kb_query) and leaves parameter detail to the well-covered schema. A brief note on the low-confidence abstain path's shape would close the last gap, but nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including semanticFacets, sourceLocations and workspaceRoot is already explained in the schema. The description only adds the framing that intent-v1 accepts questions, facets and changed-code locations, without new syntax, defaults, or constraints — baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a concrete verb+resource ('Ask the KB a question or search it') and immediately characterizes the default ranking behavior (intent-v1, question-aware, evidence-returning, abstaining). It explicitly differentiates from the sibling kb_query ('for exact follow-up'), so an agent can choose between them without reading schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use before changing behavior, then kb_query for exact follow-up' gives an explicit trigger and names the follow-up alternative, and the hints sentence explains the re-ask loop when an answer is weak. It stops short of saying when NOT to use this tool versus other siblings like kb_find_gaps or kb_graph.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server