Tool reference
Your agent works with Docket through 14 tools. Each is listed here with the description and the arguments your agent is given for it, word for word: this page is generated from the adapter’s own definitions every time the site is built, and nothing on it below this point is written by hand.
It describes @usedocket/mcp 0.1.0.
claim_next
Section titled “claim_next”Claim the next card
Claim a card to work on and receive everything needed to start: goal, constraints, files in scope, the acceptance command, handoff notes from the work it depends on, and what it unblocks.
Call this before starting any work. With no arguments it takes the next ready card in priority order. Pass card to claim a specific one — that still respects dependencies, so a card whose prerequisites are unfinished is refused with an explanation.
Keep the claim token from the response: finish_card, release_card and add_note all require it.
Arguments
card(string, optional): Claim this specific card, e.g. "DKT-14". Omit to take the next ready one.version(string, optional): Only consider this version label, e.g. "1.0".workdir(string, optional): Absolute path you are working in. Required if you are in a git worktree — Docket reads git from where it was started, which is not where you are.
get_card
Section titled “get_card”Read a card
Read a card's full brief without claiming it. Same content claim_next returns — use this to check what a card involves before deciding, or to re-read the brief for work already in progress.
Arguments
card(string, required): Card reference, e.g. "DKT-14".
list_cards
Section titled “list_cards”List cards
One line per card: reference, status, title, and either who holds it or what it is waiting on. Use it to see the shape of the board. To find what to work on next, call claim_next instead — it applies priority and dependency order for you.
Arguments
status(one oftodo,doing,done,abandoned,orphaned, optional): Filter by status.orphanedlists cards whose dependency was deleted or abandoned and which need repair.version(string, optional): Filter by version label.feature(string, optional): Only cards on this feature, by slug.
create_card
Section titled “create_card”Create a card
Record work that needs doing. Use it when you discover something out of scope for the card you are on — write it down rather than widening the current task.
A good card states the goal in a sentence and names its constraints. depends_on is what makes ordering work: list the cards that must finish first and this one stays off the board until they do. acceptance_command is how anyone knows it is done — a command that exits zero.
Arguments
title(string, required): Short imperative summary.goal(string, optional): What done looks like, in a sentence or two.constraints(string, optional): Decisions the implementer must respect: approaches to avoid, patterns to follow.depends_on(list of strings, optional): Card references that must be done first, e.g. ["DKT-3"].scope_globs(list of strings, optional): File globs this work should touch.scope_symbols(list of strings, optional): Function or type names involved.acceptance_command(string, optional): Command that exits zero when the card is done.version(string, optional): Version label, e.g. "1.0".feature(string, optional): Feature slug, e.g. "billing".
update_card
Section titled “update_card”Update a card
Change a card's fields. Status is not a field here — claim_next, finish_card and release_card move cards between states, because each transition needs different information. Pass null to clear an optional field.
Arguments
card(string, required): Card reference, e.g. "DKT-14".title(string, optional)goal(string or null, optional)constraints(string or null, optional)acceptance_command(string or null, optional)scope_globs(list of strings, optional)scope_symbols(list of strings, optional)version(string or null, optional)feature(string or null, optional): Feature slug; null takes the card off its feature.
create_feature
Section titled “create_feature”Create a feature
Group cards that ship together, more finely than a version label. Create it once, then put cards on it with feature on create_card or update_card.
The slug is derived from the name when omitted. It may later name a branch, so keep it short.
Arguments
name(string, required): What the feature is called, e.g. "Billing".slug(string, optional): Lowercase letters, digits and hyphens, e.g. "billing".description(string, optional)
list_features
Section titled “list_features”List features
One line per feature: slug, name and how many of its cards are done. Use it to find a slug or to see how close a feature is to shipping; list_cards with feature shows the cards themselves.
Arguments
None.
link_cards
Section titled “link_cards”Add a dependency
Make a card depend on other cards that already exist.
Use it when an ordering constraint turns up after the plan was written: the card you are holding needs work that has not happened yet, or two cards would edit the same files and one has to go first. Write the edge down rather than leaving the order as prose in the constraints, where nothing enforces it.
Adding an edge takes the card off the board until its new dependencies are done. A cycle is refused. Safe to re-run — an edge that is already there is left alone.
Arguments
card(string, required): The card that should wait, e.g. "DKT-14".depends_on(list of strings, required): Cards it should wait for, e.g. ["DKT-3"].
unlink_cards
Section titled “unlink_cards”Remove a dependency
Remove dependencies from a card.
This is how an orphaned card is repaired. A card whose dependency was deleted or abandoned cannot be claimed until that dead edge is gone; list_cards(status: "orphaned") lists them and claim_next names the edge. Removing the last dead one puts the card back on the board.
Also how to undo an ordering decision that turned out to be wrong. Safe to re-run.
Arguments
card(string, required): The card to free up, e.g. "DKT-14".depends_on(list of strings, required): Dependencies to drop, e.g. ["DKT-3"]. Deleted cards can be named here.
finish_card
Section titled “finish_card”Finish a card
Report a card complete. Run its acceptance command first and report the real result — a failure recorded honestly is more useful than a pass that was never run.
notes is the handoff: the next agent picking up a dependent card sees it and nothing else of your session. Write what they would otherwise have to rediscover — decisions you made, approaches that failed, anything surprising. Skipping it leaves them a file list.
Add a Card-Id: <ref> trailer to your commits and the work links itself; commit before finishing so the link points at something.
If the project requires a branch, push, or pull request, this call checks for them and tells you what is missing rather than recording the card done. The brief lists those requirements under "Before you finish".
Arguments
card(string, required): Card reference, e.g. "DKT-14".claim_id(integer, required): The claim token returned by claim_next. Required — a stale or missing token is rejected.workdir(string, optional): Absolute path you are working in. Required if you are in a git worktree — Docket reads git from where it was started, which is not where you are.notes(string, optional): Handoff for whoever picks up the dependent cards.files_changed(list of strings, optional): Paths you changed.acceptance(string, optional): Result of the acceptance command — what actually happened when you ran it.
claim_files
Section titled “claim_files”Take more files
Take files for the card you are holding, so no other agent can edit them while you work.
CALL THIS BEFORE YOU EDIT a file the brief did not list — not afterwards. If another card in flight is holding it you are told which one and how long its lease has left, and at that point backing out is free: you can wait, or make this card depend on that one with link_cards. Once you have edited it there is nothing left to decide.
Literal file paths, not globs. Taking a file also adds it to the card's declared scope, so the board ends up recording what the work really touched. Safe to re-run, and it extends your lease.
Arguments
card(string, required): Card reference, e.g. "DKT-14".claim_id(integer, required): The claim token returned by claim_next. Required — a stale or missing token is rejected.paths(list of strings, required): Files you are about to edit, e.g. ["apps/web/lib/db.ts"].workdir(string, optional): Absolute path you are working in. Required if you are in a git worktree — Docket reads git from where it was started, which is not where you are.
add_note
Section titled “add_note”Leave a note
Record progress mid-task: a decision, a blocker, something you learned. Also extends your lease, so a long task does not get reclaimed while you are still on it.
Arguments
card(string, required): Card reference, e.g. "DKT-14".claim_id(integer, required): The claim token returned by claim_next. Required — a stale or missing token is rejected.note(string, required)workdir(string, optional): Absolute path you are working in. Required if you are in a git worktree — Docket reads git from where it was started, which is not where you are.
release_card
Section titled “release_card”Release a card
Give a card back without finishing it. Use this when you are blocked or the task turned out to be wrong — it returns to the board for someone else. Say why in reason; it is recorded on the card.
Arguments
card(string, required): Card reference, e.g. "DKT-14".claim_id(integer, required): The claim token returned by claim_next. Required — a stale or missing token is rejected.reason(string, optional): Why you are handing it back.
delete_card
Section titled “delete_card”Delete a card
Remove a card that should not exist — a duplicate, or work that is no longer wanted. Prefer release_card if you merely cannot do it, and abandon rather than delete if the work was considered and rejected; the record is worth keeping.
Default mode block refuses when other cards depend on this one. orphan deletes anyway and marks those dependents as needing repair. Cascade deletion is not available here — it is a human decision made in the web app.
Arguments
card(string, required): Card reference, e.g. "DKT-14".mode(one ofblock,orphan, optional): block (default) refuses if anything depends on this card; orphan deletes and flags them.