Skip to main content
Glama

declare

Record a thread's current focus, unresolved questions, or next action and owner so Worktrail preserves context for pausing and resuming.

Instructions

Declare the thread's current focus (what it is for), open (what is still unresolved: questions, blockers, uncertainty) or next (the 1–3 concrete actions to take next). kind = focus|open|next. focus says what the thread is FOR and what would finish it — not how far along you are. In the body, explain first — what the thread does and what would finish it — and put where it came from (the engineer's words, quoted) last, as its grounds: the screen shows the body in order, so a quote first hides the focus. Re-declaring it with exactly the same words is a confirmation (it resets the turn cap and is not shown as a change); re-declare with different words only when the direction itself changed — then pass next and owner too (what happens next in the new direction, and whose turn); a confirmation takes neither. Append-only: the previous declaration of that kind is superseded, not edited. next REQUIRES owner — whose turn it is: "user" (the engineer must act), "watch" (nothing to do — observing only), or an agent name such as "codex" / "claude". It IS the thread's phase in Worktrail, and it is not carried over: a new next declaration without it is refused. A next owned by the user is written TO the engineer ('Decide X'), never about them ('The user decides X'). Declare open and next before pausing, switching, or when the engineer's direction changes; resume shows them as the starting point. source_refs = the prompt id(s) a declaration comes from (the id from the prompt's "casebook source_ref: " line, or on a chat client the id add_utterance returns. Required for a focus with authority='user'.) 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>",
      "kind": "<kind>",
      "statement": "<statement>"
    },
    "name": "declare"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindYes
nextNo
ownerNo
captureNo
case_idYes
authorityNoagent
statementYes
source_refsNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.1/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: append-only supersede semantics, confirmation resets the turn cap and is not shown as a change, next without owner is refused, a user-owned next is written to the engineer not about them, and the server refuses record numbers in the first screen paragraphs. These are non-obvious behaviors an agent could not infer from the schema.

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?

It is one dense block with no headings or line breaks, and the focus instruction is restated twice ('what the thread is FOR and what would finish it' / 'what the thread does and what would finish it'), adding length without new information. Almost every sentence does carry a rule, but the lack of structure makes the required title-format and owner rules easy to miss.

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 described, and the text covers the hard parts: phase semantics, owner requirement, append-only behavior, and screen rendering constraints. Two parameters (case_id, capture) and the significance of authority remain undefined, which leaves a real gap for an 8-parameter tool with zero schema descriptions.

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 coverage is 0% across 8 parameters, and the text supplies real meaning for kind, owner (with its full value set: user/watch/agent name), next, statement (first line = title, body ordering), and source_refs (where the id comes from, required for focus with authority='user'). case_id and capture are never explained, and authority is only partially covered.

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 opening sentence states a concrete verb and three concrete resources (focus, open, next) plus the kind enum, so an agent knows exactly what is being recorded. It does not name any sibling (add_utterance, note_turn, resume) to differentiate itself, and the core statement is buried under a long normative tail.

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?

Gives explicit timing triggers: declare open and next before pausing, switching, or when the engineer's direction changes, and confirms that resume surfaces them as a starting point. It also defines when to re-declare verbatim (confirmation) versus with changed words (direction change). It never contrasts with alternatives like note_turn or decide, so routing is only partly covered.

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