大多数任务追踪器集成都是 CRUD 包装器：它们给代理提供 create_task、update_task、delete_task，然后希望提示词能让它保持诚实。这个项目恰恰相反。它暴露了十二个狭窄的工具，每个工具都会拒绝那些会破坏流程的操作：
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，生成工作日志和证据 sha 以离开 Build。
Your Call 是侧分支，用于代理需要做出不应独自决定的情况。它保留其分配和上下文；人类在卡片上回答。
门禁是代理的护栏，而不是安全边界——真正的边界是 Vikunja 生成的作用域 API 令牌。参见 SECURITY.md。
Related MCP server: Accordo
一个自主代理在普通任务 API 上持续运行，会以各种方式偏离轨道，这些方式单独看都合理，但合起来却毫无用处：它标记自己的工作已完成，它在完成当前任务之前就开始下一件事，它通过删除测试来“修复”错误，而这一切的唯一记录是一个三小时前就已经滚走的聊天日志。
这些问题都不是更长的提示词能解决的。提示词只是建议；工具调用才是决策点。所以流程在决策发生的地方强制执行：
与其希望代理…… | ……工具会拒绝 |
不给自己打分 |
|
在编码前写下计划 | 没有 |
说明它做了什么以及在哪里 | 没有 |
一次只做一件事 | 超过项目 WIP 限制的 |
升级而不是猜测 |
|
留下人类可以审计的痕迹 | 每次转换都会在卡片上写入一条带标记的评论 |
你得到的是一块看板，其中每张卡片都携带自己的历史——认领、计划、工作、独立裁决——按发生顺序排列。
一张卡片已经完整走完整个循环。这里没有任何内容是人类输入的：标记、标签和阶段都是工具在代理移动卡片时写入的。
从上到下阅读，那就是 claim → advance(to="build", spec=…) → advance(to="review", worklog=…, evidence=…) → 一个不同代理的 review_task(verdict="approve", report=…)。reviewed 标签是裁决留下的；卡片现在位于 Review 中，等待人类签核。每个任务都会得到这种审查，而不仅仅是 bug 修复——只有 epic 容器例外，因为它的代码存在于其子任务中。
当代理遇到一个不属于它决定的决策时，它会停放卡片而不是猜测：
卡片保留其分配人，所以当你回答时它会回到同一个代理。设置 VIKUNJA_NOTIFY_WEBHOOK，你还会收到一个带有深度链接的 Slack 风格通知，因此停放问题并不意味着要等别人注意到看板。
1. 安装 — 无需克隆，uvx 直接从仓库运行：
uvx --from git+https://github.com/ufna/vikunja-mcp@stable vikunja-mcp --version2. 创建看板。 使用管理员令牌，如果项目不存在则创建，并协调七个标准列（它还会迁移默认 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 用于你在观看时。
工具 | 门禁 / 行为 |
| 按顺序做一件事：你活跃的 Design/Build 卡片（包括从 Your Call 退回的），然后是已分配给你的 Queue 卡片，然后是等待独立裁决的 Review 卡片，最后是顶部空闲的 Queue 卡片。绝不提供 Backlog、带有 |
| 仅限 Queue → Design，且仅在 WIP 限制内。先分配后验证：它分配给你，重新读取卡片，如果其他人赢得了同一窗口则退出。 |
| 档案：描述、阶段、分配人、标签、附件、完整评论线程。 |
| 卡片上的进度说明。 |
|
|
|
|
| Design/Build → Your Call，保留你的分配。发布问题，如果配置了，则 ping 一个 webhook。 |
| 用于外部阻塞（无访问权限、缺少依赖、他人服务宕机）。取消分配你，添加 |
| 将你自己过大的任务拆分为 ≥2 个链接到父任务的 Queue 子任务；父任务成为 Backlog 中的 |
| 将超出范围的问题归档到 Backlog 供人类分诊——绝不直接进入 Queue。可选地链接到你发现它的卡片。 |
| 附加本地文件——通常是完成工作的截图——以便审查者能看到结果。在卡片上记录自身。 |
| 返回一个可读取的路径，而不是 base64，这样截图永远不会膨胀代理的上下文。 |
三个命令完善了循环；它们都不使用 MCP，并且 SDK 是惰性导入的，因此它们不会为此付出代价。
vikunja-mcp claimable — 一行 JSON 回答“这个令牌现在是否有可认领的工作？”，如果检查运行则退出码为 0。它调用真正的 next_task()，因此不会偏离门禁，并且按约定是只读的。专为监督者设计，否则它会在每次轮询时启动一个付费代理会话，却发现无事可做。
vikunja-mcp workspace <id> — 每个任务一个 git worktree，放在一次性的 task/<id> 分支上，这样多个代理可以并行处理队列，而不会争抢同一个检出。--release 推送并清理；--gc 回收孤儿并快进你的主检出。它的安全规则只有一行：推送成功 → 移除，推送失败 → 保留。 脏的、未推送的或不可达的工作会被报告，但绝不会被销毁。（有一个真实的例外，已记录而非掩盖：git-忽略 的文件对脏检查不可见。在释放 worktree 之前，请将截图带出——参见 档案。）
vikunja-mcp setup / install-skill — 幂等的看板协调，以及上述面向代理的技能安装。两者都可以安全地重新运行；MCP 服务器还会在启动时自愈已安装的技能，因此移动的 stable 会自动刷新它。
四层，优先级从高到低：
环境 — VIKUNJA_URL、VIKUNJA_TOKEN、VIKUNJA_PROJECT_ID、VIKUNJA_NOTIFY_WEBHOOK
.vikunja-mcp.env — 位于 toml 旁边的仓库本地 KEY=VALUE 文件，已被 git 忽略。适用于跨多个仓库工作的机器的项目级令牌。
.vikunja-mcp.toml — 已提交，从当前工作目录向上查找。可以安全提交，因为它不包含任何秘密。
~/.config/vikunja-mcp/env — 个人 VIKUNJA_TOKEN 的通常存放位置（chmod 600）。
两条规则让这种划分变得重要，而且它们方向相反：
秘密永远不会从 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]、……）：其中两个使用 startswith 匹配来决定卡片是否被提供审查，因此它们在每种语言中都是固定的。
完整推理，包括为什么 WIP 限制只控制一个转换而不是监管计数：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 中，还有那些看起来不明显但实际很重要的内部规则（为什么行长度是两个数字，以及为什么没有对照轮次的变异扫描毫无意义）。
docs/ — 规则位于 CLAUDE.md 中；证据 存在于九个档案中，每个子系统一个。如果你要更改某个防护，其档案中记录了当初设置它的测量依据。
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
