Stage code updates, creates, deletes, and renames in a transaction to prepare multiple source modifications for atomic commit.
Transaction plumbing for writes. Stage an update, create, delete or rename.
| Name | Required | Description | Default |
|---|---|---|---|
| operations | Yes | What to stage. | |
| session_id | No | Owning session UUID. | |
| transaction_id | Yes | UUID |
Changes observed during successful MCP inspections.
v0.7.17Input schema / properties / operations / descriptionPrevious value: -"Array of mutation operations to stage"New value: +"What to stage."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 declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the agent knows this writes and is neither destructive nor idempotent. The description adds almost nothing beyond that: it never states that staging is deferred and unpublished until commit, nor mentions staleness/refusal behavior that the schema repeatedly references. For a write-plumbing tool, the key behavioral fact (nothing is published at stage time) is absent.
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 filler. However, the extreme brevity is arguably under-specification for a tool with such a large surface rather than true economy.
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?
The schema is enormous, with six distinct operation shapes, stale-base refusal semantics and unit-addressed creation rules, while the description conveys none of this. With no output schema, the description should at least characterize the staging/commit lifecycle and refusal behavior; it does not.
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%, so the schema already documents transaction_id, session_id and the operations structure in depth. The description adds no parameter-level meaning at all, leaving the baseline 3 for a fully-covered schema.
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 ('stage') and the resource (transaction operations), and enumerates the operation kinds (update, create, delete, rename). It does not distinguish this from kin_mutate or kin_transaction_commit, so an agent cannot tell from the description alone why it should stage here rather than mutate directly. Notably, 'rename' is listed but no rename verb appears in the schema's oneOf variants.
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?
There is no explicit when-to-use guidance, no mention of the begin/stage/commit workflow, and no reference to the sibling tools kin_transaction_begin, kin_transaction_commit or kin_mutate. The phrase 'transaction plumbing for writes' implies a role but leaves the agent to infer the workflow ordering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.