Skip to main content
Glama

open_thread

Start a durable work thread for one question or repository change, bind it to a worktree, and track decisions and evidence until the thread is finished.

Instructions

Start a thread — one question or change in one repository, followed to the end (deciding and building are one thread; re-declare focus to continue) — and bind it to this worktree. Open a new one only when the question changes. focus = one sentence, what this thread is for (durable declaration, not a summary). 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. topic (required) = the line of work this thread belongs to — it must be one of the engineer's existing topics; a name that is not one of them is refused once, with the list, so you choose instead of inventing. Only when none of them fits, call again with new_topic=true. "Uncategorized" (미분류) is refused — every thread belongs to a topic. Returns case_id; use it for evidence, note_turn, decide. 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": {
      "focus": "<focus>",
      "topic": "<topic>"
    },
    "name": "open_thread"
  }
}

Input Schema

NameRequiredDescriptionDefault
factsNo
focusYes
titleNo
topicYes
worktreeNo
authorityNoagent
new_topicNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations, the description carries the behavioral burden and mostly does: it discloses server-side refusals (unknown topic refused once with the list, "Uncategorized" refused, record numbers in the title or lead paragraph refused), the recovery path (retry with new_topic=true), and the return value (case_id, and which tools consume it). What it omits is the basic mutation profile — that this creates and persists an object bound to a worktree — and any permissions or idempotency note.

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?

The content is largely load-bearing — title formatting rules, refusal semantics, return value — but it is delivered as one undifferentiated block of em-dash clauses and parentheticals. The key instruction (first line is the title, body follows, quotes go last) is buried mid-paragraph rather than structured, which slows an agent trying to extract call-shaping constraints under time pressure.

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 7-parameter creation tool with no annotations and no output schema, the definition covers the essentials: what it creates, how topic validation fails and recovers, the exact title/body layout contract, and what it returns. The residual gap is the unexplained 'facts' and 'authority' parameters and the absence of any statement about persistence or side effects.

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%, so the description must carry parameter meaning, and it explains focus (durable one-sentence declaration, not a summary), topic (must match an existing engineer topic, with the refusal protocol), new_topic (escape hatch when nothing fits), title (first line, 120-column CJK-aware limit, no joiner, no record numbers), and worktree binding. Only 'facts' and 'authority' go entirely unexplained, which is a real but contained gap across 7 parameters.

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?

Opens with a concrete verb+resource: "Start a thread — one question or change in one repository ... and bind it to this worktree." It scopes the unit of work precisely (one question, one repo) and states the boundary condition "Open a new one only when the question changes," which implicitly separates it from continuing/re-declaring. It never names the sibling it is not (switch_thread, open_case), so differentiation is inferential rather than explicit.

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 real when-to-use and when-not rules: only when the question changes, re-declare focus instead of re-opening, and only use new_topic=true when no existing topic fits. It also states an exclusion ("Uncategorized" is refused). The gaps are that it does not name the alternative tool for continuing an existing thread, and the phrase "re-declare focus to continue" is ambiguous about which call performs that.

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