This server lets an AI assistant work with a killBottleneck instance: read and build goal maps, manage goals/tasks and their owners, deadlines and statuses, and configure automation rules and organizational targets — all through MCP tools.
Maps: list maps, read a map as an indented tree (statuses, deadlines, owners), create new maps from an outline, and add whole subtrees of nodes.
Goals/tasks: update individual nodes (title, status, description, deadline, owner, colors, executor, automation wish) and delete a node with its subtree.
Automation rules: create, list, update, and delete rules with triggers (status change, unblocked, deadline approaching, node created, file uploaded, schedule), conditions, and actions (set status/owner/deadline, move node, create subnodes, notify, run agent).
Rule runs & templates: inspect a map's rule run log, list instance-wide rule templates, save and delete templates.
Organization: read the org structure and use position/deputy node ids as dynamic rule targets.
🧪 Public beta. killBottleneck is feature-complete and in beta — the cloud and the self-hosted version alike; it is one and the same app. What we are testing here is the self-hosted side: installation, reverse proxies, your own SMTP, upgrades. Install it (Quick start below), try to break it, and tell us what happened: bugs → Issues, ideas → Discussions. v1.0 ships when the beta goes quiet.
A visual picture of your projects, your company and its processes — goal maps that people and AI agents work on together, entirely on your own server: your data never leaves the company. Open in the spirit of open source, just without the right to resell it as a hosted service — see License.
Nothing here phones home. On a default install the server sends no request anywhere, and the app loads nothing from a third-party CDN — fonts included, they are served from your own instance. Everything that could leave your network is something you switch on:
Outbound request | When it happens | Turn it off |
GitHub Releases API | Version check, from the user's browser — not the server |
|
The AI endpoint you configured | Only with |
|
Google (sign-in, Drive picker) | Only when you configure | leave those empty (default) |
There is no telemetry, no analytics and no licence check.
Who performs a step: a person, or an automation — includes the webhook contract for your own agents
Appearance (skins) · Notifications · Time zone and recurring templates
Data and backup · Team · Registration and the registration key
All you need is Docker. Then:
cp .env.example .env # optional — the defaults are fine
docker compose up -dkillBottleneck runs at http://SERVER-IP:8090. Colleagues on the local network just open it in a browser.
The first user to register automatically becomes the administrator. Everyone else can register themselves, or the administrator invites them from Administration (this creates an account with a temporary password to hand over).
Related MCP server: stablebaseline-mcp
A full goal map editor (nodes, edges, statuses, notes), multiple maps per user, comments on goals, sharing maps with colleagues (read / edit), public maps, export to image/PDF.
The “My day” panel (both the home page and the Tasks page): a clickable overview of overdue / today / within a week / blocking others, computed live from your data; name days next to the date; a portrait PNG export for mobile — both full (with task names) and anonymous (names redacted, for social media). Over HTTPS you also get Share… (your phone's native Web Share dialog, no third-party service involved).
Time tracking: a ⏱ timer in the top bar (one click starts an “empty” measurement — the project/client/goal is assigned while it runs or afterwards), a timer on every task and every goal in a map (measuring never changes a status — it is purely supplementary), a left-hand “Time tracking” panel with the records (from–to, retroactive assignment), a “Time worked” dialog in the user menu (today/this week, broken down by project and client), a client registry (project→client, so time adds up per client too), and auto-stop for forgotten timers after 12 h. Inbox behaviour: an unassigned measurement stopped with a note (e.g. “call with the client”) also saves itself as an idea in your stash.
The same instance, opened on a phone, switches to a simplified view: today's tasks, tick them off, add one, and read messages — no map canvas to fight with on a small screen. You can switch back to the full view at any time, and the app can be added to the home screen (over HTTPS) so it behaves like a native one.
More in the Simplified view guide.
The AI advisor (draft a map from a goal, expand branches, chat about a map, AI project summary,
suggest tasks from a goal, a map from text/voice) is switched on in .env via KB_AI_PROVIDER:
openai — any OpenAI-compatible API: OpenAI, OpenRouter, Groq, Mistral, Together,
or your own vLLM / LM Studio / llama.cpp / liteLLM proxy. Set
KB_AI_URL=https://openrouter.ai/api/v1 (the base address, usually ending in /v1),
KB_AI_TOKEN=<your API key> and KB_AI_MODEL=<exact model name>. Dictation works
through the same service; your provider bills you for the requests.
api — a remote AI service compatible with the killBottleneck API contract: enter the
address and token you got from your provider. No GPU of your own and no maintenance.
ollama — your own local model: install Ollama, pull a model
(ollama pull gpt-oss:20b) and set
KB_AI_URL=http://IP:11434 + KB_AI_MODEL=gpt-oss:20b.
Everything runs on your side, no data leaves your network. (Basic prompts; voice
transcription is not included.)
custom — your own endpoint honouring the same API contract
(the contract is written down here).
When AI is used, map data is sent to the endpoint you chose; with none (the default) nothing
ever leaves your server.
Daily AI encouragement (a line in the My day panel): 1–2 sentences prioritising “what
blocks others → overdue → today”, with the occasional proverb. It is generated in the morning
by a cron job (KB_SUMMARY_HOUR, default 6) only for accounts that signed in within the last
KB_SUMMARY_ACTIVE_DAYS days (default 14, 0 = everyone); for the rest it is generated when
they open the app. Optionally a separate (smaller/faster) model just for the summaries:
KB_SUMMARY_PROVIDER/URL/MODEL/TOKEN — without them the general AI configuration above is
used. The panel works in full without AI, just without this one line. The AI never enumerates
task lists (those are computed from your data and clickable) and task names are sanitised
before they go into the prompt.
killBottleneck ships with a built-in MCP server (mcp/): connect your AI assistant to your
own instance and maps get built conversationally — “make a map out of these meeting notes”,
bulk edits, ticking off what's done. It works the same for self-hosted and hosted instances,
only the address differs.
In the app: user menu → API keys → a new key with the Read and write scope (Read only is enough for read access). The token is shown only once. Recommended: give the key an expiry and revoke it once you stop using it.
Nothing to install — the server is on npm as
killbottleneck-mcp, so npx fetches
it on first use. (Prefer running it from this repository? cd mcp && npm install and use
node /absolute/path/mcp/index.js instead of the npx command below.)
Register it with your assistant:
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_..."
}
}
}
}Tools (17): list_maps, get_map, create_map, add_nodes, update_node, delete_node,
list_people, get_portfolio, get_org_structure and the rule tools (create_rule, list_rules,
update_rule, delete_rule, list_rule_runs, list_rule_templates, save_rule_template,
delete_rule_template). A goal with an assignee or a deadline IS a task — there are no
separate task records. Assigning an owner through the API shares the map with that person as a
collaborator, so the work shows up in their My Day (the response lists who was shared with).
Remote, without anything local: every instance also serves MCP directly at /mcp
(Streamable HTTP, same keys, same tools) — claude mcp add --transport http killbottleneck https://your-instance/mcp --header "Authorization: Bearer kb_user_..."; the claude.ai connector
signs in through OAuth. Details: MCP server.
Security: a key acts as its owner — it sees and edits exactly what the owner can in the app,
shared and team maps included (edit/own = full write; work and read = only the status of
the owner's own nodes, exactly like ticking off in the app); it never reads the account's role, so an admin's key cannot see
anyone's private map, and someone else's public map is not reachable either (404). Administration,
AI settings and users are never reachable. Writes can add/edit/delete goals and tasks; a whole map cannot be deleted through the API, and neither can the apex of
a map. Limits: 120 reads + 30 writes per minute per key, at most 200 nodes per call, at most 20
keys per account. Working alongside an open editor is handled by conflict detection (the editor
offers to reload, the assistant reloads the map itself). Note: add_nodes re-runs the layout
of the whole map. MCP tool output is in English (assistants always understand it); server error
messages arrive in the language of your account.
For every goal in a map you can say whether a person or an automation does it. Whether there is an AI agent or a scheduled cron job behind that automation is not your problem — whoever builds it knows.
Important: the responsible person for a goal is always a human. Even for an automated step there is someone accountable, who gets the notifications and whose “My day” the goal counts towards. The automation does the work; a person is answerable for it.
For an automated step you also record which automation does it — this is a record of how things are today (“n8n already does this step for us”), not a command. That is what makes it visible at a glance which parts of the map are done by people and which by machines.
On any goal you can tick a request to have the step automated, and optionally add a sentence explaining why. The request goes to the AI agent manager — a separate flag on a user (User management → AI manager), independent of their role; both an administrator and an ordinary member can hold it alongside their role.
Once the manager builds the automation and records it on the goal, the request tidies itself away and the requester gets a message that their goal is now automated. The full cycle:
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"You can upload files to any goal. On a goal with an automation, uploading a file starts it right away — instead of filling in a form somewhere else you simply attach whatever needs processing (typically subtitles, source material, an export).
Attachments are visible only to people with access to the project. The files are protected: the link alone gives nothing away.
The AI agent manager (or an administrator) maintains a directory of automations under AI agent registry: name, webhook address, signing secret, enabled/disabled. On a goal the automation is picked by name — team members never see the address or the secret. When the name on a goal matches an agent in the registry, killBottleneck can start it itself.
Who may start it. Each agent can carry a list of allowed e-mail addresses. An empty list means the automation can be started by anyone who can edit any map — inside a company that is usually fine, but restrict it on an instance you let contractors into: whoever may edit a map can otherwise start any of your n8n workflows and feed their own text into it (the goal's title and description go to the agent in the payload).
Attachments are capped at 200 files per project, plus an optional space limit for the WHOLE
instance (KB_FILES_MB in MB; 0 = uploads disabled entirely, empty = no limit — set one on a
shared disk so a hosted instance cannot fill it up). ⚠️ The former FLOWMAP_MAP_FILES_MB was a
PER-PROJECT quota defaulting to 200 MB — if you have it set it still applies to you, but
without it there is now NO space limit at all.
An automation starts when:
an attachment is uploaded to the goal, or
the goal's turn comes — it was waiting for its sub-goals and they have all just been completed, or
somebody manually switches the goal to “in progress” (this is also how you retry a failed run)
A running automation will not be started a second time until it reports back or expires.
The outgoing request (POST to the agent's address, with an X-Signature header =
HMAC-SHA256 of the entire body using the agent's secret):
{
"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"
}The agent downloads files using its run token; files_url is a live listing, so it also
sees attachments added while it is running. The token expires once the result is reported.
Reporting back (POST to callback_url, no login — the run token authenticates it):
{ "run_id": "…", "run_token": "kbr_…", "status": "done", "result": "Translated into 3 languages" }status is done or failed. A token is valid for one goal and one report — a second
call with the same token will not go through.
After done the goal is completed, and that sets the rest of the process in motion: the
following goal is unblocked and the person responsible for it is notified that they can start.
If that following goal is automated as well, it starts straight away — so the steps chain
themselves.
Set the address the agent should call back on. callback_url is assembled by the server,
not the browser — without configuration it uses PocketBase's “Application URL”, which after
installation is http://localhost:8090. An agent running on another machine would therefore
call itself, and the run would hang until it timed out. In .env:
KB_PUBLIC_URL=https://killbottleneck.yourcompany.com
KB_AGENT_TIMEOUT_MIN=90Any address the agent can reach will do — on a self-hosted setup http://192.168.1.10:8090 on
the LAN is perfectly fine. Hosted instances (killBottleneck Cloud) have this set automatically.
Is your n8n on the same network? The webhook address is called by the server, which makes
it a classic internal-network scanning vector — so by default killBottleneck refuses to call
private addresses (10.x, 192.168.x, 172.16–31.x, localhost, cloud metadata). On a
self-hosted setup where n8n runs next to killBottleneck, allow it:
KB_ALLOW_PRIVATE_WEBHOOKS=1Without this the run is marked failed and the AI agent manager gets a message explaining why. An agent must have its secret filled in — without one the request would be signed with an empty key and the recipient would have no protection whatsoever, so killBottleneck rejects such a run outright. The currently effective address is always shown at the bottom of the AI agent registry, which warns you when it points at localhost. This only concerns automations — if you do not use them, you do not need to set this variable.
The state of a run is visible right in the goal's dialog — pending / running / done / failed, with the reason on failure. A run is restarted by switching the goal back to “In progress”.
What each state means:
State | What is happening |
pending | the run is queued and goes out within a minute (a single map save sends at most a handful of webhooks, so nobody is left waiting) |
running | the agent has picked up the work and has not reported back yet |
done / failed | the agent reported a result, or the run expired |
A run that does not report back within KB_AGENT_TIMEOUT_MIN (default 90) minutes is marked
failed by a watchdog, which notifies both the responsible person and the AI agent managers — so
a goal never hangs silently.
The most common causes of failure: the agent is not in the registry or is disabled; it has no
secret; its address points into a private network and KB_ALLOW_PRIVATE_WEBHOOKS=1 is missing;
or the webhook is unreachable. The details (including connection errors) are in the server log —
docker compose logs killbottleneck — they are deliberately not surfaced in the app.
A project can be exported to a .json file and imported somewhere else — between colleagues
and between instances. In the editor: Export → Export JSON, choosing with names or
without names. Import lives in the menu next to the “New project” button.
What the file contains: the title, the description, the whole goal structure (including statuses, deadlines, who performs each step and automation requests) and the tasks attached to it. The “without names” option clears both the responsible people and the assignees — the names of automations stay, since they describe the process.
Switching from Asana or Trello: the same import also accepts an Asana project export (CSV) and a Trello board export (JSON). Sections/lists become map branches, tasks/cards become goals, subtasks and checklists become child goals; statuses (done), due dates, descriptions and — for Asana — assignees carry over (e-mails unknown to this instance are cleared and counted). Everything is converted locally in the browser — nothing calls Asana or Trello. Limit: 400 items per file.
What is not transferred: attachments, comments, sharing, archiving and numbering series. An import always creates a new project owned by whoever imports it, regenerates the goal identifiers (so it does not collide with the original) and shares nothing with anybody and sends no notifications — you have to share the project manually to collaborate on it. Assignments to e-mail addresses that do not exist on this instance are dropped, and the import tells you how many.
In the avatar menu → Appearance everyone picks a skin: Indigo (default), High contrast, Terminal or Paper. The choice is saved to the account, so it applies on every device, in both light and dark mode, and in the simplified lite view too (the picker there sits in the footer).
Custom skins: a skin is a small JSON file (kb-skin v1 format) — a set of
colors (HSL), fonts and corner radius. The Appearance dialog can export the
current skin (for a built-in, its definition — "take it and tweak it") and
import someone else's, from a file or by pasting. By design it is not
arbitrary CSS: values pass a whitelist on both the client and the server, so a
shared skin cannot run or send anything. No web fonts are ever downloaded —
only fonts bundled with the app and system fonts are used; an unknown font
harmlessly falls back to the next one in the stack.
Company look: an administrator sets the instance-wide default skin in the organization admin — it applies to everyone who has not picked their own, including the login screen. A user's own choice always takes precedence.
What a skin does not change in v1 (by design): status colors (red/amber/green = overdue/in progress/done stay readable everywhere the same). Map export (PNG/PDF) is true to the screen — captured in the active skin and light/dark mode, including the background color; only the backdrop artwork is left out. The project dashboard PDF and the "My day" image deliberately stay light so they can be sent to anyone.
Community skins and the open source skin editor: https://github.com/tengolabs/killbottleneck-skins — skins are free data (CC0), the editor is MIT. Try the editor right in your browser, nothing to install: https://tengolabs.github.io/killbottleneck-skins/.
The bell in the header shows the last 20 events; the full list with filters and paging is at
/notifications. That is also where notification settings live, so everyone can switch
individual types on or off.
Notifications are sent for: a task or a goal being assigned to you (including in a map that already exists), a comment on a task or a goal, a project being shared with you, a waiting goal being unblocked, an approaching or missed deadline (one digest per day, not one per item), an automation request and its fulfilment, an automation finishing or failing, and a timer being stopped automatically.
Deadline reminders are sent in the morning; set the hour with KB_DEADLINE_HOUR (default 7,
the container's local time). Notifications you have read are cleaned up after 30 days.
The e-mail channel is ready but only switches on once SMTP is configured (see below) — until then it is greyed out in the settings.
A template can be set up so that a project is created from it automatically (e.g. “every
Monday” or “on the Nth day of the month”). For “Monday” and the time of creation to match your
local time, set this in .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 dayIf the server slept through that hour (it was switched off), the project is created at the next later hour of the same day — it is not skipped.
The zone applies to the whole instance — for a team spread across zones the server's zone is used, not each user's.
Recurring tasks (moving the deadline on completion) deliberately compute in UTC, so crossing midnight or a daylight-saving change does not shift them by a day.
All data lives in the ./pb_data folder (SQLite + uploaded files). Use the bundled script to
back it up:
./backup.sh # creates kb-backup-YYYY-MM-DD.tgz
./backup.sh restore FILE # restores data from a backup(By hand: to back up, copy the pb_data folder; to restore, put it back.)
Backups can be encrypted: set KB_BACKUP_PASSPHRASE and the script writes
kb-backup-….tgz.gpg (GPG, AES-256). restore accepts encrypted as well as
older plain archives. Keep the passphrase off the server — without it nobody
can read the backup.
My account has Download all my data: one JSON file (killbottleneck.export/1) with every
project you can see — each in the same shape as a single map export, so it imports elsewhere —
plus tasks, rules, comments, change log, attachment list, idea stash, time entries, external
contacts and notifications. It works even after a trial has expired, and Upload data from an export brings the projects (with rules) and the idea stash back into another instance. Self-hosters additionally
have ./backup.sh, which backs up the whole pb_data folder including uploaded files.
One instance = one team. Roles: Administrator (manages users and roles, organization settings — name and logo), Manager (invites members, sees and manages all tasks), Member (their own tasks and shared maps). Administrators and managers also get Organization in the top bar — the view from above across team and shared projects (private projects are never counted). You can invite people from Administration or straight from the Tasks page.
The first account to register becomes the administrator. If the instance is reachable from
the internet, set KB_SETUP_CODE in .env — every registration then requires that key, so not
just anyone who knows the address can create an account. Hand the key out to the people you
want to let in; on top of that an administrator can invite users directly (an invitation does
not need the key). Empty = registration without a key.
Users can sign in with Google instead of e-mail and password. To set it up:
In the Google Cloud Console go to APIs & Services → Credentials → Create credentials → OAuth client ID → type Web application.
Under Authorized redirect URIs add: https://YOUR-DOMAIN/api/oauth2-redirect
Copy the Client ID and Client secret into .env:
KB_GOOGLE_CLIENT_ID=…apps.googleusercontent.com
KB_GOOGLE_CLIENT_SECRET=…docker compose up -d — the “Sign in with Google” button appears by itself.
Empty variables = Google sign-in is off (the button is not shown). On an instance with a registration key, Google sign-in is only for existing users — a new account cannot be created through Google (there is no way to enter the key), so the account has to be created with the key first.
You can pin either an uploaded file or a link (Drive, OneDrive, SharePoint, a specific
e-mail, anything on https://) to any goal. A link has three advantages: it takes up no space,
the team always opens the current version, and the file stays where you keep it.
How much space uploaded files may take is governed by KB_FILES_MB — it applies to the whole
instance, not per project:
Value | Behaviour |
empty | no limit (the default for self-hosting — it is your disk) |
a number | the cap in MB, e.g. |
| uploads disabled, attachments as links only |
Hosted instances run with 0: that way the provider does not hold your documents, only links
to them. A link has to start with http:// or https:// — a network drive path
(\\server\folder) will not open from a browser for security reasons, so that belongs in the
description.
SMTP is configured in the PocketBase admin UI: http://SERVER-IP:8090/_/ → Settings → Mail
settings (the superuser account is created on first start — you will find the link in
docker compose logs). With SMTP configured:
an invitation to a new user is sent by e-mail (with a link to set a password) — without SMTP the administrator is shown a temporary password to hand over manually,
self-service password reset works.
killBottleneck itself runs over HTTP — to reach it from outside your LAN, use a VPN or a reverse proxy. An example with Caddy (automatic HTTPS certificates):
# Caddyfile
killbottleneck.your-domain.com {
reverse_proxy 127.0.0.1:8090
}Add it to compose through docker-compose.override.yml (that file is not overwritten by
updates):
services:
caddy:
image: caddy:2
ports: ["80:80", "443:443"]
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile
- caddy_data:/data
volumes:
caddy_data:HTTPS additionally unlocks Share… for the “My day” image (the Web Share API — your phone's native share dialog, no third-party service) and adding the app to your phone's home screen (a service worker only runs in a secure context). Browsers do not allow either of these over plain HTTP; on an HTTPS domain they appear by themselves, with no configuration.
killBottleneck does not compress responses itself (there is no way to enable it safely in PocketBase without breaking how the API behaves when it rejects an oversized body). The main frontend file is 488 kB uncompressed and 157 kB gzipped — on mobile data that is the difference you notice most when opening it for the first time. One line is enough:
# Caddyfile
killbottleneck.your-domain.com {
encode gzip zstd
reverse_proxy 127.0.0.1:8090
}(In nginx: gzip on; gzip_types application/javascript text/css;. Behind Cloudflare or a
similar service it happens on its own — there is nothing to configure.)
git pull # or download the new version
docker compose up -d --buildDatabase migrations run automatically on start. Before a bigger update it is worth taking a
backup (./backup.sh).
Always with
--build: the app and its server-side logic are baked into the image, so after every update (a code change,.envvariables such asTZ) you needdocker compose up -d --build, not justrestart.
One-off, when updating from a version up to v0.11: after the product was renamed the
container is called killbottleneck instead of flowmap. The old container holds port 8090,
so the new one would not come up — stop and remove it first:
docker rm -f flowmap
docker compose up -d --buildYour data is in the ./pb_data folder on disk, not in the container — you will not lose
anything. FLOWMAP_* variables in your .env keep working, there is no need to rewrite them.
A public link to a map shares only the map canvas — tasks and task comments are not visible through it.
Licence: fair-code — Sustainable Use License (see the License section below).
killBottleneck isn't "open source" in the strict (OSI) sense — and we say so plainly. It's fair-code: the source is public, you can download it, run it, modify it and use it, and for the vast majority of people it delivers the same benefits as classic open source. The parts that can be classic open source, are: the skin editor (MIT) and the whole skin gallery including its validator (CC0).
You get the whole of killBottleneck — every feature, including team collaboration and the AI features. No stripped-down "free version", nothing locked behind a paywall. You can even power the AI yourself, for free — with your own model (Ollama) on your machine, or your own API key. Our hosted cloud (AI included) is offered only as a convenience for those who have nowhere to run killBottleneck — it's convenience, not a condition.
What you may do with killBottleneck — free and with no catch:
Run it yourself on your own computer or server — your data stays with you.
Use it in your company for your own work and your team — fully.
Plug in your own AI (a local model or your own API key), or use no AI at all.
Modify it however you need.
Offer services around killBottleneck (setup, consulting, customizations for a client).
What we keep for ourselves — and what keeps killBottleneck alive:
Hosting killBottleneck and charging people for access.
White-labeling it — releasing it under someone else's brand.
Reselling it as a paid service.
That's our business — it's what lets us keep adding features, fixing bugs, and keeping killBottleneck alive. We actively encourage you to build on killBottleneck and use it however you need; just don't turn it into a competing hosted service. Full terms: LICENSE. Third-party components keep their original licenses (MIT, Apache-2.0, BSD, …) — the full list with license texts is in THIRD-PARTY-LICENSES.md.
Rights holder: Tengo, s.r.o., ID No. 03339165, Dolní Valy 205, 262 72 Březnice, Czech Republic. Want to host killBottleneck as a service, ship it under your own brand, or resell it? The license doesn't allow that — but a commercial license is available, write to licence@killbottleneck.com.
Česká verze této sekce je v README.cs.md.
Built by Richard Pobrislo (LinkedIn, Ctrl+Alt+AI) — one person, which is why the support channels below are what they are.
The code is written 100% by AI — Claude Fable 5, Claude Opus 5 and Claude Opus 4.8 — under human direction. Every release goes through an automated regression suite and a manual click-through before it ships; the release notes list what was verified and what deliberately wasn't.
Where | What for |
GitHub Issues / Discussions | bugs and ideas for improvements — in the open, so others can see them too |
security issues (not in a public issue) — see SECURITY.md | |
paid plans: the hosted instance | |
commercial licensing — hosting as a service, white-label, reselling | |
everything else |
We do not accept code from outside contributors (see CONTRIBUTING.md) — ideas and bug reports we do, and they are welcome.
killBottleneck is fair-code — the whole product (every feature) is free to self-host and will stay that way. If it helps you:
follow our YouTube channel with tutorials and AI news,
join us on 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
