Tirith

Official

Overview Schema Source Related Servers Discussions Admin

decision_record

Record a final Tirith project decision with rationale, alternatives, and affected paths to stop agents from re-deciding it.

Instructions

Record a settled project choice with its rationale, the alternatives considered and the paths it constrains, so no agent decides it again. It is written as one committed Markdown file under .tirith/decisions/ and appears in the brief of later claims on those paths. Use only once the choice is final; for discussion use message_send, and for lessons about code use memory_write. Lead-only while a swarm has a lead. Returns the decision with its permalink.

Input Schema

Name	Required	Description
`agent`	Yes	Your stable agent name.
`title`	Yes	Short title, the line shown in briefs.
`decision`	Yes	What was decided, stated so it can be followed.
`rationale`	No	Why it was decided.
`alternatives`	No	The alternatives that were considered and rejected.
`affects_paths`	No	Paths the decision constrains.

Output Schema

Name	Required	Description
`lead`	No	On a lead-only conflict: the lead to message.
`status`	Yes	ok. conflict: lead-only while a swarm has a lead. invalid: bad input.
`message`	No	Human-readable detail, on most outcomes other than ok.
`decision`	No	id, title, decision, rationale, alternatives, affects_paths, recorded_by, recorded_at, and the permalink of its committed file.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.3.0Oct 16, 2026

addedOutput schema / properties / lead

Added value: +{
+  "description": "On a lead-only conflict: the lead to message."
+}

changedOutput schema / properties / status / description

Previous value: -"ok. invalid: bad input."New value: +"ok. conflict: lead-only while a swarm has a lead. invalid: bad input."

Changed7 schema fields changedv1.1.2Sep 18, 2026

addedInput schema / properties / affects_paths / description
```
Added value: +"Paths the decision constrains."
```
addedInput schema / properties / agent / description
```
Added value: +"Your stable agent name."
```

addedInput schema / properties / alternatives / description

Added value: +"The alternatives that were considered and rejected."

addedInput schema / properties / decision / description

Added value: +"What was decided, stated so it can be followed."

addedInput schema / properties / rationale / description
```
Added value: +"Why it was decided."
```

addedInput schema / properties / title / description

Added value: +"Short title, the line shown in briefs."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "Any result may also carry lost, inbox, inbox_more and persist_error; see guide.",
+  "properties": {
+    "decision": {
+      "description": "id, title, decision, rationale, alternatives, affects_paths, recorded_by, recorded_at, and the permalink of its committed file.",
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable detail, on most outcomes other than ok.",
+      "type": "string"
+    },
+    "status": {
+      "description": "ok. invalid: bad input.",
+      "enum": [
+        "ok",
+        "conflict",
+        "not_found",
+        "none",
+        "invalid",
+        "cancelled"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}

First observedv1.1.1Sep 18, 2026

TDQS

A4.3/5.0

Behavior3/5

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

Annotations only declare destructiveHint=false, so the lower bar applies and the description adds genuinely useful context: the output is a committed Markdown file under .tirith/decisions/, it surfaces in the brief of later claims on those paths, and it is lead-restricted. It does not describe permanence/immutability of the file or what happens on conflicting paths, so it is good but not exhaustive.

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?

Front-loads the core action, then adds storage behavior, usage gating and the return, in that priority order. Dense but every clause carries distinct information with no filler.

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?

An output schema exists so return values needn't be detailed, and the description still caps it with 'returns the decision with its permalink'. Purpose, usage, side effects and authority constraints are all present for a six-parameter write tool.

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 100%, so the baseline is 3. The description reinforces the meaning of affects_paths (appears in the brief of later claims on those paths) but adds little syntactic detail for the six parameters already documented 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 (Record) and resource (a settled project choice) with its rationale, alternatives and constraining paths, and explicitly distinguishes itself from message_send and memory_write. An agent can tell it apart from the discussion and lesson-memory 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 Guidelines5/5

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

Gives explicit when (only once the choice is final) and when-not with named alternatives (message_send for discussion, memory_write for code lessons), plus an authority constraint (lead-only while a swarm has a lead). Nothing is left to inference.

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