mason

Overview Schema Source Related Servers Discussions Admin

save_decision

Capture or revise evidence-backed lesson decisions as pending proposals; compare existing context and proposals first, and pass an existing id when assumptions, scope, or action change.

Instructions

Capture or revise a decision proposal as soon as the lesson is supported by evidence, without waiting for implementation or merge. Keep unimplemented remedies tentative. Include rationale, anchors, optional owner, sources, and a known actor. Compare matching get_context records and pending proposals before saving. When new evidence changes the same lesson's assumptions, scope, or recommended action, pass its existing id, including for accepted records. Preserve supported rationale and sources and replace obsolete instructions. Create a new record for a genuinely distinct lesson; skip unchanged restatements. No setup or map required. Writes a local record and preserves content history. Changes create a pending proposal while the last accepted revision remains operative; unchanged content does not re-verify or refresh it. Use review_decision for authorized acceptance or reaffirmation. A proposal cannot supersede a record with an operative accepted revision; review its replacement and retire the original separately.

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": {
      "dir": "<dir>",
      "title": "<title>",
      "body": "<body>",
      "category": "<category>"
    },
    "name": "save_decision"
  }
}

Input Schema

Name	Required	Description
`id`	No	Pass the matching record's existing id when evidence changes that lesson's assumptions, scope, or recommended action, including for accepted records. Changed content becomes a proposal while the accepted version remains operative; unchanged content leaves review and freshness untouched.
`dir`	Yes	Absolute path to the project root directory
`body`	Yes	The knowledge itself: what was tried/decided, why, and what to avoid. Must contain information NOT derivable by reading the code. Aim for 1500 characters or fewer; up to 2500 is accepted with a warning above the target. Matching context and hooks include the full body. Preserve exceptions; use sources for supporting references. Name the functions, types, or settings the decision constrains in backticks, such as `refresh()`; drift notices use those names to judge whether a change is relevant.
`actor`	No	Known person or agent recording this revision. Omit if unknown; do not infer from Git identity.
`files`	No	Repo-relative files or directory prefixes this applies to. Matching is shared by retrieval, hooks, review, and drift checking; changes flag the decision for re-verification.
`force`	No	Save even when a near-duplicate was detected
`owner`	No	Responsible person or team, when known. Null clears it. Required for acceptance.
`title`	Yes	Short, specific headline (max 80 characters). Generates a stable id on creation; revising the title keeps the existing id.
`sources`	No	Known PR, issue, incident, discussion, or document references. Omit to preserve; [] clears. At least one is required for acceptance.
`category`	Yes
`supersedes`	No	Id of an unreviewed record or proposal with no accepted revision to replace. Operative accepted decisions require separate review and retirement.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.24.0Nov 2, 2026

changedInput schema / properties / body / description

Previous value: -"The knowledge itself: what was tried/decided, why, and what to avoid. Must contain information NOT derivable by reading the code. Aim for 1500 characters or fewer; up to 2500 is accepted with a warning above the target. Matching context and hooks include the full body. Preserve exceptions; use sources for supporting references."New value: +"The knowledge itself: what was tried/decided, why, and what to avoid. Must contain information NOT derivable by reading the code. Aim for 1500 characters or fewer; up to 2500 is accepted with a warning above the target. Matching context and hooks include the full body. Preserve exceptions; use sources for supporting references. Name the functions, types, or settings the decision constrains in backticks, such as `refresh()`; drift notices use those names to judge whether a change is relevant."

Addedv0.17.0Sep 12, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations present, the description carries the full burden and discloses key mutation semantics: it writes a local record, preserves content history, creates a pending proposal while the accepted revision remains operative, and does not refresh unchanged content. It also states the supersede constraint and that no setup or map 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?

The description is front-loaded with the core action and is appropriately sized for a complex stateful write tool. It is dense and mostly earns its length, though the id-revision guidance is repeated in slightly different wording.

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?

For an 11-parameter mutation tool with no output schema, the description covers the workflow, lifecycle outcomes, deduplication expectations, and relationship to review_decision. An agent has enough context to call it correctly without opening the schema.

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 91%, so the schema already documents most parameters in detail. The description adds workflow context around the id field and says to include rationale, anchors, owner, sources, and a known actor, but much of this repeats the schema's own descriptions and does not explain force, category, or files beyond 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?

The opening sentence states a specific verb ('Capture or revise') and resource ('decision proposal') with scope ('as soon as the lesson is supported by evidence'). It clearly distinguishes this write tool from review_decision and get_context by naming those siblings later.

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

Usage Guidelines5/5

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

It explicitly says when to save, when to reuse an existing id, when to create a new record, and when to skip unchanged restatements. It also routes acceptance and reaffirmation to review_decision, leaving no ambiguity about alternatives.

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

Deploy Server