Skip to main content
Glama

assign_topic

Create or find a named topic and assign threads to it for retrospective review, adding case IDs, repositories, summary, and a conclusion to group related work across threads and repos.

Instructions

Put threads under a topic for the engineer's Review (retrospective) screen — a topic is a line of work spanning threads and repositories (e.g. 'MCP for code agents', 'incident lab'). name finds or creates the topic; case_ids are added (idempotent). repos = repository identities whose pre-thread git commits belong to this topic. conclusion = one sentence to pin on the topic when the engineer wraps it up (a topic's phase is derived; only the conclusion is written by hand). Use it only when the engineer names the topic or a new thread clearly continues one. 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": {
      "name": "<name>",
      "case_ids": "<case_ids>"
    },
    "name": "assign_topic"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYes
reposNo
summaryNo
case_idsYes
conclusionNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the burden well: it discloses the find-or-create side effect of name, idempotency of case_ids, that a topic's phase is derived rather than written, and that the server actively refuses record numbers in the title and first paragraph. It still says nothing about permissions, failure modes beyond that one refusal, or what an existing topic's untouched fields do.

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?

Purpose, usage and formatting rules are front-loaded in a sensible order, but the prose is a dense run-on of em-dash clauses, and the lengthy title/body formatting constraints would be better placed on the field they govern. Information-dense rather than padded, yet harder to scan than it needs to be.

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 five-parameter mutation tool with zero schema description coverage, most of what an agent needs is present, and an output schema exists so return values needn't be explained. The unexplained summary parameter and the ambiguous mapping of the title/body rule to a field are the remaining holes.

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 compensate, and it does for name (find-or-create), case_ids (added, idempotent), repos (pre-thread git commits belong to the topic), and conclusion (one sentence pinned at wrap-up). Two gaps remain: the summary parameter is never mentioned, and the FIRST LINE = TITLE / body-after-blank-line rule is stated without saying which parameter it applies to.

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?

States a specific verb and resource — putting threads under a topic for the Review screen — and defines what a topic is (a line of work spanning threads and repositories) with concrete examples. An agent can tell this is topic assignment, not topic merging or listing, without opening the schema.

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 an explicit gating condition: use it only when the engineer names the topic or a new thread clearly continues one. That is a real when-not-to-use rule (no speculative topic creation). It stops short of naming an alternative sibling such as merge_topic or list_topics for the excluded cases.

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