Kibi

Overview Schema Source Related Servers Discussions Admin

kb_delete

Destructive

Delete knowledge-base entities by ID or exact relationship triples after dependency checks; preview removals with dryRun and apply a deletion plan for authored sources.

Instructions

Delete entities by ID, or exact relationship triples. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. An entity authored in a Markdown or YAML source is not deleted directly: the call writes nothing and returns outcome plan_returned with a hash-bound deletionPlan and a nextActions entry holding the exact kb_apply_plan input ({plan, approvedPlanHash}); apply that unmodified, or repeat this call with approvedPlanHash = deletionPlan.planHash to apply the freshly computed plan in one step (a stale or different hash fails with DELETE_PLAN_HASH_MISMATCH and writes nothing). Authored requirements are never deleted: outcome supersession_required points to kb_upsert with a supersedes relationship. dryRun:true previews any delete and writes nothing. Side effects: mutates and saves KB and authored sources; skips entities with dependents; dryRun and plan_returned write nothing.

Input Schema

Name	Required	Description
`ids`	No	Entity IDs to delete after dependency checks.
`dryRun`	No	Preview without writing. Relationship and direct entity deletes run their preflight and return outcome dry_run with wouldDelete counts, the sourceWrites (paths and hashes) a commit would make, and skippedEffects. Authored ids return the same deletion plan as without dryRun.
`relationships`	No	Exact relationship triples to retract, including legacy shard records.
`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.
`approvedPlanHash`	No	With ids only: the deletionPlan.planHash a prior call for the same ids returned. The plan is recomputed and applied through kb_apply_plan when its hash still matches; a mismatch fails with DELETE_PLAN_HASH_MISMATCH and writes nothing. Not allowed with relationships or dryRun.

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.

First observedv0.1.0Oct 17, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare destructive=true and non-idempotent, but the description goes far beyond them: it discloses that entities with dependents are skipped, that authored entities trigger a hash-bound plan instead of a direct write, the exact DELETE_PLAN_HASH_MISMATCH failure mode, and what dryRun and plan_returned write (nothing). This is unusually rich behavioral disclosure.

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

Conciseness4/5

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

Front-loaded with the core action, and the long plan-workflow sentence is dense but justified by genuine complexity. It reads as one unbroken paragraph, so structural breaks would improve scanability; the 'Use only for intentional removals' sentence is also somewhat redundant with the following clause.

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

Completeness5/5

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

For a destructive, multi-path tool with an output schema already present, the description covers side effects, dependency handling, the plan/hash workflow, dry-run semantics, and failure outcomes. An agent has everything needed to call it correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description adds real value on top by explaining how ids + approvedPlanHash interact (a stale hash fails; must match), and by distinguishing dryRun behavior for authored vs direct deletes. It stops short of full coverage but clearly exceeds schema-only semantics.

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?

Opens with a concrete verb and two distinct resources: 'Delete entities by ID, or exact relationship triples.' This distinguishes it from kb_upsert, kb_apply_plan, and the read-only siblings without ambiguity.

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

Usage Guidelines5/5

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

Explicitly states when to use it ('intentional removals after dependency checks'), when not to ('not as a bulk cleanup shortcut'), and names the alternative path (kb_upsert with a supersedes relationship for authored requirements, kb_apply_plan for plan application). Routing guidance is complete.

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

Deploy Server