This server provides a workflow-driven task management interface for Vikunja, guiding an AI agent through a fixed pipeline (Backlog → Queue → Design → Build → Review → Done).
next_task() — Retrieve your active task in Design/Build, or the top-priority free task from the Queue. Never surfaces Backlog or blocked tasks; only one task at a time.
claim(task_id) — Claim a task from the Queue, assigning it to yourself and moving it to Design. Includes race-condition protection.
get_task(task_id) — Fetch full details of a task: description, current stage, assignees, labels, and complete comment thread.
comment(task_id, text) — Add a progress note or decision log to a task's comment thread.
advance(task_id, to, spec, worklog, evidence) — Move your task forward: Design → Build (requires a spec), or Build → Review (requires worklog + evidence). Advancing directly to Done is blocked — only humans can sign off.
call_human(task_id, question) — Escalate to a human for a decision or input. Posts your question as a comment and moves the task to "Call to Human" while preserving your assignment.
return_task(task_id, reason) — Return a task due to an external blocker (missing access, broken dependency, etc.). Unassigns you, adds a blocked label, and moves it back to Backlog for human re-triage.
decompose(task_id, subtasks) — Break a large task into 2+ subtasks (each with a title, optional description, and priority). Subtasks are created in Queue with a parent relation; the parent is labeled epic and moved to Backlog.
Provides optional Slack notifications via a webhook when tasks are moved to 'Your Call' status, alerting humans about pending questions.
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., "@vikunja-mcp Get me the next task I should work on."
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.
Most task-tracker integrations are CRUD wrappers: they hand an agent create_task,
update_task, delete_task and hope the prompt keeps it honest. This one does the opposite.
It exposes twelve narrow tools, and each one refuses the moves that would break the process:
Backlog → Queue → Design → Build → Review → [human] → Done
↕ ↕
Your Call (+ independent review of every task in Review)Backlog and Done are human territory. Triage in at one end, sign off at the other.
There is no argument to advance that reaches Done — an agent that tries is told
only a human moves a task to Done after review.
Queue → Design → Build → Review is the agent loop. Claim a task, write a spec to leave
Design, produce a worklog and an evidence sha to leave Build.
Your Call is the side branch for when an agent needs a decision it should not make
alone. It keeps its assignment and its context; the human answers on the card.
Gates are guardrails for agents, not a security boundary — the real boundary is the scoped API token Vikunja mints. See SECURITY.md.
Related MCP server: Accordo
An autonomous agent left running against a plain task API drifts in ways that are individually reasonable and collectively useless: it marks its own work done, it starts the next thing before finishing this one, it "fixes" a bug by deleting the test, and the only record of any of it is a chat log that scrolled away three hours ago.
None of that is fixed by a longer prompt. The prompt is advice; the tool call is the decision point. So the process is enforced where the decision happens:
Instead of hoping the agent… | …the tool refuses |
doesn't grade its own homework |
|
writes down a plan before coding |
|
says what it did and where |
|
works on one thing at a time |
|
escalates instead of guessing |
|
leaves a trail a human can audit | every transition writes a marked comment on the card |
What you get back is a board where each card carries its own history — the claim, the plan, the work, the independent verdict — in the order it happened.
A card that has been all the way through the loop. Nothing here was typed by a human: the markers, the labels and the stage are what the tools wrote as the agents moved it.
Read top to bottom, that is claim → advance(to="build", spec=…) → advance(to="review", worklog=…, evidence=…) → a different agent's review_task(verdict="approve", report=…).
The reviewed label is what the verdict left behind; the card now sits in Review waiting for
a human to sign it off. Every task gets that review, not just bug fixes — only an epic
container is exempt, because its code lives in its children.
And when the agent hits a decision that isn't its to make, it parks the card instead of guessing:
The card keeps its assignee, so it comes back to the same agent when you answer. Set
VIKUNJA_NOTIFY_WEBHOOK and you also get a Slack-shaped ping with a deep link, so parking a
question doesn't mean waiting for someone to notice a board.
1. Install — no clone needed, uvx runs it straight from the repo:
uvx --from git+https://github.com/ufna/vikunja-mcp@stable vikunja-mcp --version2. Create the board. With an admin token, this creates the project if it's missing and
reconciles the seven canonical columns (it also migrates a default Vikunja board's
Todo/Doing columns, and prints ready-to-commit config snippets):
VIKUNJA_TOKEN=<admin token> uvx --from git+https://github.com/ufna/vikunja-mcp@stable \
vikunja-mcp setup --project "My Project" --share agent-bot:write --url https://vikunja.example.com3. Point the repo at it. Commit .vikunja-mcp.toml; keep the token out of it:
[tracker]
url = "https://vikunja.example.com"
project_id = 12
wip_limit = 3 # how many Design/Build tasks one token may claim into at once
language = "en" # "en" | "ru" — what language cards are written in# .vikunja-mcp.env — same directory, gitignored, NEVER committed
VIKUNJA_TOKEN=tk_xxxxxxxxxxxx4. Register the server with Claude Code (.mcp.json) or opencode
(opencode.json). Both subscribe to the moving stable branch, so releases roll out on the
next session start with no per-repo bumps:
{ "mcpServers": { "tracker": {
"command": "uvx",
"args": ["--refresh-package", "vikunja-mcp",
"--from", "git+https://github.com/ufna/vikunja-mcp@stable", "vikunja-mcp"]
} } }{ "$schema": "https://opencode.ai/config.json", "mcp": { "tracker": {
"type": "local",
"command": ["uvx", "--refresh-package", "vikunja-mcp",
"--from", "git+https://github.com/ufna/vikunja-mcp@stable", "vikunja-mcp"],
"enabled": true
} } }5. Teach the agent the process — vikunja-mcp install-skill installs the packaged
tracker skill (queue discipline, when to escalate, what a worklog owes a reviewer) for both
Claude Code and opencode. For Claude Code it also provisions a conditional SessionStart
hook so that inside a tracker-configured project a bare /loop drains the queue instead of
falling back to the generic "don't start work on your own" default. Outside such a project
the hook emits nothing.
Then run the loop. /loop 10m for unattended work, plain /loop when you're watching.
Tool | Gate / behavior |
| One thing, in order: your active Design/Build card (including one bounced back from Your Call), then a Queue card already assigned to you, then a card in Review awaiting an independent verdict, then the top free Queue card. Never offers Backlog, a |
| Queue → Design only, and only under the WIP limit. Assign-then-verify: it assigns you, re-reads the card, and backs off if someone else won the same window. |
| The dossier: description, stage, assignees, labels, attachments, full comment thread. |
| A progress note on the card. |
|
|
|
|
| Design/Build → Your Call, keeping your assignment. Posts the question and, if configured, pings a webhook. |
| For external blockers (no access, a dependency missing, someone else's service down). Unassigns you, adds |
| Splits your own oversized task into ≥2 Queue subtasks linked to the parent; the parent becomes an |
| Files an out-of-scope finding into Backlog for human triage — never straight into Queue. Optionally linked to the card you found it on. |
| Attaches a local file — typically a screenshot of the finished work — so the reviewer can see the result. Journals itself on the card. |
| Returns a path to read, not base64, so a screenshot never bloats the agent's context. |
Three commands round out the loop; none of them speak MCP, and the SDK is imported lazily so they don't pay for it.
vikunja-mcp claimable — one JSON line answering "is there claimable work for this token
right now?", exit 0 if the check ran. It calls the real next_task(), so it cannot drift from
the gates, and it is read-only by contract. Built for a supervisor that would otherwise boot a
paid agent session every poll tick just to discover there was nothing to do.
vikunja-mcp workspace <id> — a per-task git worktree on a throwaway task/<id> branch,
so several agents can drain the queue in parallel without fighting over one checkout.
--release pushes and cleans up; --gc reaps orphans and fast-forwards your main checkout.
Its safety rule is one line: push OK → remove, push FAIL → keep. Dirty, unpushed or
unreachable work is reported, never destroyed. (One real exception, documented rather than
papered over: git-ignored files are invisible to the dirty check. Carry screenshots out of
the worktree before you release it — see the dossier.)
vikunja-mcp setup / install-skill — idempotent board reconcile, and the agent-facing
skill install described above. Both are safe to re-run; the MCP server also self-heals the
installed skill on start, so a moving stable refreshes it automatically.
Four layers, highest priority first:
Environment — VIKUNJA_URL, VIKUNJA_TOKEN, VIKUNJA_PROJECT_ID, VIKUNJA_NOTIFY_WEBHOOK
.vikunja-mcp.env — repo-local KEY=VALUE file beside the toml, gitignored. The
per-project token for a machine that works across several repos.
.vikunja-mcp.toml — committed, found by walking up from the cwd. Safe to commit
because it holds no secret.
~/.config/vikunja-mcp/env — the usual home for a personal VIKUNJA_TOKEN (chmod 600).
Two rules make that split matter, and they run in opposite directions:
A secret is never read from the toml. Not the token, not the webhook URL. So the committed file cannot leak one even by accident.
Team policy is never read from the environment. wip_limit,
require_review_independence and language are toml-only, because they describe how the
project works, not which machine you're on. Unset, wip_limit is 3 — not "unlimited";
wip_limit = 0 is a config error, because "no limit" is deliberately not expressible. Unset,
language is "en", and an unrecognised value is a config error for the same reason.
worktree_root sits on the machine side of that line, so there the environment does win.
language governs more than the tool's own output. The spec, the worklog and the review report
are the bulk of a card's text and the tool does not write them — the agent does — so the value
also rides in every next_task response, and the packaged rulebook tells the agent to write in
it. What it never touches is the comment markers ([worklog], [review], …): two of them are
matched with startswith to decide whether a card is offered for review, so they are frozen in
every language.
Full reasoning, including why the WIP limit gates one transition rather than policing a count: docs/dossier/config.md.
Consumers subscribe to the moving stable branch. Every green push to main auto-bumps the
patch version, tags vX.Y.Z, and moves stable onto it — so a fix reaches every consuming
repo at their next session start, with no PR bots and no per-repo version bumps. Immutable
tags remain the history and the rollback points:
git branch -f stable vX.Y.Z && git push -f origin stable # rollback to a known-good tagMinor and major bumps are a hand-edited commit; CI resumes auto-patching from the new baseline. docs/dossier/releases.md has the race analysis behind the atomic push and the forward-only channel.
uv sync
uv run ruff check .
uv run pytest tests/unit -qIntegration tests run against a real Vikunja container and skip themselves without
VIKUNJA_TEST_URL — the recipe is in CONTRIBUTING.md, along with the
house rules that are less obvious than they look (why line length is two numbers, and why a
mutation sweep without a control round measures nothing).
docs/ — the rules live in CLAUDE.md; the evidence lives in nine dossiers, one
per subsystem. If you are about to change a guard, its dossier is where the measurement that
put it there is written down.
MIT — see LICENSE.
Продвинуть СВОЮ задачу: to='build' требует spec (подход/дизайн); to='review' требует worklog + evidence (коммит/PR/вывод верификации). Перехода в Done нет — Done ставит человек после ревью.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| spec | No | ||
| task_id | Yes | ||
| worklog | No | ||
| evidence | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that 'Done' is not set by this tool and that specific parameters are required per transition. However, no annotations are present, and the description lacks details on side effects, permissions, or 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?
Three sentences, front-loaded with purpose and specific conditions. No redundant information, though could be slightly 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?
Given the tool's complexity (5 params, 2 required) and lack of output schema, the description covers the two main use cases and their requirements. Could mention if other 'to' values exist or indicate return value.
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 beyond input schema by explaining that 'to' values 'build' and 'review' require 'spec' and 'worklog'+'evidence' respectively. Schema has 0% description coverage, so description compensates for key parameters, though not all 5 parameters are explained.
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 tool advances a task to 'build' or 'review' states, with specific parameter requirements. It distinguishes from siblings like 'claim' or 'decompose' by focusing on state transitions.
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 (for 'build' and 'review' transitions) and when not to use ('no transition to Done'). Provides conditions for each transition, though no explicit comparison to other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Застрял и нужен человек (решение/вводные): вопрос уйдёт комментом, задача — в колонку 'Call to Human', assignee сохранится. Это НЕ ревью и НЕ внешняя блокировка.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| question | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It transparently discloses key behaviors: question becomes a comment, task moves to a specific column, assignee is preserved. It also clarifies exclusions (not a review, not an external blocker). This is solid for a simple tool.
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, using only two sentences to convey purpose, effects, and exclusions. Every sentence adds value with no redundancy. Front-loaded with main action.
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 no annotations, output schema, or complex parameters, the description covers the essential behavioral context and flow. It could mention prerequisites (e.g., task existence) but is largely complete for the tool's simplicity.
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%, so description must compensate. It implicitly maps parameters to their roles: task_id (task to move) and question (comment content). However, it does not provide explicit parameter descriptions or constraints, relying on context. Adds value but insufficiently detailed.
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 purpose: to call a human when stuck, moving the task to 'Call to Human' column and posting the question as a comment. It also distinguishes itself by stating what it is NOT (review or external blocker), aiding differentiation from 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?
The description implies when to use ('stuck and need a human') and what it is not, but does not explicitly compare to sibling tools or provide when-not-to-use guidance. Usage context is clear but lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Взять задачу из Queue: назначает тебя и переносит в Design. Откажет, если задача не в Queue, занята или проиграна гонка (тогда next_task).
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description conveys key behaviors: it assigns the user, moves the task, and lists failure conditions. This is comprehensive for a mutation tool.
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, with two sentences that convey the main action, constraints, and alternatives. Every word 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?
For a simple one-parameter tool with no output schema, the description covers purpose, side effects, error handling, and references to sibling tools, making it contextually complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explicitly define the parameter 'task_id', but the context of claiming a task makes its purpose obvious. With 0% schema coverage, more explicit parameter description would be beneficial.
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 claims a task from Queue, assigns it to the user, and moves it to Design. It specifies the resource and action, distinguishing it from sibling tools.
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 to use (take task from Queue) and when not (if not in Queue, already taken, or race condition). It provides the alternative 'next_task' for failure cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Заметка о ходе работы: находки, решения ('выбрал X вместо Y потому что Z').
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It indicates a non-destructive action (adding a note), but does not disclose whether the comment is appended, overwritten, or has any side effects. No rate limits or permissions are mentioned.
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 short and front-loaded, but it omits critical parameter information. While concise, it fails to be sufficiently informative, reducing its practical 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 no output schema and zero schema description coverage, the description is severely incomplete. It does not explain input expectations, return values, or behavior, leaving an agent with significant ambiguity.
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%, yet the description provides no explanation of the required parameters (task_id and text). An agent cannot determine what task_id refers to or what form text should take without additional 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?
The description clearly states the tool is for adding notes on progress, findings, and decisions, which aligns with the verb 'comment'. It provides specific examples of content ('chose X instead of Y because Z'), making it distinct from sibling tools like 'advance' or 'claim'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives. The description implies it is for recording observations, but does not specify when not to use it or mention any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Разбить СВОЮ большую задачу (>~полдня работы) на >=2 подзадачи: [{'title': ..., 'description'?: ..., 'priority'?: 0-5}]. Подзадачи встают в Queue с relation на родителя; родитель уходит в Backlog с label 'epic'.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| subtasks | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains that subtasks go into the Queue with a relation to the parent, and the parent moves to Backlog with an 'epic' label. This provides useful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, stating the action and conditions immediately. Every sentence adds value, 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 there is no output schema and only two parameters, the description fully explains what the tool does, what inputs are expected, and what side effects occur (parent/child task states). 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?
Schema coverage is 0%, so the description must compensate. It details the subtask format: title, optional description, and optional priority (0-5). This adds meaning to the otherwise generic 'additionalProperties: true' array items.
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 breaks a large task into subtasks, specifying that the task must be 'YOUR large task' (>~half day) and that subtasks must be at least two. This clearly differentiates it from sibling tools like get_task or next_task.
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: for tasks that are large (more than about half a day) and need to be broken down. However, it does not explicitly state when not to use or provide alternatives, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Досье задачи: описание, стадия, assignees, лейблы и все комментарии.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It lists the returned fields but does not disclose whether the operation is read-only (though implied) or any side effects. Provides basic behavioral 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?
A single sentence that is front-loaded and contains no unnecessary words. Every part of the description 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?
For a simple get tool with one parameter and no output schema, the description adequately lists what is returned. Could mention that it does not modify data, but overall reasonable.
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 the description does not mention the task_id parameter at all. It fails to add meaning 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 it retrieves a task dossier including description, stage, assignees, labels, and all comments. This distinguishes it from sibling tools which are mutation operations (comment, advance, claim, etc.).
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. The description only states what it does, not when it is appropriate or when another tool might be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Что делать дальше: сначала возвращает ТВОЮ активную задачу (Design/Build, в т.ч. вернувшуюся из Call to Human), иначе — верхнюю свободную из Queue. Backlog и blocked не выдаёт. Одна задача за раз.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals that the tool returns one task at a time, does not give backlog or blocked tasks, and prioritizes the user's active task. This addresses all key behavioral aspects for a read-heavy tool.
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 front-loads the main verb and resource. It covers priority logic, exclusions, and limitation without any redundant or unnecessary text.
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 (no parameters, no output schema), the description is complete. It explains the full behavior required for an agent to use it correctly, including prioritization, exclusions, and the one-task-per-call limit.
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, so the input schema is empty. The description adds all meaningful context by explaining what the tool actually does, which is entirely beyond the schema. This effectively compensates for the lack of 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?
The description explicitly states it returns the user's active task or the top free task from the queue, and excludes backlog and blocked tasks. This is a specific verb (returns) and resource (task), and it distinguishes itself from siblings like get_task (which retrieves a specific task) and claim (which assigns tasks).
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 the tool: when determining the next task to work on. It explains the priority logic and exclusions. However, it does not explicitly compare to siblings or state when not to use it, which is a minor gap for a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Вернуть задачу из-за ВНЕШНЕЙ блокировки (нет доступа/зависимость/чужой сервис): снимает тебя, ставит label 'blocked', уносит в Backlog на ре-триаж человеком.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses side effects: unassigns user, sets label, moves task to backlog. Clear and honest.
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 purpose, efficient no waste.
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 the tool's effect and context well for its simplicity, but omits prerequisites (e.g., task assignment status) and error conditions. Adequate for a basic 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?
Schema coverage is 0% (no property descriptions). Description does not elaborate on 'task_id' or 'reason' beyond the tool's context, leaving meaning implicit.
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 tool returns a task due to external blocking, with specific actions (removes assignee, sets label 'blocked', moves to backlog). Distinguishes from siblings like claim, advance, etc.
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 specifies when to use (external blocking), but does not mention when not to use or alternatives like comment or decompose.
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.1.0advancecall_humanclaimcommentdecomposeget_tasknext_taskreturn_taskScored across 8 tools
Each tool has a distinct purpose: advance moves stages, call_human asks for help, claim assigns tasks, comment documents progress, decompose splits tasks, get_task retrieves details, next_task suggests what to do next, and return_task handles blocking issues. No two tools overlap in functionality, making it easy for an agent to select the correct one.
Tool names mix conventions: some are single verbs (advance, claim, comment, decompose), others are verb+noun with underscore (call_human, get_task, return_task), and one is adjective+noun (next_task). While all are lowercase and readable, the lack of a uniform pattern reduces predictability.
With 8 tools, the server is well-scoped for the domain of managing task workflow from queue to completion. Each tool serves a clear role without unnecessary bulk, and the count comfortably fits the typical range for a focused MCP server.
The tools cover core workflow actions (claim, advance, return, get, next, comment, call_human, decompose) but lack basic CRUD operations like creating, updating, or deleting tasks directly. This can force agents into workarounds if new tasks are needed or details must be edited.
Work management where AI agents are first-class members: tasks, projects, memory over hosted MCP
Open-source Zapier/n8n alternative as an MCP server: agents build, run and debug your workflows.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
MCP Server for an Agent Task Marketplace
