mnema

Official

Overview Schema Source Related Servers Discussions Admin

Move a skill through the workflow

skill_transition

Move a skill through its lifecycle: review, adopt, reject, or deprecate it with a required note or reason. Illegal moves are refused with the gate's reason, keeping the record verifiable.

Instructions

Move an existing skill to a new state: review a proposed skill, adopt a reviewed one as a live pattern, reject a proposed or reviewed one, or deprecate an adopted one that fell out of use. review/adopt/reject each need a note; deprecate needs a reason. An illegal move or missing proof is refused with the gate’s reason. The skill is looked for in EVERY project of this workspace and the move lands in the project that holds it: the id decides, so no project is taken. RECORDING IS PERMANENT: mnema is append-only and nothing deletes a fact. A record in the public scope is committed to the repository and reaches every machine that clones it (published, if that repository is public). So do NOT record credentials here. Values in a recognized format (cloud keys, API tokens, private keys, a password inside a URL) are replaced with a typed placeholder before anything is written and the reply says what was replaced, but a format mnema does not recognize is written verbatim and cannot be taken back. Do not record personal data either: an email address is replaced with and reported, and the mnid already says who wrote. Each text field holds at most 65536 bytes; a longer one is refused, not truncated.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>",
      "action": "<action>"
    },
    "name": "skill_transition"
  }
}

Input Schema

Name	Required	Description
`id`	Yes	The skill id to move.
`note`	No	Why this verdict (review, adopt, reject).
`action`	Yes	The transition: review, adopt, reject, or deprecate.
`reason`	No	Why it fell out of use (deprecate).

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Adds substantial behavior beyond the annotations: append-only permanence, workspace-wide id lookup with no project parameter, gate refusals returned with reasons, public-scope commit/publish consequences, secret and email redaction with reporting, and a 65536-byte per-field cap that refuses rather than truncates. The annotations only cover read/write/idempotency shape, so this description carries the real behavioral content.

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?

Front-loaded with the core transitions before the safety material, and most sentences earn their place. The permanence point is restated three ways ('RECORDING IS PERMANENT', 'append-only', 'cannot be taken back'), which is mild redundancy in an otherwise dense but organized description.

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?

Covers everything needed for a mutation tool with no output schema: valid actions, required proof per action, implicit targeting rule, failure behavior ('refused with the gate's reason'), and post-write reply contents. Little an agent would need is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline would be 3, but the description adds conditional semantics the schema lacks: note is required for review/adopt/reject, reason for deprecate, and the id alone decides the target project. The 65536-byte limit on text fields is also an extra constraint not in the schema.

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?

States a specific verb and resource ('Move an existing skill to a new state') and enumerates the exact four transitions with their preconditions. An agent can distinguish this from create_skill and the other *_transition siblings without opening any 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?

Gives per-action context: review a proposed skill, adopt a reviewed one, reject a proposed or reviewed one, deprecate an adopted one that fell out of use. It also states which proof each action needs. It never names an alternative tool (e.g. create_skill) or a when-not-to-use case, so it falls short of a 5.

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