Commit all staged operations in a transaction atomically, applying changes only if every operation succeeds.
Transaction plumbing for writes. Publish everything staged, atomically.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | One sentence on what this change does. | |
| operations | No | Operations to stage in this commit. | |
| session_id | No | Owning session UUID. | |
| transaction_id | Yes | UUID |
Changes observed during successful MCP inspections.
v0.7.17Input schema / properties / message / descriptionPrevious 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 on what this change does."Input schema / properties / operations / descriptionPrevious value: -"Optional exact mutation operations to stage atomically in this commit request"New value: +"Operations to stage in this commit."Input schema / properties / operations / items / oneOfPrevious 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"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntitySourcePatch": {
+ "additionalProperties": false,
+ "properties": {
+ "edits": {
+ "description": "Exact unique nonoverlapping anchors in the original entity body. All edits use that same original body, not earlier replacements.",
+ "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": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ }
+ },
+ "required": [
+ "source_base",
+ "edits"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntitySourcePatch"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "The exact entity UUID in source_base.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "patch"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "Anchored entity source patch",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "body": {
+ "description": "Complete new entity text, indentation kept, never truncated.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "description": {
+ "description": "What this changes.",
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntitySourceBase": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntitySourceBase"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "source_base UUID.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "verb": {
+ "description": "Edit an entity.",
+ "enum": [
+ "update",
+ "modify"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "body",
+ "payload",
+ "description"
+ ],
+ "title": "Guarded entity source body edit",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "What this changes.",
+ "type": "string"
+ },
+ "payload": {
+ "description": "{\"Relation\": {from, to, kind}}; create with EntityCreate.",
+ "oneOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "Entity": {
+ "type": "object"
+ }
+ },
+ "required": [
+ "Entity"
+ ]
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "Relation": {
+ "type": "object"
+ }
+ },
+ "required": [
+ "Relation"
+ ]
+ }
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "Entity UUID; empty for a Relation payload.",
+ "type": "string"
+ },
+ "verb": {
+ "description": "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"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntityCreate": {
+ "additionalProperties": false,
+ "description": "Create one declaration, in one of two forms, with no path or offset. Addressed to a unit (repository_base and unit): the form for an empty repository and for every Go declaration kind. Kin derives the unit's file, writes its package clause, places the declaration (a method directly after its receiver type or that type's last method, anything else at the end of the unit) and merges imports into the unit's one import block. The operation's target is the declared name. Anchored (source_base and placement): one top-level function in Rust, Python or Go beside a current function, whose UUID is the target. Occupied names, ambiguous placement and stale bases refuse without publication.",
+ "oneOf": [
+ {
+ "required": [
+ "repository_base",
+ "unit"
+ ]
+ },
+ {
+ "required": [
+ "source_base",
+ "placement"
+ ]
+ }
+ ],
+ "properties": {
+ "body": {
+ "description": "Exactly the declaration's source, optionally led by its doc comment: no package clause, imports or sibling declarations.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "imports": {
+ "description": "Unit form: import paths the declaration needs, added to the unit's import block.",
+ "items": {
+ "oneOf": [
+ {
+ "description": "An import path, such as \"fmt\" or \"example.com/app/internal/store\".",
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "alias": {
+ "description": "Explicit package name, \"_\" or \".\".",
+ "type": "string"
+ },
+ "path": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "path"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "kind": {
+ "description": "Go admits function, method, struct, interface, type, const and var; anchored creation admits function. The graph kinds class, type_alias, constant and static_var are accepted as synonyms.",
+ "enum": [
+ "function",
+ "method",
+ "struct",
+ "class",
+ "interface",
+ "type",
+ "const",
+ "var"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "description": "The declared name as the graph names it: Name, Receiver.Method for a method, the first name of a grouped const or var, or _ for a blank var or const such as var _ Getter = (*Store)(nil), whose entity is named after the assertion (_ Getter = (*Store)(nil)).",
+ "minLength": 1,
+ "type": "string"
+ },
+ "placement": {
+ "enum": [
+ "sibling_after",
+ "new_source_unit"
+ ],
+ "type": "string"
+ },
+ "repository_base": {
+ "additionalProperties": false,
+ "description": "The repository_base Kin returned from session, status or the last mutate, unchanged. Work addressed to a unit is refused as repository_base_conflict when repository authority has moved since.",
+ "properties": {
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "schema": {
+ "const": "kin.repository.base.v1"
+ }
+ },
+ "required": [
+ "schema",
+ "context"
+ ],
+ "type": "object"
+ },
+ "source_base": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ },
+ "unit": {
+ "additionalProperties": false,
+ "description": "A source unit named by language identity, never by path. Go: package is the import path relative to the module root (\".\" or \"internal/store\"), name is the package clause, role is source or test (the package's _test unit). Kin derives the file and owns the package clause.",
+ "properties": {
+ "language": {
+ "const": "go"
+ },
+ "name": {
+ "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+ "type": "string"
+ },
+ "package": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "role": {
+ "default": "source",
+ "enum": [
+ "source",
+ "test"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "language",
+ "package",
+ "name"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "name",
+ "kind",
+ "body"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntityCreate"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "The declared name for a unit-addressed creation; the source_base anchor UUID for an anchored one.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "create"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "EntityCreate",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "UnitImports": {
+ "additionalProperties": false,
+ "description": "Add or remove imports on one source unit. Kin writes the unit's single import block deterministically (standard library first, each group sorted). Adding a held import or removing an absent one is a no-op.",
+ "properties": {
+ "add": {
+ "items": {
+ "oneOf": [
+ {
+ "description": "An import path, such as \"fmt\" or \"example.com/app/internal/store\".",
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "alias": {
+ "description": "Explicit package name, \"_\" or \".\".",
+ "type": "string"
+ },
+ "path": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "path"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "remove": {
+ "items": {
+ "oneOf": [
+ {
+ "description": "An import path, such as \"fmt\" or \"example.com/app/internal/store\".",
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "alias": {
+ "description": "Explicit package name, \"_\" or \".\".",
+ "type": "string"
+ },
+ "path": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "path"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "repository_base": {
+ "additionalProperties": false,
+ "description": "The repository_base Kin returned from session, status or the last mutate, unchanged. Work addressed to a unit is refused as repository_base_conflict when repository authority has moved since.",
+ "properties": {
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "schema": {
+ "const": "kin.repository.base.v1"
+ }
+ },
+ "required": [
+ "schema",
+ "context"
+ ],
+ "type": "object"
+ },
+ "unit": {
+ "additionalProperties": false,
+ "description": "A source unit named by language identity, never by path. Go: package is the import path relative to the module root (\".\" or \"internal/store\"), name is the package clause, role is source or test (the package's _test unit). Kin derives the file and owns the package clause.",
+ "properties": {
+ "language": {
+ "const": "go"
+ },
+ "name": {
+ "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+ "type": "string"
+ },
+ "package": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "role": {
+ "default": "source",
+ "enum": [
+ "source",
+ "test"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "language",
+ "package",
+ "name"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "repository_base",
+ "unit"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "UnitImports"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "The unit's package name.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "update"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "UnitImports",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "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": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ }
+ },
+ "required": [
+ "source_base"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntityRemove"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "Exact source_base anchor/entity UUID.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "remove"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "EntityRemove",
+ "type": "object"
+ }
+]Input schema / properties / session_id / descriptionPrevious value: -"Optional owning session UUID mirror; when present in enforce mode it must match the authenticated caller and transaction owner"New value: +"Owning session UUID."Input schema / properties / transaction_id / descriptionPrevious value: -"Transaction UUID"New value: +"UUID"v0.7.16Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and closed-world, so the safety profile is covered structurally. The description adds one genuine behavioral fact beyond them — publication is atomic (all-or-nothing) — but says nothing about failure handling, validation of stale bases, or what a rejected commit does to staged work.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short front-loaded sentences with no redundancy; the atomicity guarantee is stated immediately. The opening phrase 'Transaction plumbing for writes' is somewhat vague filler relative to the precise second sentence, keeping it just short of a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, high-stakes commit step in a multi-tool transaction workflow, the description omits the prerequisites (a begun transaction with staged operations), the consequences of failure, and any hint of what is returned or how success is confirmed. Annotations and a rich schema help, but the prose is too thin for the risk profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the nested operation variants are documented exhaustively in the schema. The description contributes only the loose phrase 'everything staged' mapping to the operations array and adds no detail on transaction_id, session_id, or message beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: publish staged operations as a commit. The word 'commit' in the name and 'Publish everything staged, atomically' make it distinguishable from kin_transaction_begin/stage/abort without opening the schema, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Publish everything staged' implies it must follow kin_transaction_stage, but there is no explicit when-to-use, no note that a transaction must be begun first, and no guidance on when to prefer kin_transaction_abort instead. Usage is left to inference from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.