🧪 公开测试版。 killBottleneck 功能完整，目前处于测试阶段——云版本 和自托管版本都是如此；它们是同一个应用。我们在这里测试的是 自托管这一侧：安装、反向代理、你自己的 SMTP、升级。 请安装它（见下方“快速开始”），尝试搞坏它，然后告诉我们 发生了什么：bug → Issues，想法 → Discussions。 当测试平静下来后，v1.0 就会发布。
你的项目、你的公司及其流程的可视化图景——人和 AI 代理共同协作的目标地图，完全运行在你自己的服务器上：你的数据永远不会离开公司。以开源的精神开放，只是没有将其作为托管服务转售的权利——参见许可证。
这里没有任何东西会向外部回传数据。 在默认安装下，服务器不会向任何地方发送请求， 应用也不会从第三方 CDN 加载任何内容——包括字体，它们都由你自己的实例提供。 所有可能离开你网络的东西，都是你主动开启的：
出站请求 | 何时发生 | 关闭方式 |
GitHub Releases API | 版本检查，从用户的浏览器发起——不是服务器 |
|
你配置的 AI 端点 | 仅在 |
|
Google（登录、Drive 选择器） | 仅当你配置了 | 保持为空（默认） |
没有遥测、没有分析、也没有许可证检查。
谁执行一个步骤：人，还是自动化 — 包括供你自己的代理使用的 Webhook 契约
使用 Google 登录 · 附件 · 电子邮件（SMTP）
你只需要 Docker。然后：
cp .env.example .env # optional — the defaults are fine
docker compose up -dkillBottleneck 运行在 http://SERVER-IP:8090。局域网内的同事只需在浏览器中打开它即可。
第一个注册的用户会自动成为管理员。 其他人可以自行注册， 也可以由管理员从“管理”中邀请他们（这会创建一个带有临时密码的 账户，以便移交）。
Related MCP server: stablebaseline-mcp
完整的目标地图编辑器（节点、连线、状态、备注），每个用户可拥有多张地图，目标上的评论， 与同事共享地图（读/编辑），公开地图，导出为图片/PDF。
“My day”面板（主页和“任务”页面都有）：一个可点击的概览，显示逾期 / 今天 / 一周内 / 阻塞他人的事项， 根据你的数据实时计算；日期旁边显示名字日；提供竖版 PNG 导出，适合手机——既有完整版（含任务名称）， 也有匿名版（名称已隐去，适合社交媒体）。在 HTTPS 下你还可以使用共享… （你手机原生的 Web Share 对话框，不涉及第三方服务）。
时间跟踪：顶部栏有一个 ⏱ 计时器（单击即可开始一次“空”计时——项目/客户/目标可以在计时期间或之后指定）， 地图中的每个任务和每个目标上都有一个计时器（计时绝不改变状态——它纯粹是辅助性的）， 左侧有一个“时间跟踪”面板，显示记录（起止时间、追溯指定），用户菜单中有“已工作的时间”对话框 （今天/本周，按项目和客户细分），以及一个客户注册表（项目→客户，因此时间也可以按客户汇总）， 还有对忘记的计时器在 12 小时后自动停止的功能。收件箱行为： 停止一次未指定的计时并附带备注 （例如“与客户通话”）时，它还会作为一条想法保存到你的暂存中。
同一个实例在手机上打开时会切换到简化视图：今日任务、勾选完成、添加任务、阅读消息—— 无需在小屏幕上与地图画布较劲。你可以随时切回完整视图，并且可以将应用添加到主屏幕 （通过 HTTPS），使其行为类似原生应用。
更多内容请参见简化视图指南。
AI 顾问（从目标起草地图、展开分支、就地图进行聊天、AI 项目摘要、从目标建议任务、从文本/语音生成地图）
通过 .env 中的 KB_AI_PROVIDER 开启：
api — 与 killBottleneck API 契约兼容的远程 AI 服务：输入从提供商处获得的地址和令牌。无需自己的 GPU，也无需维护。
ollama — 你自己的本地模型：安装 Ollama，拉取一个模型（ollama pull gpt-oss:20b），并设置 KB_AI_URL=http://IP:11434 + KB_AI_MODEL=gpt-oss:20b。一切都在你这边运行，数据不会离开你的网络。（支持基本提示词；不包含语音转录。）
custom — 你自己的、遵循相同 API 契约的端点。
使用 AI 时，地图数据会被发送到你选择的端点；使用 none（默认值）时，数据永远不会离开你的服务器。
每日 AI 鼓励（My day 面板中的一行）：1–2 句话，按“什么阻塞了他人 → 逾期 → 今天”的优先级排序，偶尔附带一句谚语。
它由 cron 任务在早上生成（KB_SUMMARY_HOUR，默认 6），仅针对最近 KB_SUMMARY_ACTIVE_DAYS 天内登录过的账户
（默认 14，0 = 所有人）；其余账户在打开应用时生成。也可以为摘要单独指定一个（更小/更快的）模型：
KB_SUMMARY_PROVIDER/URL/MODEL/TOKEN——不设置则使用上述通用 AI 配置。该面板在没有 AI 的情况下也能完整工作，
只是少了这一行。AI 绝不会枚举任务列表（任务列表是根据你的数据计算出来的，并且可点击），
任务名称在进入提示词之前会经过净化处理。
killBottleneck 自带内置的 MCP 服务器（mcp/）：将你的 AI 助手连接到自己的实例，地图就可以通过对话方式构建——
“把这些会议记录做成一张地图”、批量编辑、勾选已完成事项。自托管实例和托管实例的工作方式相同，只是地址不同。
在应用中：用户菜单 → API 密钥 → 新建一个具有读写权限的密钥（只读对于读取访问已经足够）。令牌仅显示一次。建议：为密钥设置过期时间，并在不再使用时撤销它。
无需安装任何东西——该服务器以 killbottleneck-mcp 的形式发布在 npm 上，因此 npx 会在首次使用时获取它。（更喜欢从本仓库运行吗？执行 cd mcp && npm install，然后使用 node /absolute/path/mcp/index.js 而不是下面的 npx 命令。）
将其注册到你的助手中：
Claude Code：
claude mcp add killbottleneck \
-e KB_URL=http://SERVER-IP:8090 \
-e KB_API_KEY=kb_user_... \
-- npx -y killbottleneck-mcpClaude Desktop（claude_desktop_config.json → mcpServers）：
{
"mcpServers": {
"killbottleneck": {
"command": "npx",
"args": ["-y", "killbottleneck-mcp"],
"env": {
"KB_URL": "http://SERVER-IP:8090",
"KB_API_KEY": "kb_user_..."
}
}
}
}工具：list_maps、get_map、create_map、add_nodes、update_node、delete_node（以及规则工具）。一个带有负责人或截止日期的目标就是一个任务——没有单独的任务记录。
安全性： 密钥只能访问其所有者的地图（与应用中完全一致）；共享地图和团队地图刻意不能通过密钥访问（目前如此），管理、AI 设置和用户信息则永远不能。写入操作可以添加/编辑/删除目标和任务；不能通过 API 删除整张地图，也不能删除地图的顶点。限制：每个密钥每分钟 120 次读取 + 30 次写入，每次调用最多 200 个节点，每个账户最多 20 个密钥。与打开的编辑器同时工作由冲突检测处理（编辑器会提供重新加载，助手会自行重新加载地图）。注意：add_nodes 会重新运行整张地图的布局。MCP 工具输出为英文（助手始终能理解）；服务器错误消息会以你账户的语言显示。
对于地图中的每个目标，你可以指定由人还是自动化来执行。该自动化背后是 AI 代理还是计划好的 cron 任务，这不是你需要关心的问题——构建它的人知道。
重要：目标的负责人始终是人。 即使是自动化步骤，也有一个负责的人，他会收到通知，并且目标会计入他的“My day”。自动化做工作，人对它负责。
对于自动化步骤，你还要记录由哪个自动化执行——这是对现状的记录（“n8n 已经为我们做了这一步”），而不是命令。这样一眼就能看出地图的哪些部分由人完成，哪些由机器完成。
在任何目标上，你都可以勾选请求将该步骤自动化，并可选地添加一句说明原因。该请求会发送给 AI 代理管理器——这是用户上的一个独立标志（用户管理 → AI 管理器），与其角色无关；管理员和普通成员都可以在担任其角色的同时拥有该标志。
一旦管理器构建了自动化并将其记录在目标上，请求会自动清理，请求者会收到一条消息，告知其目标现已自动化。完整流程：
person: ☑ I would like this automated ("I upload subtitles by hand, 20 minutes")
↓
the AI manager gets a notification → decides → builds an n8n workflow
↓
the manager records it on the goal: "n8n — subtitle translation"
↓
the requester gets a notification: "your goal is now automated by n8n — subtitle translation"你可以向任何目标上传文件。在带有自动化的目标上，上传文件会立即启动它——你只需直接附加需要处理的内容（通常是字幕、源材料、导出文件），而不是在别处填写表单。
附件仅对有权访问项目的人员可见。文件受到保护：仅凭链接不会泄露任何信息。
AI 代理管理器（或管理员）在 AI 代理注册表下维护一个自动化目录：名称、Webhook 地址、签名密钥、启用/禁用。在目标上，自动化通过名称选择——团队成员永远不会看到地址或密钥。当目标上的名称与注册表中的代理匹配时，killBottleneck 可以自行启动它。
谁可以启动它。 每个智能体可以携带一个允许的电子邮件地址列表。空列表意味着自动化可以由任何能够编辑任何地图的人启动——在公司内部这通常没问题，但如果你允许承包商进入实例，则要加以限制：否则，任何可以编辑地图的人都可以启动你的任何 n8n 工作流，并向其中输入他们自己的文本（目标的标题和描述会通过 payload 发送给智能体）。
附件限制为每个项目 200 个文件，另外还可以为整个实例设置空间限制（KB_FILES_MB，单位为 MB；0 = 完全禁用上传，空 = 无限制——在共享磁盘上设置一个限制，这样托管实例就不会把它填满）。⚠️ 以前的 FLOWMAP_MAP_FILES_MB 是默认 200 MB 的按项目配额——如果你设置了它，它仍然适用于你，但不设置的话，现在完全没有空间限制。
自动化在以下情况启动：
向目标上传了附件，或
目标的轮次到来——它一直在等待其子目标，而子目标刚刚全部完成，或
有人手动将目标切换为“进行中”（这也是你重试失败运行的方式）
正在运行的自动化在其报告返回或过期之前，不会第二次启动。
发出的请求（POST 到智能体的地址，带有 X-Signature 头 = 使用智能体的密钥对整个请求体进行 HMAC-SHA256）：
{
"run_id": "…", "run_token": "kbr_…",
"callback_url": "https://your-instance/api/kb/agent-callback",
"files_url": "https://your-instance/api/kb/agent-files?run_token=kbr_…",
"files": [{ "id": "…", "name": "subtitles.sbv", "size": 1234, "url": "https://…?run_token=kbr_…" }],
"map_id": "…", "map_title": "…",
"node_id": "…", "node_title": "…",
"description": "…", "deadline": "2026-08-01",
"owner": "responsible@company.com", "triggered_by": "who@company.com"
}智能体使用其运行令牌下载文件；files_url 是一个实时列表，因此它也能看到运行期间新增的附件。一旦结果被报告，令牌就会过期。
报告返回（POST 到 callback_url，无需登录——运行令牌负责认证）：
{ "run_id": "…", "run_token": "kbr_…", "status": "done", "result": "Translated into 3 languages" }status 的值为 done 或 failed。一个令牌仅对一个目标和一次报告有效——使用相同令牌的第二次调用将无法通过。
在 done 之后，目标被完成，这将推动流程的其余部分：下一个目标被解除阻塞，负责该目标的人会收到通知，告知他们可以开始。如果下一个目标也是自动化的，它会立即启动——因此步骤会自行串联起来。
设置智能体应回调的地址。 callback_url 由服务器组装，而不是浏览器——未配置时，它使用 PocketBase 的“应用 URL”，安装后该 URL 为 http://localhost:8090。因此，运行在另一台机器上的智能体会调用自己，运行将一直挂起直到超时。在 .env 中：
KB_PUBLIC_URL=https://killbottleneck.yourcompany.com
KB_AGENT_TIMEOUT_MIN=90智能体能访问到的任何地址都可以——在自托管设置中，局域网上的 http://192.168.1.10:8090 完全没问题。托管实例（killBottleneck Cloud）会自动设置此项。
你的 n8n 在同一网络上吗？ Webhook 地址由服务器调用，这使其成为典型的内网扫描向量——因此默认情况下，killBottleneck 拒绝调用私有地址（10.x、192.168.x、172.16–31.x、localhost、云元数据）。在 n8n 与 killBottleneck 并排运行的自托管设置中，允许它：
KB_ALLOW_PRIVATE_WEBHOOKS=1没有这个设置，运行将被标记为失败，AI 智能体管理器会收到一条消息说明原因。智能体必须填写其密钥——没有密钥，请求将使用空密钥签名，接收方将没有任何保护，因此 killBottleneck 会直接拒绝此类运行。当前生效的地址始终显示在 AI 智能体注册表的底部，当它指向 localhost 时会发出警告。这仅与自动化相关——如果你不使用自动化，则无需设置此变量。
运行状态直接显示在目标对话框中——pending / running / done / failed，失败时会显示原因。将目标切换回“进行中”即可重新启动运行。
每个状态的含义：
状态 | 说明 |
pending | 运行已排队，并在一分钟内发出（一次地图保存最多发送少量 webhook，因此不会有人一直等待） |
running | 智能体已开始处理工作，但尚未报告返回 |
done / failed | 智能体已报告结果，或运行已过期 |
如果在 KB_AGENT_TIMEOUT_MIN（默认 90）分钟内没有报告返回，看门狗会将运行标记为失败，并通知负责人和 AI 智能体管理器——这样目标绝不会无声地挂起。
最常见的失败原因：智能体不在注册表中或被禁用；它没有密钥；其地址指向私有网络但缺少 KB_ALLOW_PRIVATE_WEBHOOKS=1；或 webhook 无法访问。详细信息（包括连接错误）在服务器日志中——docker compose logs killbottleneck——这些信息有意不在应用中显示。
项目可以导出为 .json 文件并导入到其他位置——在同事之间和实例之间。在编辑器中：导出 → 导出 JSON，选择带名称或不带名称。导入位于“新建项目”按钮旁边的菜单中。
文件包含的内容：标题、描述、整个目标结构（包括状态、截止日期、每个步骤的执行者以及自动化请求）以及附加到其上的任务。“不带名称”选项会清除负责人和受指派者——自动化的名称保留，因为它们描述的是流程。
从 Asana 或 Trello 迁移： 同样的导入也接受 Asana 项目导出（CSV） 和 Trello 看板导出（JSON）。分区/列表成为地图分支，任务/卡片成为目标，子任务和检查清单成为子目标；状态（完成）、截止日期、描述以及——对于 Asana——受指派者会保留（此实例未知的电子邮件会被清除并计数）。所有内容都在浏览器的本地转换——不会调用 Asana 或 Trello。限制：每个文件 400 个项目。
不转移的内容：附件、评论、共享、归档和编号序列。导入总是创建一个由导入者拥有的新项目，重新生成目标标识符（因此不会与原始项目冲突），并且不与任何人共享任何内容，也不发送任何通知——你必须手动共享项目才能协作。分配给此实例上不存在的电子邮件地址的指派会被丢弃，导入会告诉你数量。
在头像菜单 → 外观中，每个人都可以选择皮肤：靛蓝（默认）、高对比度、终端或纸张。选择会保存到账户中，因此在每台设备、浅色和深色模式下以及简化的精简视图中都适用（那里的选择器位于页脚）。
自定义皮肤： 皮肤是一个小的 JSON 文件（kb-skin v1 格式）——一组颜色（HSL）、字体和圆角半径。外观对话框可以导出当前皮肤（对于内置皮肤，导出其定义——“拿去调整”）并导入其他人的皮肤，可以从文件导入或粘贴。按设计，它不是任意 CSS：值会通过客户端和服务器的白名单，因此共享的皮肤无法运行或发送任何内容。不会下载任何网络字体——只使用应用自带的字体和系统字体；未知字体无害地回退到栈中的下一个字体。
公司外观： 管理员在组织管理中设置实例范围的默认皮肤——它适用于所有尚未选择自己皮肤的人，包括登录屏幕。用户自己的选择始终优先。
在 v1 中，皮肤不会改变的内容（按设计）：状态颜色（红色/琥珀色/绿色 = 逾期/进行中/完成，在任何地方都保持相同的可读性）。地图导出（PNG/PDF）与屏幕一致——以当前皮肤和浅色/深色模式捕获，包括背景颜色；只省略背景装饰画。项目仪表板 PDF 和“我的一天”图像故意保持浅色，以便可以发送给任何人。
社区皮肤和开源皮肤编辑器：https://github.com/tengolabs/killbottleneck-skins——皮肤是免费数据（CC0），编辑器的许可证是 MIT。直接在浏览器中试用编辑器，无需安装：https://tengolabs.github.io/killbottleneck-skins/。
顶部的铃铛显示最近 20 条事件；带筛选和分页的完整列表位于 /notifications。通知设置也在这里，每个人都可以单独开启或关闭各类通知。
通知的发送场景：任务或目标被分配给你（包括在已存在的地图中）、对任务或目标的评论、项目与你共享、等待中的目标被解除阻塞、截止日期临近或错过（每天一封摘要，而不是每个项目一封）、自动化请求及其完成、自动化结束或失败，以及计时器被自动停止。
截止日期提醒在早上发送；使用 KB_DEADLINE_HOUR 设置小时（默认为 7，容器本地时间）。已读通知在 30 天后被清理。
电子邮件渠道已就绪，但只有在配置了 SMTP 后才会启用（见下文）——在此之前，它在设置中显示为灰色。
模板可以设置为自动从中创建项目（例如“每周一”或“每月第 N 天”）。为了让“周一”和创建时间与你的本地时间匹配，请在 .env 中设置：
TZ=Europe/Prague # your time zone (empty = UTC)
KB_AUTO_HOUR=5 # the hour (0–23) from which projects are created on a given day如果服务器在该小时处于关闭状态（它被关掉了），项目将在同一天的下一个更晚的小时创建——不会被跳过。
该时区适用于整个实例——对于分布在不同时区的团队，使用服务器的时区，而不是每个用户的时区。
重复的任务（完成时移动截止日期）特意使用 UTC 计算，因此跨越午夜或夏令时变更不会使它们偏移一天。
所有数据都存放在 ./pb_data 文件夹中（SQLite + 上传的文件）。使用附带的脚本进行备份：
./backup.sh # creates kb-backup-YYYY-MM-DD.tgz
./backup.sh restore FILE # restores data from a backup（手动操作：备份时复制 pb_data 文件夹；恢复时将其放回。）
一个实例 = 一个团队。角色：管理员（管理用户和角色、组织设置——名称和徽标）、经理（邀请成员，查看和管理所有任务）、成员（自己的任务和共享地图）。你可以从管理页面或直接从任务页面邀请人员。
第一个注册的账户成为管理员。如果实例可以从互联网访问，请在 .env 中设置 KB_SETUP_CODE——此后每次注册都需要该密钥，这样不是任何知道地址的人都能创建账户。把密钥交给你想放行的人；除此之外，管理员可以直接邀请用户（邀请不需要密钥）。空 = 无需密钥即可注册。
用户可以使用 Google 登录，而不必使用电子邮件和密码。设置方法如下：
在 Google Cloud Console 中，转到 API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID → 类型选择 Web 应用。
在已获授权的重定向 URI 下添加：https://YOUR-DOMAIN/api/oauth2-redirect
将客户端 ID 和客户端密钥复制到 .env 中：
KB_GOOGLE_CLIENT_ID=…apps.googleusercontent.com
KB_GOOGLE_CLIENT_SECRET=…docker compose up -d — “使用 Google 登录”按钮会自动出现。
空变量 = 关闭 Google 登录（不显示按钮）。在带有注册密钥的实例上，Google 登录仅适用于现有用户——无法通过 Google 创建新账户（没有输入密钥的途径），因此必须先使用密钥创建账户。
你可以将上传的文件或链接（Drive、OneDrive、SharePoint、特定电子邮件，以及 https:// 上的任何内容）固定到任何目标。链接有三个优点：不占用空间，团队始终打开当前版本，而且文件保存在你原来的位置。
上传文件可占用的空间由 KB_FILES_MB 控制——它适用于整个实例，而不是按项目：
值 | 行为 |
空 | 无限制（自托管的默认值——这是你自己的磁盘） |
数字 | 以 MB 为单位的限制，例如 |
| 禁用上传，附件仅限链接 |
托管实例以 0 运行：这样提供商不会保存你的文档，只保留指向它们的链接。链接必须以 http:// 或 https:// 开头——出于安全原因，网络驱动器路径（\\server\folder）无法从浏览器打开，因此应放在描述中。
SMTP 在 PocketBase 管理界面中配置：http://SERVER-IP:8090/_/ → 设置 → 邮件设置（超级用户账户在首次启动时创建——你会在 docker compose logs 中找到链接）。配置 SMTP 后：
新用户的邀请通过电子邮件发送（附带设置密码的链接）——如果没有 SMTP，管理员会看到临时密码，需要手动转交，
自助密码重置可用。
killBottleneck 本身通过 HTTP 运行——要从局域网外访问，请使用 VPN 或反向代理。以下是一个使用 Caddy 的示例（自动 HTTPS 证书）：
# Caddyfile
killbottleneck.your-domain.com {
reverse_proxy 127.0.0.1:8090
}通过 docker-compose.override.yml 将其添加到 compose 中（该文件不会被更新覆盖）：
services:
caddy:
image: caddy:2
ports: ["80:80", "443:443"]
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile
- caddy_data:/data
volumes:
caddy_data:HTTPS 还额外解锁了“我的一天”图片的分享…功能（Web Share API——你手机的原生分享对话框，无需第三方服务）以及将应用添加到手机主屏幕（service worker 仅在安全上下文中运行）。浏览器不允许在纯 HTTP 下使用这两项功能；在 HTTPS 域上它们会自动出现，无需任何配置。
killBottleneck 本身不会压缩响应（在 PocketBase 中无法安全地启用压缩，同时不影响 API 在拒绝超大请求体时的行为）。主要前端文件未压缩为 488 kB，gzip 后为 157 kB——在移动数据下，这是首次打开时感受最明显的差异。一行配置即可：
# Caddyfile
killbottleneck.your-domain.com {
encode gzip zstd
reverse_proxy 127.0.0.1:8090
}（在 nginx 中：gzip on; gzip_types application/javascript text/css;。在 Cloudflare 或类似服务后面，它会自动进行——无需配置任何东西。）
git pull # or download the new version
docker compose up -d --build数据库迁移会在启动时自动运行。在进行较大更新之前，值得先备份（./backup.sh）。
始终使用
--build：应用及其服务端逻辑已构建到镜像中，因此每次更新（代码更改、.env变量如TZ）后都需要docker compose up -d --build，而不仅仅是restart。
一次性操作，从最高 v0.11 版本更新时： 产品改名后，容器名为 killbottleneck 而不是 flowmap。旧容器占用 8090 端口，因此新容器无法启动——请先停止并移除旧容器：
docker rm -f flowmap
docker compose up -d --build你的数据保存在磁盘上的 ./pb_data 文件夹中，而不是容器内——你不会丢失任何数据。.env 中的 FLOWMAP_* 变量仍然有效，无需重写。
地图的公开链接仅共享地图画布——任务和任务评论无法通过它看到。
许可证：fair-code — 可持续使用许可证（请参阅下面的许可证部分）。
killBottleneck 不是严格（OSI）意义上的“开源”——我们对此直言不讳。它是 fair-code：源代码公开，你可以下载、运行、修改和使用它，对绝大多数人来说，它提供了与经典开源相同的益处。其中可以成为经典开源的部分是：皮肤编辑器（MIT）和整个皮肤库（包括其验证器，CC0）。
你可以获得完整的 killBottleneck——所有功能，包括团队协作和 AI 功能。 没有精简的“免费版”，也没有任何功能被付费墙封锁。你甚至可以免费自行驱动 AI——使用你自己机器上的模型（Ollama），或你自己的 API 密钥。我们托管的云服务（包含 AI）仅作为方便那些无处运行 killBottleneck 的用户而提供——这是便利，而不是条件。
你可以用 killBottleneck 做什么——免费且没有任何附加条件：
在你自己的电脑或服务器上自行运行——你的数据始终由你自己掌控。
在你的公司里完全用于你自己的工作和团队——没有任何限制。
接入你自己的 AI（本地模型或你自己的 API 密钥），或者完全不使用 AI。
按照你的需要随意修改。
围绕 killBottleneck 提供服务（设置、咨询、为客户端定制）。
我们保留的权利——以及让 killBottleneck 持续发展的方式：
托管 killBottleneck 并向用户收取访问费用。
将其白标化——以其他品牌名义发布。
将其作为付费服务转售。
这就是我们的商业模式——它让我们能够持续添加功能、修复错误，并让 killBottleneck 保持活力。我们积极鼓励你在 killBottleneck 基础上进行构建，并按照你的需要随意使用；只是不要把它变成一项相互竞争的托管服务。完整条款请参阅 LICENSE。第三方组件保留其原始许可证（MIT、Apache-2.0、BSD、…）——包含许可证文本的完整列表位于 THIRD-PARTY-LICENSES.md。
权利持有者： Tengo, s.r.o.，注册号 03339165，Dolní Valy 205, 262 72 Březnice，捷克共和国。想要将 killBottleneck 作为服务托管、以你自己的品牌发布或转售？许可证不允许这样做——但可以提供商业许可证，请写信至 licence@killbottleneck.com。
Česká verze této sekce je v README.cs.md.
由 Richard Pobrislo（LinkedIn、Ctrl+Alt+AI）一人构建——正因为是一个人，所以下面的支持渠道就是这个样子。
代码100% 由 AI 编写——Claude Fable 5、Claude Opus 5 和 Claude Opus 4.8——在人工指导下完成。每个版本在发布前都会经过自动化回归测试套件和手动点击测试；发布说明会列出哪些已经过验证，以及哪些故意未验证。
渠道 | 用途 |
GitHub Issues / Discussions | 错误和改进想法——公开进行，这样其他人也能看到 |
安全问题（不要在公开问题中）——请参阅 SECURITY.md | |
付费方案：托管实例 | |
商业许可——作为服务托管、白标、转售 | |
其他一切事项 |
我们不接受外部贡献者的代码（请参阅 CONTRIBUTING.md）——但我们接受想法和错误报告，而且非常欢迎。
killBottleneck 是 fair-code——整个产品（所有功能）都可以免费自托管，并将一直如此。如果它对你有帮助：
关注我们的 YouTube 频道，获取教程和 AI 资讯，
加入我们的 Discord。
Add a subtree of nodes to an existing map under parent_id (or under the apex when parent_id is omitted). A node is a goal; a node with an assignee (owner) OR a deadline IS a task — that is the only kind of task in killBottleneck (there is no separate task record; new work = new node). NOTE: this re-computes the layout of the whole map. Max 200 nodes per call. Returns the updated tree.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| map_id | Yes | ||
| parent_id | No | Existing node id to attach under; omit for apex |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure and does so well: it explicitly notes that the whole map layout is recomputed, caps calls at 200 nodes, returns the updated tree, and explains the node-vs-task model (owner/deadline makes a task). It does not cover failure modes or permissions, but the disclosed behaviors are valuable and non-obvious.
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 compact and front-loaded: the first sentence states the action and target, the second adds the crucial task-model semantics, and the third highlights warnings and return value. Every sentence earns its place with useful, non-redundant information.
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 nested item structure and lack of an output schema, the description provides essential operational details: return value (updated tree), limits (max 200 nodes), side effects (layout recomputation), and task-model rules. It is sufficient for an agent to invoke the tool confidently, even if it doesn't enumerate all field behaviors or error scenarios.
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 only 33%, so the description must compensate. It does by explaining parent_id semantics (omit for apex) and characterizing items as a subtree of nodes. Combined with the schema's field-level descriptions, the parameters are reasonably understandable, though map_id and the items array itself could use slightly more elaboration.
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 uses a specific verb-resource pair ('Add a subtree of nodes to an existing map') and clearly distinguishes this from siblings such as create_map (whole map) and update_node (existing node). It also clarifies placement under a parent_id or the apex, leaving no ambiguity about the tool's core function.
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 gives clear context for when to use it: adding nodes to an existing map under a specified parent or as apex nodes. It implicitly differentiates from update_node by focusing on adding a subtree. It does not explicitly list exclusions or alternatives, but the usage scenario is unambiguous enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new goal map from an outline. The map gets an apex (root goal) from title/apex_text; outline items become nested nodes. Layout is computed automatically. Max 200 nodes per call. Returns the created tree with node ids.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Map/project title | |
| outline | Yes | Top-level items under the apex, each may have children | |
| apex_text | No | Root goal statement, defaults to title | |
| description | No | Map description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description itself discloses key behavioral traits: layout is computed automatically, max 200 nodes per call, and the tool returns the created tree with node ids. This goes beyond a bare 'create' statement. It does not cover permission requirements or side effects like notifications, but for a creation tool the disclosed behaviors are meaningful and helpful.
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 three sentences, each earning its place: the first states the core purpose, the second explains the mapping of inputs to structure, and the third states constraints and return value. It is front-loaded with the action verb and completely free of filler.
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?
The description covers the essential operational context: input transformation, automatic layout, node limit, and the returned tree with ids. With no output schema present, this return value information is valuable. It does not elaborate on the many optional outline node fields, but those are fully documented in the input schema, so the description does not need to repeat them.
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 top-level parameter schema has 100% description coverage, so the baseline is 3. The description adds value by explaining how parameters relate to the output: title/apex_text become the apex, and outline items become nested nodes. It also introduces the 200-node limit and the return shape, which are not in the schema definitions.
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 uses a specific verb+resource construction ('Create a new goal map from an outline') and clearly distinguishes from siblings by focusing on creation as opposed to listing, retrieval, or modification. It also specifies the key transformation (outline to nested nodes) and the automatic layout behavior.
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 usage context by stating this creates a goal map from an outline, which strongly suggests the appropriate time to use it. It also gives a hard constraint (max 200 nodes per call) that helps decide feasibility. However, it does not explicitly mention alternatives like add_nodes for adding to an existing map, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an automation rule on a map: WHEN trigger fires (and optional AND conditions match) DO the actions in order. Rules run for changes made in the UI, via API and by agents alike. Structural limits: 50 rules per map, 10 actions, 20 conditions — there is NO monthly run quota. A rule applies only to future events, never retroactively. node_id scopes the rule to one node (required for schedule rules whose actions target a node).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable rule name (max 120 chars) | |
| map_id | Yes | ||
| actions | Yes | 1-10 actions, executed in order | |
| enabled | No | Default true | |
| node_id | No | Optional: scope the rule to one node of the map | |
| trigger | Yes | ||
| conditions | No | Optional AND chain checked on the trigger node |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It reveals important non-obvious traits: structural limits (50 rules per map, 10 actions, 20 conditions), the absence of a monthly run quota, forward-only applicability, and the node_id scoping requirement for schedule rules. This exceeds what one would expect from a typical description.
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 five sentences, each contributing unique value: the core purpose, cross-UI/API/agent behavior, limits/quota, forward-only semantics, and the crucial node_id requirement. It is front-loaded and free of fluff or redundancy.
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?
This is a complex, nested tool with no output schema, yet the description covers key constraints and behavioral rules (limits, quota, future events, node_id requirement) that an agent needs before invoking. It omits any mention of return values, which would be helpful given the absence of an output schema, but the overall context is sufficient for selection.
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 input schema already covers 71% of parameters with detailed descriptions, so the description need not repeat them. The added clarification that node_id is 'required for schedule rules whose actions target a node' is genuinely useful, but the description does not compensate for the remaining 29% of parameters lacking schema descriptions (e.g., map_id, enabled).
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 opens with 'Create an automation rule on a map' and explains the WHEN/DO structure, making the tool's purpose unmistakable. It clearly differentiates from sibling tools like list_rules, update_rule, and delete_rule by focusing on creation.
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 provides relevant context such as 'Rules run for changes made in the UI, via API and by agents alike' and 'applies only to future events, never retroactively,' which helps an agent understand when creating a rule is appropriate. However, it does not explicitly contrast with alternatives like update_rule or list_rule_templates, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a node INCLUDING its whole subtree. The apex (root) cannot be deleted and whole maps cannot be deleted via the API. Irreversible — read the map first and double-check the node id.
| Name | Required | Description | Default |
|---|---|---|---|
| map_id | Yes | ||
| node_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the most critical behaviors: recursive deletion of the whole subtree, irreversibility, and API limitations (cannot delete apex or whole maps). This goes beyond the bare 'delete' semantics and gives the agent essential warnings.
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 short sentences, each carrying distinct value: action/scope, restrictions, and irreversibility warning. No filler or repetition, with the most important information front-loaded.
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 two-parameter delete tool, the description covers the deletion scope, exclusions, and safety advice. It does not mention permissions or side effects on related entities like rules, but given the lack of an output schema and the tool's simplicity, it is reasonably complete. A score of 5 would require covering those potential side effects.
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%, so the description must compensate. While the parameter names 'map_id' and 'node_id' are self-explanatory, the description does not explicitly map them to their roles or add constraints like format/required prerequisites. The advice to 'double-check the node id' subtly indicates importance but adds no concrete parameter semantics.
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 action ('Delete a node') and specifies the scope ('INCLUDING its whole subtree'), distinguishing it from node update/add operations. It also clarifies constraints (apex and whole maps cannot be deleted), which reinforces the tool's purpose.
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 provides clear context by stating irreversible nature and advising to 'read the map first', implying the use of a read tool. It also gives explicit exclusions (apex, whole maps), but does not name alternative tools like update_node for replacement or get_map as the read step, so it falls short of explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an automation rule. Its run log stays (with the rule name snapshot). Irreversible.
| Name | Required | Description | Default |
|---|---|---|---|
| map_id | Yes | ||
| rule_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral traits: the run log persists with a snapshot of the rule name, and the operation is irreversible. This goes beyond the function name, though it could also mention effects on scheduled actions or related data.
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?
Two short sentences with no redundant content. The key points (deletion, log retention, irreversibility) are front-loaded and concise.
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 delete tool with two parameters, the description provides essential behavior (log retention, irreversibility) but is missing usage context such as how to find rule_id or map_id, and does not cross-reference related tools like list_rules or delete_rule_template to aid selection.
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 schema provides no descriptions for map_id and rule_id (0% coverage), and the description does not explain what these parameters refer to or how to obtain them. The tool name implies rule_id is the rule identifier, but map_id is ambiguous without 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 verb ('Delete') and the resource ('an automation rule'), and adds a specific detail about run log retention, making it distinct from sibling tools like delete_rule_template.
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 on when to use this tool versus alternatives. It doesn't mention that list_rule_templates or delete_rule_template should be used for templates, and there are no exclusions or context cues beyond the action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a rule template from the library (author or admin only). Rules already created from it are independent copies and stay untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| template_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It openly states the permission prerequisite and that existing rules are unaffected (no cascade). It does not detail whether deletion is permanent, but the verb 'delete' implies destruction. This is appropriate for a simple delete 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 two concise sentences with no fluff. The verb and object are front-loaded, and the second sentence adds valuable clarification about side-effects.
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 tool with one parameter, no output schema, and no annotations, the description covers the essential aspects: purpose, permission, and side-effect behavior. It could mention whether deletion is reversible, but for a delete operation this is generally understood.
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 schema has one parameter (template_id) with no description, and schema description coverage is 0%. The tool name and description make the purpose of template_id obvious, but the description does not explicitly define the parameter's format or source. It partially compensates but leaves some room for interpretation.
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 action ('Delete a rule template from the library') with a specific resource and scope. It distinguishes itself from sibling tools like delete_rule (which deletes rules) and save_rule_template (which manages templates).
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 provides usage context by noting the permission requirement ('author or admin only') and clarifies a key implication ('Rules already created from it are independent copies and stay untouched'). It does not explicitly mention alternatives, but the distinction from sibling tools is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one map as an indented tree with node ids, statuses ([✓] done, [~] in progress, [ ] todo), deadlines and owners. Always call this before modifying a map you have not read yet.
| Name | Required | Description | Default |
|---|---|---|---|
| map_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly indicates this is a read operation, describes the output content, and implies safety precondition (read before modify). It does not detail edge cases or permissions, but for a straightforward read tool the description is sufficient.
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 two sentences: the first states the purpose and output format, the second gives a usage directive. Every word earns its place, and it is entirely front-loaded with no filler.
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 (one parameter, no output schema), the description fully covers the essentials: what the tool does, what it returns, and when to invoke it. The safety instruction also adds important operational context, making the description complete for this 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?
The schema has 0% description coverage, so the description must compensate for map_id. The phrase 'Read one map' clarifies that map_id identifies the specific map to read. This gives enough semantic context for a single parameter, though it does not provide format or example values.
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 uses a specific verb 'Read' and resource 'one map', and clearly details the output as an indented tree with node ids, statuses, deadlines, and owners. This differentiates it from sibling tools like list_maps (which lists maps) and get_org_structure (which reads organization structure).
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 the tool: 'Always call this before modifying a map you have not read yet.' This provides a clear context for usage, though it does not explicitly name alternatives or exclusions like using list_maps for a high-level map list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the organization structure (the org map): positions and functions with node ids, holders and deputies. Use the node ids as dynamic rule targets "position:" / "deputy_of_position:". Read-only — holders and deputies are appointed by an admin in the app.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description states 'Read-only' and explains that holders and deputies are appointed by admin. This discloses the non-mutating nature and external data source. However, it does not describe return format or pagination, though for a simple read this is acceptable.
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?
Two concise sentences, front-loaded with purpose, then usage note. No fluff.
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 zero-parameter read tool with no output schema, the description covers purpose, read-only nature, and dynamic node id usage. It is reasonably 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?
No parameters exist, so baseline is 4. The description adds meaning about node ids but no parameters to document.
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 'Read the organization structure (the org map): positions and functions with node ids, holders and deputies.' This is a specific verb and resource, but it does not explicitly distinguish from sibling tool get_map, despite the parenthetical '(the org map)' which could cause confusion.
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 over alternatives. It provides usage of node ids for rule targets but no comparison with get_map or other read tools. This is essentially no guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List goal maps in the killBottleneck account (id, title, node count, last update). Use archived=true to list archived maps instead.
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the scope (killBottleneck account), the returned fields, and the behavior of the archived flag (default vs archived). It doesn't explicitly state read-only, but 'List' inherently conveys non-mutating behavior, and the details about fields and filtering add meaningful 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?
The description is two sentences, front-loaded with the main purpose, and includes the only parameter guidance without any fluff. 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 list tool with one optional parameter and no output schema, the description covers all essential aspects: what is listed, account scope, returned fields, and filtering option. No pagination or rate limit details are necessary for this level of 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?
The schema only defines 'archived' as a boolean with no description (0% coverage). The description compensates by explaining what archived=true does ('list archived maps instead'), implicitly clarifying that false (or omitted) lists non-archived maps. This is sufficient for the single parameter.
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 function: 'List goal maps in the killBottleneck account' with specific details on returned fields (id, title, node count, last update). It distinguishes from siblings like get_map (singular fetch) and create_map (creation).
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?
It provides clear context for when to use the tool (listing maps in the named account) and gives explicit guidance for the archived parameter ('Use archived=true to list archived maps instead'). It does not explicitly name alternative tools for other use cases, but the 'instead' implies default behavior, which is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the run log of a map's automation rules (newest first, max 100): what fired, on which node, ok/failed/skipped and what the actions did. skipped = a safety stop (rule chain depth or per-save cap), detail says which.
| Name | Required | Description | Default |
|---|---|---|---|
| map_id | Yes | ||
| rule_id | No | Optional: only runs of this rule |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates a read operation ('Read'), defines output semantics (ok/failed/skipped), and explains the non-obvious 'skipped' status as a safety stop with a detail field. This goes beyond minimal transparency, though it does not mention potential edge cases like empty results or rate limits.
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 two sentences, front-loaded with the action ('Read the run log'), and each phrase provides useful information: ordering, limit, output fields, and status explanation. No filler or redundancy.
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, the description adequately explains what the tool returns: recent run logs with node, status, action outcomes, and special handling of 'skipped'. It covers the essential behavior for a read-only log tool, though it could mention the response format (e.g., array) or pagination limits beyond 'max 100'. Overall, it is reasonably complete for the 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?
The input schema documents 'rule_id' as optional and its purpose ('only runs of this rule'), covering 50% of parameter semantics. The description adds contextual meaning by referring to 'a map's automation rules', helping to clarify that 'map_id' is the map identifier. However, it does not explicitly name the parameters or add detail beyond the schema for 'map_id', making it adequate but not exceptional.
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 starts with 'Read the run log of a map's automation rules', which uses a specific verb ('Read') and resource ('run log'), making the tool's purpose unambiguous. It also specifies key details like ordering (newest first), limit (max 100), and output fields (node, ok/failed/skipped, actions), clearly distinguishing it from sibling tools like list_rules.
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 it (when you need to inspect rule run history), but it does not explicitly state when not to use it or name alternatives. For example, it does not contrast with list_rules or explain that this is for execution history rather than rule definitions. The context is clear but lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List automation rules of a map: id, name, enabled, scope node, trigger, conditions, actions, last_fired and last_error (a non-empty last_error means the rule is misconfigured and its owner was notified).
| Name | Required | Description | Default |
|---|---|---|---|
| map_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It goes beyond a simple 'list' statement by explaining the meaning of last_error (misconfiguration and notification), which is useful context. It does not mention side effects or permissions, but the read-only nature of listing is inherent.
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, dense sentence that efficiently lists the tool's purpose, the fields returned, and the special meaning of one field. There is no fluff, and every part 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 listing tool with one parameter and no output schema, the description is largely complete: it specifies the resource scope, the fields returned, and the significance of last_error. It lacks details about pagination, sorting, or whether all rules (enabled/disabled) are included, but these are not critical for a basic listing operation.
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 sole parameter map_id is required and has no schema description (0% coverage). The description mentions 'of a map', which contextually identifies map_id as the map identifier, but it does not explicitly define the parameter or its format. This provides minimal compensation for the missing schema documentation.
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 uses a specific verb ('List') and resource ('automation rules of a map'), clearly distinguishing it from sibling tools like list_rule_runs and list_rule_templates. It also lists the exact fields returned, making the purpose explicit.
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 provides clear context by specifying the scope ('of a map') and listing the returned fields, which implies it is for inspecting rule configurations. However, it does not explicitly mention alternatives or when not to use it, though the purpose is distinct enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the instance-wide library of rule templates (shape of a rule without a map or node scope). To use one, read it and call create_rule on the target map with its trigger/conditions/actions — the created rule is an independent copy.
| 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 carries the full burden. It clarifies the template shape and the copy relationship with create_rule, but does not explicitly state read-only behavior, pagination, or return format. The verb 'List' implies read-only, but other behavioral details are missing.
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?
Two concise, front-loaded sentences with no fluff. The first sentence states the purpose, the second explains usage, earning its place.
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 parameterless list tool, the description covers what the tool returns (rule templates without scope) and how to use the result (create_rule). No output schema exists, but the description explains the key fields (trigger/conditions/actions) and the copy semantics.
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 zero parameters, so schema coverage is 100% and there is no param info to add. The description enriches understanding by explaining what a template contains (trigger/conditions/actions), which aids interpretation of the output.
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 uses a specific verb 'List' with a clear resource 'instance-wide library of rule templates' and explicitly differentiates from siblings by noting templates are 'without a map or node scope'. This makes it distinguishable from list_rules and other related 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?
It provides explicit usage flow: 'read it and call create_rule on the target map with its trigger/conditions/actions', indicating when to use this tool. However, it does not explicitly name alternative tools for when not to use it, so it falls short of full exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a rule shape into the instance-wide template library (create, or update with template_id — only the author or an admin may update). Templates carry no map and no node scope; create_subnodes may only use parent=trigger_node. Template names are unique.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Unique template name (max 120 chars) | |
| actions | Yes | ||
| trigger | Yes | ||
| conditions | No | ||
| template_id | No | Update an existing template (author or admin only); omit to create |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It discloses key behaviors: templates have no map/node scope, create_subnodes restricted to parent=trigger_node, names must be unique, and update permissions. This is good 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?
Three sentences, all high-signal: action+scope, key constraints, and uniqueness. No fluff or repetition of schema details.
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 rich schema and complexity (nested actions, triggers, conditions), the description provides the essential context: what templates are, permission model, uniqueness, and a critical behavioral constraint. It doesn't explain return values, but no output schema is present. Minor gap: no statement about validation or failure modes.
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 mentions template_id for updates and name uniqueness, but those are already in the schema. The schema itself provides detailed descriptions for trigger, actions, and conditions, so the description does not need to compensate heavily. Baseline 3 is appropriate.
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 uses the specific verb 'Save' and clearly identifies the resource: 'rule shape into the instance-wide template library.' It explicitly distinguishes create from update and notes templates are not rules, differentiating from siblings like create_rule/update_rule.
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?
It provides clear context: create or update with template_id, and that only the author or admin may update. It implies this is for reusable templates (no map, no node scope) rather than instance rules, but does not explicitly name alternatives like create_rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields of one node: title, status (todo/in_progress/done), description, deadline (YYYY-MM-DD, empty string clears), owner (e-mail, empty string clears), wait_for_children, colour, who performs it (executor_kind / executor_name) and the automation wish (automation_wanted / automation_note). Marking status done may unblock waiting nodes, notify their owners and trigger automations on them.
| Name | Required | Description | Default |
|---|---|---|---|
| color | No | Node colour as #rrggbb, empty string clears | |
| owner | No | Accountable PERSON (e-mail). Stays a human even for AI/cron steps — this is who gets notified. Empty string clears. | |
| title | No | ||
| map_id | Yes | ||
| status | No | ||
| node_id | Yes | ||
| deadline | No | ||
| description | No | ||
| executor_kind | No | Who performs the step. Default "human". | |
| executor_name | No | Which automation handles this step, e.g. "n8n backup" — a record of what exists, not an instruction. Empty string clears. | |
| automation_note | No | Optional context for the automation wish. Empty string clears. | |
| automation_wanted | No | Wish that this step were automated; notifies the AI agent managers. | |
| wait_for_children | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals important side effects: 'Marking status done may unblock waiting nodes, notify their owners and trigger automations on them.' It also explains clearing behavior for several fields. However, it does not clarify whether omitted fields remain unchanged or are reset, which is a key behavioral gap given no annotations to fill it.
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?
Two sentences, no redundancy. The first sentence efficiently lists the fields, the second explains the done-status side effects. Every phrase 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?
Given the tool's complexity and the absence of annotations and output schema, the description covers most critical aspects: updatable fields, their semantics, and side effects. The main missing element is explicit partial-update semantics and any required permissions.
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?
With schema coverage at 46%, the description compensates by listing and explaining all 13 parameters, including enum values for status, deadline format (YYYY-MM-DD), owner email semantics, and clearing with empty strings. It adds meaning beyond the sparse schema for fields like wait_for_children and automation_wanted.
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 opens with 'Update fields of one node' and enumerates all updatable fields, clearly distinguishing this from sibling tools like add_nodes and delete_node by specifying the update action.
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 provides a clear usage context: updating an existing node's fields. However, it does not explicitly state when to avoid this tool in favor of alternatives (e.g., add_nodes for creation, delete_node for removal), so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an automation rule. Pass only enabled to toggle it on/off; otherwise pass the FULL new shape (name, trigger, actions, optional conditions/node_id) — partial field edits are not merged. Edits apply to future events only and clear the rule's error state.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| map_id | Yes | ||
| actions | No | ||
| enabled | No | ||
| node_id | No | ||
| rule_id | Yes | ||
| trigger | No | ||
| conditions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses important behavioral traits: partial field edits are not merged, edits apply to future events only, and the rule's error state is cleared. This goes beyond the minimum but doesn't cover every edge case (e.g., not found behavior, permissions), so it earns a 4 rather than 5.
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 three sentences long, front-loaded with the tool's core purpose. Every sentence adds value: the first defines the action, the second explains the two usage modes and the non-merging rule, and the third notes the temporal scope and side effect. No filler or redundancy.
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 (8 parameters, nested objects) and lack of output schema or annotations, the description provides a solid high-level context: update modes, required fields, and side effects. It doesn't explicitly mention how to obtain the rule_id or what the response is, but these are relatively self-evident given the schema and sibling tools. The description is complete enough for correct usage.
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 schema's top-level properties have no descriptions (0% coverage), so the description must compensate. It adds meaning by explaining that `enabled` can be used alone as a toggle, while a full update requires `name`, `trigger`, `actions`, and optionally `conditions`/`node_id`. This clarifies the parameter relationships and the non-merge semantics, which the schema alone doesn't convey.
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 with a specific verb ('Update') and resource ('automation rule'). It distinguishes itself from sibling tools by emphasizing the update action and the unique toggle behavior. The phrase 'automation rule' is precise and unambiguous.
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 gives explicit usage guidance by separating the toggle mode ('pass only `enabled`') from the full-replacement mode ('otherwise pass the FULL new shape'). It also warns that partial edits are not merged. While it doesn't explicitly name alternatives like create_rule, the update vs create distinction is implicit and the mode selection is clear.
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. Dates show when Glama detected each change.
v0.33.2-betaadd_nodescreate_mapcreate_ruledelete_nodedelete_ruledelete_rule_templateget_mapget_org_structurelist_mapslist_rule_runslist_rule_templateslist_rulessave_rule_templateupdate_nodeupdate_ruleEach tool targets a distinct resource and action. Map tools (list_maps, get_map, create_map, add_nodes, update_node, delete_node) are clearly separated from rule tools (create_rule, list_rules, update_rule, delete_rule, list_rule_runs) and template tools (list_rule_templates, save_rule_template, delete_rule_template). No two tools appear to do the same thing.
All tool names follow a consistent verb_noun pattern in snake_case, with verbs like list, get, create, add, update, delete, save. The nouns are appropriately pluralized for collections and singular for single entities, creating a predictable and readable API surface.
15 tools is well within the ideal 3-15 range. The count is justified by the dual domain of map management and automation rule management, with each tool serving a distinct purpose and no apparent bloat.
The tool surface covers the core lifecycle for maps (create, read, update nodes, delete nodes) and automation rules (create, read, update, delete, runs, templates), plus organization structure. The only notable gaps are lack of map-level update/delete, but these appear to be intentional API limitations rather than oversights.
End-to-end agent-managed company brain. Docs, diagrams, plans, Knowledge Graph. Lean & affordable.
Self-hostable shared brain for you and your AI agents — docs, flows, meetings, decisions, rationale
Turn AI conversations into visual knowledge maps. Create, connect, search, and organize thoughts.
Company brain for AI agents — temporal knowledge graph search, exploration, and durable memory.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/tengolabs/killbottleneck'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
