ADHD Progress Hub

Overview Schema Source Related Servers Discussions Admin

upsert_progress

Save a progress checkpoint to the active thread and project PROGRESS.md, updating goal, focus, next steps, blockages, and resume state to keep context continuous.

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`goal`	No
`focus`	No
`title`	No
`content`	No
`thread_id`	No
`next_steps`	No
`resume_step`	No
`source_tool`	No
`project_slug`	No
`blocked_reason`	No
`workspace_path`	No
`force_new_thread`	No
`create_thread_if_missing`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.12.0Sep 14, 2026

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 behavioral burden, and it does disclose key side effects: saving to PROGRESS.md, possibly creating a missing thread, and the ability to request a thread_id when selection is ambiguous. It does not mention overwrite/merge semantics or auth requirements, but the main 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 purpose, then provides compact behavioral rules. It is somewhat dense with multiple directives in a few sentences, but every sentence adds operational value and there is no filler.

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?

Given 13 optional parameters and no annotations, the description covers the important usage decisions: thread selection, content discipline, and thread-creation side effects. It does not explain every parameter or return behavior, but the output schema exists and the most consequential behavior is documented.

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 must add meaning, and it does: thread_id is tied to avoiding wrong-thread checkpoints, content is reserved for rare meaningful events, force_new_thread and create_thread_if_missing are explained. Some parameters like project_slug, workspace_path, and source_tool are not addressed, but the most decision-critical ones are clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence, 'Save a checkpoint to active thread state and project PROGRESS.md', states a specific verb, resource, and destination. It is clear about what the tool does, and the mention of PROGRESS.md hints at its distinct role, though it does not explicitly name a sibling tool it differs from.

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?

The description gives explicit when-to-use and when-not-to-use guidance: 'Prefer a known thread_id', 'Update structured Goal/Focus/Next/Blocked/Resume only on routine checkpoints', and 'Reserve content for rare human-meaningful events'. It also explains decision paths for ambiguous selection, force_new_thread, and create_thread_if_missing, giving an agent actionable routing rules.

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