ほとんどのタスクトラッカー統合はCRUDラッパーです。エージェントにcreate_task、update_task、delete_taskを渡し、プロンプトが正直さを保ってくれることを願います。これはその逆です。12個の狭いツールを公開し、それぞれがプロセスを壊す動きを拒否します。
Backlog → Queue → Design → Build → Review → [human] → Done
↕ ↕
Your Call (+ independent review of every task in Review)BacklogとDoneは人間の領域です。 一方の端でトリアージ、もう一方の端で承認。advanceにDoneに到達する引数はありません。試みるエージェントにはレビュー後にタスクをDoneに移動できるのは人間だけと伝えられます。
Queue → Design → Build → Reviewはエージェントのループです。 タスクをクレームし、Designを離れるためのスペックを書き、Buildを離れるためのワークログとエビデンスshaを生成します。
**Your Call**は、エージェントが単独で下すべきでない決定が必要なときのサイドブランチです。割り当てとコンテキストを保持し、人間がカード上で回答します。
ゲートはエージェントのためのガードレールであり、セキュリティ境界ではありません。実際の境界はVikunjaが発行するスコープ付きAPIトークンです。SECURITY.mdを参照してください。
Related MCP server: Accordo
素のタスクAPIに対して自律エージェントを動かし続けると、個々には合理的でも全体としては役に立たない方向に漂流します。自分の作業を完了とマークし、これを終える前に次のことを始め、テストを削除してバグを「修正」し、その記録は3時間前にスクロールして消えたチャットログだけです。
それのどれも、より長いプロンプトでは修正されません。プロンプトはアドバイスであり、ツール呼び出しが決定ポイントです。だからプロセスは決定が行われる場所で強制されます。
エージェントに期待する代わりに… | …ツールは拒否する |
自分の宿題を自分で採点しない |
|
コーディング前に計画を書き留める |
|
何をどこでやったかを言う |
|
一度に一つのことに取り組む | プロジェクトのWIP制限を超えた |
推測せずにエスカレーションする |
|
人間が監査できる痕跡を残す | すべての遷移がカードにマーク付きコメントを書く |
得られるのは、各カードが独自の履歴（クレーム、計画、作業、独立した判定）を発生順に保持するボードです。
ループを一巡したカードです。ここにあるものは人間が入力したものはありません。マーカー、ラベル、ステージは、エージェントがカードを移動させたときにツールが書いたものです。
上から下に読むと、claim → advance(to="build", spec=…) → advance(to="review", worklog=…, evidence=…) → 別のエージェントのreview_task(verdict="approve", report=…)です。reviewedラベルは判定が残したもので、カードは現在Reviewにあり、人間の承認を待っています。すべてのタスクがそのレビューを受けます。バグ修正だけではありません。epicコンテナだけは例外で、そのコードは子に存在するからです。
そして、エージェントが自分が下すべきでない決定に直面したとき、推測する代わりにカードを駐車します。
カードは割り当て先を保持するので、あなたが回答すると同じエージェントに戻ります。VIKUNJA_NOTIFY_WEBHOOKを設定すると、ディープリンク付きのSlack形式のpingも受け取れます。質問を駐車しても、誰かがボードに気づくのを待つ必要はありません。
1. インストール — クローンは不要、uvxがリポジトリから直接実行します：
uvx --from git+https://github.com/ufna/vikunja-mcp@stable vikunja-mcp --version2. ボードを作成。 管理者トークンを使用すると、プロジェクトが存在しない場合は作成し、7つの標準列を調整します（デフォルトのVikunjaボードのTodo/Doing列も移行し、コミット可能な設定スニペットを出力します）：
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. リポジトリをそれに向けます。 .vikunja-mcp.tomlをコミットし、トークンはその外に保持します：
[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. サーバーを登録 Claude Code (.mcp.json) または opencode (opencode.json) で。両方とも移動するstableブランチにサブスクライブするため、リリースは次回のセッション開始時にリポジトリごとのバンプなしで展開されます：
{ "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. エージェントにプロセスを教える — vikunja-mcp install-skillは、Claude Codeとopencodeの両方にパッケージ化されたトラッカースキル（キュー規律、いつエスカレーションするか、ワークログがレビュアーに何を負うか）をインストールします。Claude Codeでは、条件付きSessionStartフックもプロビジョニングし、トラッカー設定済みプロジェクト内では、裸の/loopが「自分で作業を始めない」という一般的なデフォルトにフォールバックする代わりにキューを排出します。そのようなプロジェクトの外では、フックは何も出力しません。
次にループを実行します。無人作業には/loop 10m、見ているときは素の/loop。
ツール | ゲート / 動作 |
| 順序に従って1つ：アクティブなDesign/Buildカード（Your Callから返されたものを含む）、次にすでにあなたに割り当てられたQueueカード、次に独立した判定を待つReviewのカード、次に空いているQueueカードの先頭。Backlog、 |
| Queue → Designのみ、かつWIP制限内のみ。割り当ててから検証：あなたを割り当て、カードを再読み込みし、他の誰かが同じウィンドウを勝ち取った場合はバックオフします。 |
| ドシエ：説明、ステージ、割り当て先、ラベル、添付ファイル、完全なコメントスレッド。 |
| カード上の進捗メモ。 |
|
|
|
|
| Design/Build → Your Call、割り当てを保持。質問を投稿し、設定されていればwebhookにpingします。 |
| 外部のブロッカー（アクセス不可、依存関係の欠落、他者のサービスの停止）用。あなたの割り当てを解除し、 |
| 自分の過大なタスクを、親にリンクされた≥2つのQueueサブタスクに分割；親はBacklogの |
| スコープ外の発見を人間のトリアージのためにBacklogに提出 — 決して直接Queueには入れません。オプションで、見つけたカードにリンクされます。 |
| ローカルファイル（通常は完成した作業のスクリーンショット）を添付し、レビュアーが結果を見ることができるようにします。カードに自身を記録します。 |
| base64ではなく読み取り用のパスを返すため、スクリーンショットがエージェントのコンテキストを肥大化させません。 |
3つのコマンドがループを完成させます。どれもMCPを話さず、SDKは遅延インポートされるため、そのコストを支払いません。
vikunja-mcp claimable — 「このトークンに対して今クレーム可能な作業はあるか？」に答える1行のJSON。チェックが実行された場合は終了コード0。実際のnext_task()を呼び出すため、ゲートから逸脱できず、契約上読み取り専用です。ポーリングのたびに有料エージェントセッションを起動して何もすることがないと発見するだけのスーパーバイザーのために作られました。
vikunja-mcp workspace <id> — 使い捨ての task/<id> ブランチ上にタスクごとの git worktree を作成します。これにより、複数のエージェントが1つのチェックアウトを奪い合うことなく、並行してキューを処理できます。--release はプッシュしてクリーンアップし、--gc は孤立した worktree を回収してメインのチェックアウトを fast-forward します。安全ルールは1行です: プッシュ成功 → 削除、プッシュ失敗 → 保持。 汚れた作業、未プッシュの作業、到達不能な作業は報告され、決して破棄されません。(実際の例外が1つあり、隠蔽ではなく文書化されています: git で 無視 されたファイルは汚れチェックでは見えません。リリースする前に worktree からスクリーンショットを取り出してください — 資料 を参照。)
vikunja-mcp setup / install-skill — 冪等なボード調整と、前述のエージェント向けスキルインストールです。どちらも再実行しても安全で、MCP サーバーは起動時にインストール済みスキルを自己修復するため、移動する stable があれば自動的に更新されます。
4つのレイヤーがあり、優先度が高い順に:
環境変数 — VIKUNJA_URL、VIKUNJA_TOKEN、VIKUNJA_PROJECT_ID、VIKUNJA_NOTIFY_WEBHOOK
.vikunja-mcp.env — toml の隣にあるリポジトリローカルの KEY=VALUE ファイルで、gitignore されています。複数のリポジトリで作業するマシン用のプロジェクト別トークンを置く場所です。
.vikunja-mcp.toml — コミットされ、cwd から上方向に探索して見つかります。秘密情報を含まないためコミットしても安全です。
~/.config/vikunja-mcp/env — 個人の VIKUNJA_TOKEN を置く通常の場所です(chmod 600)。
この分割が重要になる理由は2つのルールにあり、それらは逆方向に働きます:
秘密情報は toml から読み取られることはありません。 トークンも webhook URL もです。したがって、コミットされたファイルが偶発的に秘密情報を漏らすことはありません。
チームの方針は環境変数から読み取られることはありません。 wip_limit、require_review_independence、language は toml のみです。なぜなら、これらは プロジェクト がどう動くかを記述するものであり、どのマシンにいるかではないからです。未設定の場合、wip_limit は 3 であり、「無制限」ではありません。wip_limit = 0 は設定エラーです。「制限なし」が意図的に表現不可能だからです。未設定の場合、language は "en" であり、認識できない値は同じ理由で設定エラーです。
worktree_root はその線のマシン側にあるため、そこでは環境変数が優先されます。
language はツール自身の出力だけでなく、より多くのものを管理します。仕様、作業ログ、レビューレポートはカードのテキストの大部分を占めますが、ツールはそれらを書きません — エージェントが書きます — したがって、この値はすべての next_task レスポンスにも含まれ、パッケージ化されたルールブックはエージェントにその言語で書くよう指示します。決して触れないのはコメントマーカー([worklog]、[review]、…)です。そのうち2つは startswith で照合され、カードがレビュー対象として提供されるかどうかを決定するため、すべての言語で固定されています。
WIP 制限がカウントを監視するのではなく1つの遷移を制限する理由を含む完全な論拠は、docs/dossier/config.md にあります。
利用者は移動する stable ブランチを購読します。main へのすべてのグリーンのプッシュはパッチバージョンを自動的に上げ、vX.Y.Z にタグを付け、stable をその上に移動させます — したがって、修正は PR ボットもリポジトリごとのバージョンアップもなしに、次のセッション開始時にすべての利用リポジトリに届きます。不変のタグは履歴とロールバックポイントとして残ります:
git branch -f stable vX.Y.Z && git push -f origin stable # rollback to a known-good tagマイナーおよびメジャーバージョンのアップは手動編集のコミットです。CI は新しいベースラインから自動パッチを再開します。アトミックなプッシュと前方のみのチャネルの背後にある競合分析は docs/dossier/releases.md にあります。
uv sync
uv run ruff check .
uv run pytest tests/unit -q統合テストは実際の Vikunja コンテナに対して実行され、VIKUNJA_TEST_URL がない場合は自分自身をスキップします — レシピは CONTRIBUTING.md にあり、見た目ほど明白ではないハウスルール(行の長さが2つの数値である理由、対照ラウンドなしのミューテーションスイープが何も測定しない理由)もそこにあります。
docs/ — ルールは CLAUDE.md にあり、証拠 は9つの資料にあり、サブシステムごとに1つです。ガードを変更しようとしている場合、その資料が、そのガードを設置した測定値が記録されている場所です。
MIT — 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
