docs(mcp): every create_* tool says what it is NOT for (#3123)

Scribe's record kinds get reached for interchangeably, and the moment of
choice is the only moment a correction is cheap. Rule 119 puts product
guidance in the instruction surfaces, so the docstring is where this
belongs — but a docstring that only documents parameters answers "how do I
call this" and leaves "should I be calling this at all" unasked.

The gap was lopsided. create_rule and start_planning already carried real
disambiguators; create_note — far and away the highest-volume surface —
carried none at all. The guidance sat in the rarest tool and was missing
from the most common one.

Each surface now opens with ONE deciding question in its own terms rather
than a pasted block:

  create_note     WHAT ELSE COULD HOLD THIS?      note is right when nothing
                                                  is owed and nothing enforces
  create_task     IS ANYTHING ACTUALLY OWED?      nothing owed -> note;
                                                  an arc -> start_planning
  create_snippet  SHAPE, OR ADVICE?               a snippet is code with a
                                                  LOCATION
  create_process  FOLLOWED, OR READ?              applies uninvoked -> rule

create_project_rule now points at the entity check too; it had only ever
covered rule-vs-rule scope.

The guard asserts STRUCTURE, never wording: each surface must name at least
two siblings. Pinning phrasing would make every improvement a test failure,
and a test that punishes editing is a test that gets deleted. Its second
half asserts the Args: block survives — the first check is satisfiable by
turning a docstring into an essay about the other tools, which would be a
worse contract than the one being fixed.

The guard caught two gaps on its first run, one of them its own: "design
system" is hard-wrapped across a line break in create_rule, so matching the
raw docstring reported it absent. _doc() now flattens whitespace. It also
caught start_planning naming only one alternative, which was true and is
now fixed.

Deliberately NOT built: an intent-router tool. It has a bootstrapping
problem — it is itself a tool that must be reached for — and MCP clients
already list every tool's description. Recorded in #3123; build it only if
wrong-surface reaches survive this.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/scribe/mcp/tools/notes.py

@@ -107,6 +107,17 @@ async def create_note(
 ) -> dict:
     """Create a new note in Scribe.
 
+    WHAT ELSE COULD HOLD THIS? A note is the right home when the answer is
+    "nothing": it records what you know, nobody owes anything on it, and
+    nothing enforces it. Otherwise —
+    - someone has to DO something -> create_task. A note titled "we should…"
+      is a task nobody will ever see again.
+    - future sessions must OBEY it -> create_rule. The test is whether
+      ignoring it would be a mistake, not merely uninformed.
+    - reusable code with a place in a repo -> create_snippet. The location is
+      what lets it be found from the file someone is about to edit.
+    - a procedure followed start to finish -> create_process.
+
     Args:
         title: Note title (required).
         body: Markdown content. Supports [[wikilinks]] to other notes by title.

src/scribe/mcp/tools/processes.py

@@ -54,6 +54,12 @@ async def create_process(
 ) -> dict:
     """Create a stored process (a reusable saved prompt).
 
+    FOLLOWED, OR READ? A process is invoked deliberately and worked through
+    start to finish. If it should apply whether or not anyone invokes it, it
+    is a rule (create_rule) — that is the whole difference between a procedure
+    and a standing instruction. If it is knowledge to consult rather than
+    steps to execute, it is a note (create_note).
+
     AUTHOR IT AS A SHAPE, NOT A SCRIPT. A process's value is the accumulated
     procedure — the steps, the taxonomy, the quality bar, the failure modes
     worth guarding. It must not force anything the invoking conversation

src/scribe/mcp/tools/rulebooks.py

@@ -407,6 +407,13 @@ async def create_project_rule(
     the rule is returned in get_project's applicable_rules (under
     project_rules) and in list_rules(project_id=...).
 
+    Check first whether a rule is the right shape at all — create_rule's
+    opening asks that question and it applies identically here. A visual
+    standard is a design system; a procedure is a process (create_process);
+    reusable code is a snippet (create_snippet). Each of those is structure a
+    tool can resolve, render and check, where a rule is only prose someone
+    has to remember and apply.
+
     ONE RULE = ONE THING YOU COULD VIOLATE — see create_rule. A rule that
     STRICTENS or REPLACES an inherited one is not a fresh rule: write it, then
     relate_rules(kind="overrides") to the rule it supersedes, so the pair stays

src/scribe/mcp/tools/snippets.py

@@ -115,6 +115,13 @@ async def create_snippet(
     """Record a shape in the project's pattern library, so every later
     instance starts from it instead of re-deriving it.
 
+    IS THE SHAPE THE POINT, OR THE ADVICE? A snippet is code with a LOCATION —
+    that is what lets it surface from the file someone is about to edit. If
+    what wants recording is a standing instruction about how to work, it is a
+    rule (create_rule); a procedure followed start to finish is a process
+    (create_process); what you LEARNED rather than what to copy is a note
+    (create_note).
+
     Reach for this the FIRST time any shape is built — a component, a control,
     a route handler, a service class, a helper, a test scaffold — not only
     when something is judged "reusable": the builder of the first instance

src/scribe/mcp/tools/tasks.py

@@ -135,6 +135,13 @@ async def create_task(
 ) -> dict:
     """Create a new task in Scribe.
 
+    IS ANYTHING ACTUALLY OWED? A task carries a status and someone is on the
+    hook to move it. If nothing is owed — you are recording what you learned,
+    decided or observed — that is a note (create_note), and filing it here
+    leaves a to-do nobody will ever close. If the work is an ARC of several
+    steps toward one goal, start_planning makes the milestone that holds
+    them; a task is one step, not the plan.
+
     Args:
         title: Task title (required).
         body: Markdown description / notes for the task.
@@ -323,7 +330,9 @@ async def start_planning(project_id: int, title: str) -> dict:
     Reach for this when the work has an ARC — several steps toward one goal,
     worth tracking as a unit. Work without one (a fix, a one-file change, a
     question answered) is a task, not a plan: create_task, drive its status, and
-    record progress with add_task_log. A milestone holding a single step is
+    record progress with add_task_log. A design or decision you are RECORDING
+    rather than executing is a note (create_note) — a plan nobody is going to
+    work through is a document filed in the place reserved for open work. A milestone holding a single step is
     ceremony, and it leaves the project with a plan that never meant anything.
 
     Creates a MILESTONE that IS the plan: its `body` is seeded with a design