Kibi

Overview Schema Source Related Servers Discussions Admin

kb_apply_plan

Destructive

Applies an approved Kibi plan safely: revalidates its SHA-256 hash and live snapshots, then commits all changes atomically with recovery if interrupted.

Instructions

Apply an explicitly approved kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or entity-deletion plan after revalidating its canonical hash and live snapshots. Compile plans apply all-or-nothing: a durable journal records every source write and store mutation before the first write, all steps commit in one store transaction, and an interrupted application is completed or rolled back by the next mutating call. Bootstrap actions are dependency-ordered, sequential, source-first, and recoverable from a typed journal.

Input Schema

Name	Required	Description
`plan`	No	The complete kibi.bootstrap-plan.v1, kibi.compile-plan.v1, kibi.migration-plan.v2, or hash-bound kibi.entity-deletion-plan.v1 object. Migration plans require approvedActionIds and reject blocked actions and review actions Kibi cannot execute.
`async`	No	MCP only. When true, start the apply as a background job and return a kibi.job.v1 receipt immediately instead of holding the request open; poll kb_job_status with the returned jobId for the final result. Use for large bootstrap plans (hundreds of actions) that can outlast a client's request timeout. The MCP server registers kb_job_status only when KIBI_MCP_OPTIONAL_TOOLS includes it; otherwise async applies synchronously. A synchronous apply sends notifications/progress after each bootstrap action when the request carries a progressToken. The CLI ignores this field.
`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	Exact SHA-256 planHash returned by kb_plan_bootstrap, kb_compile_intent, or another approved plan after human review.
`approvedActionIds`	No	Required for migration-plan.v2. Exact action IDs explicitly approved for this application: automatic actions, or review actions with a cli invocation that Kibi executes only when approved by id (for example semantic_inventory_rederive_drop_grounding).
`recoveryJournalId`	No	Typed recovery journal identifier returned by a committed_with_repairs result or a PLAN_APPLY_RECOVERY_REQUIRED error. Recovery replays only the immutable journal and never the original plan request; a compile-plan journal (plan-apply-*) is completed or rolled back deterministically and reports which. A bootstrap journal left `applying` by a process that died mid-action is resumed without edits: the interrupted action is re-applied and a source lock held by the dead process is reclaimed and recorded in the journal.

Output Schema

Name	Required	Description
`data`	Yes	Synchronous apply result, or a kibi.job.v1 receipt when async:true detached the apply into a background job (poll kb_job_status with the jobId).
`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.4/5.0

Behavior5/5

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

Annotations declare destructive/non-idempotent/non-read-only, and the description goes well beyond them: compile plans are all-or-nothing, a durable journal records every source write and store mutation before the first write, all steps commit in one transaction, and an interrupted apply is completed or rolled back by the next mutating call. Bootstrap ordering (dependency-ordered, sequential, source-first) and typed-journal recoverability are disclosed too.

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?

Three sentences, front-loaded with the action and the approval precondition, then the transactional guarantees. Dense and information-bearing throughout, though the stacked plan-type enumeration and journal terminology make it slightly heavy for a reader orienting quickly.

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?

An output schema exists so return values need not be explained, and the description supplies the missing high-stakes context for a destructive, non-idempotent tool: atomicity, journal-before-write ordering, and crash/rollback behavior. Nothing an agent needs to decide to call this is absent.

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 all six parameters are already documented, including async, workspaceRoot, approvedActionIds, and recoveryJournalId. The description adds only framing (plan must be approved, deduped plan types) and no syntax, format, or default detail beyond the schema, so the baseline 3 applies.

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?

Names a specific verb (apply) and resource (an approved kibi plan) and enumerates the exact plan types accepted (bootstrap-plan.v1, compile-plan.v1, migration-plan.v2, entity-deletion). An agent can distinguish it from the plan-producing siblings (kb_plan_bootstrap, kb_compile_intent) without opening the schema.

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?

Clearly conditions use on the plan being 'explicitly approved' and on hash/live-snapshot revalidation, and the schema ties approvedPlanHash back to kb_plan_bootstrap/kb_compile_intent. However, no explicit when-not guidance or named alternative (e.g., 'use kb_plan_bootstrap first') is given for an agent that arrives without an approved plan.

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

Deploy Server