Die meisten Task-Tracker-Integrationen sind CRUD-Wrapper: Sie geben einem Agenten create_task,
update_task, delete_task und hoffen, dass der Prompt ihn ehrlich hält. Dieses hier macht das Gegenteil.
Es stellt zwölf schmale Tools bereit, und jedes einzelne verweigert die Schritte, die den Prozess brechen würden:
Backlog → Queue → Design → Build → Review → [human] → Done
↕ ↕
Your Call (+ independent review of every task in Review)Backlog und Done sind menschliches Territorium. Triage am einen Ende, Abnahme am anderen.
Es gibt kein Argument für advance, das Done erreicht – ein Agent, der es versucht, bekommt gesagt:
nur ein Mensch verschiebt eine Aufgabe nach der Überprüfung nach Done.
Queue → Design → Build → Review ist die Agenten-Schleife. Eine Aufgabe übernehmen, einen Spec schreiben, um Design zu verlassen, ein Worklog und einen Evidence-SHA erstellen, um Build zu verlassen.
Your Call ist der Seitenzweig für den Fall, dass ein Agent eine Entscheidung braucht, die er nicht allein treffen sollte. Es behält seine Zuweisung und seinen Kontext; der Mensch antwortet auf der Karte.
Tore sind Leitplanken für Agenten, keine Sicherheitsgrenze – die eigentliche Grenze ist das eingeschränkte API-Token, das Vikunja ausstellt. Siehe SECURITY.md.
Related MCP server: Accordo
Ein autonomer Agent, der gegen eine einfache Task-API läuft, driftet auf eine Weise ab, die einzeln betrachtet vernünftig und insgesamt nutzlos ist: Er markiert seine eigene Arbeit als erledigt, er beginnt das Nächste, bevor er das Aktuelle beendet, er „behebt“ einen Bug, indem er den Test löscht, und die einzige Aufzeichnung davon ist ein Chat-Log, das vor drei Stunden weggescrollt wurde.
Nichts davon wird durch einen längeren Prompt behoben. Der Prompt ist Ratschlag; der Tool-Aufruf ist der Entscheidungspunkt. Also wird der Prozess dort durchgesetzt, wo die Entscheidung passiert:
Statt zu hoffen, dass der Agent… | …verweigert das Tool |
seine eigene Arbeit nicht selbst benotet |
|
einen Plan niederschreibt, bevor er codet |
|
sagt, was es getan hat und wo |
|
an einer Sache zur Zeit arbeitet |
|
eskaliert statt zu raten |
|
eine Spur hinterlässt, die ein Mensch prüfen kann | jeder Übergang schreibt einen markierten Kommentar auf die Karte |
Was du zurückbekommst, ist ein Board, auf dem jede Karte ihre eigene Geschichte trägt – die Übernahme, den Plan, die Arbeit, das unabhängige Urteil – in der Reihenfolge, in der es passiert ist.
Eine Karte, die komplett durch die Schleife gelaufen ist. Hier wurde nichts von einem Menschen getippt: Die Marker, die Labels und die Stufe sind das, was die Tools geschrieben haben, als die Agenten sie bewegt haben.
Von oben nach unten gelesen ist das claim → advance(to="build", spec=…) → advance(to="review", worklog=…, evidence=…) → das review_task(verdict="approve", report=…) eines anderen Agenten. Das reviewed-Label ist das, was das Urteil hinterlassen hat; die Karte sitzt jetzt in Review und wartet darauf, dass ein Mensch sie absegnet. Jede Aufgabe bekommt diese Überprüfung, nicht nur Bugfixes – nur ein epic-Container ist ausgenommen, weil sein Code in seinen Kindern lebt.
Und wenn der Agent auf eine Entscheidung stößt, die nicht seine ist, parkt er die Karte, statt zu raten:
Die Karte behält ihren Bearbeiter, sodass sie zum selben Agenten zurückkommt, wenn du antwortest. Setze VIKUNJA_NOTIFY_WEBHOOK und du bekommst zusätzlich einen Slack-förmigen Ping mit einem Deep Link, sodass das Parken einer Frage nicht bedeutet, darauf zu warten, dass jemand ein Board bemerkt.
1. Installieren – kein Klonen nötig, uvx führt es direkt aus dem Repo aus:
uvx --from git+https://github.com/ufna/vikunja-mcp@stable vikunja-mcp --version2. Das Board erstellen. Mit einem Admin-Token erstellt dies das Projekt, falls es fehlt, und gleicht die sieben kanonischen Spalten ab (es migriert auch die Todo/Doing-Spalten eines Standard-Vikunja-Boards und gibt konfigurationsfertige Snippets aus):
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. Das Repo darauf ausrichten. Committe .vikunja-mcp.toml; halte das Token daraus heraus:
[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. Den Server registrieren bei Claude Code (.mcp.json) oder opencode (opencode.json). Beide abonnieren den beweglichen stable-Branch, sodass Releases beim nächsten Session-Start ohne pro-Repo-Anpassungen ausgerollt werden:
{ "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. Dem Agenten den Prozess beibringen – vikunja-mcp install-skill installiert den gepackten Tracker-Skill (Queue-Disziplin, wann zu eskalieren ist, was ein Worklog einem Reviewer schuldet) für sowohl Claude Code als auch opencode. Für Claude Code richtet es außerdem einen bedingten SessionStart-Hook ein, sodass innerhalb eines tracker-konfigurierten Projekts ein nacktes /loop die Queue leert, anstatt auf den generischen Standard „starte keine Arbeit von dir aus“ zurückzufallen. Außerhalb eines solchen Projekts gibt der Hook nichts aus.
Dann führe die Schleife aus. /loop 10m für unbeaufsichtigte Arbeit, einfaches /loop, wenn du zusiehst.
Tool | Tor / Verhalten |
| Eine Sache, in Reihenfolge: deine aktive Design/Build-Karte (einschließlich einer, die aus Your Call zurückgeworfen wurde), dann eine Queue-Karte, die bereits dir zugewiesen ist, dann eine Karte in Review, die auf ein unabhängiges Urteil wartet, dann die oberste freie Queue-Karte. Bietet nie Backlog, eine mit |
| Nur Queue → Design, und nur unter dem WIP-Limit. Zuweisen-dann-prüfen: Es weist dich zu, liest die Karte erneut und zieht sich zurück, wenn jemand anderes dasselbe Zeitfenster gewonnen hat. |
| Das Dossier: Beschreibung, Stufe, Bearbeiter, Labels, Anhänge, vollständiger Kommentar-Thread. |
| Eine Fortschrittsnotiz auf der Karte. |
|
|
|
|
| Design/Build → Your Call, unter Beibehaltung deiner Zuweisung. Postet die Frage und pingt, falls konfiguriert, einen Webhook. |
| Für externe Blocker (kein Zugriff, fehlende Abhängigkeit, Dienst von jemand anderem down). Hebt deine Zuweisung auf, fügt |
| Teilt deine eigene überdimensionierte Aufgabe in ≥2 Queue-Unteraufgaben, die mit der übergeordneten verknüpft sind; die übergeordnete wird zu einem |
| Legt einen außerhalb des Rahmens liegenden Befund in Backlog zur menschlichen Triage ab – nie direkt in Queue. Optional mit der Karte verknüpft, auf der du ihn gefunden hast. |
| Hängt eine lokale Datei an – typischerweise einen Screenshot der fertigen Arbeit – damit der Reviewer das Ergebnis sehen kann. Protokolliert sich selbst auf der Karte. |
| Gibt einen Pfad zum Lesen zurück, nicht base64, sodass ein Screenshot den Kontext des Agenten nie aufbläht. |
Drei Befehle runden die Schleife ab; keiner von ihnen spricht MCP, und das SDK wird lazy importiert, sodass sie nicht dafür zahlen.
vikunja-mcp claimable – eine JSON-Zeile, die die Frage beantwortet „Gibt es gerade beanspruchbare Arbeit für dieses Token?“, Exit 0, wenn die Prüfung lief. Es ruft das echte next_task() auf, kann also nicht von den Toren abweichen, und ist vertraglich schreibgeschützt. Entwickelt für einen Supervisor, der sonst bei jedem Poll-Tick eine kostenpflichtige Agenten-Session starten würde, nur um festzustellen, dass es nichts zu tun gibt.
vikunja-mcp workspace <id> — ein Git-Worktree pro Aufgabe auf einem Wegwerf-Zweig task/<id>, damit mehrere Agenten die Warteschlange parallel abarbeiten können, ohne sich um einen Checkout zu streiten. --release pusht und räumt auf; --gc erntet verwaiste Worktrees und führt deinen Haupt-Checkout per Fast-Forward. Seine Sicherheitsregel ist eine Zeile: Push OK → entfernen, Push fehlgeschlagen → behalten. Schmutzige, nicht gepushte oder unerreichbare Arbeit wird gemeldet, nie zerstört. (Eine echte Ausnahme, dokumentiert statt übertüncht: git-ignorierte Dateien sind für den Schmutz-Check unsichtbar. Bringe Screenshots aus dem Worktree, bevor du ihn freigibst — siehe das Dossier.)
vikunja-mcp setup / install-skill — idempotente Board-Abgleichung und die oben beschriebene agentenorientierte Skill-Installation. Beide können gefahrlos erneut ausgeführt werden; der MCP-Server heilt den installierten Skill auch beim Start selbst, sodass ein sich bewegendes stable ihn automatisch aktualisiert.
Vier Ebenen, höchste Priorität zuerst:
Umgebung — VIKUNJA_URL, VIKUNJA_TOKEN, VIKUNJA_PROJECT_ID, VIKUNJA_NOTIFY_WEBHOOK
.vikunja-mcp.env — repo-lokale KEY=VALUE-Datei neben der TOML, git-ignoriert. Das projektspezifische Token für eine Maschine, die über mehrere Repos arbeitet.
.vikunja-mcp.toml — eingecheckt, wird vom aktuellen Arbeitsverzeichnis aus aufwärts gesucht. Sicher zu committen, da es keine Geheimnisse enthält.
~/.config/vikunja-mcp/env — der übliche Ort für ein persönliches VIKUNJA_TOKEN (chmod 600).
Zwei Regeln machen diese Aufteilung wichtig, und sie laufen in entgegengesetzte Richtungen:
Ein Geheimnis wird niemals aus der TOML gelesen. Weder das Token noch die Webhook-URL. So kann die eingecheckte Datei selbst versehentlich keines leaken.
Teamrichtlinie wird niemals aus der Umgebung gelesen. wip_limit, require_review_independence und language sind nur in der TOML, weil sie beschreiben, wie das Projekt funktioniert, nicht auf welcher Maschine du bist. Nicht gesetzt, ist wip_limit 3 — nicht „unbegrenzt“; wip_limit = 0 ist ein Konfigurationsfehler, weil „keine Begrenzung“ bewusst nicht ausdrückbar ist. Nicht gesetzt, ist language "en", und ein nicht erkannter Wert ist ein Konfigurationsfehler aus demselben Grund.
worktree_root liegt auf der Maschinenseite dieser Linie, also gewinnt dort die Umgebung.
language regelt mehr als nur die eigene Ausgabe des Tools. Die Spezifikation, das Arbeitsprotokoll und der Review-Bericht machen den Großteil des Textes einer Karte aus, und das Tool schreibt sie nicht — der Agent tut das —, also steckt der Wert auch in jeder next_task-Antwort, und das mitgelieferte Regelwerk sagt dem Agenten, darin zu schreiben. Was es nie berührt, sind die Kommentar-Marker ([worklog], [review], …): zwei von ihnen werden mit startswith abgeglichen, um zu entscheiden, ob eine Karte zum Review angeboten wird, also sind sie in jeder Sprache eingefroren.
Vollständige Begründung, einschließlich warum das WIP-Limit einen Übergang begrenzt, anstatt eine Anzahl zu überwachen: docs/dossier/config.md.
Konsumenten abonnieren den sich bewegenden stable-Zweig. Jeder grüne Push auf main erhöht automatisch die Patch-Version, taggt vX.Y.Z und bewegt stable darauf — so erreicht ein Fix jedes konsumierende Repo beim nächsten Sitzungsstart, ohne PR-Bots und ohne versionsspezifische Bumps pro Repo. Unveränderliche Tags bleiben die Historie und die Rollback-Punkte:
git branch -f stable vX.Y.Z && git push -f origin stable # rollback to a known-good tagMinor- und Major-Bumps sind ein manuell bearbeiteter Commit; CI setzt das automatische Patchen ab der neuen Basis fort. docs/dossier/releases.md enthält die Rennanalyse hinter dem atomaren Push und dem Nur-Forward-Kanal.
uv sync
uv run ruff check .
uv run pytest tests/unit -qIntegrationstests laufen gegen einen echten Vikunja-Container und überspringen sich selbst ohne VIKUNJA_TEST_URL — das Rezept steht in CONTRIBUTING.md, zusammen mit den Hausregeln, die weniger offensichtlich sind, als sie aussehen (warum die Zeilenlänge zwei Zahlen ist und warum ein Mutations-Sweep ohne Kontrollrunde nichts misst).
docs/ — die Regeln leben in CLAUDE.md; die Beweise leben in neun Dossiers, eines pro Subsystem. Wenn du eine Schutzmaßnahme ändern willst, ist ihr Dossier der Ort, an dem die Messung, die sie dorthin gebracht hat, niedergeschrieben ist.
MIT — siehe 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
