Skip to main content
Glama

add_decision

Record architectural or product decisions permanently for future sessions. Appends a decision event and updates summary.md; supports superseding old decisions without editing history.

Instructions

Record an architectural or product decision permanently.

Call when you make a choice that future sessions or contributors
should know about. Decisions show up in `summary.md` and in
`pjm wrap` context blocks.

Side effects: appends a `decision` event and updates summary.md.
Decisions are append-only — to revise, pass `supersedes` with the old
decision's event id instead of editing history.

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": {
      "summary": "<summary>"
    },
    "name": "add_decision"
  }
}

Input Schema

NameRequiredDescriptionDefault
projectNoWhich project this call is about — a registered id, alias, or absolute path (e.g. 'ossdrop'). Omit it when the server was started for a single repo, or when an active project is set with `pjm project use`. Call list_projects to see the registered names.
summaryYesOne-line description of the architectural or product decision (e.g., 'use bcrypt rounds=12 for password hashing'). Becomes part of the project's permanent record — write it for a future contributor. Keep it under 300 characters: summary.md clips longer text.
locationNoOptional file path or scope where the decision applies (e.g., 'src/auth/' for a module-level choice). Helps precheck_file cite the decision when the file is later touched.
supersedesNoOptional event id (evt_...) of a prior decision this one retires. The old event stays in the log tagged (superseded); only the new decision appears in summary.md. Use when precheck_file flags a decision as possibly stale and you are revising it.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.5
    • changedInput schema / properties / summary / description
      Previous value: -"One-line description of the architectural or product decision (e.g., 'use bcrypt rounds=12 for password hashing'). Becomes part of the project's permanent record — write it for a future contributor."New value: +"One-line description of the architectural or product decision (e.g., 'use bcrypt rounds=12 for password hashing'). Becomes part of the project's permanent record — write it for a future contributor. Keep it under 300 characters: summary.md clips longer text."
  2. Changed1 schema field changedv0.3.2
    • addedInput schema / properties / project
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Which project this call is about — a registered id, alias, or absolute path (e.g. 'ossdrop'). Omit it when the server was started for a single repo, or when an active project is set with `pjm project use`. Call list_projects to see the registered names.",
      +  "title": "Project"
      +}
  3. Changed1 schema field changedv0.1.4
    • addedInput schema / properties / supersedes
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Optional event id (evt_...) of a prior decision this one retires. The old event stays in the log tagged (superseded); only the new decision appears in summary.md. Use when precheck_file flags a decision as possibly stale and you are revising it.",
      +  "title": "Supersedes"
      +}
  4. Changed2 schema fields changedv0.1.3
    • addedInput schema / properties / location / description
      Added value: +"Optional file path or scope where the decision applies (e.g., 'src/auth/' for a module-level choice). Helps precheck_file cite the decision when the file is later touched."
    • addedInput schema / properties / summary / description
      Added value: +"One-line description of the architectural or product decision (e.g., 'use bcrypt rounds=12 for password hashing'). Becomes part of the project's permanent record — write it for a future contributor."
  5. First observedv0.1.1

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does it well: it states the side effects (appends a `decision` event, updates summary.md), the append-only immutability, and the correct revision mechanism. It omits error/edge behavior — e.g. what happens with an unregistered project or a bad `supersedes` id — which keeps it from a 5.

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 purpose, then usage, then side effects — a sensible order with little waste. There is minor redundancy with the schema on `supersedes`, and the 'shows up in summary.md' detail is repeated by the side-effects sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/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 values need not be explained, and the description covers purpose, trigger, side effects, and the revision path. The main remaining gap is the absence of sibling differentiation for a tool set containing add_note, log_issue, and record_fix.

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 coverage is 100%, so all four parameters are already documented in detail, making 3 the baseline. The description's only parameter-adjacent content is the `supersedes` revision workflow, which the schema already spells out; it adds no syntax or format detail beyond that.

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 first sentence gives a specific verb and resource ('Record an architectural or product decision') plus a persistence qualifier ('permanently'). It is clearly a decision-logging tool, but it never names or contrasts the adjacent siblings (add_note, log_issue, record_fix), leaving the agent to infer the boundary between a decision and a note or issue.

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?

It gives a concrete trigger: 'Call when you make a choice that future sessions or contributors should know about,' and explains the revision path via `supersedes` instead of editing history. It stops short of explicit exclusions — there is no 'use add_note instead when…' guidance despite several similarly-named siblings.

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