Skip to main content
Glama

write_milestone

Create or update a project milestone with a one-line goal, ordered acceptance checks, and position; rename, reorder, or delete it, including synced Linear/GitHub milestones.

Instructions

Write one of the project's milestones, or change it when one with this name exists (names are unique). Each milestone ships something a person can check: goal says what in one line, checks are its acceptance checks, [{"check": "", "expect": "", "for": "person"?}]. A check is the crew's (the default): the crew runs it and records it when the milestone's last ticket merges. Mark for: "person" only a step a person must do themselves (look at a screen, try a flow in the console); those reach the person to accept. position orders them (a new one goes last). To rename one, pass its current name or id as id and the new name. Give tickets a milestone with write_ticket(milestone=). When the project's tickets live in Linear or GitHub (link_tickets), a new milestone is created there, one per call, and a repeat of the same name finds it again; goal goes to Linear or GitHub as its description and checks stay here. Rename, reorder and delete a milestone in Linear or GitHub (position is ignored there).

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>"
    },
    "name": "write_milestone"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNo
goalNo
nameYes
checksNo
projectNo
positionNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.57.0

TDQS

A4.3/5.0
Behavior4/5

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

No annotations exist, so the description must carry the full load and it does: it discloses the unique-name upsert rule, that crew checks are recorded when the milestone's last ticket merges, and the non-obvious external side effect that new milestones are created one-per-call in Linear/GitHub, with `goal` mirrored there and `checks` kept local. Gaps remain around permissions, failure modes, and what happens to lower-level state on overwrite.

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 content is front-loaded with purpose first, then check semantics, then renaming/ordering, then the external-integration caveat, and every section carries information an agent needs. It is dense but not padded; only the inline embedded JSON example and mid-sentence parenthetical caveats make it slightly 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 six-parameter mutation tool with zero annotation coverage and an output schema, this covers the high-risk surface: upsert behavior, cross-system side effects, the local-vs-remote divergence for rename/reorder/delete, and the ignored `position` in Linear/GitHub mode. The unexplained `project` parameter and the absence of any note on what a write returns or whether it is idempotent are the remaining omissions.

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 description coverage is 0%, so the description has to compensate and largely does — it explains `id` (current name or id for renames), `goal`, `name` uniqueness, `checks` including the exact {check, expect, for} shape and the optional `for: "person"` escalation, and `position` ordering with 'a new one goes last'. Only `project` is left entirely undefined, which is the sole meaningful gap given six undocumented parameters.

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 precise verb+resource statement — 'Write one of the project's milestones, or change it when one with this `name` exists' — which makes the upsert semantics unambiguous. It also positions the tool relative to write_ticket (assignment) and link_tickets (external sync), so an agent can distinguish its role from the siblings it will interact with.

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 concrete operational guidance: use write_ticket(milestone=<name>) to attach tickets, pass `id` plus a new `name` to rename, and `position` to order. It also states a clear condition for marking a check `for: "person"` ('only a step a person must do themselves') versus the crew default. It stops short of explicit exclusions or a full when-not-to-use statement, which keeps it below a 5.

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