Skip to main content
Glama

upsert_progress

Destructive

Save a checkpoint to an active thread and project PROGRESS.md so coding agents can resume unfinished work with clear goals, next steps, and blockers.

Instructions

Save a checkpoint to active thread state and project PROGRESS.md.

    Prefer a known thread_id so the checkpoint cannot land on the wrong
    thread. Update structured Goal/Focus/Next/Blocked/Resume only on routine
    checkpoints — do not pass ritual content such as "Thread upserted from …".
    Reserve content for rare human-meaningful events (decision, blocker note,
    ship note). If selection is ambiguous the tool can request a thread_id;
    force_new_thread explicitly starts another outcome. Depending on
    create_thread_if_missing, a missing thread may be created as a side effect.
    When completion.ready is false, prefer this plus pause_thread over mark_done.
    Saving thread progress clears paused_at and may sync to a configured
    forge/wiki or refresh scan-line AI. The returned thread.return_cue is
    advisory coaching on resume_step (missing / vague / concrete); weak cues
    do not reject a save. Name the first action using only facts you know.
    

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "upsert_progress"
  }
}

Input Schema

NameRequiredDescriptionDefault
goalNoFinishable outcome; null preserves it on update, empty string clears it.
focusNoCurrent focus, whitespace collapsed and truncated to 500 characters; null or blank preserves existing focus.
titleNoOptional thread title and new-project title; also used for outcome matching. Null preserves an existing thread title.
contentNoOptional meaningful history note (decision, blocker or ship note); omit for routine structured checkpoints. Boilerplate is dropped; exclude secrets.
thread_idNoExact existing thread ID in the resolved project; preferred for checkpoints. Takes precedence over force_new_thread.
next_stepsNoOrdered actions; retains the first 3 nonblank entries, each at most 500 characters. Null preserves; [] clears.
resume_stepNoConcrete first action on return; null preserves it, empty string clears it. Updating thread progress clears paused_at.
source_toolNoOptional originating client/tool name for attribution; null preserves an existing thread source.
project_slugNoProject identifier; takes precedence over workspace_path. Either this or workspace_path is required, even with thread_id.
blocked_reasonNoCurrent blocker; null preserves it, empty string clears it. Does not change thread status.
workspace_pathNoClient workspace folder path for project resolution; required when project_slug is absent and may register a missing project.
force_new_threadNoDefaults to false. True bypasses outcome matching when thread_id is absent; requires create_thread_if_missing=true.
create_thread_if_missingNoDefaults to true: select or create a thread when thread_id is absent. False saves project notes only unless thread_id is supplied.

Output Schema

NameRequiredDescriptionDefault
hintNo
errorNoPresent only when the checkpoint fails.
forgeNoConfigured forge/wiki sync outcomes; may contain sync errors.
detailNoAdditional detail for a missing thread.
threadNoSaved state on success; null for notes-only.
thread_idNoSelected thread; null for notes-only or selection-required.
candidatesNoPresent when explicit thread selection is required.
project_slugNo
progress_pathNoWritten PROGRESS.md path; null while selection is required.
created_threadNoPresent on success; whether a thread was created.
needs_thread_selectionNoIf true, choose a candidate thread_id or explicitly force a new thread.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changedv0.22.0
    • addedInput schema / properties / blocked_reason / description
      Added value: +"Current blocker; null preserves it, empty string clears it. Does not change thread status."
    • addedInput schema / properties / content / description
      Added value: +"Optional meaningful history note (decision, blocker or ship note); omit for routine structured checkpoints. Boilerplate is dropped; exclude secrets."
    • addedInput schema / properties / create_thread_if_missing / description
      Added value: +"Defaults to true: select or create a thread when thread_id is absent. False saves project notes only unless thread_id is supplied."
    • addedInput schema / properties / focus / description
      Added value: +"Current focus, whitespace collapsed and truncated to 500 characters; null or blank preserves existing focus."
    • addedInput schema / properties / force_new_thread / description
      Added value: +"Defaults to false. True bypasses outcome matching when thread_id is absent; requires create_thread_if_missing=true."
    • addedInput schema / properties / goal / description
      Added value: +"Finishable outcome; null preserves it on update, empty string clears it."
    • addedInput schema / properties / next_steps / description
      Added value: +"Ordered actions; retains the first 3 nonblank entries, each at most 500 characters. Null preserves; [] clears."
    • addedInput schema / properties / project_slug / description
      Added value: +"Project identifier; takes precedence over workspace_path. Either this or workspace_path is required, even with thread_id."
    • addedInput schema / properties / resume_step / description
      Added value: +"Concrete first action on return; null preserves it, empty string clears it. Updating thread progress clears paused_at."
    • addedInput schema / properties / source_tool / description
      Added value: +"Optional originating client/tool name for attribution; null preserves an existing thread source."
    • addedInput schema / properties / thread_id / description
      Added value: +"Exact existing thread ID in the resolved project; preferred for checkpoints. Takes precedence over force_new_thread."
    • addedInput schema / properties / title / description
      Added value: +"Optional thread title and new-project title; also used for outcome matching. Null preserves an existing thread title."
    • addedInput schema / properties / workspace_path / description
      Added value: +"Client workspace folder path for project resolution; required when project_slug is absent and may register a missing project."
    • addedOutput schema / $defs
      Added value: +{
      +  "CompactThreadResult": {
      +    "additionalProperties": true,
      +    "description": "Checkpoint state and candidate selection; timestamps retain wire format.",
      +    "properties": {
      +      "authority": {
      +        "$ref": "#/$defs/WorkAuthority"
      +      },
      +      "blocked_reason": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Blocked Reason"
      +      },
      +      "completion": {
      +        "$ref": "#/$defs/CompletionResult"
      +      },
      +      "external_host": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Host"
      +      },
      +      "external_issue_number": {
      +        "anyOf": [
      +          {
      +            "type": "integer"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Issue Number"
      +      },
      +      "external_issue_state": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/ExternalIssueState"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "external_owner": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Owner"
      +      },
      +      "external_provider": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/WorkSource"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "external_repo": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Repo"
      +      },
      +      "focus": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Focus"
      +      },
      +      "goal": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Goal"
      +      },
      +      "id": {
      +        "title": "Id",
      +        "type": "string"
      +      },
      +      "next_steps": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "Next Steps",
      +        "type": "array"
      +      },
      +      "project_slug": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Project Slug"
      +      },
      +      "resume_step": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Resume Step"
      +      },
      +      "return_cue": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/ReturnCueResult"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "status": {
      +        "$ref": "#/$defs/ThreadStatus"
      +      },
      +      "summary": {
      +        "title": "Summary",
      +        "type": "string"
      +      },
      +      "title": {
      +        "title": "Title",
      +        "type": "string"
      +      },
      +      "updated_at": {
      +        "format": "date-time",
      +        "title": "Updated At",
      +        "type": "string"
      +      },
      +      "work_source": {
      +        "$ref": "#/$defs/WorkSource"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "title",
      +      "summary",
      +      "goal",
      +      "status",
      +      "focus",
      +      "next_steps",
      +      "blocked_reason",
      +      "resume_step",
      +      "updated_at",
      +      "project_slug",
      +      "completion",
      +      "return_cue",
      +      "work_source",
      +      "authority",
      +      "external_provider",
      +      "external_host",
      +      "external_owner",
      +      "external_repo",
      +      "external_issue_number",
      +      "external_issue_state"
      +    ],
      +    "title": "CompactThreadResult",
      +    "type": "object"
      +  },
      +  "CompletionResult": {
      +    "additionalProperties": true,
      +    "description": "Readiness based on stored thread state, without checking a forge or PR.",
      +    "properties": {
      +      "ready": {
      +        "description": "True when stored state has no completion blockers.",
      +        "title": "Ready",
      +        "type": "boolean"
      +      },
      +      "reasons": {
      +        "description": "Stored blockers; empty when ready is true.",
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "Reasons",
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "ready",
      +      "reasons"
      +    ],
      +    "title": "CompletionResult",
      +    "type": "object"
      +  },
      +  "ExternalIssueState": {
      +    "enum": [
      +      "open",
      +      "closed"
      +    ],
      +    "title": "ExternalIssueState",
      +    "type": "string"
      +  },
      +  "ReturnCueResult": {
      +    "additionalProperties": true,
      +    "description": "Advisory resume coaching; never rejects a save, pause or completion.",
      +    "properties": {
      +      "advisory": {
      +        "const": true,
      +        "title": "Advisory",
      +        "type": "boolean"
      +      },
      +      "hint": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Hint"
      +      },
      +      "quality": {
      +        "enum": [
      +          "missing",
      +          "vague",
      +          "concrete"
      +        ],
      +        "title": "Quality",
      +        "type": "string"
      +      },
      +      "signals": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "Signals",
      +        "type": "array"
      +      },
      +      "suggestion": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/ReturnCueSuggestion"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "version": {
      +        "title": "Version",
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "quality",
      +      "signals",
      +      "hint",
      +      "suggestion",
      +      "advisory",
      +      "version"
      +    ],
      +    "title": "ReturnCueResult",
      +    "type": "object"
      +  },
      +  "ReturnCueSuggestion": {
      +    "additionalProperties": true,
      +    "properties": {
      +      "source": {
      +        "enum": [
      +          "focus",
      +          "next_steps"
      +        ],
      +        "title": "Source",
      +        "type": "string"
      +      },
      +      "text": {
      +        "title": "Text",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "source",
      +      "text"
      +    ],
      +    "title": "ReturnCueSuggestion",
      +    "type": "object"
      +  },
      +  "ThreadStatus": {
      +    "enum": [
      +      "open",
      +      "blocked",
      +      "done",
      +      "dismissed"
      +    ],
      +    "title": "ThreadStatus",
      +    "type": "string"
      +  },
      +  "WorkAuthority": {
      +    "enum": [
      +      "hub",
      +      "external"
      +    ],
      +    "title": "WorkAuthority",
      +    "type": "string"
      +  },
      +  "WorkSource": {
      +    "enum": [
      +      "local",
      +      "github",
      +      "gitea"
      +    ],
      +    "title": "WorkSource",
      +    "type": "string"
      +  }
      +}
    • addedOutput schema / description
      Added value: +"Saved checkpoint, ambiguous selection, or error; absent keys stay absent."
    • addedOutput schema / properties
      Added value: +{
      +  "candidates": {
      +    "description": "Present when explicit thread selection is required.",
      +    "items": {
      +      "$ref": "#/$defs/CompactThreadResult"
      +    },
      +    "title": "Candidates",
      +    "type": "array"
      +  },
      +  "created_thread": {
      +    "description": "Present on success; whether a thread was created.",
      +    "title": "Created Thread",
      +    "type": "boolean"
      +  },
      +  "detail": {
      +    "description": "Additional detail for a missing thread.",
      +    "title": "Detail",
      +    "type": "string"
      +  },
      +  "error": {
      +    "description": "Present only when the checkpoint fails.",
      +    "title": "Error",
      +    "type": "string"
      +  },
      +  "forge": {
      +    "additionalProperties": true,
      +    "description": "Configured forge/wiki sync outcomes; may contain sync errors.",
      +    "title": "Forge",
      +    "type": "object"
      +  },
      +  "hint": {
      +    "title": "Hint",
      +    "type": "string"
      +  },
      +  "needs_thread_selection": {
      +    "description": "If true, choose a candidate thread_id or explicitly force a new thread.",
      +    "title": "Needs Thread Selection",
      +    "type": "boolean"
      +  },
      +  "progress_path": {
      +    "anyOf": [
      +      {
      +        "type": "string"
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ],
      +    "description": "Written PROGRESS.md path; null while selection is required.",
      +    "title": "Progress Path"
      +  },
      +  "project_slug": {
      +    "title": "Project Slug",
      +    "type": "string"
      +  },
      +  "thread": {
      +    "anyOf": [
      +      {
      +        "$ref": "#/$defs/CompactThreadResult"
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ],
      +    "description": "Saved state on success; null for notes-only."
      +  },
      +  "thread_id": {
      +    "anyOf": [
      +      {
      +        "type": "string"
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ],
      +    "description": "Selected thread; null for notes-only or selection-required.",
      +    "title": "Thread Id"
      +  }
      +}
    • changedOutput schema / title
      Previous value: -"upsert_progressDictOutput"New value: +"ProgressResult"
  2. First observedv0.12.0

TDQS

A4.7/5.0
Behavior5/5

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

Goes well past the annotations by disclosing side effects: create_thread_if_missing can create a thread, saving clears paused_at, and the save may sync to a configured forge/wiki or refresh scan-line AI (matching openWorldHint=true). It also flags that the returned thread.return_cue is advisory coaching that does not reject a save, which prevents an agent from misreading a weak cue as an error.

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?

Front-loads the core purpose, then layers routing rules, and every sentence carries a decision rule rather than filler. A few clauses are dense or opaque ('refresh scan-line AI', the truncated quoted boilerplate example), which slightly slows parsing but does not obscure the guidance.

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 13-parameter mutation tool with full schema coverage, annotations, and an output schema, the description covers the risky parts: thread creation side effects, cleared pause state, external sync, and sibling routing. What remains thin is failure behavior (e.g., ambiguous selection outcomes beyond 'may request a thread_id') and what exactly the PROGRESS.md write entails.

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 100%, so the baseline is 3, but the description adds real selection logic on top: thread_id takes precedence and is preferred over force_new_thread, force_new_thread requires create_thread_if_missing, and content should be omitted for routine checkpoints. It does not extend the null-vs-empty-string semantics, which the schema already documents well.

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?

Opens with a specific verb and dual resource: 'Save a checkpoint to active thread state and project PROGRESS.md.' That immediately separates it from upsert_thread (thread metadata), mark_done (completion), and pause_thread (suspension), all of which appear in the sibling list.

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?

Gives explicit routing rules: prefer a known thread_id, use this plus pause_thread when completion.ready is false instead of mark_done, and use force_new_thread only to start another outcome. It also states exclusions for content ('do not pass ritual content such as "Thread upserted from …"') and reserves content for decision/blocker/ship notes.

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