Skip to main content
Glama

define

Record the meaning of a coined term so readers who weren't there understand it. Use it to capture or tidy up project-specific names within a work thread or across a repository.

Instructions

Give a coined name its meaning — a term the work uses that a reader who was not there would not know (e.g. '1층 조리법', '3회차', 'blinding'). term = the name as written (≤40 chars); meaning = one line (≤120 columns), details after a blank line. scope 'thread' (default) or 'repo' (every thread of the repository). Not enforced: use it when the engineer asks what a name meant or asks you to tidy up, or when you coin a name inside a record. Superseded (supersedes=), never edited. resume and the screens show current terms; the Find screen shows first use.

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>",
      "term": "<term>",
      "meaning": "<meaning>"
    },
    "name": "define"
  }
}

Input Schema

NameRequiredDescriptionDefault
termYes
scopeNothread
case_idYes
meaningYes
authorityNoagent
supersedesNo

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, the description carries the behavioral burden and does well: entries are 'Superseded (supersedes=<term id>), never edited', so the agent knows this is an append-only mutation, not an in-place update. It also discloses hard limits (term ≤40 chars, meaning ≤120 columns) and the scope escalation from 'thread' (default) to 'repo' (every thread of the repository). It does not discuss permissions, error behavior, or whether re-defining the same term in the same scope is rejected versus auto-superseded.

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 purpose and constraints are front-loaded, then usage triggers, then lifecycle rules — a sensible order with no filler sentences. It is telegraphic in places ('Not enforced:') and packs limits, scope, and lifecycle into a single dense block, which costs a little readability but not content.

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 six-parameter mutation tool with an output schema (so return values need no explanation), the description covers purpose, triggers, immutability, and most parameter meaning. The gap is case_id and authority, plus no note on what happens when a term collides with an existing one in the same scope.

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 documents four of six parameters with meaning beyond the schema: term (≤40 chars, 'as written'), meaning (one line ≤120 columns, details after a blank line), scope ('thread' default vs 'repo' = every thread), and supersedes (<term id>). case_id and authority are never mentioned, leaving two parameters with no guidance anywhere.

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 opens with a concrete verb+resource pair ('Give a coined name its meaning') and immediately qualifies the resource as a term 'a reader who was not there would not know', with three concrete examples. That distinguishes it from sibling read tools like find, resume, and search_prior, which surface existing content rather than mint definitions.

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?

It gives explicit triggers: 'use it when the engineer asks what a name meant or asks you to tidy up, or when you coin a name inside a record', and flags that the tool is 'Not enforced', which tells the agent it is optional. It also points to resume and the Find screen for reading terms back. There is no explicit statement of when NOT to use it, which keeps it short of a 5.

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