Skip to main content
Glama

note_turn

Record a diagnostic step's observation, conclusion, next action, and owner in the case brief to prevent stale handoffs.

Instructions

Record one diagnostic step: observed = what was seen, in your words or quoted, conclusion = what you concluded, ruled out, or propose next. Both are stored as the note — your account, not evidence. Machine output that grounds it goes in add_evidence verbatim first, then cite it in evidence_ids. kind (required) = change(바꿈: code/screen/config changed) · verified(확인: test/prod/repro confirmed) · finding(발견: measured or found out, a fact) · thought(생각: proposal/hypothesis/judgment — can be overturned); if two apply, split into two notes. next (required) = after this turn, what happens next, and owner (required) = whose turn it is: "user" (the engineer must act), "watch" (nothing to do, only watching), or an agent name such as "codex" / "claude". Say next EVERY turn, even when nothing changed — if it is the same line as before, nothing new is written, so this costs you a sentence and keeps the thread honest. A stale next is the failure this product exists to prevent: the next session reads it and goes off to do work that is already done. Updates the case brief. Call at the end of each step, not every message. Refused once 15 turns have piled up since the thread's focus was last declared: re-declare the focus if it is still the same work, or open_thread for the new subject. evidence_ids (optional) = the evidence numbers this conclusion rests on — cite them here, not in the text; the screen renders them as links. observed_from = "machine" (tool output, tests, diffs, files) or "user" (the engineer's words) — required; when "user", source_refs is required too (the id from the prompt's "casebook source_ref: " line, or on a chat client the id add_utterance returns) A next owned by the user is written TO the engineer ('Decide X'), never about them ('The user decides X'). FIRST LINE = TITLE: at most 120 columns (CJK counts as 2), no ' — ' joiner, and no record numbers (#517, D15635, 확장 122호, turn 80, commit hashes) — a person reads that line on the screen; put the rest after a blank line as the body. The paragraph right under the title is read on the screen too, so no record numbers there either; they go in a later paragraph or evidence_ids (the server refuses otherwise).

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": {
      "case_id": "<case_id>",
      "observed": "<observed>",
      "conclusion": "<conclusion>",
      "kind": "<kind>",
      "next": "<next>",
      "owner": "<owner>"
    },
    "name": "note_turn"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindYes
nextYes
ownerYes
clientNo
captureNo
case_idYes
observedYes
conclusionYes
source_refsNo
evidence_idsNo
observed_fromNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/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 so well: it discloses the side effect ('Updates the case brief'), a server-side refusal (after 15 turns without a declared focus), a deduplication behavior ('if it is the same line as before, nothing new is written'), and hard validation refusals ('the server refuses otherwise' for record numbers in title or lead paragraph). It also states conditional requirements (source_refs mandatory when observed_from='user') that no annotation would convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Nearly all content earns its place, but it is delivered as a single undifferentiated block where parameter semantics, enum glosses, workflow rules, and formatting constraints (120 columns, CJK counts as 2, no em-dash joiner) are interleaved. Splitting into short labeled lines would make the same content far easier to act on. Size is defensible for the complexity; presentation is not.

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 mutation, refusal, and citation behaviors are all covered. What remains thin is peripheral: capture and client are never mentioned, and case_id is assumed self-evident. For a six-required-parameter workflow tool with zero schema documentation, this is close to complete.

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 description coverage is 0%, so the description must supply all meaning, and it does for the important ones: kind gets four values with glosses (change/verified/finding/thought) plus a splitting rule, owner gets its three value classes including agent names, evidence_ids gets usage guidance ('cite them here, not in the text'), observed_from gets its two values and the source_refs dependency. It leaves case_id, client, and capture entirely unexplained, which holds it below a 5 for an 11-parameter tool.

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 names a specific verb and resource ('Record one diagnostic step') and immediately defines the two payload fields (observed, conclusion). It also draws explicit boundaries against siblings: machine output belongs in add_evidence first, and a new subject requires open_thread. An agent can distinguish this from add_evidence, add_utterance, and open_thread 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?

Timing is stated explicitly ('Call at the end of each step, not every message'), alternatives are named with the condition that selects them (add_evidence for grounded machine output, open_thread for a new subject, re-declare focus when the same work continues). Refusal conditions (15 turns since declared focus) tell the agent when this call will fail and what to do instead.

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