Skip to main content
Glama

update_epic

Update an epic. Pass only the fields to change. Set disabledReason to a string to mark an epic disabled, or null to re-enable. When you start working on an epic set planStatus=now and active=true. progressStatus is maturity: idea -> designed -> (acceptance, only if the project enables it) -> ready. Set 'designed' once the design/spec exists. 'acceptance' and 'ready' need no open tasks or unresolved questions — the server rejects them otherwise; close/move the tasks and resolve the questions first. When development, tests and review are done: set 'acceptance' if the project enables it (shown as Stages: in get_epic/list_epics), otherwise 'ready'. Moving past that stage to the next one is for the human, unless the user explicitly asks for it. If there is a known development gap, stay at 'designed'. Setting a stage the project has turned off is rejected — pick another status. 'deployed' is human-only, set only from 'ready' in the web UI — never available to agents; a deployed epic is locked to further changes. Work only on items assigned to the user unless told otherwise; see list_tasks assignee='me'.

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": {
      "epicId": "<epicId>"
    },
    "name": "update_epic"
  }
}

Input Schema

NameRequiredDescriptionDefault
ownerNo"me", a person's name, the email shown for members without a name, or id, or null to unassign.
titleNo
activeNo
epicIdYes
labelsNoFree-form tags, e.g. ['ui', 'auth']. Replaces the full set.
surfacesNoSurface names or ids this epic touches. Replaces the full set; [] = project-wide.
documentIdNoLink a detail/spec document. Pass null to unlink.
planStatusNo
descriptionNo
disabledReasonNo
progressStatusNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / labels
      Added value: +{
      +  "description": "Free-form tags, e.g. ['ui', 'auth']. Replaces the full set.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / surfaces
      Added value: +{
      +  "description": "Surface names or ids this epic touches. Replaces the full set; [] = project-wide.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  2. First observed

TDQS

A4.5/5.0
Behavior4/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 a strong job: it discloses server-side rejection rules, disabled-stage constraints, the locked state of deployed epics, and human-only transitions. It does not describe the response format or broader permission model, and the partial-update phrasing may understate that labels/surfaces replace their full sets, but the key behavioral risks are surfaced.

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 description is front-loaded with the core update instruction and then moves through status semantics efficiently. It is dense and somewhat run-on, but nearly every sentence carries operational meaning and no major filler is present.

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 an 11-parameter mutation tool with no annotations or output schema, the description is substantially complete around the complex workflow rules and rejection conditions. It leaves some parameter-level detail and return behavior to the schema and inference, but an agent can call the tool correctly for the primary status-management use cases.

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 only 36%, so the description must compensate, and it does so for the most complex parameters: disabledReason, planStatus, active, and every progressStatus value are explained with conditions. It adds little for simpler parameters like title, description, or epicId, but those are either obvious or covered by the schema.

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 specific verb and resource: 'Update an epic,' and immediately clarifies the partial-update behavior with 'Pass only the fields to change.' It distinguishes this from create_epic/get_epic by making the update action explicit and references get_epic/list_epics only as sources of related stage information.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance for planStatus and progressStatus, including the full maturity sequence and the conditions required for each stage. It also states when not to advance stages, that 'deployed' is human-only, and that agents should work only on items assigned to the user unless told otherwise.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources