Skip to main content
Glama

add_utterance

Records an engineer's exact words as pasted source text and returns an id for source_refs, so user-grounded decisions, constraints, and focus stay byte-exact.

Instructions

Chat clients only (no prompt hook — if the engineer's prompt came with a line 'casebook source_ref: ', use that id instead). When the engineer's words ground a record (a decision or constraint with authority='user', a focus with authority='user', a note with observed_from='user'), paste their message here EXACTLY as they wrote it: first person, every character, no summary, no trimming, never your own words. Returns the id to pass in source_refs. Stored as pasted by you (origin: model_pasted), so a reader can tell it apart from a hook-captured prompt.

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": {
      "text": "<text>"
    },
    "name": "add_utterance"
  }
}

Input Schema

NameRequiredDescriptionDefault
textYes
clientNo
captureNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations at all, the description carries the full burden and does most of it: it discloses that the call writes a record, that the record is tagged origin: model_pasted so readers can distinguish it from hook-captured prompts, that the return value is the id used in source_refs, and that the content is immutable-by-intent verbatim text. It stops short of stating permissions, idempotency, or what happens on duplicate paste, which are the remaining behavioral unknowns.

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 critical exclusion is front-loaded in the opening parenthetical and the verbatim rule is stated compactly with reinforcing clauses. It is dense but almost every clause carries real instruction; the nested parenthetical in the first sentence slightly hurts readability but not waste.

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?

For a provenance-sensitive write tool with an output schema, the description covers provenance tagging, the return value's use, and the alternate capture path, which is the complex part. The gap is parameter coverage for client/capture, whose effect on an agent's call is left entirely to guesswork.

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 0%, so the description must compensate, and it only partly does. It richly constrains the required `text` parameter (first person, every character, no summary, no trimming, never the model's own words), but the `client` and especially the `capture` boolean (default false) are never mentioned, leaving two of three parameters undefined anywhere in the definition.

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 description states a concrete action on a concrete resource: paste the engineer's message verbatim into storage and get back an id for source_refs. It also carves out the boundary against the prompt-hook capture path ('no prompt hook — if the prompt came with a line casebook source_ref: <id>, use that id instead'), so an agent can place this tool relative to the hook/record_utterances family without opening another 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?

It gives an explicit positive trigger with enumerated cases (decision or constraint with authority='user', focus with authority='user', note with observed_from='user') and an explicit negative trigger (prompt-hook clients should reuse the supplied source_ref id). This is a genuine when/when-not rule rather than implied usage.

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