A shared, attributed kanban board served over MCP for you and your coding agents — you manage boards/columns/cards, agents pull and atomically lease their own work, and every write lands in an append-only change-log.
Boards — list_boards, get_board, create_board, update_board, delete_board; a board owns its columns plus a label registry. Deletion is refused while live cards remain.
Columns — list_columns, create_column, update_column, delete_column; each carries name, order, a portable category (triage/backlog/unstarted/started/done/canceled) and a wip_limit enforced on every move. Deleting a column with live cards is refused.
Cards — list_cards (archived hidden unless asked), get_card, create_card, update_card; a card holds placements, labels, assignees, start/due dates, checklists, link attachments, description and free-form ext.
Move work — move_card re-columns/re-positions within a board the card is already on, refused when WIP limits or the board's workflow scheme forbid it; force=true overrides and stamps forced: true. list_transitions reports a card's currently legal moves and list_flows lists available schemes.
Multi-board cards — add_placement / remove_placement; the last placement can't be removed.
Safe removal — archive_card (soft, recoverable), unarchive_card, and delete_card, which only purges a card that is already archived.
Agent work queue — list_work answers "what should I work on?" with workable cards and their legal transitions inline; claim_card takes an atomic lease with TTL, heartbeat_claim renews it, release_claim gives it up (a crashed worker's lease expires and the card returns to the queue).
Structured handoff — record_work_report upserts one section/item at a time on a card; answer_work_report_question answers a filed question and mirrors the answer as a normal comment.
Escalation — raise_attention flags a card for a named actor (human or agent) via the change feed; clear_attention retires it.
Comments & relations — list_comments/add_comment/delete_comment, and typed card-to-card edges via list_relations/add_relation/delete_relation (blocks, parent/child, duplicates, precedes, …).
Event bus — list_changes reads the audit trail from a since cursor, and wait_changes long-polls it, returning the moment events land (since=-1 probes the head without replaying history).
Retry safety — create_board, create_column, create_card, add_comment, add_relation and record_work_report accept an idempotency_key, so a retried call returns the original instead of duplicating.
Attribution — every write is stamped with the connection's actor; a connection with no actor can only read.
Note on the schema — it exposes workflow reads (list_transitions, list_flows) but no set_flow/set_transitions/set_route/init_board/capabilities tools, so the flow-editing and presets the README describes aren't reachable from this tool list.
Planned integration to allow multi-mount of Jira boards alongside the native kanban-pro board, enabling a unified API over Jira issues and kanban-pro cards.
Planned integration to allow multi-mount of Trello boards alongside the native kanban-pro board, enabling a unified API over Trello cards and kanban-pro cards.
Click on "Deploy 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., "@kanban-pro create a board for sprint 24 with columns todo, doing, done"
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.
A kanban board your coding agents natively understand — and a state machine they can't wander out of.
Don't want to read this? Paste this into any agent that can browse — Claude Code, Codex, ChatGPT, whatever you use:
Do I need this? https://github.com/galvani/kanban-proIt finds
llms.txt, which is written for the agent rather than for you: what works today versus what's still planned, who should use it, who should walk away, how it compares to a plain kanban / Jira+MCP / your agent's own to-do list, and what AGPL-3.0 means for whatever you're planning to build. It's told not to sell you anything and to say plainly if you don't need it.Then, in the same conversation:
Yes — install it for me and prove it works.It runs the commands itself (needs uv; no clone), verifies the package builds before touching your config, and proves the server works by creating a board and moving a card — not by trusting that a config entry means success.
You run coding agents every day — Claude Code, Codex, whatever comes next. They do real work: fix bugs, ship features, review each other's changes. But their tasks live in chat scrollback. You come back to your desk asking: what is my agent doing right now? What's blocked? What did it finish while I slept? There is no board that both you and the agents can see and update.
kanban-pro is that board — and, once you have more than one agent, rather more than a board. A kanban board is a passive signalling surface: no move is illegal, and the rules live in your team's habits. That works when the workers are people who can be told. It does not survive a cheap model on a long unattended run. So underneath the board there is a state machine (a card may move only along transitions you declared), gates (a card cannot advance until verification someone else specified has been recorded against it), and a leased work queue (a claim expires, so a crashed agent's card comes back). The board is what you watch and intervene through; those three are what actually hold.
It's a real kanban (boards, columns, cards, comments) served over MCP, the protocol your agent harness already speaks, so registering it once turns every agent session into a worker on a shared, rule-enforced pipeline: it pulls its own card, leases it so nobody else takes it, moves it only along transitions you declared legal, reports what it found, and asks you when it's stuck. Every one of those steps is stamped with which agent did it. Concretely:
Make the pipeline strict, not suggested. Each board carries a state machine over
its columns (ready → running → review → done, and nothing else), stored on the board
itself (no config file) and administered over MCP with set_flow/set_transitions. An
illegal move is refused, not logged and allowed. Agents call list_transitions instead
of guessing — and list_work inlines each card's legal moves, so a worker sees its
options without a second call. A one-off card can carry its own inline machine or the
free-roam escape, and force=true always works but stamps forced: true on the event.
Overrides are allowed and never silent — the audit trail is the safeguard, not a lock.
(The tools are still spelled flow; prose calls it a state machine. See
SPEC.md § Terminology.)
Let agents pull their own work. list_work answers "what should I work on?" —
the agent's cards, each with its legal moves inline — and an atomic claim/lease
(TTL + heartbeat + crash-reclaim) guarantees two agents never grab the same card. A
crashed worker's lease expires and its card returns to the queue on its own.
Give all your agents one shared board. One claude mcp add line per harness;
multiple harnesses share the same store safely, each under its own identity — a Claude
Code session, a Codex run, and a Hermes dispatcher all working the same pipeline.
Always know who did what. Every connection declares an actor
(agent:claude-code, human:jan); every write lands in an append-only change-log.
Ask list_changes and see exactly which agent moved which card, and when.
Sleep through agent mistakes. A misfiring agent can't one-shot destroy data: deletes are archive-first (purge only what's already archived), board/column deletes refuse while cards remain, WIP limits are enforced on every move, and retried creates with an idempotency key return the original instead of a duplicate. When an agent hits a decision it isn't entitled to make, it raises an attention flag routed through the change-feed — instead of guessing or dying silently.
Let the fleet escalate within itself. An attention flag names who should answer,
and that target is any actor — agent:architect as readily as human:jan. A coder that
finds the ticket ambiguous bounces the decision to the agent whose call it is, files the
question in its work report, and moves on; only what no agent may decide reaches you.
Read a status report, not scrollback. Each card carries a structured
work report: what it's about, the plan, findings, verification checks, the
verdict, the handoff — and the agent's open questions. Agents write one section at a
time (record_work_report, upserted by item id, never a blind blob rewrite); you
answer a question with answer_work_report_question, and the answer is mirrored back
as a normal comment. This is the handoff contract between one agent and
the next — a reviewer reads the coder's findings and checks, not its transcript.
Keep your own board next to the team's Jira. Per-board routing (routes.toml)
puts a whitelisted Jira project and your native boards behind the same server, one
shared change-log and cursor across both — a routed card's id is its Jira key, resolved
by shape, nothing to prefix or mount by hand. A move on a routed card lands in
kanban-pro's own store, never back on the ticket; a comment does too unless the route's
writes names comments, which posts it to the ticket with @Name resolved to a real
mention, and a create_card on the board files an issue where writes names issues.
Trello is not built (🔜).
One agent working one card doesn't need any of this. The moment a harness is dispatching work — a dispatcher spawning workers, a coder handing to a reviewer, a rebaser retrying a conflict, all unattended while you sleep — the board stops being a to-do list and becomes the control plane. That is what kanban-pro is shaped for.
The failure modes of an unsupervised agent fleet are specific, and each has a mechanism here rather than a convention:
The failure | What stops it |
Two workers pick up the same card | Atomic claim/lease. The second |
A worker dies holding a card | TTL + heartbeat. The lease expires and the card is reclaimable — no stuck lane, no cleanup job. |
An agent skips the review gate | The board's state machine refuses the transition. Not a lint, not a prompt instruction — a rejected call. |
An agent decides to "clean up" the board | Archive-first deletes; a live card cannot be purged; column deletes refuse while cards remain. |
A retried tool call creates a duplicate card | Idempotency key returns the original result, with no second change-log event. |
A lane silently fills up | WIP limits are enforced on every move, over any backend. |
An agent guesses at a decision that was yours | It raises an attention flag and files a question on the card, routed to you through the change-feed. |
Nobody can reconstruct what happened | Append-only change-log, every write stamped with the acting agent, forced moves flagged |
Prompt instructions are advisory: an agent that drifts, or a cheap model on a long run, will step outside them. These are enforced at the API, so drift surfaces as a refused call the agent must handle, and a deliberate override survives as evidence in the log.
The pieces compose into a real pipeline. A dispatcher creates cards in triage. Workers
list_work, claim, and move along the declared transitions — ready → running, then review.
Each writes its plan, findings, and checks into the card's work report, so the reviewer
inherits a structured handoff instead of the previous agent's transcript. A blocked
worker raises attention and waits for your answer rather than inventing one. Meanwhile
wait_changes lets a notifier, a dashboard, or the next stage in your harness block on
the feed and wake the instant something moves — a durable, cursored queue where every
"message" is a card with an owner, a history and a verdict.
The state machine this board actually runs — triage → todo → scheduled → ready → running → blocked → review → done, with waiting for mr, a won't do cancel lane, the reopen
edge, and an ad-hoc staging lane — is the agent-lifecycle preset (init_board(preset= "agent-lifecycle")); set_flow/set_transitions edit it live.
Related MCP server: Pigeon MCP Server
uv sync # install deps (incl. dev tools)
uv run kanban-pro-mcp # MCP server (stdio) over the native SQLite store
uv run kanban-pro-mcp --profile memory # ... over an ephemeral in-memory boardPass --actor kind:name (e.g. agent:claude-code, human:jan) so every write is
attributed in the change-log.
The store lives at ~/.local/share/kanban-pro/kanban.db (override: KANBAN_PRO_DB).
Two shapes. One keyed daemon is the intended one wherever more than one agent works the
board: a single kanban-pro-mcp --http --keys process, every client arriving over HTTP
with its own bearer key (actor and board scope come from the key, never from the client),
one poller for any routed Jira board, one change log. Get the registration line:
uv run kanban-pro-mcp --print-config claude --url http://127.0.0.1:8775/mcp --key-env CLAUDE_KANBAN_TOKENwhich prints, for Claude Code:
claude mcp add --transport http -s user kanban-pro http://127.0.0.1:8775/mcp \
--header 'Authorization: Bearer ${CLAUDE_KANBAN_TOKEN}'The harness expands ${CLAUDE_KANBAN_TOKEN} from its own environment when it connects, so
the token lives in your secrets manager and the process that launches the harness carries
it (keys-pro run --as claude -- claude); a missing variable fails the connection with a
named warning rather than silently reaching the board as nobody.
Stdio spawn — no daemon, no port — is the single-user shape: the harness starts its own
server and --actor is a claim the client makes about itself. It cannot carry a key and
sees no routed board.
uv run kanban-pro-mcp --print-config claude # or: codex | opencode | hermes
claude mcp add kanban-pro -s user -- \
uv run --directory /path/to/kanban-pro kanban-pro-mcp --actor agent:claude-codeSeveral harnesses may register either shape; over stdio each spawns its own process and they share the SQLite store safely.
Then install the agent skills so your sessions know how to drive the board — an orchestrator (plan work, set up a board's state machine) and a pull worker (claim/move/report):
uv run kanban-pro-mcp --install-skills # -> ~/.claude/skills (never overwrites)
uv run kanban-pro-mcp --install-skills /some/dir # or a custom skills dirAny OS (mac/Windows/Linux), no clone needed once the repo has a remote: install
uv, then uvx --from git+<repo-url> kanban-pro-mcp, or
uv tool install to put kanban-pro-mcp on PATH.
An agent session over MCP (all real today except the PRO-12 human-readable card
keys, which are 🔜 — ids are uuid hex for now):
agent> list_boards
→ [{id: "b1", name: "kanban-pro"}]
agent> create_card {title: "Add retry logic to the sync worker",
placements: [{board_id: "b1", column_id: "todo", position: 0}]}
→ Card PRO-12 created (actor agent:claude-code, logged)
agent> move_card PRO-12 → doing
→ conflict: WIP limit reached on 'doing' (3/3)
agent> list_transitions PRO-12
→ source: flow (board) — legal from todo: [doing]
agent> move_card PRO-12 → done
→ conflict: board flow does not allow todo -> done; use force=true to override
agent> move_card PRO-12 → done, force=true
→ Card moved. The event carries forced=true — never silent.
human> list_changes since=41
→ [{seq: 42, actor: "agent:claude-code", op: "card.moved", forced: true, …}]One thing is required: say who you are. kanban-pro-mcp with no arguments gives you
the native SQLite board and free movement, but a connection that declares no actor may
only read — every write is refused, because an event nobody can be held to makes the
board look audited while telling you nothing. Everything else has a working default, and
the configuration guide covers each in full.
Setting | How | Default |
Which backend |
|
|
Who is writing |
| none — required for writes (per-board opt-out: |
Where the board lives |
|
|
What a card id looks like |
|
|
Which moves are legal |
| none — free movement |
Who may connect at all |
| off — no authentication |
Which boards a connection may reach |
| all of them |
One named operation on an otherwise read-only board |
| none granted |
Other backends behind this process |
| absent — single-backend, unchanged |
Over stdio, each client spawns its own server and --actor is a claim it makes about
itself. Over HTTP that stops working: whoever reaches the port writes as that server's
actor. A keyfile replaces the claim — each key carries the actor it writes as and the
boards it may read and write, so one server serves every agent:
# ~/.config/kanban-pro/keys.toml — chmod 600, or it is refused
[keys.verde]
token = "kp_…"
actor = "agent:verde"
write = ["verde"] # read + write
read = ["shared"] # read only; `read` with no `write` = a read-only keyTwo rules: auth on means the key is required (no exempt paths — everything is 401
without one), and no permission granted means access denied (a key with no write/read
reaches no board, never all of them; write = ["*"] is the one way to be unconfined, and you
have to type it).
uv run kanban-pro-mcp --issue-key verde --actor agent:verde --board verde # generate one
uv run kanban-pro-mcp --http --keys # then serveScope is enforced on reads as well as writes — list_boards, list_work and the change
feed are all filtered — and a call the server cannot resolve to a board is refused rather
than passed through. Neither is on unless you ask for it: no --keys means no
authentication, and no --board means unconfined, exactly as before.
A key stops accidents and stray clients, not a local attacker: everything running as your uid can read the keyfile. See the configuration guide for what that does and does not buy you.
A board says what its cards are called — id_scheme, set when the board is created and
changeable with update_board. The default is short:6 (6 readable chars); uuid opts
back into the old 32-hex shape:
init_board(board_id="ops", preset="simple-kanban", id_scheme="seq:OPS") // OPS-1, OPS-2short:8 gives k7f3q9xw, prefix:KAN:6 gives KAN-k7f3q9, seq:KAN counts KAN-1,
KAN-2, KAN-3. Each board counts on its own, and switching a board's scheme leaves the
ids it already handed out alone — an id is an opaque string. Re-shaping the ids on a board
that already has cards is kanban-pro-migrate reid: it mints a fresh id per card in the
target scheme and keeps the old one resolving forever as an alias.
A card can move anywhere until you give the board a flow — the legal column→column moves, keyed by column id, stored on the board itself and set over MCP:
set_flow("b1", {
"b1:todo": ["b1:doing"],
"b1:doing": ["b1:review", "b1:todo"],
"b1:review": ["b1:done", "b1:doing"],
})
# or one lane at a time: set_transitions("b1", "b1:review", ["b1:done", "b1:doing"])
# or start a NEW board pre-wired: init_board("b1", preset="agent-lifecycle")Every edge references a real column on that board — set_flow refuses a dangling id, and
deleting a column strips the edges that named it, so the machine can't drift from the columns.
A card overrides its board's machine with ext["kanban_pro.scheme"] = "free-roam" (unrestricted)
or carries its own one-off flow inline in ext["kanban_pro.flow"]. A column named in no
edge stays free, so you can keep an ad-hoc lane without governing it. No flow at all →
the whole board is free-roam: enforcement is opt-in and never appears uninvited.
A board may also declare named routes: alternative workflows over the same columns, for
work that takes a shorter path than the default. set_route("b1", "no-customer", {...})
declares one with the same shape as set_flow; a card follows it with
ext["kanban_pro.route"] = "no-customer", list_transitions reports the name in route, and
the board page shows it on the card with a selector while the card still rests in a backlog
lane. A route governs only the lanes it names, exactly like the flow, so a lane is shut out
of a route by listing it as a key with no out-edges and never as a target. A card naming a
route the board does not declare cannot move at all until the name is fixed or the route
declared — it never falls back to the default. set_route(..., {}) drops a route.
Agents never guess — list_transitions (and every item list_work returns) carries the
card's legal moves. An illegal move is refused; force=true performs it anyway and
stamps forced: true on the event. Overrides are always allowed, never silent.
WIP limits are separate: they live on the column (update_column), not in the flow,
and kanban-pro enforces them over any backend.
New boards come pre-wired from a preset — blank, simple-kanban, docs, or
agent-lifecycle (the swarm lifecycle this board runs) — via init_board(preset=…).
raise_attention(card_id, reason, for_actor="human:jan") flags the card, shows it on the
board, and puts an attention.raised event on the change-feed carrying the reason and
the target — so a listener can deliver the question wherever you are. You answer;
clear_attention retires the flag.
A flag says how loudly it speaks: severity="block" (the default) halts the card
until someone clears it, while warn and info are visible on the board and on the feed
but let the work carry on — so a worker can flag something worth knowing without stopping
the card.
Attention is the signal, not the content: the question itself goes in the card's work
report under questions[], which you resolve with answer_work_report_question
and which is mirrored back as a normal comment.
Every write lands in the append-only change-log. A listener is anything that reads it
from a cursor it stores — no broker, no registration. Probe the head once with
wait_changes(since=-1), then loop: wait_changes blocks until events land and returns
the next cursor. Persist that cursor and a listener that was down resumes exactly where
it stopped, dropping nothing and re-delivering nothing.
A runnable one — long-polls the feed, DMs Slack on card moves and on attention raised for you — is in examples/notifier/.
Out of the box, kanban-pro is the board — cards live in its own SQLite store. But the board API is deliberately separated from where cards are stored, via adapters.
The scenario that motivates this: your team tracks work in Jira. You point kanban-pro
at a whitelisted Jira project, and your agents see and discuss real Jira tickets through
the exact same safe, attributed kanban tools — no agent ever learns the Jira API or
holds a Jira token. By default that's read-only toward Jira: a comment your agent
adds lands in kanban-pro's own store, merged into list_comments alongside Jira's real
ones, and no transition reaches the ticket. A route whose writes names comments posts
the agent's comment to the ticket instead, @Name resolved to a real mention when exactly
one person on the ticket matches — the returned comment says who was notified and who
was not — and one whose writes names issues lets create_card file a real issue,
handed back with its key as the card id. And where Jira lacks something kanban-pro offers
(WIP limits, per-board flow, checklists), kanban-pro fills the gap itself — and
tells you honestly which is which: query capabilities and each one reports
native (the backend does it), polyfilled (kanban-pro does it on top), or
unavailable. It never lies about what's real.
Your data stays where it belongs. When a backend is attached, that backend is the
system of record — kanban-pro does not quietly copy your cards into its own SQLite. The
adapter maps canonical fields onto the backend's fields, and everything the backend knows
that the canonical model doesn't rides back out through ext (Hermes's harness columns
arrive as ext["hermes"], verbatim). kanban-pro supplies storage only for what the
backend has nowhere to put — and only then. Rules that store nothing (WIP limits, flow
enforcement) are pure enforcement: no data, so no split. Data that a backend genuinely
can't hold falls to kanban-pro's overlay, keyed to the backend's own ids. Since only
that last case creates a second home for data, the goal is to shrink it: where the
backend has any usable container (a comment, a description, a custom field), the
polyfill is written through into it so the backend stays authoritative and can show
the data in its own UI. Write-through encoding is designed, not yet built (🔜) — today
polyfilled comments and relations live in the overlay. Full breakdown:
docs/configuration.md.
your agents (Claude Code, Codex, …)
│ MCP tools (51)
▼
┌──────────────────── kanban-pro core ────────────────────┐
│ actor stamping · change-log · delete guards · │
│ WIP + flow enforcement · capability polyfills │
└───────┬───────────────────┬────────────────────┬────────┘
native SQLite memory jira
(default system (ephemeral, (polled; whitelisted;
of record) for tests) comments per route)Adapters today: native (the default SQLite system of record), memory, one
harness adapter (hermes — the pattern for wiring in your own harness's built-in
kanban), and jira — a Jira project is a board, a ticket a card, the card id the
Jira key. It runs under its own credential-holding process (keys-pro run --as gitlab-pro, reading a Jira email + API token that never touch a file an agent reads)
and is read-only toward Jira unless a route says otherwise: it polls a whitelisted
set of projects into the shared change-log, and neither a transition nor a field write
reaches a real ticket — a comment lands in kanban-pro's own store, merged back into
list_comments alongside Jira's own (tagged ext.origin: "jira"), or is posted to the
ticket on a route whose writes names comments; a route whose writes names issues
creates an issue from create_card. All four pass one shared contract test suite.
Pick the backend with a profile — --profile default / --profile memory (or
KANBAN_PRO_PROFILE). A profile bundles an adapter with its settings; kanban-pro
always exposes the full canonical surface regardless of the backend's gaps.
And you're not limited to one world. Per-board routing (routes.toml — see
configuration.md) puts several backends behind one process at
the same time: your native boards plus a whitelisted Jira project, one shared
change-log and cursor across both. A card id resolves to its backend by SHAPE — a Jira
key looks like PROJ-123, a native seq:/prefix: board can mint the same shape, and
a genuine collision refuses rather than guessing — so there is no mount prefix to type
and no separate address space to learn. An absent routes.toml reproduces today's
exact single-backend behavior. Copying a card across backends with a provenance link
and confirmation-gated sync remains 🔜 — routing dispatches each board to its own
backend, it does not copy or sync one card between two.
Boards move, too: a generic migration tool (kanban-pro-migrate) copies any
profile into any other — idempotent, dry-run first, provenance-stamped, the import
itself attributed in the change-log. It has run for real: a 172-card board with 608
comments imported port-to-port.
Look at the mechanics and you'll notice kanban-pro quietly replaces the queueing infrastructure an agent fleet would otherwise need:
The change-log is an append-only event stream with consumer cursors — an agent
(or your Slack notifier) reads list_changes since=<seq> and resumes exactly where
it left off. Kafka-style offsets, no broker to run. ✅
Push without polling loops: wait_changes long-polls the same cursor and returns
the moment events land (instantly for writes through this server), so a consumer
blocks instead of spinning. ✅
Claim/lease is the competing-consumers pattern: atomic claim with a TTL, heartbeats, crash-reclaim = redelivery. Two agents never grab the same card. ✅
The attention flag is routing: "this needs a decision" targeted at a specific agent or human, carried in the event stream for notifiers to deliver. ✅
Durable subscriptions (🔜 webhook listeners with per-listener cursors + retry, and MCP notifications) round out fan-out.
The difference from a real broker: here every "message" is a card — durable, stateful, attributed, with history — and the queue is a board, which you can read, reprioritize and answer through the same tools your agents use.
If you are a human choosing a kanban board, you probably want one of the others. kanban-pro has no user accounts, no hosting and no web interface, and is version 0.1.0. It does have API keys and per-board read/write scopes — but they are sized for telling your own agents apart, not for holding a boundary against people: everything running as your uid can read the keyfile. Trello, Linear, Jira, Vikunja, Wekan and GitHub Projects each beat it on UX, mobile, multi-user and maturity, and it isn't close. The full, cited breakdown — including who should walk away — is in docs/comparison.md.
What is hard to find elsewhere is the coordination machinery an unattended agent fleet needs. Surveyed 2026-07-10 across sixteen products:
Enforced flow (refuses illegal moves) | WIP enforced on write | Resumable cursor feed | Atomic claim/lease | |
kanban-pro | ✅ | ✅ | ✅ | ✅ |
Jira | ✅ validators | ⚠️ soft | ⚠️ org audit only | ❌ |
Linear | ❌ categories | ❌ | ⚠️ GraphQL cursor | ❌ |
Trello | ❌ | ⚠️ soft | ⚠️ | ❌ |
GitHub Projects v2 | ❌ automation | ⚠️ soft | ⚠️ webhooks | ❌ |
Vikunja · Planka · Taiga · Kanboard | ❌ | ❌ | ❌ | ❌ |
Wekan | ❌ | ⚠️ blocks (server-side unverified) | ❌ | ❌ |
Agent boards (Flux, Backlog.md, | ❌ | ⚠️ one of them | ⚠️ SSE at best | ❌ |
Claim/lease appears in nothing else surveyed — every other tool's "assignment" is a last-write-wins field two agents can both grab. Neither does anything else combine a no-miss cursor feed with transition enforcement.
Be clear about what is not novel, though. MCP kanbans are a crowded category (at least ten exist). Self-hosting is table stakes. Jira has enforced workflows and has for twenty years. multidimensionalcats/kanban-mcp already ships structured work reports; Backlog.md already does archive-first deletes; Flux is a real, active, git-native agent board. Those three are the closest prior art. What has no precedent found is the bundle: claim/lease and a resumable cursor and enforced flow and capability-honest adapters, self-hosted, MCP-first.
Two further corrections to what this README used to say: classic kanbans are not
MCP-illiterate any more — Trello, Jira, Linear and GitHub all ship official MCP servers
now, and the rest have community ones. And the backend-proxy idea isn't new either
(Composio, Unified.to); the honest native/polyfilled/unavailable reporting is the
part that is.
kanban-pro | Unified task APIs (Unified.to) | MCP aggregators (Composio Rube) | Agent boards (Flux, Backlog.md) | Per-backend MCP (Atlassian, Linear, GitHub) | Classic kanbans (Planka, Vikunja) | |
Self-hosted | ✅ | ❌ SaaS | ⚠️ self-host path | ✅ | varies | ✅ |
Backend-agnostic | ✅ one model, any adapter | ✅ normalize-only | ➖ many apps, per-app tools | ❌ own store only | ❌ one backend | ❌ own store only |
MCP-native | ✅ primary interface | ❌ | ✅ | ✅ | ✅ | ⚠️ community servers |
Capability polyfill | ✅ delegate → polyfill → honest | ❌ gaps are just missing | ❌ | ➖ n/a | ❌ | ❌ |
Agent-safety semantics | ✅ archive-first, guarded deletes, WIP, claim/lease | ❌ | ❌ | ➖ partial | ❌ raw backend semantics | ❌ |
Actor audit trail | ✅ per-connection actor + change-log | ❌ | ❌ | ➖ | ➖ backend's own | ➖ |
Multi-user / permissions | ❌ single-user | ✅ | ✅ | ➖ | ✅ | ✅ |
Ports & adapters (hexagonal), consumed MCP-first / shell-first (agent harnesses are the primary clients; HTTP is secondary):
harnesses / clients
│ MCP (primary) · CLI (🔜) · HTTP (secondary) — thin, stateless
▼
core/ — Recording(Augmenting(adapter)): actor stamping + change-log,
delegate/polyfill routing, guards, dedupe
▼
KanbanBackend port ──▶ adapter ──▶ backend
▲
canonical domain model (Pydantic)Interfaces never talk to an adapter directly — everything goes through core/, so no
interface can bypass the guards or the audit trail. Directory layout:
AGENTS.md; design: SPEC.md.
llms.txt — the agent-facing brief. Hand the repo to an AI agent, ask "do I need this?", then let it install and verify.
docs/configuration.md — start here to configure it: profiles, actors, workflow rules, WIP limits, the attention flag, and listeners
docs/comparison.md — cited comparison against 16 boards, including who should walk away and what here isn't actually novel
CHANGELOG.md — what changed, for people who use it — including a frank known limitations list
SPEC.md — what and why (canonical model, the core+passthrough decision, capability model)
JOURNAL.md — decisions and rationale: what was rejected, what broke, why
TODO.md — open backlog (nothing in it is done)
AGENTS.md — conventions & hard rules for coding agents, incl. how to author a new adapter
docs/internals.md — how it fits together: the layer stack, the
invariants, the event kinds, ext versioning, and the traps. Read this before changing code.
docs/methods.md — every operation + its MCP projection
docs/hermes-kanban.md — ground truth for the first harness adapter & its migration map
Working today: the canonical model and port, four adapters behind one contract
suite (native, memory, hermes, and a Jira adapter, whitelisted per project, writing
nothing but a comment or a new issue and only where a route allows it),
per-board routing so several of them share one process and one change-log, per-operation
ACL on top of board scope, the augmenting layer (WIP enforcement, comments/relations
polyfill, honest capability reporting), the MCP server (51 tools + 9 resources), actor
identity + the append-only change-log with both the list_changes pull feed and the
wait_changes long-poll, the state machine engine (per-board transitions, inline
per-card machines, free-roam, audited force), structured work reports with
human-answerable questions, and the generic migration tool — all tested, and verified
live against a real production board.
Next (🔜): the CLI, a canonical HTTP surface, bulk operations, flow hooks/validators, a Trello adapter, cross-board copy/link with
confirmation-gated two-way sync, write-through polyfill encoding, human-readable card
keys (PRO-12), MCP push notifications, and durable webhook listeners. Roadmap:
SPEC.md; the full queue: TODO.md. Anything marked 🔜 does
not run today.
AGPL-3.0-only — free software. Copyright © 2026 Jan.
Use it, run it, fork it, change it. If you distribute a modified version — or run one as a service others can reach — you must publish your source (AGPL §13). Fixes and ideas are asked for, not compelled: see CONTRIBUTING.md.
Add a comment to a card (card_id, author = User id, body).
idempotency_key (reused on retry) prevents duplicate comments.
| Name | Required | Description | Default |
|---|---|---|---|
| comment | Yes | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| body | Yes | |
| author | Yes | |
| card_id | Yes | |
| created_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is not read-only and not destructive, which aligns with the description of adding a comment. The description adds value by noting the idempotency_key behavior, but it does not disclose permissions, side effects, or error conditions, leaving some behavioral gaps.
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 short (two sentences) and front-loaded with the primary action. It is efficient with no extraneous wording, though it could benefit from slightly more structure to separate required vs optional parameters.
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?
Given the tool's simplicity and the presence of an output schema, the description adequately covers the core action. However, it omits discussion of error scenarios, behavior on duplicate idempotency keys, or network failure handling, which limits completeness for a production tool.
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?
With 0% schema description coverage, the description must compensate. It explains the comment fields card_id, author, body, and introduces idempotency_key with its purpose. However, it does not explain other comment properties like id, ext, or created_at, leaving some parameters underdocumented.
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 clearly states the tool adds a comment to a card, specifying the required fields (card_id, author, body). While it distinguishes this action from other comment-related tools like list_comments or delete_comment, it does not explicitly differentiate from sibling tools like add_relation, but the core purpose is unambiguous.
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 briefly mentions idempotency_key for retry prevention but provides no guidance on when to use this tool versus alternatives, prerequisites, or context. There is no comparison with sibling tools, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put a card on an additional board (one placement per board; errors if already on it).
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes | ||
| placement | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden. It discloses the error condition ('errors if already on it'), which is helpful. However, it does not mention permissions, rate limits, or what the mutation does beyond adding (e.g., no mention of return value or side effects). The provided information is adequate but not comprehensive.
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, well-constructed sentence that conveys the purpose and a key constraint. It is concise with no wasted words, and the most important information (action and constraint) 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?
Given the tool complexity (2 parameters, one nested object), and the presence of an output schema, the description is somewhat incomplete. It does not mention prerequisites (e.g., card must exist, board must exist) or other potential errors beyond the 'already on it' case. It covers the core action but leaves gaps in context.
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 has 2 parameters (card_id and placement) with 0% description coverage in the schema. The tool description does not explain what these parameters are or how to use them. The nested 'Placement' object in the schema does have a description, but that is part of the schema, not the tool description. Since the description compensates poorly for low schema coverage, it gets a low score.
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 ('Put') and clearly identifies the resource and action: adding a card to an additional board. It explicitly states the constraint 'one placement per board; errors if already on it,' which distinguishes it from siblings like 'move_card' and 'remove_placement.'
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 clearly indicates when to use: when you want to add a card to a board where it is not already placed. It warns against use if already on the board ('errors if already on it'). However, it does not explicitly name alternatives like 'move_card' for moving between boards, which would strengthen guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Link two cards with a typed relation. Subtask = kind 'child' from parent card. idempotency_key (reused on retry) prevents duplicate relations.
| Name | Required | Description | Default |
|---|---|---|---|
| relation | Yes | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| kind | Yes | |
| to_card | Yes | |
| from_card | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate not read-only and not destructive. The description adds value by disclosing idempotency behavior ('idempotency_key prevents duplicate relations') which is beyond annotations.
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 are concise and front-loaded. Every sentence adds essential information: action, example use case, and idempotency feature. No fluff.
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?
Given the tool's complexity (2 params, output schema present), the description covers the main action, a key use case, and idempotency. It could be more detailed on return values but is sufficient with sibling tools present.
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 0%, so description should compensate. It explains idempotency_key purpose and gives a subtask example for relation kind, but does not detail all relation fields beyond 'link two cards'.
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 clearly states the action: 'Link two cards with a typed relation.' It uses a specific verb ('link') and resource ('cards'), and distinguishes from siblings like delete_relation and list_relations.
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 a specific example ('Subtask = kind child from parent card') but lacks explicit guidance on when to use vs alternatives. It does not mention exclusions or compare to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer one work_report question and mirror the answer as a normal comment.
| Name | Required | Description | Default |
|---|---|---|---|
| answer | Yes | ||
| card_id | Yes | ||
| question_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's a write operation but not destructive. The description adds the key behavior of mirroring the answer as a comment, which is not conveyed by annotations alone. However, other potential behaviors (e.g., permissions, side effects) are not 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?
The description is a single, well-structured sentence that efficiently conveys the core action and a notable side effect. It is front-loaded with the verb 'Answer' and maintains brevity without sacrificing essential purpose.
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?
Given the presence of an output schema and sibling tools, the description lacks sufficient context. It does not clarify what a work_report question is, how to obtain card_id or question_id, or any constraints. The output schema exists, so return values are covered, but other context is missing.
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 has 0% description coverage, meaning no parameter descriptions exist in the schema. The tool description does not compensate by explaining any parameters (card_id, question_id, answer). The agent must infer meaning solely from parameter names.
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 clearly states the tool's function: answering a work_report question and mirroring the answer as a normal comment. It distinguishes itself from sibling tools like 'record_work_report' and 'add_comment' by combining both actions.
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 provided on when to use this tool versus alternatives. It does not mention prerequisites, non-usage conditions, or related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a card (soft, recoverable — the default way to remove one).
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and not destructive. The description adds 'soft, recoverable', confirming the non-destructive nature. No contradictions.
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?
Single sentence with immediate action verb and resource. Every word adds value; no 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 tool with one parameter and an output schema, the description covers the essential behavior and reversibility. Could mention visibility after archiving, but overall sufficient.
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 schema has 0% description coverage for the required 'card_id' parameter, and the description does not explain what it is or how to obtain it. The agent must infer from the name alone.
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 clearly states 'Archive a card' and specifies it is 'soft, recoverable — the default way to remove one', distinguishing it from destructive deletion and from unarchiving.
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 indicates this is the default removal method, implying it should be used over delete_card for recoverable removal. It does not explicitly mention when not to use, but sibling tools provide context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically lease a card so no other agent picks it up (visible in list_work).
The lease expires after ttl_seconds unless renewed via heartbeat_claim — a crashed
agent's card becomes claimable again automatically. owner overrides the actor
(claim on behalf of a specific worker); defaults to the connection's own actor.
Convention: after claiming, assign yourself and move the card to a started column.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | No | ||
| card_id | Yes | ||
| ttl_seconds | No |
| Name | Required | Description |
|---|---|---|
| owner | Yes | |
| card_id | Yes | |
| expires_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses atomic leasing, lease expiry, heartbeat renewal, owner override, and crash recovery. Adds significant value beyond annotations (readOnlyHint=false, destructiveHint=false).
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?
Three concise sentences: purpose/atomicity, expiration/owner override, and usage convention. No fluff.
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?
Covers leasing timeout, renewal, owner override, and post-claim convention. Could mention failure mode if card already claimed, but output schema likely covers return values.
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?
With 0% schema description coverage, description compensates by explaining `owner` (override actor) and `ttl_seconds` (lease expiry). `card_id` is self-explanatory.
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?
Specific verb 'lease a card' and resource 'card' with clear atomicity guarantee. Distinguishes from siblings like heartbeat_claim and release_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?
Describes conventions (after claiming, assign yourself and move to started column) and expiration behavior. Lacks explicit when-not-to-use but provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear a card's attention flag (question answered / decision made). Put the
answer in a comment; resolution is a one-liner for the event stream.
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes | ||
| resolution | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds value by detailing the specific action (clearing flag) and its relationship to comments and event stream, which goes beyond the annotations.
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 concise with two sentences, front-loading the main action and keeping it efficient without unnecessary words.
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?
Given the low complexity (2 parameters, simple action) and presence of an output schema, the description is fairly complete, though it could mention prerequisites like the card having an attention flag.
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?
With 0% schema description coverage, the description partially compensates by explaining 'resolution' as a one-liner for the event stream, but does not elaborate on 'card_id' beyond what the schema 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 clearly states the verb 'Clear a card's attention flag' and explains the context 'question answered / decision made', effectively distinguishing it from sibling tools like 'raise_attention'.
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 context for when to use the tool (question answered / decision made) and hints at a workflow (add comment, use resolution), but does not explicitly contrast with alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a board. Omit id to have one generated; columns/labels may be inlined.
Send an idempotency_key (any unique string, REUSED on retry) so a retried call returns the original board instead of creating a duplicate.
| Name | Required | Description | Default |
|---|---|---|---|
| board | Yes | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| name | Yes | |
| labels | No | |
| columns | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is mutating and non-destructive. The description adds the behavioral trait of idempotency via a key, which is valuable. No other behavioral aspects (e.g., side effects, authorization) are disclosed, but the annotations carry the safety profile.
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 very concise with two sentences. The first sentence states the core action and key details (id generation, inlining), and the second explains idempotency. No wasted words; every sentence adds value.
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?
Given the existence of an output schema and the tool's complexity (creating a board with nested objects), the description covers the most critical usage aspects: id generation and idempotency. It does not need to describe return values or all field details since the schema provides that.
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 description adds meaning beyond the schema: it explains that omitting 'id' generates one and that columns/labels can be inlined. It also clarifies the idempotency_key usage. Schema documentation coverage is low (0% on properties), so the description's parameter-level explanation compensates well.
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 'Create a board' and explains id generation and inlining, clearly indicating the tool's purpose. The sibling tools include update_board, delete_board, etc., so purpose is distinct. However, it could be slightly more explicit about the board's structure (e.g., container of columns and labels), which is defined in the schema instead.
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 specific guidance on when to omit the id and how to use the idempotency_key for retries, which aids correct usage. It does not explicitly mention when not to use this tool versus siblings, but the unique action of creating a board makes this clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a card. placements must have >=1 entry (board_id, column_id, position).
Send an idempotency_key (any unique string, REUSED on retry) so retries return the
original card instead of duplicating it.
| Name | Required | Description | Default |
|---|---|---|---|
| card | Yes | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds behavioral traits: the constraint on placements and the idempotency mechanism. This provides useful context beyond annotations, though it doesn't detail the exact response behavior.
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, no wasted words. The main purpose is front-loaded. Every sentence adds value: the first states the action, the second explains critical constraints and idempotency. Excellent conciseness.
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?
Given the tool has an output schema and 2 parameters, the description is fairly complete. It covers the most important nuance (placements required) and a key feature (idempotency). However, it could briefly note that the card parameter must include title (as per schema required) to be fully self-contained.
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 has no descriptions for the top-level properties (0% coverage). The description adds important semantics: it explains the placements requirement and the purpose of idempotency_key (for retries without duplication). This significantly aids correct invocation.
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 clearly states 'Create a card' - a specific verb and resource. It distinguishes from sibling tools like archive_card, delete_card, update_card by being the creation tool. It also adds key requirements about placements and idempotency.
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 guidance: placements must have >=1 entry, and idempotency_key should be used for retries. While it doesn't explicitly exclude alternatives, the context is sufficient for an agent to know when to use this tool (to create a card).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a column to a board. category gives it portable semantics (e.g. 'done').
idempotency_key (reused on retry) prevents duplicate creation.
| Name | Required | Description | Default |
|---|---|---|---|
| column | Yes | ||
| board_id | Yes | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| name | Yes | |
| order | No | |
| category | No | |
| wip_limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-destructive mutation. The description adds that idempotency_key prevents duplicate creation, which is useful. However, it does not disclose side effects (e.g., default ordering) or error conditions, leaving gaps despite annotation coverage.
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 concise, front-loaded sentences. First sentence states core purpose, second highlights key details. No redundant words.
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?
Given 3 parameters (plus nested object), presence of output schema, and sibling tools, the description covers the main action but omits details on board_id and column properties like order. Sufficient for basic use but lacks completeness for advanced scenarios.
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 0%, so the description must compensate. It clarifies 'category' portable semantics and 'idempotency_key' purpose, but does not explain 'board_id' or nested column properties like 'order' and 'wip_limit'. Partial coverage.
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 clearly states 'Add a column to a board', specifying the verb (add), resource (column), and destination (board). This distinguishes it from siblings like create_board or create_card.
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 explicit guidance on when to use vs. alternatives. The description mentions category semantics and idempotency but does not contrast with update_column or delete_column. Usage is implied from the action name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a board permanently. Refused while live cards remain — move/archive first.
| Name | Required | Description | Default |
|---|---|---|---|
| board_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds value by specifying permanence and the refusal condition, which are behavioral traits beyond the annotation. No contradictions with annotations.
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 two sentences with no fluff. It front-loads the primary action and immediately follows with the critical constraint. 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?
Given the tool has one parameter and an output schema, the description covers the essential behavioral context. However, the lack of parameter documentation leaves a gap, making it incomplete for an agent to use correctly without additional inference.
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 schema has 0% description coverage for parameters, and the description adds no information about the board_id parameter, such as its format (e.g., UUID) or constraints. The agent must rely solely on the schema's type and name.
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 clearly states the action ('Delete a board permanently') and the resource ('board'). It distinguishes from sibling tools like delete_card and delete_column by specifying the scope 'permanently' and the unique constraint about live cards.
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 explicitly states when the tool will be refused ('while live cards remain') and what to do instead ('move/archive first'). This provides actionable guidance for the agent to avoid errors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently purge a card. Only allowed on an ARCHIVED card — archive_card first.
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive (destructiveHint=true) and mutation (readOnlyHint=false). The description adds 'permanently purge' and the prerequisite of archiving, which enhances transparency beyond annotations.
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 with an additional instruction, no wasted words, front-loaded with the core action, and efficiently structured.
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 tool with one parameter and an output schema (not shown), the description covers purpose, precondition, and permanency. It doesn't detail return values, but that may be covered by the output schema.
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 0%, but the description does not elaborate on the 'card_id' parameter beyond its title, offering no added semantic value. The parameter is required but the description doesn't explain its format or source.
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 clearly states 'Permanently purge a card' with specific verb and resource, and distinguishes from 'archive_card' by requiring it to be archived first.
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?
Explicitly states the precondition 'Only allowed on an ARCHIVED card' and instructs to use 'archive_card first', providing clear when-to-use and prerequisite guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a column permanently. Refused while live cards sit in it — move/archive first.
| Name | Required | Description | Default |
|---|---|---|---|
| column_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint: true, but the description adds unique behavioral context: the tool is refused if the column contains live cards. This goes beyond what annotations provide. No contradiction.
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, no wasted words. Front-loaded with the core action and immediately followed by a critical constraint. Highly efficient.
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?
Given the tool's simplicity (one required param, no nesting, output schema exists), the description covers the essential behavioral constraint. It doesn't explain return values, but the output schema is present. Almost 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?
Schema description coverage is 0%, so the description must compensate. However, it does not explain the column_id parameter beyond implication. While the single parameter is obvious, no additional meaning is added.
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?
Clearly states 'Delete a column permanently' with a specific verb and resource. Distinguishes from sibling tools like delete_board or archive_card by specifying the resource and adding a precondition about live cards.
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?
Explicitly states when to use (delete a column) and when not ('Refused while live cards sit in it'), with an alternative: 'move/archive first'. Provides clear guidance for agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a comment permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| comment_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior. The description adds 'permanently', implying irreversibility, which is useful but minimal beyond the annotations.
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, direct sentence with no unnecessary words. It is appropriately sized for the tool's simplicity.
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?
Despite the simple interface, the description lacks parameter details and usage context. The omission is notable for a destructive action where clear guidance is important.
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?
With 0% schema description coverage, the description must explain the parameter. It does not mention comment_id at all, leaving the agent without guidance on how to obtain or format it.
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 explicitly states the verb 'Delete' and resource 'comment' with the qualifier 'permanently', clearly distinguishing it from sibling tools like add_comment or list_comments.
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 on when to use this tool versus alternatives (e.g., updating a comment instead). No exclusion or prerequisite information provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a relation permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| relation_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior (destructiveHint=true). The description adds 'permanently', which reinforces irreversibility but does not provide additional behavioral context such as cascading effects or permission requirements. With annotations present, the description adds minimal extra value.
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 short sentence that front-loads the action. It is concise with no wasted words, though it could benefit from slightly more detail without being verbose.
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 destructive tool with an output schema, the description is minimally complete. However, it does not explain what a relation is in this context or how to find the relation_id, which could be clarified for better usability.
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 0%, and the description does not elaborate on the relation_id parameter (e.g., what it represents, how to obtain it). The parameter name is somewhat self-explanatory, but the lack of additional meaning beyond the schema leaves room for ambiguity.
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 clearly states the verb 'Delete' and the resource 'relation', and it distinguishes from sibling tools like add_relation and list_relations. It is specific enough for an agent to understand the tool's core function.
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 on when to use this tool versus alternatives (e.g., add_relation for creation, list_relations for viewing). No when-not-to-use conditions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one board (includes its columns and label registry).
| Name | Required | Description | Default |
|---|---|---|---|
| board_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| name | Yes | |
| labels | No | |
| columns | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint: true, indicating a safe read. The description adds value by stating that the response includes columns and label registry, giving richer behavioral context beyond the annotation.
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 (8 words), front-loaded with the action and resource, with no wasted words.
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?
Given a simple tool with one required parameter and an output schema, the description covers the essential scope (what is included). It does not discuss error states or permissions, but that is acceptable for a straightforward read 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?
With 0% schema description coverage, the description carries full burden but does not explain the board_id parameter beyond its name. It adds no meaning about how to find or format board_id, so it falls short for the only required parameter.
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 clearly states 'Get one board' with verb 'Get' and resource 'board', and adds that it includes columns and label registry. This distinguishes it from sibling tools like list_boards (which gets multiple boards) and get_card (which gets a card).
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 use when you need a specific board with all its details, naturally contrasting with list_boards. However, it lacks explicit when-not-to-use or mentions of alternatives, so it's clear but not fully prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one card (works for archived cards too).
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds one behavioral nuance (works for archived cards). However, there is no mention of error handling for non-existent cards. The description does not contradict annotations.
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 extremely concise at one sentence with no filler. However, it sacrifices important parameter information, so it is not optimally structured for completeness.
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?
Given the low complexity (1 parameter, output schema present), the description is mostly adequate. It covers the core functionality and the archived card behavior, but lacks details on parameter format and error conditions.
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 has 100% coverage of one parameter but no description field. The tool description adds no meaning to 'card_id', failing to explain its format or semantics, which is critical given 0% schema description coverage.
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 clearly states the verb 'get' and resource 'card', and adds the distinguishing nuance that it works for archived cards, differentiating it from sibling tools like list_cards.
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 on when to use this tool versus alternatives (e.g., list_cards for multiple cards). The description does not mention when not to use it or provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renew your live lease on a card while still working it. owner must match
the one the claim was taken with (claims held on a worker's behalf renew on
that worker's behalf); defaults to the connection's own actor.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | No | ||
| card_id | Yes | ||
| ttl_seconds | No |
| Name | Required | Description |
|---|---|---|
| owner | Yes | |
| card_id | Yes | |
| expires_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive. The description adds behavioral details: renewing a live lease, owner must match original claim owner, defaults to connection's actor. This adds meaningful context beyond annotations.
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 brief sentences with no fluff, both sentences add value. Could be slightly more structured but is appropriately concise.
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?
With an output schema present, return values may be documented. However, the description omits precondition details (e.g., what happens if card not claimed or owner mismatch). The overall completeness is adequate but could be improved with edge-case guidance.
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 0%. The description only explains the 'owner' parameter (matching and default). It does not add meaning for 'card_id' (required) or 'ttl_seconds' (default 3600), leaving two of three parameters semantically unexplained.
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 clearly states the tool renews a live lease on a card using the verb 'renew' and specifies the resource. It distinguishes from siblings like 'claim_card' and 'release_claim' by implying it is for extending an existing 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?
The description gives context for when to use it ('while still working it') and provides important behavior on owner matching and default. It does not explicitly compare to alternatives or state when not to use, but the context signals list sibling tools, making the usage scenario clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all boards.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint already indicates safe read operation. Description adds no behavioral context beyond annotations, such as pagination or return format.
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?
Extremely concise (3 words) with no wasted text. 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?
Output schema exists, so return values are documented. Still, missing context like whether results are paginated or limited, though 0 params implies unfiltered.
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?
No parameters exist; schema coverage is 100% trivially. Description is sufficient for a parameterless tool, earning baseline score of 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?
Clear verb and resource: 'List all boards.' Distinguishes from siblings like get_board (single board) and create_board.
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 explicit guidance on when to use vs. alternatives. Implied usage as a simple listing tool, but lacks comparison to get_board for details or list_cards for cards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a board's cards. Archived cards are hidden unless include_archived=true (that's how you find unarchive/purge targets).
| Name | Required | Description | Default |
|---|---|---|---|
| board_id | Yes | ||
| include_archived | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the readOnlyHint annotation, such as the default hiding of archived cards and the effect of include_archived. It also implies the tool is used in conjunction with unarchive/purge actions, providing useful context.
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 exceptionally concise, with two sentences that front-load the core purpose and immediately follow with a key behavioral detail. No unnecessary words.
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?
Given the presence of an output schema and only two parameters, the description covers the essential functionality. It might miss advanced features like pagination or sorting, but for a basic list tool it is sufficient.
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?
Despite 0% schema description coverage, the description explains the include_archived parameter's behavior and use case, adding significant meaning beyond the schema's type and default. It helps the agent understand when and how to use this parameter.
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 clearly states it lists a board's cards, which is a specific verb and resource. It distinguishes from sibling tools like get_card (single card) or list_boards (boards) by focusing on listing multiple cards within a board.
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 context on when to use include_archived=true (to find unarchive/purge targets), which helps differentiate from tools that modify cards. However, it does not explicitly specify when not to use this tool or compare to other listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change feed: every recorded write after cursor since (audit trail + sync).
Each event carries seq (the cursor — pass the last seq back as since), ts,
actor (who did it), entity/op (e.g. card.moved), and a slim data payload.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses the event payload structure (seq, ts, actor, entity/op, data) and the cursor-based pagination behavior. No contradictions.
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 concise sentences plus a bullet list, front-loaded with the core purpose. Every sentence adds value, no fluff.
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?
Given the presence of an output schema, the description explains the key event fields and usage pattern. It lacks details on rate limits or error cases, but is sufficient for a straightforward list tool.
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?
Adds meaning to the 'since' parameter (cursor, pass last seq back) but does not mention the 'limit' parameter. With 0% schema coverage, the description partially compensates but misses an opportunity for the limit field.
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 clearly states the tool lists a change feed of recorded writes after a cursor, using specific verb 'list' and resource 'changes'. It differentiates from siblings like 'wait_changes' by implying it's a scanning/listing operation.
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 explicit guidance on how to use the 'since' cursor by passing the last seq back. Does not explicitly state when not to use it or compare to siblings, but the context is clear for a change feed tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a board's columns (name, order, semantic category, wip_limit).
| Name | Required | Description | Default |
|---|---|---|---|
| board_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description is consistent. It adds the specific return fields but does not disclose other behavioral aspects like auth needs or rate limits. With annotations covering the read-only nature, this is acceptable.
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 sentence, concise and front-loaded with the verb and object. Every word adds value, with no 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?
Given the presence of an output schema (not shown but indicated), the description is nearly complete. It lists the returned fields but could mention that it returns all columns for the board without filters or pagination, which is implied.
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 0%, meaning board_id is not described in the schema. The tool description does not explain the parameter 'board_id' at all, failing to compensate for the low coverage. Users may not know what value to provide.
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 ('List') and resource ('board's columns'), and lists the returned fields (name, order, semantic category, wip_limit), clearly distinguishing it from sibling tools like list_boards or list_cards.
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 when to use (to list columns of a board), but provides no explicit guidance on when not to use, prerequisites, or alternatives. It is adequate for a simple tool but lacks context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a card's comments.
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint: true, but description adds no further behavioral details (e.g., ordering, pagination, or limits). The description relies solely on the annotation.
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 with no extraneous words. Perfectly concise for a simple list operation.
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?
Given the one-parameter input and existence of an output schema, the description is mostly adequate. However, missing behavioral details (like ordering) slightly reduces completeness for a tool with many siblings.
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 0% for the single parameter card_id. The description does not elaborate on its meaning or format beyond the name, failing to compensate for the schema's lack of documentation.
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?
Description 'List a card's comments' clearly states verb (list) and resource (comments scoped to a card), distinguishing it from siblings like add_comment or delete_comment.
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 explicit guidance on when to use this tool versus alternatives like list_cards or other list tools. Usage is implied by the context of card-specific comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Available workflow schemes: every flow.yaml scheme (+ built-in 'free-roam'), with states, allowed transitions, and which scheme is the default.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. The description adds behavioral context by specifying what is returned (schemes, states, transitions, default), which goes beyond the annotations. No contradictions.
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, well-structured sentence with no redundant words. It is front-loaded with the core purpose and efficiently conveys all necessary information.
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?
Given the simplicity of the tool (no parameters, output schema present, read-only annotation), the description is complete. It covers what the tool lists and does not require additional explanation of return values.
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 no parameters, and schema coverage is 100%. Per guidelines, baseline for 0 parameters is 4. Description adds no further parameter info, which is acceptable.
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 specific verb 'list' and defines the resource 'workflow schemes' with details: every flow.yaml scheme plus built-in 'free-roam', with states, allowed transitions, and default scheme. This clearly distinguishes it from sibling tools like list_transitions, which likely list transitions for a specific scheme.
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 tool is used to view all available workflow schemes, but it does not explicitly state when to use it versus alternatives like list_transitions. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a card's typed relations (blocks, parent/child, duplicates, ...).
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already indicates the tool is safe and read-only. The description adds value by listing example relation types, giving the agent a sense of what 'typed relations' includes.
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 sentence that conveys all necessary information without any fluff. It is perfectly concise and 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?
Given the tool's simplicity, a single required parameter, and the presence of an output schema, the description is complete. It covers the tool's purpose and the nature of the results.
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 card_id is self-explanatory from its name, and the description implies it by referring to 'a card's typed relations'. However, with 0% schema description coverage, the description could have explicitly stated that card_id identifies the card, but it adds minimal extra meaning.
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 clearly states the verb 'List' and the resource 'a card's typed relations', providing examples like blocks, parent/child, duplicates. This distinguishes it from sibling tools like list_boards or list_cards.
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?
While no explicit when-to-use or alternatives are given, the purpose is straightforward and the context of listing relations on a card is clear. The tool's simplicity makes explicit guidance less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What moves are legal for this card right now, and under which resolved scheme.
Sources: the card's flow scheme (flow.yaml; 'free-roam' = unrestricted), the backend's own workflow (e.g. hermes), or free movement when nothing is configured.
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes | ||
| board_id | No |
| Name | Required | Description |
|---|---|---|
| note | No | |
| scheme | Yes | |
| source | Yes | |
| card_id | Yes | |
| options | Yes | |
| board_id | Yes | |
| resolved_scheme | Yes | |
| current_column_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, confirming it's a safe read operation. The description adds value by revealing the sources of legal moves (flow scheme, backend workflow, free movement), providing behavioral context beyond the annotation. No contradictions.
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 two sentences long, front-loaded with the core purpose, and includes a supplementary line about sources. Every sentence adds value with no 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?
An output schema exists, so return values are handled elsewhere. However, the description omits prerequisites (e.g., card must exist, board must exist) and does not clarify the role of board_id. It is sufficient for basic understanding but lacks completeness for a tool with 2 parameters and 0% schema coverage.
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 0% (no descriptions in input schema). Two parameters exist: required card_id and optional board_id. The description mentions card implicitly ('for this card') but does not define either parameter or explain board_id's purpose. It partially compensates by describing the overall purpose, but parameter semantics are not clarified.
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 clearly states: 'What moves are legal for this card right now, and under which resolved scheme.' It specifies the verb (list), resource (card), and the specific outcome (legal moves with scheme). This distinguishes it from siblings like move_card (which performs a move) and list_flows (which lists all flows).
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 context about sources (flow scheme, backend workflow, free movement) but does not explicitly state when to use this tool versus alternatives like list_flows or move_card. It implies usage for checking legal transitions before moving, but lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What should I work on? Workable cards for assignee (default: YOU, this
connection's actor) — assigned to you or unassigned, in backlog/ready/started
columns, cards leased to others excluded. Each item carries its legal transitions,
so one call gives you the whole plan.
| Name | Required | Description | Default |
|---|---|---|---|
| assignee | No | ||
| include_unassigned | No |
| Name | Required | Description |
|---|---|---|
| actor | Yes | |
| items | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the readOnlyHint annotation, such as including cards in backlog/ready/started columns, excluding leased cards, and noting that each item carries legal transitions. No contradictions with annotations.
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 concise, front-loaded with the purpose, and every sentence adds value without 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?
Given the tool has an output schema (not shown) and two optional parameters, the description explains filtering logic well but does not mention pagination or limits, which would be helpful. Still, it is largely complete for its intended use.
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?
Despite 0% schema description coverage, the description adds meaning by explaining the assignee parameter defaults to the current actor and mentioning 'unassigned' which corresponds to include_unassigned. It adds context the schema lacks.
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 clearly states it lists workable cards for an assignee, with specific filtering criteria (assigned/unassigned, certain columns, excludes leased cards), which distinguishes it from sibling tools like list_cards.
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 provides context on when to use (to get a work plan) and defaults to the current user, but does not explicitly exclude alternatives or give when-not-to-use guidance. Still, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a card within a board it's already on (re-column / re-position).
Errors if the card has no placement on to_board_id (use add_placement), or if the card's workflow scheme forbids the transition — check list_transitions first. force=true deliberately overrides scheme + WIP validation; the override is always recorded in the change-log, never silent.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| card_id | Yes | ||
| position | No | ||
| to_board_id | Yes | ||
| to_column_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses error conditions and that force=true override is always logged, adding context beyond annotations (idempotentHint=true, destructiveHint=false). No contradiction.
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?
Four sentences, front-loaded with main purpose, no fluff. Every sentence adds value.
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?
Covers main usage, error conditions, force behavior, and assumes output schema handles return values. Adequate for a move operation with 5 straightforward parameters.
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?
Despite 0% schema description coverage, the description implies meanings of key parameters like card_id, to_board_id, to_column_id, and position. However, it does not provide explicit parameter semantics for all 5 parameters.
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?
Clearly states the tool moves a card within a board (re-column/re-position), differentiating from add_placement which adds a card to a board.
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?
Explicitly warns about errors when card lacks placement (advises add_placement) or workflow forbids transition (advises list_transitions), and explains force=true override behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Flag a card as needing a decision or input (e.g. a question only a human or a specific agent can answer). Routable: the change-log event carries the reason and the target actor, so notifier agents DM the right party. Put the actual question in a comment; this flag is the signal, not the discussion.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| card_id | Yes | ||
| for_actor | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate not read-only and not destructive. The description expands on this by explaining the side effect: a change-log event carrying the reason and target actor, enabling routing and DM notifications. It also clarifies the flag is not the discussion itself.
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 exceptionally concise at three sentences. The first sentence immediately states the main purpose. No superfluous words. Every sentence adds value.
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?
Given the presence of an output schema and sibling tools, the description covers the essential aspects: purpose, key parameters, and behavioral impact. It does not mention prerequisites or error scenarios, but it is adequate for an agent to understand how to use the 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?
With 0% schema description coverage, the description adds meaning for 'reason' and 'for_actor' by stating they are carried in the change-log event. 'Card_id' is implied. It could be more explicit about 'for_actor' being optional and its default behavior, but it provides context beyond the schema.
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 clearly states the tool flags a card as needing a decision or input. It provides an example and distinguishes from sibling 'clear_attention' by explaining the flag is a signal, not a discussion. The verb 'Flag' and resource 'card' are specific.
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 gives clear context on when to use: when a decision or input is needed, especially for humans or specific agents. It advises to put the actual question in a comment, implying this tool is for signaling, not discussion. However, it does not explicitly state when not to use or compare with alternatives like 'add_comment'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one structured work_report section/item on a card.
Current state lives in card.ext["work_report"]; every successful call also emits a work_report.updated changelog event. Use this instead of rewriting the whole ext blob. List sections require item.id and are upserted by that id; singleton sections are replaced.
| Name | Required | Description | Default |
|---|---|---|---|
| op | No | upsert | |
| item | Yes | ||
| card_id | Yes | ||
| section | Yes | ||
| idempotency_key | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds detail beyond annotations: mentions that state lives in card.ext['work_report'] and each successful call emits a changelog event. Specifies upsert behavior for list sections and replacement for singleton sections, with no contradictions.
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?
Extremely concise: 4 short sentences that are front-loaded with the primary action, every sentence adds value without 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?
Given the presence of an output schema, the description covers the tool's functionality adequately: updating a section, state location, event emission, and section type behavior. Minor missing details about optional parameters, but overall 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?
Despite 0% schema description coverage, the description explains the purpose of key parameters like section, item (with id required for lists), and op (default upsert), adding meaningful context.
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?
Clearly states it updates a structured work_report section/item on a card, distinguishes from rewriting the full ext blob, and differs from sibling tools like 'answer_work_report_question'.
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?
Explicitly recommends using this tool instead of rewriting the whole ext blob, and clarifies behavior for list vs singleton sections. Lacks explicit alternatives but provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release your lease (done or giving up). owner overrides the actor
(release on behalf of the claimed worker); defaults to the connection's own actor.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | No | ||
| card_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds that the owner can override the actor and defaults to the connection's own actor. This provides useful behavioral context for the 'owner' parameter.
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 consists of two concise sentences that front-load the purpose and then detail a key parameter. No unnecessary words.
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?
The description is adequate for a mutation tool with an output schema (not shown), but lacks context on prerequisites (e.g., must have a claim), error scenarios, or post-conditions. It is not fully 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?
With schema description coverage at 0%, the description should explain both parameters. It only explains 'owner' (override behavior) but fails to describe 'card_id', which is required. This leaves a significant gap.
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 clearly states the tool releases a lease/claim and mentions the owner override, but does not explicitly differentiate from sibling tools like 'claim_card' or 'heartbeat_claim'. It is specific enough for understanding the core action.
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 use when finishing or giving up a lease, but lacks explicit guidance on when to use versus alternatives or prerequisites. No when-not-to-use context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a card off one board (its other placements stay). The last placement can't be removed — archive_card instead.
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes | ||
| board_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds that other placements remain unaffected and highlights the last-placement constraint, providing behavioral context beyond annotations. Could mention error cases or permissions, but it's sufficient.
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 concise sentences with no wasted words. All information is front-loaded and earns its place. Efficient and clear.
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?
Given the simple operation (2 params), presence of output schema, and annotations, the description covers the essential behavior, the edge case (last placement), and the relationship to archive_card. It is complete for this tool's complexity.
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 schema has 0% description coverage for its two parameters (card_id, board_id). The description implies these are required ('take a card off one board') but does not add explicit meaning or format details. It compensates somewhat by linking to the action, but a score of 3 is appropriate as the parameters are minimally contextualized.
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 ('Take a card off one board') and resource ('placement'), clearly distinguishing it from sibling tools like archive_card by explaining that other placements stay and the last placement must use archive_card instead.
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?
Explicitly states when not to use this tool: 'The last placement can't be removed — archive_card instead.' This provides clear guidance and an alternative, satisfying the dimension fully.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore an archived card.
| Name | Required | Description | Default |
|---|---|---|---|
| card_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds context that it changes card state from archived to active. Annotations indicate idempotent and non-destructive, which description aligns with, but no additional behavioral details.
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?
One short sentence, no fluff. Could be more informative but efficient.
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?
Simple tool with output schema, but missing parameter description and usage guidance, making it only minimally 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?
Single parameter card_id has no description in schema (0% coverage) and description does not explain its purpose or format, leaving agent without meaning.
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?
Description clearly states the action ('Restore') and resource ('an archived card'). It distinguishes from sibling tool 'archive_card' which does the opposite.
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?
Implied usage when wanting to unarchive a card, but no explicit guidance on when to use vs alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update a board — only the fields set in patch are applied.
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | ||
| board_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| name | Yes | |
| labels | No | |
| columns | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false. Description adds that only fields in patch are applied, implying other fields remain unchanged. No mention of permissions, rate limits, or preconditions.
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?
Single sentence, front-loaded with key information, no wasted words.
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?
Output schema exists and annotations cover safety, but description lacks parameter explanations and usage guidance. Adequate for a simple tool but with gaps.
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 0% and description adds no parameter details beyond mentioning 'patch'. Does not explain board_id or the patch fields (name, description, ext).
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?
Description clearly states verb 'update', resource 'board', and specifies partial update semantics. Distinguishes from sibling operations like create_board or delete_board.
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 explicit guidance on when to use this tool versus alternatives, no exclusions or context provided. Agent must infer usage from the partial update nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update a card — only the fields set in patch are applied.
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | ||
| card_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| title | Yes | |
| labels | No | |
| archived | No | |
| due_date | No | |
| assignees | No | |
| checklists | No | |
| created_at | No | |
| placements | No | |
| start_date | No | |
| updated_at | No | |
| attachments | No | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds the key behavioral detail that the update is partial (only patch fields applied), which is beyond annotations and adds value.
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?
Single sentence with no extraneous information, front-loads the key action and constraint.
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?
Given the presence of an output schema, return values are covered. The description covers the essential update behavior, but lacks guidance on constraints field values or error scenarios.
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?
With 0% schema description coverage, the description must compensate. It explains the `patch` parameter's purpose ('only fields set in patch are applied') but does not describe `card_id` or enumerate the subfields of patch. Partial compensation.
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 clearly states the verb 'update' and the resource 'card', and specifies the partial update semantics ('only the fields set in patch are applied'). It distinguishes from related tools like create_card, delete_card, and archive_card.
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 when to use (when you want to update specific fields) but does not explicitly contrast with siblings like update_board or move_card, nor does it state prerequisites (e.g., card must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update a column (rename, reorder via order, set wip_limit...).
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | ||
| column_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ext | No | |
| name | Yes | |
| order | No | |
| category | No | |
| wip_limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false, so the description's 'partially update' adds minimal extra context. No contradictions.
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?
Single sentence with examples, front-loaded with purpose. Efficient, though could be more structured.
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?
Low complexity, output schema exists, but description could explain behavior on omitted fields or reference category meanings. Adequate but not thorough.
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?
With 0% schema coverage, the description adds meaning for name, order, and wip_limit via examples, but ignores category and ext. Partial but not comprehensive.
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 explicitly states the verb 'update' and resource 'column', and lists specific updatable attributes (rename, order, wip_limit), clearly distinguishing it from create/delete column siblings.
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 on when to use this tool versus alternatives (e.g., update_card vs update_column), nor any conditions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Long-poll change feed: returns AS SOON AS events exist after cursor since
(instant for writes through this server; other processes within ~2s), or empty
after timeout_seconds. since=-1 probes the current cursor without replaying
history — call that once, then loop with the returned cursor. Push semantics
without polling loops.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | No | ||
| timeout_seconds | No |
| Name | Required | Description |
|---|---|---|
| cursor | Yes | |
| events | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses crucial behavioral details: the long-poll nature, instant vs delayed event delivery, and the timeout behavior. It adds transparency about the polling mechanism and latency characteristics, fully informing the agent.
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 concise with two sentences that front-load the key concept 'Long-poll change feed.' Every phrase adds value, and there is no redundancy or fluff.
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?
Given the presence of an output schema (not shown but indicated), the description covers all necessary aspects: purpose, usage pattern, cursor handling, and latency behavior. It is complete for an agent to invoke the tool correctly without additional context.
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 description adds meaning for 'since' (used for probing cursor) and 'timeout_seconds' (implicitly mentioned as timeout_seconds). However, 'limit' is not explained despite having a default. With 0% schema coverage, the description partially compensates but leaves a small gap.
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 clearly states 'Long-poll change feed' and explains it returns events as soon as they exist after a cursor, distinguishing it from sibling tools like list_changes which likely provides a batch listing. It specifies the behavior for writes through this server (instant) vs others (~2s), making the purpose precise.
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 explicit usage guidance: 'since=-1 probes the current cursor without replaying history — call that once, then loop with the returned cursor.' It also contrasts with polling loops, making it clear when to use this tool for push semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.0.1add_commentadd_placementadd_relationanswer_work_report_questionarchive_cardclaim_cardclear_attentioncreate_boardcreate_cardcreate_columndelete_boarddelete_carddelete_columndelete_commentdelete_relationget_boardget_cardheartbeat_claimlist_boardslist_cardslist_changeslist_columnslist_commentslist_flowslist_relationslist_transitionslist_workmove_cardraise_attentionrecord_work_reportrelease_claimremove_placementunarchive_cardupdate_boardupdate_cardupdate_columnwait_changesScored across 37 tools
Each tool has a clearly distinct purpose, with detailed descriptions that prevent ambiguity. The verbs and nouns are specific (e.g., 'claim_card' vs 'heartbeat_claim' and 'release_claim'), and overlapping operations are differentiated by context (e.g., 'list_work' vs 'list_cards').
All tool names follow a consistent verb_noun pattern in snake_case, with clear actions like 'create', 'delete', 'list', 'update', and specific nouns. No mixing of conventions or vague verbs.
With 37 tools, the server is comprehensive but slightly heavy. Each tool serves a distinct function in the Kanban lifecycle, covering boards, columns, cards, comments, relations, placements, claims, workflow, and auditing. The count is justifiable but at the upper bound of typical scope.
The tool surface covers most CRUD operations and advanced features (claims, workflow transitions, change feed, work reports). Minor gaps exist: lack of explicit label management (only present in get_board) and inability to create or modify workflow schemes, but core Kanban operations are fully supported.
Kanban board for teams and coding agents: manage tasks, subtasks, sprints and wiki pages via MCP.
Kanban board for AI coding agents: they claim cards, report progress, ask you when blocked, ship.
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
