pin

kaeru memory

Overview Schema Source Related Servers Discussions Admin

Keep a memory record in view or release it; this controls visibility only and does not assign roles or supersede other knowledge.

Instructions

Keep a record in view or release the pin; does not assign a role or supersede other knowledge.

Input Schema

Name	Required	Description
`node`	Yes
`reason`	No
`enabled`	Yes
`initiative`	Yes
`request_id`	No	Optional stable operation key supplied by the host/SDK; see replay contract.
`expected_revision`	No	Opaque revision of the primary target, as returned by reads.

Output Schema

Name	Required	Description	Default
`data`	Yes
`state`	Yes
`issues`	Yes
`coverage`	No
`replayed`	Yes
`operation`	Yes
`request_id`	No
`api_version`	Yes
`continuation`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedv0.8.0Oct 21, 2026

addedInput schema / $defs

Added value: +{
+  "NodeRef": {
+    "oneOf": [
+      {
+        "description": "Returned UUID or exact name in the call initiative; ambiguity is an error.",
+        "minLength": 1,
+        "type": "string"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "description": "Returned canonical ID, including IDs from older vaults.",
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "type": "object"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "initiative": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "name": {
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "initiative"
+        ],
+        "type": "object"
+      }
+    ]
+  }
+}

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / allOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean"
+      },
+      "expected_revision": {
+        "description": "Opaque revision of the primary target, as returned by reads.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "initiative": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "node": {
+        "$ref": "#/$defs/NodeRef"
+      },
+      "reason": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "request_id": {
+        "description": "Optional stable operation key supplied by the host/SDK; see replay contract.",
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "initiative",
+      "node",
+      "enabled"
+    ],
+    "type": "object"
+  },
+  {
+    "if": {
+      "properties": {
+        "enabled": {
+          "const": true
+        }
+      }
+    },
+    "then": {
+      "required": [
+        "reason"
+      ]
+    }
+  }
+]

addedInput schema / properties / enabled
```
Added value: +{
+  "type": "boolean"
+}
```

addedInput schema / properties / expected_revision

Added value: +{
+  "description": "Opaque revision of the primary target, as returned by reads.",
+  "minLength": 1,
+  "type": "string"
+}

removedInput schema / properties / initiative / default
```
Removed value: -null
```
addedInput schema / properties / initiative / minLength
```
Added value: +1
```

changedInput schema / properties / initiative / type

Previous value: -[
-  "string",
-  "null"
-]New value: +"string"

removedInput schema / properties / name

Removed value: -{
-  "description": "Node name or UUIDv7 id.",
-  "type": "string"
-}

addedInput schema / properties / node

Added value: +{
+  "$ref": "#/$defs/NodeRef"
+}

removedInput schema / properties / reason / description

Removed value: -"Why the node deserves a place in the active window."

addedInput schema / properties / reason / minLength
```
Added value: +1
```

addedInput schema / properties / request_id

Added value: +{
+  "description": "Optional stable operation key supplied by the host/SDK; see replay contract.",
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "name",
-  "reason"
-]New value: +[
+  "initiative",
+  "node",
+  "enabled"
+]

removedInput schema / title
```
Removed value: -"PinParams"
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "AmgOmission": {
+      "additionalProperties": false,
+      "properties": {
+        "count": {
+          "format": "uint",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "reason": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "reason",
+        "count"
+      ],
+      "type": "object"
+    },
+    "ArchiveFormat": {
+      "enum": [
+        "markdown",
+        "amg"
+      ],
+      "type": "string"
+    },
+    "Artifact": {
+      "properties": {
+        "bytes": {
+          "format": "uint",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "edges": {
+          "format": "uint",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "format": {
+          "$ref": "#/$defs/ArchiveFormat"
+        },
+        "initiatives": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "nodes": {
+          "format": "uint",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "omissions": {
+          "items": {
+            "$ref": "#/$defs/AmgOmission"
+          },
+          "type": "array"
+        },
+        "path": {
+          "type": "string"
+        },
+        "sha256": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "path",
+        "format",
+        "bytes",
+        "sha256",
+        "initiatives",
+        "omissions",
+        "nodes",
+        "edges"
+      ],
+      "type": "object"
+    },
+    "Change": {
+      "properties": {
+        "after": true,
+        "before": true,
+        "field": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "field",
+        "before",
+        "after"
+      ],
+      "type": "object"
+    },
+    "Continuation": {
+      "properties": {
+        "cursor": {
+          "type": "string"
+        },
+        "next_arguments": true
+      },
+      "required": [
+        "cursor",
+        "next_arguments"
+      ],
+      "type": "object"
+    },
+    "Coverage": {
+      "properties": {
+        "complete": {
+          "type": "boolean"
+        },
+        "initiatives": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "omitted": {
+          "items": {
+            "$ref": "#/$defs/Omission"
+          },
+          "type": "array"
+        },
+        "rules_complete": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "initiatives",
+        "complete",
+        "rules_complete",
+        "omitted"
+      ],
+      "type": "object"
+    },
+    "Entity": {
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "revision": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "revision"
+      ],
+      "type": "object"
+    },
+    "EvidenceResult": {
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "relation": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "relation"
+      ],
+      "type": "object"
+    },
+    "FailedStep": {
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "step": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "step",
+        "code",
+        "message"
+      ],
+      "type": "object"
+    },
+    "Issue": {
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "field": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "retryable": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "code",
+        "message",
+        "retryable"
+      ],
+      "type": "object"
+    },
+    "MutationData": {
+      "properties": {
+        "affected": {
+          "items": {
+            "$ref": "#/$defs/Entity"
+          },
+          "type": "array"
+        },
+        "artifacts": {
+          "items": {
+            "$ref": "#/$defs/Artifact"
+          },
+          "type": "array"
+        },
+        "changes": {
+          "items": {
+            "$ref": "#/$defs/Change"
+          },
+          "type": "array"
+        },
+        "created": {
+          "items": {
+            "$ref": "#/$defs/Entity"
+          },
+          "type": "array"
+        },
+        "evidence": {
+          "items": {
+            "$ref": "#/$defs/EvidenceResult"
+          },
+          "type": "array"
+        },
+        "failed_steps": {
+          "items": {
+            "$ref": "#/$defs/FailedStep"
+          },
+          "type": "array"
+        },
+        "primary": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Entity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "slots": {
+          "items": {
+            "$ref": "#/$defs/SlotChange"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "created",
+        "affected",
+        "changes",
+        "evidence",
+        "failed_steps",
+        "slots",
+        "artifacts"
+      ],
+      "type": "object"
+    },
+    "Omission": {
+      "properties": {
+        "count": {
+          "format": "uint",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "reason": {
+          "type": "string"
+        },
+        "section": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "section",
+        "count",
+        "reason"
+      ],
+      "type": "object"
+    },
+    "SlotChange": {
+      "properties": {
+        "after": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "before": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "revision": {
+          "type": "string"
+        },
+        "slot": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "slot",
+        "revision"
+      ],
+      "type": "object"
+    },
+    "State": {
+      "enum": [
+        "ok",
+        "applied",
+        "unchanged",
+        "partial",
+        "rejected"
+      ],
+      "type": "string"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "properties": {
+    "api_version": {
+      "const": 1,
+      "format": "uint32",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "continuation": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/Continuation"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "coverage": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/Coverage"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "data": {
+      "$ref": "#/$defs/MutationData"
+    },
+    "issues": {
+      "items": {
+        "$ref": "#/$defs/Issue"
+      },
+      "type": "array"
+    },
+    "operation": {
+      "const": "pin",
+      "type": "string"
+    },
+    "replayed": {
+      "type": "boolean"
+    },
+    "request_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "state": {
+      "$ref": "#/$defs/State"
+    }
+  },
+  "required": [
+    "api_version",
+    "operation",
+    "state",
+    "replayed",
+    "data",
+    "issues"
+  ],
+  "title": "Response",
+  "type": "object"
+}

First observedv0.7.5Oct 5, 2026

TDQS

B3.3/5.0

Behavior3/5

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

Annotations declare only readOnlyHint=false, so the description usefully adds that pinning is about visibility, not role assignment or knowledge supersession. However, it omits important mutation behavior such as the conditional reason requirement when enabling a pin, revision-conflict handling via expected_revision, and whether pinning is reversible or idempotent.

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

Conciseness5/5

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

The description is a single compact sentence that front-loads the core action and follows with a useful scope boundary. There is no wasted wording.

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?

An output schema exists, so return value details are not required in the description. Still, for a six-parameter mutation tool with partial schema coverage and conditional requirements, the description leaves out behavioral details an agent would benefit from knowing before invoking it.

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

Parameters2/5

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

Schema description coverage is only 33%, and the description adds no parameter-level meaning. It does not explain initiative scoping, what enabled=true/false mean in context, why reason becomes required when enabling, or how expected_revision and request_id affect the operation.

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 states a specific action and resource: keeping a record in view or releasing the pin. It also clarifies what the tool does not do (assign a role or supersede other knowledge), which helps distinguish it from related knowledge-governance tools. It stops short of naming a sibling tool directly.

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

Usage Guidelines3/5

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

Usage is implied by 'keep a record in view or release the pin,' but there is no explicit guidance on when to choose pin versus alternatives such as note, reference, or claim. The negative boundary ('does not assign a role or supersede other knowledge') is useful but not a full when-to-use rule.

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

Deploy Server

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools