This server provides a shared, encrypted TODO list with MCP tools, a real-time web dashboard, claims, history, and optional multi-device sync.
Add todos to the todo or backlog list with optional description, category, priority, due date, and source URL.
Edit existing todos by id (title, description, category, priority, due date, list).
Claim/release items to show who is actively working on them; claims auto-expire.
List and filter todos by status, list, category, agent, session, or in-progress state.
Complete or permanently delete todos.
View full change history per item (who did what and when).
Check server version and start time to verify the running process.
Real-time web dashboard (SSE) at http://localhost:8787 with search, sort, inline edit, undo-delete, and mobile-friendly UI.
Secure LAN Viewer Gate for phone access with host approval.
Encrypted at-rest storage, CLI export/import in JSON/Markdown, and optional device pairing for multi-machine sync.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@todo-mcp add a todo: review pull request by Friday"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
One todo list, shared by every AI tool you use. Claude Code, Claude Desktop, Cursor, Windsurf, Warp, Codex — add an item in one, see it in all of them, plus a real-time web dashboard and your phone. Nothing gets lost switching tools or starting a new session.
Claude Code · Claude Desktop · Cursor · Windsurf · Warp · Codex
|
MCP
|
v
Docket ----> Encrypted list (your machine)
| ^
v |
Web dashboard :8787 -----------'
(SSE, live updates)
^
| browser, Viewer Gate approved
|
Your phoneEvery client talks to the same server, which is the only thing that ever touches the data file — so there's one source of truth, not four out-of-sync copies. Everything lives locally: no account, no cloud, nothing to sign up for.
What it adds beyond "just a list":
See who's doing what. Claim an item before starting on it — other sessions see it's taken (with a live pulsing highlight) instead of duplicating the work.
Full history, not just a checkbox — every edit/claim/complete is logged with who and when.
Todo vs. backlog — keep near-term work separate from things you want to park without losing them.
Private by default — the data file is encrypted on disk; nobody reading your filesystem casually sees your task list in plain text.
Jump back to the source — attach a link (a GitHub issue/PR, a Notion page, an Obsidian note, anything with a URL) so a card takes you straight back to where it came from.
Real-time Web UI (SSE) — zero-delay live updates via Server-Sent Events whenever an AI agent or peer modifies a task.
Secure LAN Viewer Gate — access your list from your phone with an explicit approval handshake on your computer.
CLI & Backup Tools — terminal stats widget, fast command-line lists, and export/import in JSON and Markdown, from the terminal or from an Export & Import panel in the web UI itself.
Optional multi-device sync — pair your laptop and desktop and the same list follows you, with an explicit approve/deny handshake on both ends (see Devices & sync).
Self-updating — docket check-update / docket update check npm
for a newer version, ask for confirmation, and verify the new version
actually starts before keeping it (see Updating).
Five minutes, no prior MCP experience needed. This sets up the server, the web UI, and the optional Claude Code skill in one go.
You need: Claude Code (or another MCP host) already
installed, and Node.js 18+ (check with node --version in a terminal — if
that command isn't found, get Node from nodejs.org).
1. Run the interactive setup wizard. It creates and verifies one shared
durable data directory, configures detected MCP hosts, optionally installs the
claim skill for Claude Code and Codex, and can add a todo_stats helper to your shell startup:
npx -y @pasichdev/docket setupThe wizard writes host configuration automatically when Codex, Claude Code, Cursor, or Windsurf is detected. For automation or a non-interactive terminal, pass the directory explicitly:
npx -y @pasichdev/docket setup --data-dir "$HOME/.local/state/docket"The printed DOCKET_DATA_DIR is the value used in those host entries. The
wizard merges existing JSON configuration and does not replace unrelated
servers.
2. Register the server. Open a terminal and run:
claude mcp add docket -- npx -y @pasichdev/docketThis just tells Claude Code how to start Docket — nothing is downloaded
yet. npx fetches and runs it the first time it's actually used.
3. Restart Claude Code (close and reopen it, or start a new session) so it picks up the new server.
4. Try it. In a chat, ask Claude something like "add a todo: buy milk". If it uses the tool and confirms, the server is working.
5. Open the web UI. Go to http://localhost:8787 in your browser — it started itself the moment step 3 ran, no separate install step. From here you can add/edit/complete items with a mouse, switch light/dark theme, and search/sort/filter the list.
6. (Optional) Install the claim-tracking skill. This teaches Claude Code to mark an item as "in progress" while it's actively working on it, and to check first before starting something another session already claimed. In Claude Code:
/plugin marketplace add pasichDev/docket
/plugin install docket-claim@docketNothing to configure afterward — it applies automatically.
Using a different MCP host (Claude Desktop, Cursor, Windsurf, Zed, Warp, Codex)? See Install below for the config-file form.
Related MCP server: sprinter
docket is also a full terminal utility with subcommands for inspection, backup, and quick access:
# Terminal stats widget (great for tmux / prompt scripts)
npx @pasichdev/docket stats
# Quick task list in your terminal
npx @pasichdev/docket list
npx @pasichdev/docket list all
# Export tasks to Markdown or JSON
npx @pasichdev/docket export --format markdown > tasks.md
npx @pasichdev/docket export --format json --out backup.json
# Import tasks from Markdown or JSON
npx @pasichdev/docket import tasks.md
npx @pasichdev/docket import backup.json
# Encrypted full-device backup/restore — identity, todos, and paired peers, not just the
# task list (see "Data & encryption" below for what's in it and the recovery flow)
npx @pasichdev/docket backup ./docket.backup
npx @pasichdev/docket restore ./docket.backup
# Open or verify Web UI dashboard
npx @pasichdev/docket web
# Check for / install a newer version (global installs only — see Updating)
npx @pasichdev/docket check-update
npx @pasichdev/docket updateTwo lists: todo (near-term, actionable) and backlog (parked, out
of context)
Rich fields: title + separate description, category (e.g. a ticket id), priority, due date, source URL
Claim/release: mark an item as actively being worked on so other agents/sessions don't duplicate the effort — shown live in the web UI with the claiming agent's name and a pulsing highlight
Full history: every create/edit/claim/release/complete is logged with
who and when, visible per item in both the web UI and via todo_history
Real-Time Web UI: http://localhost:8787 by default with SSE (Server-Sent Events) — light/dark theme, search,
sort, inline edit, undo-delete, and responsive mobile UI
Secure LAN Viewer Gate: view from your phone on the same Wi-Fi with host approval and rate-limited tokens
Encrypted at rest: the data file is AES-256-GCM encrypted with a locally generated key (see Data & encryption)
Safe upgrades & Graceful Shutdown: clean signal handling (SIGINT/SIGTERM) and version safety checks
Reference for other MCP hosts, or building from source instead of npx.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"docket": {
"command": "npx",
"args": ["-y", "@pasichdev/docket"]
}
}
}Add to .cursor/mcp.json or Global MCP settings:
{
"mcpServers": {
"docket": {
"command": "npx",
"args": ["-y", "@pasichdev/docket"]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"docket": {
"command": "npx",
"args": ["-y", "@pasichdev/docket"]
}
}
}Add to ~/.config/zed/settings.json:
{
"context_servers": {
"docket": {
"command": {
"env": {},
"path": "npx",
"args": ["-y", "@pasichdev/docket"]
}
}
}
}git clone https://github.com/pasichDev/docket.git
cd docket
npm install
npm run build
claude mcp add docket -- node "$(pwd)/dist/index.js"Tool | Description |
| Add an item. |
| Edit any subset of fields by id. Pass |
| Mark an item as actively being worked on by you. Advisory, not a lock — warns (and lets you take over) if already claimed. Auto-expires after 15 minutes if never renewed or released. |
| Clear your claim without completing the item. |
| List items with optional filtering by status, list, category, agent, session, claim state, and token-saving pagination ( |
| Mark done (also clears any claim). |
| Full change log for one item — who did what, when. |
| Report the running process's data-format version and start time. |
| Permanently remove an item. |
| Check npm for a newer Docket version. Read-only — never installs anything; tells you to run |
See skills/docket-claim/SKILL.md for
the full field/workflow reference written for an agent to follow.
Covered in step 5 of the Installation guide above.
The non-interactive form: claude plugin marketplace add pasichDev/docket
then claude plugin install docket-claim@docket. Source:
skills/docket-claim/SKILL.md.
The MCP tools themselves work the same in every host — no extra setup needed
beyond Install above. The claim-workflow guidance (when to
todo_claim/todo_release, which fields to set) ships as an installable
plugin for Claude Code only; every other agent reads its instructions from a
plain file in your own project, so copy the body of
skills/docket-claim/SKILL.md — everything
below the --- frontmatter — into whichever your agent already looks for:
Agent | File |
Codex CLI, and any agent following the emerging convention |
|
Cursor |
|
Windsurf |
|
Claude Desktop / Claude web |
|
Warp | Warp's own custom-instructions setting |
The content itself doesn't mention any specific host, so it's the same paste everywhere — only the destination filename changes.
A real-time read/write dashboard on http://localhost:8787 (override with
DOCKET_WEB_PORT) — light/dark theme, search, sort, inline edit,
undo-delete.
Every time an MCP client connects, it checks whether something is already
listening on the web UI's port — if not, it spawns web.js detached in the
background. The child process survives after the short-lived MCP connection
exits, ensuring zero overhead and instant UI availability.
The web UI connects to the server via Server-Sent Events (/api/events). When
an AI agent or peer device creates, edits, claims, or completes a task, the dashboard
updates instantly without manual page refreshes or heavy polling.
The web server binds to 0.0.0.0 so you can open your dashboard from your phone or tablet on the same Wi-Fi.
Viewer Gate:
Requests originating from the local machine (127.0.0.1 / ::1) are authenticated automatically via a per-run secure UI session token.
Any other browser or phone on the LAN is presented with a Viewer Gate screen.
The host device's dashboard receives an incoming access notification. Only when a human clicks Approve on the host machine is a scoped viewer token issued to the requesting browser.
All endpoints are fortified with standard security headers (X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: same-origin) and IP rate limiting.
Pair a second computer (say, a desktop) and both keep the same list — useful if you work from more than one machine. This is off by default and stays off until you deliberately turn it on: nothing scans your network, nothing connects to anything, until you open the Devices panel (the icon in the header) and start a pairing.
Pairing, step by step:
On device A, open Devices → Show my code. It shows a QR code and a
6-character code (e.g. WY6BWK), valid once, for 5 minutes.
On device B, open Devices → I have a code, type A's host address and the 6-character code (or paste the full line shown under A's QR into either field — both work).
Device A shows a pending request — "Pairing request from <B>" — with Approve / Deny buttons. Nothing is shared until a human clicks Approve on A. There is no automatic or silent pairing path.
Once approved, both devices independently poll each other every 15s and merge changes. Unpair either side at any time from the Devices panel to revoke it.
Host and guest. Every device starts out a host — it can invite and approve others. The moment a device joins someone else's group via "I have a code", it becomes a guest: it stays fully in sync, but the Devices panel hides its own "Pair new device" controls, and the server rejects invite/approve calls even if something tried to call the API directly. Only the device that originated a group can grow it — a guest can't quietly become a new entry point into the network. Unpairing from every peer restores host status.
How the trust works: each device generates its own X25519 identity key
pair on first run (device.json in Docket's resolved data directory) and never transmits its
private half. Pairing exchanges only the two devices' public keys; each
side then independently derives the same shared secret via ECDH + HKDF —
the secret itself never crosses the network in either direction, so
capturing the pairing traffic doesn't give an eavesdropper anything usable.
That secret authenticates every sync request (HMAC-SHA256 over the request,
with a signed timestamp to block replay) and encrypts every sync response
(AES-256-GCM) — sync payloads are not plaintext on the wire. The one-time
pairing token is rate-limited per source IP to make brute-forcing it impractical.
How the merge works: two machines can each go offline and both keep
editing. When they reconnect, changes merge field by field — if device
A changed the priority and device B changed the description while apart,
both changes survive; neither clobbers the other. Deletes propagate as
tombstones (so a deleted item doesn't get silently resurrected by the other
side's older copy) but an edit made after a delete wins and brings the
item back. A claim (todo_claim) syncs like any other
field, but its 15-minute lease means a stale claim fades on its own instead
of surviving forever in the replicated history.
docket check-update # read-only — reports current vs. latest, installs nothing
docket update # checks, asks for confirmation, then installsupdate only applies to a global npm install (npm install -g @pasichdev/docket).
Running via npx always fetches the latest published version on its own, so there's
nothing to update; a git clone checkout is updated with git pull && npm run build.
update never installs anything without asking first, and after installing it boots the
new version on a throwaway port with throwaway data to confirm it actually starts —
if that check fails, it automatically reinstalls the previous version instead of leaving
you on a broken one.
Provenance: every release is published with npm publish --provenance — a
Sigstore-backed attestation
that cryptographically ties the published package to the exact GitHub Actions run and
commit that built it, verifiable via npm audit signatures. This is deliberate instead
of a custom signing scheme: it reuses npm's own trusted infrastructure rather than
Docket managing its own signing keys.
Data lives in the retained legacy location ~/.docket/ by default. Set
DOCKET_DATA_DIR to explicitly select a shared location. If creation of a
missing default-home directory is blocked, an explicitly configured
$XDG_STATE_HOME is used. If existing legacy data is inaccessible or read-only,
startup refuses rather than silently splitting the store; set
DOCKET_DATA_DIR to an approved writable durable location. If neither durable
location is writable, startup names DOCKET_DATA_DIR as the required fix rather
than creating a second list in a disposable cache. To share
one list across multiple isolated MCP hosts, set the same
DOCKET_DATA_DIR in each host's configuration.
todos.json.enc — the store, AES-256-GCM encrypted
key — a locally generated 256-bit key, written once with chmod 600
(owner-read-only)
device.json — this machine's id, display name, and X25519 identity key
pair — private half never leaves this file
peers.json.enc — paired devices and their derived sync secrets,
encrypted the same way as the todo store
server.log — plain-text process log (no todo content in it)
If you upgrade from a version before encryption was added, the old plaintext
todos.json is migrated automatically on first read and kept as todos.json.bak.
Encrypted backup/restore: docket backup <file> bundles this whole data
directory — identity, at-rest key, todos, and paired peers — into one
password-protected file (AES-256-GCM, key derived with scrypt), so a lost or
wiped machine can be brought back on the same or different hardware and still
be recognized by every device it was paired with, instead of showing up as a
new, unpaired one. docket restore <file> decrypts and writes it back,
renaming whatever's currently on disk aside as .pre-restore-*.bak first
rather than overwriting it outright. Store the backup file and its password
separately — either one alone is useless, but losing both makes the
backup itself unrecoverable, same as losing the file with no backup at all.
What Docket protects against, what it deliberately doesn't, and why:
Disk / at-rest exposure — see "Data & encryption" above: local-machine
AES-256-GCM protects against accidental exposure (a stray git add -A, a
backup tool that drops permissions, another account on a shared machine),
not against someone with read access to your own user account — the key
sits next to the data it protects.
LAN sniffing of device-to-device sync — encrypted end-to-end regardless of transport: the shared secret is derived independently on each side via X25519 ECDH + HKDF and never crosses the network, every sync request is HMAC-signed with replay protection, and every sync response is AES-256-GCM encrypted. A passive LAN listener gets nothing usable from sync traffic.
LAN sniffing of viewer (browser) traffic — not encrypted; the web UI is plain HTTP. Real transport encryption here would mean either a self-signed TLS cert (constant browser warnings on every device that opens the dashboard) or an app-layer scheme keyed off the viewer's own bearer token — which protects nothing, since that same token already travels in the clear and a LAN eavesdropper who can read the traffic can read the token. Given that, the practical mitigation is what's already in place: access requires a human to click Approve on the host device first (see "LAN Viewer Gate" above), so the exposure is "an already-approved LAN can read dashboard traffic," not "anyone on the LAN gets in."
A malicious or compromised peer — sync payloads from a peer are
validated and clamped field-by-field before touching the store (rejects
malformed items, strips javascript:/data: URLs, drops unrecognized
history actions and fieldTimestamps keys) rather than trusted wholesale,
and a sync request body is capped at 10MB. A peer can be revoked
(Devices panel) to immediately stop syncing with it without losing the
pairing itself, or fully unpaired to drop it entirely.
A stolen/leaked viewer bearer token — grants read/write dashboard access until the host explicitly revokes that viewer (Devices panel); it is not scoped further (no read-only mode, no per-token expiry today). Treat a viewer link/token the way you'd treat a shared password.
A compromised device — Docket does not detect or contain this; a device that's been compromised can read/write everything that device could already read/write (its own todos, and anything its paired peers sync to it). Revoking or unpairing it from the Devices panel of an uncompromised peer stops further sync from it.
Cross-site/CSRF requests against the web UI — the session/viewer
cookies are SameSite=Strict (the primary defense: a real cross-site
request never carries them at all), plus explicit Origin/Referer
validation on every mutating request as defense-in-depth. The Host header
itself is also validated (rejects anything but localhost, an IP literal,
or a .local mDNS name) to close DNS-rebinding as a way around both.
A malicious/tampered update — npm publish --provenance (see
"Updating" above) cryptographically ties every published version to the
exact GitHub Actions run and commit that built it, verifiable via
npm audit signatures; docket update also self-tests the freshly
installed version before keeping it, and rolls back automatically if that
fails.
npm testRuns the unit suite (node:test, no extra dependency) covering the sync
merge algorithm, encryption round-trips and tamper rejection, the pairing
handshake's signature/proof verification, JSON and Markdown export/import,
and UUIDv7 generation.
For an interactive check of the MCP tools themselves:
npx @modelcontextprotocol/inspector node dist/index.jsMIT — see LICENSE.
Add a new item to the shared global TODO list. Use list="backlog" for things to park and not hold in context (deferred findings, low-priority follow-ups); list="todo" (default) for near-term actionable items.
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | Which list this item belongs to | todo |
| title | Yes | Short one-line title/summary | |
| dueDate | No | Optional due date, YYYY-MM-DD | |
| category | No | Optional free-form category/tag, e.g. a ticket id like "VPQ-834" | |
| priority | No | Optional priority | |
| description | No | Optional longer body text — details, context, links |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations correctly indicate a non-read-only, non-destructive write operation, and the description aligns with that. The description adds valuable context beyond annotations by noting the list is 'shared global', which implies that adding affects a common resource visible to others. Minor gap: no mention of what happens on success or failure (e.g., return value), but this is relatively minor for a non-destructive add operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with zero filler. The core action is front-loaded, and the key usage distinction follows immediately. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and full schema coverage, the description covers the major decision point (which list to use). The only notable gap is that the description doesn't mention the return value (e.g., created item, ID, confirmation), which could matter since there is no output schema. Overall, it's still complete enough for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by giving each list meaningful purpose ('park' versus 'near-term actionable'), which is semantic guidance the schema doesn't provide. This additional distinction justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Add a new item') on a specific resource ('the shared global TODO list'). It clearly distinguishes this from siblings like todo_edit and todo_delete, and it even clarifies the semantics of the two lists, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides exemplary routing guidance: explicitly states when to use list='backlog' (deferred findings, low-priority follow-ups) versus list='todo' (near-term actionable items). This directly helps an agent decide which list to use, going beyond what the schema's default value alone would convey.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an item as actively being worked on by you (the calling agent). Advisory, not a lock — check todo_list(inProgress: true) before starting new work to avoid duplicating another agent's active item. Call todo_release or todo_complete when you stop.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The todo id, e.g. 3 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond annotations by stating that the claim is advisory, not a lock, and by specifying the actions that should follow. Combined with readOnlyHint=false and destructiveHint=false, the agent understands this is a non-destructive state-change operation. It does not detail edge cases like claiming an already-claimed item, but the advisory framing mitigates that gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and every sentence adds value. It fits the essential guidance into two sentences without repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation tool, the description covers the action, the advisory nature, the pre-check workflow, and the follow-up calls. There is no output schema, so the description could theoretically mention the return value, but that is not essential for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the id parameter is adequately described as 'The todo id, e.g. 3'. The description does not add extra parameter semantics, but none are needed because the schema already handles the documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair: 'Mark an item as actively being worked on by you' clearly identifies what the tool does and which resource it affects. It further distinguishes itself from related operations by calling out todo_release and todo_complete, and by emphasizing that claiming is advisory rather than a lock.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context: check todo_list with inProgress:true before starting new work to avoid duplicating someone else's active item, and call todo_release or todo_complete when stopping. It does not enumerate all alternatives or explicitly state when not to use the tool, but the workflow guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a todo as done by id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The todo id, e.g. 3 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the operation is neither read-only nor destructive; the description adds that the todo transitions to a 'done' state. It does not disclose whether completing is idempotent, reversible via todo_release, or what happens if the id is missing or invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single action-first sentence with no filler. It delivers the core operation and the required identifier without wasting tokens.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation with annotations covering safety, the description is mostly sufficient, but it does not clarify the todo lifecycle relationship to release/claim or the result of successful completion. Given the sibling set, a short lifecycle note would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' already has a complete schema description including an example, and the tool description only repeats the concept of 'by id'. With schema coverage at 100%, the baseline of 3 applies without needing additional explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('mark'), the resource ('a todo'), and the target state ('done'), and identifies the selection key ('by id'). This clearly sets it apart from siblings like todo_delete, todo_edit, and todo_claim.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use todo_complete versus alternatives. With eight siblings including todo_release and todo_claim, the description does not state conditions or exclusions, such as not for re-opening or not for editing details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently remove a todo by id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The todo id, e.g. 3 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the nuance of permanence, but it does not disclose side effects like whether related history or version records are affected, or whether any preconditions apply. This is acceptable given the annotation coverage, but not richly informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no filler. The core action and object are front-loaded, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive operation with annotations already flagging the destructive nature, the description is nearly complete. It clearly states the input requirement and behavior. The only minor gap is not mentioning what the operation returns or whether it is reversible beyond 'permanently,' but this does not block correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the sole parameter 'id' is already documented with an example. The description's phrase 'by id' adds no semantic information beyond the schema. Baseline of 3 is appropriate because the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('remove'), a resource ('todo'), and the exact scope ('by id'). The word 'permanently' clearly distinguishes this from state-changing siblings like todo_complete or todo_release, which alter status rather than delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to choose this tool over alternatives, such as whether todo_complete or todo_release would be more appropriate for non-destructive status changes. The description implies only that this is for permanent removal, but it does not explicitly rule out or redirect to any sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing item's title/description/category/priority/dueDate/list by id. Only fields you pass are changed. Pass an empty string ("") for description/category/priority/dueDate to clear that field.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The todo id, e.g. 3 | |
| list | No | Move to this list | |
| title | No | New title | |
| dueDate | No | New due date YYYY-MM-DD, or "" to clear | |
| category | No | New category, or "" to clear | |
| priority | No | New priority, or "" to clear | |
| description | No | New description, or "" to clear |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only state readOnlyHint=false and destructiveHint=false, so they do not convey how the edit behaves. The description adds valuable non-obvious behavior: updates are partial rather than full replacements, and passing """ clears fields instead of setting invalid values. It does not cover invalid id or response behavior, but the key side effects are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry the entire definition: the first front-loads the core purpose and fields, the second captures the update and clearing semantics. There is no filler or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter partial update with full schema coverage and annotations, the description plus schema is enough for an agent to select and invoke the tool correctly. It could additionally mention return value or error behavior for non-existent ids, but those are minor gaps for a simple edit operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and every parameter, including the empty-string clear behavior, is documented in the schema itself. The description provides a useful high-level summary but does not add per-parameter meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Edit'), a resource ('an existing item'), and the exact affected fields (title/description/category/priority/dueDate/list) by id. This sharply distinguishes it from sibling tools like todo_add (creation) and todo_delete (destruction) without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use this tool: editing existing todos by id. It also adds essential partial-update guidance ('Only fields you pass are changed') and explain how to clear fields with empty strings. It does not explicitly name when not to use it relative to siblings, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the change history (create/edit/claim/release/complete) for one item, who made each change and when.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The todo id, e.g. 3 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations by specifying exactly which change events are included and indicating the returned data (who made the change and when), which is useful given there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the main purpose and supplies the key details (change types, actor, timestamp) without any filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with a single integer parameter, the description is complete: it explains what the tool shows, what events are included, and what information is returned. The lack of an output schema is compensated by the description's clarity about the return contents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter already has a clear description ('The todo id, e.g. 3'). The tool description adds no new parameter-level meaning beyond implying that the id refers to 'one item,' so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Show') and a clear resource ('change history for one item'), and it enumerates the change types (create/edit/claim/release/complete). This makes it easy to distinguish from sibling tools like todo_add or todo_edit, which perform mutations rather than display history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for one item' clearly signals that this tool is for per-item history, not for listing todos or viewing aggregate state. It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for an agent to select it appropriately among the sibling mutation and list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List items from the shared global TODO list, formatted as a checklist.
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | Restrict to the todo list, the backlog, or both (default) | all |
| agent | No | Restrict to items added by this MCP client name, e.g. "claude-code" | |
| filter | No | Which todos to return | open |
| session | No | Restrict to items added during this connection's session token (see the 'via' suffix on listed items) | |
| category | No | Restrict to items with this exact category/tag | |
| inProgress | No | If true, restrict to items currently claimed via todo_claim (see the '▶working' suffix) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context beyond that: the list is 'shared' and 'global', clarifying scope, and 'formatted as a checklist' gives the agent an idea of the return presentation despite no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that states the resource, the action, and the output format with no filler. Every element earns its place and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no required parameters and a rich schema, the description covers the shared-global nature and checklist output. Without an output schema, more detail about returned fields could help, but this is adequate for correct invocation and interpretation of the core intent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters are already documented with defaults and enum constraints. The description adds no additional parameter-level meaning, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb ('List') and resource ('items from the shared global TODO list'), and adds output formatting ('as a checklist'). It distinguishes this as the read-only listing tool among sibling mutation tools like todo_add and todo_edit, though it does not explicitly name a sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for viewing items on the shared TODO list, and the sibling names make it obvious this is the read path. However, it does not state when to prefer todo_list over todo_history or mention exclusions such as 'use todo_history for past versions'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear the in-progress claim on an item without completing it (e.g. you're pausing this work).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The todo id, e.g. 3 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states the behavioral effect: the claim is cleared and the item is not completed. This adds useful context beyond the annotations, and it does not contradict readOnlyHint=false or destructiveHint=false. It also helps the agent understand the tool is a state change but non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence delivers the core action, the crucial exclusion, and a concrete use case. There is no wasted text and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, this description is largely sufficient: it names the action, gives an example scenario, and prevents confusion with completion. It does not mention prerequisites like whether the item must already be claimed, but that is a minor gap for such a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter description coverage for 'id', so the description does not need to add parameter-level detail. The description's use of 'item' instead of 'todo' is slightly loose but not confusing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Clear' and resource 'in-progress claim on an item' make the action concrete. The qualifier 'without completing it' explicitly distinguishes it from the sibling todo_complete, so an agent can tell them apart at a glance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical 'e.g. you're pausing this work' gives a practical scenario for when to use this tool. It implies this is for temporary pauses rather than finishing work, though it does not explicitly name sibling alternatives such as todo_claim or todo_complete as routing options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report this todo-mcp process's data format version and start time. Use to sanity-check whether your MCP connection is running stale code (e.g. right after an update) — if todo_list output looks wrong (missing/undefined fields), check this first and reconnect if the process looks old.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint=true, destructiveHint=false), so the description isn't burdened with that. It adds valuable behavioral context beyond annotations: the tool exposes version and start time precisely so the agent can detect stale code, and it explains how to interpret the result. It doesn't disclose the output format, but for a simple version/start-time report this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place: the first states the core function, the second states the usage scenario. The purpose is front-loaded and there is zero filler or repetition of schema/annotation content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only diagnostic tool with no output schema, the description is fully sufficient. It states what is returned (version and start time), when to call it (stale-code suspicion), and what to do with the result (reconnect if old). An agent has everything needed to invoke and act on this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage (empty schema), so there is nothing for the description to clarify about inputs. The baseline of 4 applies, and the description appropriately spends no space on parameters it doesn't have.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource — 'Report this todo-mcp process's data format version and start time' — stating exactly what the tool outputs. It clearly differentiates from the sibling tools (todo_add, todo_claim, etc.), which all operate on todo items, whereas this is a diagnostic version-check tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names the trigger condition: 'if todo_list output looks wrong (missing/undefined fields), check this first.' It also prescribes the follow-up action ('reconnect if the process looks old'), giving the agent a complete decision procedure with no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool maps to a distinct action in the todo lifecycle: add, list, edit, claim, release, complete, delete, history, and version. Even close concepts like release and complete are clearly differentiated in their descriptions, so there is little risk of an agent selecting the wrong tool.
All tools share the consistent todo_ prefix and use snake_case with single-word command names. Most are verb-based (add, edit, claim, release, complete, list, delete), but history and version are noun-based, which is a minor deviation from the otherwise predictable pattern.
Nine tools is well within the ideal range for this domain and each tool serves a clear, non-redundant purpose. The count feels neither too thin nor bloated for a shared todo-list server.
The tool set provides full CRUD coverage (add/list/edit/delete) plus lifecycle actions for claiming, releasing, and completing items. The history and version tools add useful diagnostics, and there are no obvious missing operations that would block an agent from managing todos end-to-end.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shared task queue for humans and AI agents: leases, handoffs, approvals and signed receipts.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
The shared task board for teams and their AI agents — connect over OAuth, every action signed.
The shared task board for teams and their AI agents — connect over OAuth, every action signed.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/pasichDev/docket'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
