kin

Official

Overview Schema Source Related Servers Discussions Admin

kin_mutate

Destructive

Commit targeted code entity changes atomically in a single call. Patch, update, create, or remove entities together, ensuring consistency.

Instructions

Commit targeted entity changes atomically, in one call.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`summary`	No	One sentence for the history.
`operations`	Yes	Applied atomically.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.7.17Sep 30, 2026

changedInput schema / properties / operations / description

Previous value: -"Array of mutation operations to validate and commit atomically"New value: +"Applied atomically."

removedInput schema / properties / operations / items / oneOf

Removed value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "description": {
-        "description": "Human-readable explanation of this change.",
-        "type": "string"
-      },
-      "target": {
-        "description": "Repository-relative path of the file to retire, such as \"src/parser.py\". It must be a path repository authority already tracks; a path the graph has never seen is refused.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "verb": {
-        "description": "Retire a tracked file. This is the only operation that removes a file, along with every entity derived from it and every edge incident to those entities.",
-        "enum": [
-          "delete",
-          "remove"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "verb",
-      "target",
-      "description"
-    ],
-    "title": "Retired source file",
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "description": {
-        "description": "Human-readable explanation of this change.",
-        "type": "string"
-      },
-      "destination": {
-        "description": "Repository-relative path the file moves to. It must not be tracked already, and it follows the same path rules as `target`: no leading slash, no \"..\", and no Kin or Git control component.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "target": {
-        "description": "Repository-relative path the file lives at now. It must be a path repository authority already tracks.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "verb": {
-        "description": "Relocate a tracked file. Entity identity, history, and incoming edges survive the move, which is what separates this from a delete followed by a create.",
-        "enum": [
-          "rename",
-          "move"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "verb",
-      "target",
-      "destination",
-      "description"
-    ],
-    "title": "Renamed source file",
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "body": {
-        "description": "The file's complete UTF-8 source text. Kin parses it with the same extractor the ingest path uses, so every entity in it enters the graph, and writes the file into the working directory when the transaction commits. You do not need to write the file yourself first.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "description": {
-        "description": "Human-readable explanation of this change.",
-        "type": "string"
-      },
-      "target": {
-        "description": "Repository-relative path of the new file, such as \"src/parser.py\". No leading slash, no \"..\", and no Kin or Git control component. A path the graph already tracks is refused; rewrite that one with verb 'replace' instead.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "verb": {
-        "description": "Admit a source file the graph has never seen. This is the only operation that introduces a new file.",
-        "enum": [
-          "create",
-          "add",
-          "insert"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "verb",
-      "target",
-      "body",
-      "description"
-    ],
-    "title": "New source file",
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "body": {
-        "description": "The file's complete new UTF-8 source text, never a fragment or a diff. Kin reparses it with the same extractor the ingest path uses, so entities the new text adds enter the graph, entities it drops leave it, and the rest keep their identity. A body identical to the tracked contents is refused as an empty change.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "description": {
-        "description": "Human-readable explanation of this change.",
-        "type": "string"
-      },
-      "target": {
-        "description": "Repository-relative path of the file to rewrite, such as \"src/parser.py\". It must be a path repository authority already tracks; a path the graph has never seen is refused, and 'create' is the verb for it.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "verb": {
-        "description": "Rewrite a tracked file from its complete new text. This is the operation to use when you hold a path and the file's new contents, which is what a local edit or write leaves you holding.",
-        "enum": [
-          "replace",
-          "overwrite"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "verb",
-      "target",
-      "body",
-      "description"
-    ],
-    "title": "Replaced source file",
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "body": {
-        "description": "The entity's complete new UTF-8 source text, including its own leading indentation. Do not submit a truncated retrieval body.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "description": {
-        "description": "Human-readable explanation of this change.",
-        "type": "string"
-      },
-      "target": {
-        "description": "Exact repository entity UUID or unambiguous exact entity name.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "verb": {
-        "description": "Update an existing source entity.",
-        "enum": [
-          "update",
-          "modify"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "verb",
-      "target",
-      "body",
-      "description"
-    ],
-    "title": "Entity source body edit",
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "body": {
-        "description": "Full new UTF-8 source text for a source-bound Entity update. Omit for Relation operations.",
-        "type": "string"
-      },
-      "description": {
-        "description": "Human-readable explanation of this change.",
-        "type": "string"
-      },
-      "payload": {
-        "description": "Exact mutation payload: {\"Entity\": { ...existing entity identity... }} or {\"Relation\": {\"from\": \"...\", \"to\": \"...\", \"kind\": \"...\"}}.",
-        "type": "object"
-      },
-      "target": {
-        "description": "Exact repository entity UUID for an Entity payload; empty string for a Relation payload.",
-        "type": "string"
-      },
-      "verb": {
-        "description": "Entity or relation mutation verb.",
-        "enum": [
-          "create",
-          "add",
-          "upsert",
-          "insert",
-          "update",
-          "modify",
-          "delete",
-          "remove"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "verb",
-      "target",
-      "payload",
-      "description"
-    ],
-    "title": "Structured entity or relation mutation",
-    "type": "object"
-  }
-]

addedInput schema / properties / operations / items / properties

Added value: +{
+  "body": {
+    "description": "Complete new entity source for update.",
+    "type": "string"
+  },
+  "description": {
+    "description": "What this op changes.",
+    "type": "string"
+  },
+  "payload": {
+    "additionalProperties": false,
+    "description": "Required. body only with EntitySourceBase. In an empty repository, create with EntityCreate addressed to a unit.",
+    "oneOf": [
+      {
+        "required": [
+          "EntitySourcePatch"
+        ]
+      },
+      {
+        "required": [
+          "EntitySourceBase"
+        ]
+      },
+      {
+        "required": [
+          "EntityCreate"
+        ]
+      },
+      {
+        "required": [
+          "UnitImports"
+        ]
+      },
+      {
+        "required": [
+          "EntityRemove"
+        ]
+      }
+    ],
+    "properties": {
+      "EntityCreate": {
+        "additionalProperties": false,
+        "description": "Unit form (empty repository, any Go kind): repository_base and unit, target the name. Anchored form (functions): source_base and placement, target the anchor UUID.",
+        "properties": {
+          "body": {
+            "description": "The declaration only: no package clause or imports.",
+            "minLength": 1,
+            "type": "string"
+          },
+          "imports": {
+            "description": "Import paths it needs.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "kind": {
+            "enum": [
+              "function",
+              "method",
+              "struct",
+              "class",
+              "interface",
+              "type",
+              "const",
+              "var"
+            ],
+            "type": "string"
+          },
+          "name": {
+            "description": "Name, or Receiver.Method.",
+            "type": "string"
+          },
+          "placement": {
+            "enum": [
+              "sibling_after",
+              "new_source_unit"
+            ],
+            "type": "string"
+          },
+          "repository_base": {
+            "description": "Unchanged repository_base from session, status or the last mutate.",
+            "type": "object"
+          },
+          "source_base": {
+            "description": "Unchanged source_base from a current get_entity_source read.",
+            "type": "object"
+          },
+          "unit": {
+            "description": "{language:\"go\", package:\".\" or \"internal/store\", name: package name, role:\"source\" or \"test\"}",
+            "type": "object"
+          }
+        },
+        "required": [
+          "name",
+          "kind",
+          "body"
+        ],
+        "type": "object"
+      },
+      "EntityRemove": {
+        "additionalProperties": false,
+        "description": "Remove one source-bound top-level leaf function in Rust, Python or Go, preserving its artifact and siblings. No whole-file removal is admitted.",
+        "properties": {
+          "source_base": {
+            "description": "Unchanged source_base from a current get_entity_source read.",
+            "type": "object"
+          }
+        },
+        "required": [
+          "source_base"
+        ],
+        "type": "object"
+      },
+      "EntitySourceBase": {
+        "description": "Unchanged source_base from a current get_entity_source read; verb update with the complete body.",
+        "type": "object"
+      },
+      "EntitySourcePatch": {
+        "additionalProperties": false,
+        "properties": {
+          "edits": {
+            "description": "Each old_text must occur exactly once. Anchors must not overlap; all address the original entity body.",
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "new_text": {
+                  "type": "string"
+                },
+                "old_text": {
+                  "minLength": 1,
+                  "type": "string"
+                }
+              },
+              "required": [
+                "old_text",
+                "new_text"
+              ],
+              "type": "object"
+            },
+            "minItems": 1,
+            "type": "array"
+          },
+          "source_base": {
+            "description": "Unchanged source_base from a current get_entity_source read.",
+            "type": "object"
+          }
+        },
+        "required": [
+          "source_base",
+          "edits"
+        ],
+        "type": "object"
+      },
+      "UnitImports": {
+        "additionalProperties": false,
+        "description": "Add or remove imports on a unit; Kin writes its import block. Target the package name.",
+        "properties": {
+          "add": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "remove": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "repository_base": {
+            "description": "Unchanged repository_base from session, status or the last mutate.",
+            "type": "object"
+          },
+          "unit": {
+            "description": "{language:\"go\", package:\".\" or \"internal/store\", name: package name, role:\"source\" or \"test\"}",
+            "type": "object"
+          }
+        },
+        "required": [
+          "repository_base",
+          "unit"
+        ],
+        "type": "object"
+      }
+    },
+    "type": "object"
+  },
+  "target": {
+    "description": "UUID, or the declared or package name.",
+    "minLength": 1,
+    "type": "string"
+  },
+  "verb": {
+    "description": "Patch, update, create or remove.",
+    "enum": [
+      "patch",
+      "update",
+      "create",
+      "remove"
+    ],
+    "type": "string"
+  }
+}

addedInput schema / properties / operations / items / required

Added value: +[
+  "verb",
+  "target",
+  "payload",
+  "description"
+]

addedInput schema / properties / operations / items / type
```
Added value: +"object"
```

removedInput schema / properties / request_id

Removed value: -{
-  "description": "Optional client request id, carried into the receipt so you can match the answer to your call; nothing deduplicates on it",
-  "type": "string"
-}

removedInput schema / properties / scope

Removed value: -{
-  "description": "Optional target scope or workspace identifier (defaults to 'repository')",
-  "type": "string"
-}

removedInput schema / properties / session_id

Removed value: -{
-  "description": "Optional owning session UUID",
-  "type": "string"
-}

changedInput schema / properties / summary / description

Previous value: -"Optional change message: one sentence in your own words saying what this change does, which becomes the subject a human reads in history. Omit it and the change records only the transaction id, which names the call and not the work."New value: +"One sentence for the history."

First observedv0.7.16Sep 12, 2026

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds the atomicity guarantee ('atomically, in one call'), which is genuinely beyond the annotations, but says nothing about failure behavior, all-or-nothing rollback semantics, or whether a base/session is required.

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?

A single short sentence with the action and the atomicity constraint front-loaded; nothing is wasted. It is arguably too terse for a tool of this complexity, but there is no filler or repetition.

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

Completeness3/5

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

For a multi-verb atomic mutation tool with a large nested payload schema and no output schema, the description omits the crucial operational facts an agent needs: how partial failure is handled, that multiple heterogeneous operations can be mixed, and that base values must come from a prior read. The rich schema compensates for parameters, but the behavioral picture is only partially complete.

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 the exceptionally detailed nested schema already documents operations, verbs, payload variants and base fields. The description adds no syntax, format, or constraint detail beyond what the schema provides — baseline 3 applies.

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

Purpose4/5

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

The description names a specific verb and resource — 'Commit targeted entity changes' — plus the atomicity scope, so an agent knows it performs batched graph mutations. However, it does not distinguish itself from its transaction siblings (kin_transaction_stage, kin_transaction_commit), and 'Commit' actively invites confusion with kin_transaction_commit.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus the transaction tools or the read-only siblings like get_entity_source. The phrase 'in one call' hints at the contrast with staged multi-call transactions, but the agent must infer that; no prerequisites (e.g. obtaining source_base/repository_base first) are stated.

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

kin_mutate

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools