Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kanbantool-mcp What's on my Engineering board right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that connects Claude Code (and other MCP clients) to a Kanban Tool account.
New to MCP? This is an MCP server — you run it from an MCP-aware assistant. If you've never set one up, install Claude Code, Claude Desktop, or Cursor first, then come back here.
Kanban Tool holds the authoritative state of your boards, tasks, and workflow — but an LLM can't see any of it without help. This MCP server gives Claude Code (and any other MCP client) read access to boards and tasks, search via Kanban Tool's query DSL, and write tools to create, update, move, archive, comment on, and break down tasks. The point: stop re-explaining your kanban state to the model on every interaction, and let it act on the board directly when you want it to.
Related MCP server: kanban-mcp
Alpha, approaching v1.0. The 26-tool surface is settled and exercised against a real Kanban Tool account via the Live Integration workflow. Pre-1.0 means the surface may still evolve based on real-world feedback — pin a specific version if you need stability across upgrades. See SEMVER.md for the v1.0 stability commitment (which surfaces are stable, which are not, deprecation policy).
Where the project is going: see the open milestones. Larger workstreams are tagged with the epic label.
Maintainer is best-effort and typically responds to issues and PRs within ~a week. If something is blocking you and the silence is longer, a polite bump on the thread is welcome.
A short illustrative session — the shape of an interaction, not literal terminal output:
User: What's on my Engineering board right now?
Assistant: (calls list_boards) -> finds "Engineering" with id 4217
(calls get_board 4217) -> reads columns: Backlog / Doing / Review / Done
(calls search_tasks
query="archived:false",
board_id=4217) -> 14 active tasks, grouped by column
Engineering has 14 active cards. Doing (3): "Migrate auth to OIDC",
"Flaky CI on macOS", "Add rate-limit headers". Review (2): ...Longer end-to-end walkthroughs (with realistic JSON request/response shapes) live in examples/.
Variable | What it is | Where to get it |
| Your account's subdomain prefix — | The URL you log into. |
| Bearer token for the Kanban Tool API v3. | Profile -> API tokens in your Kanban Tool account. |
| Optional. Set to | — |
| Optional. Set to | — |
The first two are required; the rest are optional and unset by default.
The JSON shape is the same across MCP clients — only the file location and the launcher CLI differ. Pick your client below, drop the snippet into the matching mcp.json, and substitute your KANBANTOOL_DOMAIN / KANBANTOOL_API_TOKEN values.
Each snippet shows the PyPI form (uvx kanbantool-mcp) — swap the args for the git form below if you want to track main instead of a release:
"args": ["--from", "git+https://github.com/VeryLongOrgNameSuchWow/kanbantool-mcp", "kanbantool-mcp"]Easiest path is the CLI:
claude mcp add-json kanbantool '{
"command": "uvx",
"args": ["kanbantool-mcp"],
"env": {
"KANBANTOOL_DOMAIN": "your-account",
"KANBANTOOL_API_TOKEN": "your-token"
}
}'Or edit ~/.claude.json (project-scoped via claude mcp add-json -s project ...). See https://docs.claude.com/en/docs/claude-code/mcp for scopes.
Edit the config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows). Setup docs: https://modelcontextprotocol.io/quickstart/user.
{
"mcpServers": {
"kanbantool": {
"command": "uvx",
"args": ["kanbantool-mcp"],
"env": {
"KANBANTOOL_DOMAIN": "your-account",
"KANBANTOOL_API_TOKEN": "your-token"
}
}
}
}Edit ~/.cursor/mcp.json (or per-project .cursor/mcp.json). Setup docs: https://cursor.com/docs/mcp.
{
"mcpServers": {
"kanbantool": {
"command": "uvx",
"args": ["kanbantool-mcp"],
"env": {
"KANBANTOOL_DOMAIN": "your-account",
"KANBANTOOL_API_TOKEN": "your-token"
}
}
}
}Edit ~/.continue/config.yaml (Continue uses YAML, not JSON, for MCP entries). Setup docs: https://docs.continue.dev/customize/deep-dives/mcp.
mcpServers:
- name: kanbantool
command: uvx
args:
- kanbantool-mcp
env:
KANBANTOOL_DOMAIN: your-account
KANBANTOOL_API_TOKEN: your-tokenEdit cline_mcp_settings.json via the Cline panel's MCP Servers > Edit Config button. Setup docs: https://docs.cline.bot/mcp/configuring-mcp-servers.
{
"mcpServers": {
"kanbantool": {
"command": "uvx",
"args": ["kanbantool-mcp"],
"env": {
"KANBANTOOL_DOMAIN": "your-account",
"KANBANTOOL_API_TOKEN": "your-token"
}
}
}
}Any MCP client that supports launching a stdio server. Spawn this command with the env vars set in the child process; the server speaks JSON-RPC on stdin/stdout.
KANBANTOOL_DOMAIN=your-account \
KANBANTOOL_API_TOKEN=your-token \
uvx kanbantool-mcpSet KANBANTOOL_READ_ONLY=1 (or true/yes/on) to register only the 11 read-class tools. Any value outside that set, including the empty string, leaves the full 26-tool surface intact.
Use this when you want to give an LLM safe access to your boards — search, browse, summarise, answer questions about state — without giving it the ability to create, update, move, archive, comment on, or delete anything. The write tools simply don't appear in the tool list, so the model can't call them even if it tried.
Read-class tools (always registered):
list_boards get_board get_user
search_tasks list_board_collaborators whoami
get_task list_custom_field_definitions list_my_timers
recent_changes list_subtasksWrite tools (suppressed when read-only): create_task, update_task, move_task, archive_task, set_custom_field, add_comment, delete_comment, add_subtask, update_subtask, delete_subtask, reorder_subtasks, start_timer, stop_timer, delete_timer.
The transport smoke test ping is always registered regardless of mode.
Run kanbantool-mcp --check (e.g. uvx kanbantool-mcp --check) — it validates your env vars, hits the whoami endpoint, and prints a one-line OK/FAIL signal. Sample success output:
OK: Alice Example (your-account) — token resolves; you can use kanbantool-mcp nowThe flag exits 0 on success and non-zero on failure (missing env, 401/403 auth, network failure), with an actionable hint per error class. Run it once after wiring the server into your client to confirm the token reaches Kanban Tool before asking your assistant to do anything with it.
To check which version you have installed, run kanbantool-mcp --version (e.g. uvx kanbantool-mcp --version). Useful when reporting an issue.
You can also verify from inside the assistant: ask "who am I?" — it'll call the whoami tool and confirm your token resolves. If that comes back with your name, the server is reachable and your credentials work.
Tool | Purpose | Key params |
| List boards visible to the authenticated user. | — |
| Fetch a board with its columns, swimlanes, and custom-field definitions. |
|
| Search tasks across boards using Kanban Tool's query DSL (e.g. |
|
| Fetch a task by id with headline metadata, subtask/comment counts, and tracked time. |
|
| Fetch the changelog feed for a board — the change-tracking primitive that stands in for webhooks (Kanban Tool ships none). Poll sparingly. |
|
| Create a new task on a board. Optional kwargs are omitted when unset. |
|
| Partial update of an existing task; only kwargs the caller passes are sent. |
|
| Move a task between columns, swimlanes, or positions. At least one target must be set. |
|
| Archive a task. Idempotent. |
|
| Post a comment on a task. |
|
| Soft-delete a comment on a task. Returns the deleted comment with |
|
| List subtasks attached to a task. |
|
| Add a subtask to a task. |
|
| Partial update of an existing subtask — mark complete, rename, change assignee. |
|
| Soft-delete a subtask. Returns the deleted subtask with |
|
| Reorder all subtasks under a task. |
|
| Fetch the authenticated user's profile — id, role flags, locale. Use to resolve "me" / "myself" in user requests. | — |
| Fetch one user by id. |
|
| List users with access to a board (the canonical user-discovery surface — the API has no bulk list-users endpoint). |
|
| List the per-board metadata for the 15 |
|
| Set or clear one of the 15 |
|
| Start a per-user time tracker on a task. |
|
| Stop a running time tracker. |
|
| Delete a time tracker (hard-delete). Returns |
|
| List the authenticated user's time trackers across all tasks. | — |
(ping exists as a transport smoke test; not listed above.)
The tool surface is bounded by what the Kanban Tool API v3 actually exposes. A few common workflows are intentionally absent because there is no upstream endpoint to call:
Board lifecycle. The API has no POST /boards, PUT /boards/{id}, or DELETE /boards/{id} — boards must be created, renamed, and archived through the Kanban Tool web UI, not via the MCP. list_boards and get_board are the only board-scoped surfaces. Verified via live spike against the API (every variant returns 404; see #130). Provision the board out-of-band first, then point the LLM at it.
Column / swimlane structure. Board.columns and Board.swimlanes are read-only on the wire. Re-shape your workflow in the web UI; the MCP can read the result but not edit it.
Comment editing. The API has no comment-edit endpoint. delete_comment + add_comment is the supported "fix a comment" pattern.
Webhooks. Kanban Tool ships none. recent_changes(board_id, since) is the polling primitive that stands in.
Bulk user listing. No global /users endpoint. list_board_collaborators(board_id) is the canonical user-discovery surface (per board).
Per the project's "be honest about the upstream" principle (see CLAUDE.md), these gaps are surfaced explicitly rather than papered over with shims.
A short write-flow alongside the read-flow shown above. Illustrative — shape of a session, not literal terminal output. For longer walkthroughs with realistic JSON shapes, see examples/.
User: Create a high-priority task in Engineering called "Fix login bug",
and leave a comment that I'm picking it up today.
Assistant: (calls list_boards) -> resolves "Engineering" -> id 4217
(calls create_task
name="Fix login bug",
board_id=4217,
priority="high") -> task id 88231 created
(calls add_comment
task_id=88231,
content="Picking this up today.")
Created "Fix login bug" (id 88231) in Engineering at high priority,
and added your comment.git clone https://github.com/VeryLongOrgNameSuchWow/kanbantool-mcp.git
cd kanbantool-mcp
uv sync
uv run pytest
uv run ruff check .
uv run ty checkTests are offline-only and mock HTTP via respx — no Kanban Tool account needed to contribute.
File | What it covers |
Local setup, conventional-commit rules, what a good PR looks like, how reviews work. | |
Release flow end-to-end (conventional commits → release-please → PyPI), the GitHub App that auths release-please, and break-glass procedures for stuck release PRs. | |
Compatibility commitment for v1.0+ — which surfaces are stable, which are unstable, deprecation policy. | |
How to report security vulnerabilities (GitHub private security advisories). |
Post a comment on a task. Returns the created Comment with id,
content, author, and timestamps.
Common 422 (KanbanToolValidationError with parsed field_errors):
content empty or whitespace-only — fix by passing a non-empty
string; the field_errors key matches the parameter name.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| content | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| content | Yes | |
| user_id | No | |
| created_at | No | |
| updated_at | No | |
| deleted_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-read-only, non-destructive, non-idempotent. Description adds that it returns a Comment object with specific fields and details a validation error for empty content, providing useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus error note are concise and front-loaded with purpose. Every sentence adds value without 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?
Output schema exists and description mentions return fields, but lacks prerequisites, side effects, or broader context. Adequate for simple tool but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description should explain parameters. It only mentions that content must be non-empty, but does not describe task_id or provide full semantics. Inadequate compensation for low coverage.
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 'Post a comment on a task', which is a specific verb+resource combination. It distinguishes from siblings like add_subtask and delete_comment.
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 vs alternatives. Common error (422) is documented but not usage context. Implied usage from purpose but lacking when-not or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a subtask to a task. Returns the created Subtask.
name is the human-readable label. Mirrors the parameter name used
by update_subtask and the wire/model field on Subtask.name.
Common 422 (KanbanToolValidationError with parsed field_errors):
name empty or whitespace-only — fix by passing a non-empty string.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| name | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| is_completed | No | |
| position | No | |
| task_id | No | |
| assigned_user_id | No | |
| deleted_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is not read-only, destructive, or idempotent. The description adds value by detailing the return (created Subtask) and a common validation error, providing context beyond the annotation hints.
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, front-loaded with the main purpose, followed by parameter and error details. No redundant or extraneous content.
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 tool with output schema and annotations, the description adequately covers purpose, key parameter semantics, and an error scenario. It lacks sibling differentiation but is largely sufficient 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 has 0% description coverage, so the description must compensate. It explains that name is the human-readable label, mirrors update_subtask, and notes the 422 error for empty name. This adds meaning, though task_id is not elaborated.
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 'Add a subtask to a task. Returns the created ``Subtask``.' This clearly specifies the action (add), the resource (subtask), and the output (created Subtask). It distinguishes from siblings like create_task and update_subtask.
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 helpful error-handling tip for the name parameter but does not explicitly state when to use this tool versus alternatives (e.g., update_subtask, reorder_subtasks). There is no guidance on prerequisites or contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a task. Returns the updated Task (caller can confirm
is_archived=True).
Idempotent: re-archiving an already-archived task succeeds. There is no
unarchive_task yet — archiving is currently one-way from this surface.
Failure modes: KanbanToolHTTPError(404) when the task id is unknown
(verify via get_task(task_id) first if you're unsure);
KanbanToolPermissionError(403) when the authenticated user lacks
write access to the task's board.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| description | No | |
| board_id | No | |
| workflow_stage_id | No | |
| swimlane_id | No | |
| position | No | |
| priority | No | |
| color | No | |
| due_date | No | |
| start_date | No | |
| tags | No | |
| assigned_user_id | No | |
| archived_at | No | |
| block_reason | No | |
| subtasks_count | No | |
| subtasks | No | |
| comments_count | No | |
| timers_total | No | |
| time_trackers | No | |
| created_at | No | |
| updated_at | No | |
| size_estimate | No | |
| size_estimate_description | No | |
| time_estimate | No | |
| search_tags | No | |
| card_color | No | |
| card_color_in_rgb | No | |
| card_color_invert | No | |
| card_type_id | No | |
| recurring_schedule | No | |
| reminders_schedule | No | |
| linked_tasks | No | |
| linked_tasks_status | No | |
| task_dependencies | No | |
| collaborators | No | |
| attachments | No | |
| attachments_count | No | |
| created_by_id | No | |
| moved_at | No | |
| postponed_until | No | |
| subtasks_completed_count | No | |
| external_id | No | |
| external_link | No | |
| custom_fields | No | |
| is_archived | Yes | True iff the task has an archival timestamp. |
| is_blocked | Yes | True iff the task has a non-empty block reason. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description expands on annotations: idempotency is explained in detail ('re-archiving an already-archived task succeeds'), destructiveHint is supported by the one-way nature, and failure modes (404, 403) are listed. No contradiction with annotations.
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 short paragraphs: purpose, idempotency/irreversibility, failure modes. Each sentence adds value, and the key information is 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?
Given one parameter and no output schema (but description mentions return value), the description covers purpose, idempotency, irreversibility, failure modes, and a suggested pre-check. No gaps remain.
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 only parameter task_id has no schema description (0% coverage). The description adds minimal guidance by referencing task id verification via get_task, but does not describe the parameter format or constraints beyond what schema provides. For a simple integer parameter, a baseline of 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 clearly states 'Archive a task' as the verb+resource, and explains the effect (returns updated Task with is_archived=True). Among sibling tools, no other archive tool exists, so it is fully distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns that 'archiving is currently one-way from this surface' and suggests verifying the task id with get_task first. This gives clear guidance on when to use and what precautions to take.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new task on a board. Only name and board_id are required.
lane_id is the target column (matches Task.lane_id on fetched tasks).
assigned_user_id sets the single assignee — Kanban Tool tasks have one
assignee, not a list. (The API silently ignores a legacy assignees: [int]
payload on writes, so this kwarg is the wire field name directly.)
priority accepts the string enum or the raw integer; tags is a
comma-separated string; due_date is an ISO 8601 string forwarded as-is.
Unset kwargs are omitted from the request, never sent as explicit null.
Common 422s (KanbanToolValidationError with parsed field_errors):
name empty/missing → fix by passing a non-empty string;
lane_id belongs to a different board → resolve column ids on the
target board first via get_board(board_id).columns;
assigned_user_id not a board collaborator → check via
list_board_collaborators(board_id).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| board_id | Yes | ||
| description | No | ||
| lane_id | No | ||
| position | No | ||
| assigned_user_id | No | ||
| due_date | No | ||
| priority | No | ||
| tags | No |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| description | No | |
| board_id | No | |
| workflow_stage_id | No | |
| swimlane_id | No | |
| position | No | |
| priority | No | |
| color | No | |
| due_date | No | |
| start_date | No | |
| tags | No | |
| assigned_user_id | No | |
| archived_at | No | |
| block_reason | No | |
| subtasks_count | No | |
| subtasks | No | |
| comments_count | No | |
| timers_total | No | |
| time_trackers | No | |
| created_at | No | |
| updated_at | No | |
| size_estimate | No | |
| size_estimate_description | No | |
| time_estimate | No | |
| search_tags | No | |
| card_color | No | |
| card_color_in_rgb | No | |
| card_color_invert | No | |
| card_type_id | No | |
| recurring_schedule | No | |
| reminders_schedule | No | |
| linked_tasks | No | |
| linked_tasks_status | No | |
| task_dependencies | No | |
| collaborators | No | |
| attachments | No | |
| attachments_count | No | |
| created_by_id | No | |
| moved_at | No | |
| postponed_until | No | |
| subtasks_completed_count | No | |
| external_id | No | |
| external_link | No | |
| custom_fields | No | |
| is_archived | Yes | True iff the task has an archival timestamp. |
| is_blocked | Yes | True iff the task has a non-empty block reason. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-destructive mutation. Description adds beyond annotations: notes that unset kwargs are omitted, API silently ignores legacy assignees array, and details error handling. No contradiction with annotations.
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?
Description is somewhat lengthy but well-structured: front-loaded with purpose and required fields, then optional parameters, then common errors. Every sentence adds value, though slight trimming could improve conciseness.
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 9 parameters, 2 required, and an output schema (not shown), the description covers all aspects: required params, optional param semantics, error handling, and usage context. It is complete and leaves no significant gaps.
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 0% schema description coverage, the description fully compensates by explaining each parameter's semantics: lane_id matches Task.lane_id, assigned_user_id is a single assignee, priority accepts string enum or integer, tags is comma-separated, due_date ISO 8601, and behavior for unset fields.
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 'Create a new task on a board.' and specifies required parameters (name and board_id). It distinguishes from sibling tools like update_task and archive_task 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?
Description provides explicit guidance on when to use, including required fields and common error scenarios (422s) with troubleshooting links to get_board and list_board_collaborators, effectively telling the agent when and when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a comment (soft-delete). Returns the deleted Comment with
deleted_at populated.
Like subtasks, the Kanban Tool API soft-deletes — the comment record is
retained server-side with a deleted_at timestamp and stops appearing
on the parent task's comments. The MCP-visible effect is "the comment is
gone." There is no edit endpoint on the API; if you need to "fix" a
comment, delete it and post a replacement.
Failure modes: KanbanToolHTTPError(404) when either id is unknown
or the comment isn't on that task — common cause is reusing a stale
comment_id from a previous list. Re-fetch the task's current
comments before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| comment_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| content | Yes | |
| user_id | No | |
| created_at | No | |
| updated_at | No | |
| deleted_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description adds value by explaining the soft-delete mechanism (retained server-side with deleted_at) and the absence of an edit endpoint. It also details failure modes, which goes beyond the annotation flags.
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?
Description is moderately concise, with each sentence providing essential information (soft-delete, no edit, failure modes). It could be slightly tighter by removing the analogy to subtasks, but overall it is well-structured and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (covering return values), the description is complete: it explains the soft-delete behavior, the lack of an edit endpoint, and common failure modes. No critical information is missing for an agent to use this tool correctly.
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?
Input schema has no descriptions (0% coverage), so description must compensate. It adds meaning by explaining the relationship between task_id and comment_id through the failure mode explanation (comment must belong to that task). It also mentions return value (deleted Comment with deleted_at). However, it does not explicitly describe each parameter's purpose or format.
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?
Clearly states 'Delete a comment (soft-delete)' with a specific verb and resource. Distinguishes from sibling tools like delete_subtask and archive_task by mentioning the soft-delete behavior and that no edit endpoint exists, so this is the only way to fix a comment.
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?
Provides explicit guidance: 'if you need to fix a comment, delete it and post a replacement', indicating when to use this tool instead of editing (which doesn't exist). Also advises to re-fetch comments before retrying on 404. No explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a subtask (soft-delete). Returns the deleted Subtask with
deleted_at populated.
The Kanban Tool API soft-deletes — the subtask record is retained
server-side with a deleted_at timestamp and stops appearing on the
parent task's subtasks array. This operation is not strictly
irreversible from an audit perspective, but the MCP-visible effect is
"the subtask is gone."
Failure modes: KanbanToolHTTPError(404) when the subtask id is
unknown OR was already soft-deleted in a previous call (the API
returns 404 in both cases). Re-fetch the parent task's
subtasks list to confirm the current state before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| subtask_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| is_completed | No | |
| position | No | |
| task_id | No | |
| assigned_user_id | No | |
| deleted_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint: true, but the description adds valuable context: soft-delete mechanism, server-side retention, MCP-visible effect, and specific failure modes. This goes beyond what annotations provide.
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 concise with three short paragraphs, each serving a purpose: stating the action, explaining soft-delete behavior, and listing failure modes. No 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 single parameter, existing output schema, and annotations, the description covers behavior, side effects, failure modes, and recommended follow-up actions. It provides complete context for an agent to use this tool correctly.
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 0% schema description coverage, the description does not elaborate on the subtask_id parameter beyond its existence. The schema already defines it as an integer >=1, but the description could have added context about how to obtain the ID (e.g., from list_subtasks). Score is baseline due to minimal additional meaning.
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 'Delete a subtask (soft-delete)' with a specific verb and resource. It distinguishes from sibling tools like archive_task by clarifying it applies to subtasks only and uses soft-delete semantics.
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 explains when to use this tool (when needing to soft-delete a subtask) and includes failure modes (404 for unknown or already deleted subtask) with a recommendation to re-fetch parent task's subtasks list. While it doesn't explicitly exclude alternatives, the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a time tracker entirely (e.g. cancel a mistakenly-started one). Unlike subtasks, timer deletion is hard — the record is gone, not soft-flagged.
Returns None because the API responds with an empty body to
DELETE /time_trackers/{id}.json. The caller should treat the
timer id as invalidated after this call.
Failure modes: KanbanToolHTTPError(404) when the timer id is
unknown, was already deleted, or belongs to another user (the API
scopes timer ids to the authenticated user). Use list_my_timers()
to confirm the current set of timer ids you own before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| timer_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds critical context: the record is gone (hard delete), API returns empty body, and the timer id is invalidated. It also details failure modes (404 for invalid/owned ids). This far exceeds the annotations.
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 paragraphs with clear structure: purpose, behavioral contrast, return value, failure modes, and suggestion. Every sentence adds value, no fluff. Front-loaded with main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one param, no nested objects, empty output). Description covers purpose, behavior, return, failure modes, and gives a remedial suggestion. Complete and self-contained.
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 has one parameter (timer_id) with no schema description, so the description must compensate. It provides context about valid ids (belongs to user, not previously deleted) and failure modes, but does not explicitly describe the parameter's purpose. Given only one parameter, this is sufficient.
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 deletes a time tracker entirely, using specific verbs and resource. It distinguishes from subtask deletion (hard vs soft) and provides use case (cancel a mistakenly started one).
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 explains when to use (delete a time tracker) and contrasts with subtask deletion. It also advises using list_my_timers to confirm ids before retrying, providing usage guidance. However, it does not explicitly mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one board with its columns, swimlanes, and custom-field definitions.
Use this when you need column/lane ids for move_task or create_task.
Raises KanbanToolHTTPError(404) if the board id is unknown or hidden.
| Name | Required | Description | Default |
|---|---|---|---|
| board_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| description | No | |
| slug | No | |
| use_swimlanes | No | |
| is_archived | No | |
| user_role | No | |
| workflow_stages | No | |
| swimlanes | No | |
| collaborators | No | |
| card_template | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating safe read. The description adds that it raises a 404 for unknown/hidden board ids, which is actionable behavioral info beyond what annotations provide.
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 concise sentences: purpose, use case, error note. Front-loaded, no redundancy, every sentence 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?
With output schema present and tool being simple (1 param, read-only), the description covers purpose, usage, and error. No missing critical info.
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 no description for board_id (0% coverage). The description implicitly identifies board_id as the board identifier via 'Fetch one board', but adds no detail on formatting or constraints beyond the schema's minimum value.
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 ('Fetch one board') and the specific returned data (columns, swimlanes, custom-field definitions). This distinguishes it from sibling tools like list_boards (which likely lists board summaries) and get_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool: 'Use this when you need column/lane ids for move_task or create_task.' It also mentions the error case (404), providing clear context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one task by id. Returns a Task with subtask/comment counts,
total tracked time, and inline subtasks.
Subtasks live on Task.subtasks directly — no extra round-trip needed
(use list_subtasks only when you want just the list and not the rest
of the task).
Raises KanbanToolHTTPError(404) if the task is unknown or inaccessible.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| description | No | |
| board_id | No | |
| workflow_stage_id | No | |
| swimlane_id | No | |
| position | No | |
| priority | No | |
| color | No | |
| due_date | No | |
| start_date | No | |
| tags | No | |
| assigned_user_id | No | |
| archived_at | No | |
| block_reason | No | |
| subtasks_count | No | |
| subtasks | No | |
| comments_count | No | |
| timers_total | No | |
| time_trackers | No | |
| created_at | No | |
| updated_at | No | |
| size_estimate | No | |
| size_estimate_description | No | |
| time_estimate | No | |
| search_tags | No | |
| card_color | No | |
| card_color_in_rgb | No | |
| card_color_invert | No | |
| card_type_id | No | |
| recurring_schedule | No | |
| reminders_schedule | No | |
| linked_tasks | No | |
| linked_tasks_status | No | |
| task_dependencies | No | |
| collaborators | No | |
| attachments | No | |
| attachments_count | No | |
| created_by_id | No | |
| moved_at | No | |
| postponed_until | No | |
| subtasks_completed_count | No | |
| external_id | No | |
| external_link | No | |
| custom_fields | No | |
| is_archived | Yes | True iff the task has an archival timestamp. |
| is_blocked | Yes | True iff the task has a non-empty block reason. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds error behavior (404 for unknown/inaccessible) and the inline subtasks structure, giving full behavioral context beyond the annotation.
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 with zero waste: first sentence states purpose, second details return value, third gives usage guidance and error conditions. Front-loaded and efficient.
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 simple schema with one parameter, read-only annotation, and presence of output schema, the description fully covers purpose, return structure, error case, and sibling differentiation.
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 only parameter task_id is described implicitly via 'by id' and schema constraints (minimum:1, integer). With 0% schema description coverage, the description compensates adequately for a simple param, though it adds no explicit syntax.
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 'Fetch one task by id' and lists specific return fields (subtask/comment counts, total tracked time, inline subtasks), distinguishing it from sibling tools like list_subtasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use list_subtasks instead ('only when you want just the list and not the rest of the task'), providing clear context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one user by id. Useful after list_board_collaborators finds
a candidate by name — call this to confirm role flags and active state
before assigning. Raises KanbanToolHTTPError(404) for unknown ids.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | No | |
| initials | No | |
| is_account_admin | No | |
| is_account_owner | No | |
| is_project_manager | No | |
| is_suspended | No | |
| last_activity_on | No | |
| last_login_at | No | |
| created_at | No | |
| timezone | No | |
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already indicates this is a read-only operation; the description reinforces this by stating 'Fetch one user'. It additionally discloses that the tool raises a specific HTTP error for unknown ids, which adds value beyond the annotation.
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 incredibly concise at two sentences, with the first sentence front-loading the primary purpose. Every sentence adds value, and there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (1 required parameter, output schema present), the description covers the essential aspects: what it does, a typical workflow context, and error behavior. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'user_id' parameter beyond the generic 'by id'. Since the input schema has no description for this parameter (0% coverage), the tool description should compensate, but it only implies the parameter's purpose without adding format or constraints.
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 'Fetch one user by id', which is a clear and specific verb+resource combination. It distinguishes itself from the sibling tool 'list_board_collaborators' by providing a concrete use case.
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 ('Useful after list_board_collaborators finds a candidate by name') and what actions to take ('confirm role flags and active state before assigning'). It also mentions an error condition (404 for unknown ids), providing comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the users with access to board_id.
The Kanban Tool API v3 has no bulk list-users endpoint, so this is the
canonical way to discover user IDs for assigned_user_id on tasks.
Costs one HTTP call (the same as get_board — collaborators come
inline on the detail payload). For richer per-user fields, follow up
with get_user(id).
| Name | Required | Description | Default |
|---|---|---|---|
| board_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds behavioral context: it costs one HTTP call and that collaborators come inline on the detail payload like get_board. This helps the agent understand performance and data structure without contradicting annotations.
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 serving a purpose: stating the action, explaining why it's canonical, and providing cost and follow-up guidance. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (listing collaborators for a board) and the presence of an output schema, the description covers purpose, usage context, cost, and related tools. It is complete for an agent to decide when to invoke it.
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 only parameter board_id is mentioned in the description but not described in detail. However, with 0% schema description coverage and only one integer parameter, the context provided ('access to board_id') is sufficient for understanding. The schema itself defines constraints (minimum 1, required), so description adds marginal value.
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 ('List the users with access') and the specific resource (board_id). It also distinguishes from siblings by noting this is the canonical way to get user IDs, unlike get_board (inline collaborators) or get_user (richer fields).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: to discover user IDs for assigned_user_id on tasks, as there is no bulk list-users endpoint. Provides context on cost (one HTTP call, same as get_board) and alternative for richer data (follow up with get_user).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List boards visible to the authenticated user. Use this to discover
board_id values for the other tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds that boards are 'visible to the authenticated user', providing scoping context but no further behavioral details.
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 action. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is complete: it explains the action and its utility. No missing context.
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, so high schema coverage. Description does not need to add param info; baseline 4 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 clearly states the tool lists boards and highlights its role in discovering board_id values for other tools, distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions using this tool to discover board_id values, guiding when to use it. Could be improved by noting when not to use it, but the purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the per-board metadata for the 15 custom-field slots.
Each task has up to 15 custom_field_N values surfaced as
Task.custom_fields["custom_field_N"]. The slot number alone tells
you nothing about what's IN it on a given board — call this tool once
per board to learn the labels, types, and enabled state, then
interpret task values accordingly.
Returns the 15 definitions in slot order (1..15) regardless of which
are enabled. Slots with enabled=False are usually dormant on
that board's UI even if individual tasks happen to carry values.
| Name | Required | Description | Default |
|---|---|---|---|
| board_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds valuable behavioral context: it returns all 15 definitions regardless of enabled state, and explains that enabled=False slots are dormant in the UI. There is no contradiction with annotations.
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 adequately concise with about 5 sentences, each adding value. It is front-loaded with the main purpose. However, it could be slightly tighter by integrating the parameter guidance into the first paragraph.
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 has an output schema (not shown), the description provides enough context for the return format (15 definitions in slot order, fields like labels, types, enabled state) and hints at usage in a broader workflow. It is complete for its purpose.
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 has one required parameter 'board_id' (integer, min 1) but no description in the schema. The tool description does not explicitly mention or explain the 'board_id' parameter beyond a vague 'once per board'. With 0% schema coverage, the description fails to compensate by clarifying the parameter's meaning or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists per-board metadata for 15 custom-field slots. It specifies the verb 'list' and the resource 'custom-field definitions', and distinguishes from siblings by detailing what is returned (labels, types, enabled state) and the slot numbering.
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 explains when to use this tool: 'once per board to learn the labels, types, and enabled state, then interpret task values accordingly.' However, it does not explicitly state when not to use it or mention alternatives, though the context makes it clear this is a unique tool for metadata retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the authenticated user's time trackers across all tasks.
Returns one TimeTracker per active or finished timer the current
user owns; the wire data lives on the time_trackers field of the
/users/current.json response (no dedicated list endpoint).
Use Task.time_trackers instead when you only want one task's
timers across all users.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond readOnlyHint: returns active or finished timers, explains data location in /users/current.json response. No contradiction with annotations.
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, front-loaded with purpose, no unnecessary words, well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, does not need to explain return values. Covers what is returned, data source, and usage guidance.
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, schema coverage 100%. Baseline for 0 params is 4; no need for additional param info.
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?
Clearly states verb 'List', resource 'time trackers', and scope 'authenticated user's across all tasks'. Distinguishes from sibling timer tools like start_timer, stop_timer, delete_timer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides alternative: 'Use Task.time_trackers instead when you only want one task's timers across all users.' tells when to use vs when not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subtasks on a task — id, name, completion state, position.
Subtasks are returned inline on Task.subtasks whenever you fetch a
task; this tool is sugar for callers that only want the list. Costs one
HTTP call (the same as get_task) — the Kanban Tool API has no
dedicated list-subtasks endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so description's behavioral addition is limited to cost (same as get_task) and the lack of a dedicated endpoint. No mention of error cases or pagination, but acceptable for a simple read operation.
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?
Extremely concise: two sentences plus a brief cost note. Purpose is front-loaded in the first sentence. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage context, and API limitation. Relies on output schema for return values. Missing potential details like ordering of subtasks, but overall complete for a straightforward list 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?
Only parameter is task_id, which is self-explanatory. Description implies its role ('on a task') but adds no detail beyond the schema (type integer, minimum 1). With 0% schema coverage, baseline is low; the obviousness of the parameter prevents a lower score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'list' and the resource 'subtasks on a task', listing specific fields returned. It distinguishes from sibling tools like add_subtask, update_subtask, delete_subtask, and reorder_subtasks by focus on listing.
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?
Indicates when to use ('sugar for callers that only want the list') and notes the alternative of fetching the full task via get_task. Cost comparison (one HTTP call) adds practical guidance, though explicit 'when not to use' is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a task between columns, swimlanes, or positions on its board.
At least one of column_id / swimlane_id / position must be set,
otherwise raises ValueError before issuing HTTP. column_id matches
the Task.lane_id on fetched tasks. Moves are scoped to the task's
current board — there is no cross-board move surface.
Common 422s (KanbanToolValidationError with parsed field_errors):
column_id doesn't belong to the task's board → fetch valid column
ids via get_board(get_task(task_id).board_id).columns and pick from
those; swimlane_id doesn't exist on the task's board → same fix via
.swimlanes on the same Board.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| column_id | No | ||
| swimlane_id | No | ||
| position | No |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| description | No | |
| board_id | No | |
| workflow_stage_id | No | |
| swimlane_id | No | |
| position | No | |
| priority | No | |
| color | No | |
| due_date | No | |
| start_date | No | |
| tags | No | |
| assigned_user_id | No | |
| archived_at | No | |
| block_reason | No | |
| subtasks_count | No | |
| subtasks | No | |
| comments_count | No | |
| timers_total | No | |
| time_trackers | No | |
| created_at | No | |
| updated_at | No | |
| size_estimate | No | |
| size_estimate_description | No | |
| time_estimate | No | |
| search_tags | No | |
| card_color | No | |
| card_color_in_rgb | No | |
| card_color_invert | No | |
| card_type_id | No | |
| recurring_schedule | No | |
| reminders_schedule | No | |
| linked_tasks | No | |
| linked_tasks_status | No | |
| task_dependencies | No | |
| collaborators | No | |
| attachments | No | |
| attachments_count | No | |
| created_by_id | No | |
| moved_at | No | |
| postponed_until | No | |
| subtasks_completed_count | No | |
| external_id | No | |
| external_link | No | |
| custom_fields | No | |
| is_archived | Yes | True iff the task has an archival timestamp. |
| is_blocked | Yes | True iff the task has a non-empty block reason. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds value by disclosing that missing required params raises ValueError before HTTP, that moves are scoped to the current board (no cross-board), and details of validation errors. This goes beyond what annotations provide.
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 concise and well-structured: a one-sentence purpose, followed by bullet-pointed constraints and error handling. Every sentence adds value without unnecessary verbosity.
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 that an output schema exists (mentioned in context), the description does not need to cover return values. It adequately covers behavior, constraints, and common error scenarios, making it 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?
Schema description coverage is 0%, so the description must compensate. It explains that column_id matches Task.lane_id, and that at least one of the three optional params must be set. However, it does not describe the task_id parameter or the exact semantics of position (e.g., integer index). Partial compensation.
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 a specific verb+resource: 'Move a task between columns, swimlanes, or positions on its board.' This clearly distinguishes it from sibling tools like update_task or archive_task, as it focuses on repositioning within the board.
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 the precondition that at least one of column_id/swimlane_id/position must be set, and explains common 422 errors with resolution steps (fetching valid IDs via get_board). This provides clear context for use, but does not explicitly state when not to use this tool or suggest alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Smoke-test the MCP transport. Returns the literal string pong.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true. Description confirms no side effects and specifies the exact return value, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero wasted words, front-loaded with purpose.
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?
Fully describes behavior for a simple ping tool, including return value. No missing information needed for selection or invocation.
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; schema coverage is 100%. Description correctly indicates it takes no input.
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?
Clear and specific: 'Smoke-test the MCP transport. Returns the literal string pong.' Distinguishes it from other operations as a simple health check.
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?
Implicitly suggests use for connectivity verification. No explicit exclusions or alternatives, but given the trivial nature and no similar siblings, it's adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a board's changelog (Kanban Tool has no webhooks; poll this instead).
since is required. Pass the created_at of the newest entry you've
already seen; on the first poll, use datetime.now(UTC) - timedelta(hours=1)
(or whichever lookback window matches your use case). Entries come
newest-first. Poll sparingly: 30-120s cadence, not per-keystroke.
Raises ValueError if since is None (rather than fetching the
full history) — keeps responses bounded by construction.
| Name | Required | Description | Default |
|---|---|---|---|
| board_id | Yes | ||
| since | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true; description adds error behavior (ValueError if since is None), ordering (newest-first), and bounded responses. Could note more about response structure.
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?
Well-organized with front-loaded purpose and clear sections. Could tighten phrasing, but no significant waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is an output schema, description adequately covers purpose, usage, and behavior. Missing output details are mitigated by schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description thoroughly explains `since` parameter including default strategy. No explanation for `board_id`, but it's a common 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?
Clearly states 'fetch a board's changelog' with specific verb and resource. Distinguishes from siblings by highlighting polling use-case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use (no webhooks, poll instead), provides concrete example for `since` parameter, and recommends polling cadence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reorder subtasks under a task. Returns the subtasks in the new order.
ids must be the full set of subtask ids on task_id in the
desired order.
Common 422s (KanbanToolValidationError with parsed field_errors):
ids is a partial set (missing some of the task's current subtask
ids) → list current ids via list_subtasks(task_id) and pass them
all in the new order; one or more ids belong to a different task →
same fix, since the API rejects cross-task references.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| ids | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits: the operation is idempotent (confirmed by annotation), and it explains validation constraints (API rejects partial sets and cross-task references). There is no contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds value beyond annotations.
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 concise: two sentences plus a bullet point. It front-loads the purpose and return value, then efficiently explains the key constraint and common errors. Every sentence 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?
The description is complete for a reorder operation. It explains the required parameters, constraints, and error scenarios. With an output schema present, the mention of return value is sufficient. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full burden. It explains the 'ids' parameter meaning: must be the complete list of subtask IDs in desired order. It also implies 'task_id' usage via context. This adds essential meaning that the schema alone lacks.
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: 'Reorder subtasks under a task.' This directly specifies the verb (reorder) and resource (subtasks under a task). It distinguishes itself from sibling tools like add_subtask, delete_subtask, and update_subtask.
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 guidelines: 'ids must be the full set of subtask ids on task_id in the desired order.' It also explains common errors and their fixes, such as partial sets or cross-task references, guiding the agent to use list_subtasks first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search tasks across boards using Kanban Tool's query DSL.
query is forwarded verbatim — do not URL-encode, do not wrap the whole
expression in quotes. Quote individual values only when they contain spaces
(e.g. name:"ship the thing"). Terms combine with spaces and are AND-ed.
Supported operators:
@username — assignee, e.g. @alice
name:<text> — title contains
priority:<level> — e.g. priority:high
tags:<tag> — tag match
due_date=<iso-date> — e.g. due_date=2026-05-01
subtasks_count<N> — also >, =
archived:<bool> — include archived
Unknown operators silently return zero results, so don't invent syntax for
things the DSL doesn't cover (comment full-text, fuzzy match) — say so
instead. board_id scopes to one board (omit to search all visible).
limit is clamped to 50; paginate further with page (1-indexed).
Returns a SearchResults wrapper:
results — the list of matched Task objects on this page.
total_count — total matches across all pages (from the API's
pagination envelope; None if the API omits the envelope).
page — 1-indexed page number of this response.
has_more — True when at least one further page exists. Use
this to decide whether to bump page and call again, instead of
heuristics on len(results) == limit (which is wrong on the
last page).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| board_id | No | ||
| limit | No | ||
| page | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that query is forwarded verbatim, unknown operators return zero results, limit clamped to 50, page is 1-indexed, and details the return structure (has_more, total_count, page). Adds value beyond the readOnlyHint annotation.
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?
Well-structured with sections and bullet points, front-loaded with purpose. Slightly long but justified by the complexity of the query DSL and pagination. Every sentence 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 tool with 4 parameters and an output schema (SearchResults), the description covers all aspects: query DSL details, pagination behavior, and return fields (results, total_count, page, has_more). No gaps.
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 has no parameter descriptions (0% coverage). The description compensates fully: explains query DSL, board_id optionality, limit clamping, page indexing. Provides operator syntax and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches tasks across boards using Kanban Tool's query DSL, distinguishing it from siblings like get_task (single task) and list_boards.
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?
Provides explicit guidance on when to use, query syntax (verbatim, no URL-encode), quoting rules, operators, board_id scoping, limit clamping, pagination, and warns about unknown operators returning zero results. Differentiates from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or clear one of the 15 custom_field_* slots on a task.
slot selects which numbered slot to write (1..15 inclusive — the
Kanban Tool API exposes exactly 15). Pair with
list_custom_field_definitions(board_id) to learn each slot's label
and type on a given board before writing.
value is sent verbatim — strings, numbers, and booleans all work.
Pass value=None to clear the slot: the wire body explicitly sends
null (not omits the key), and a subsequent get_task will see
custom_field_N: null. This differs from update_task semantics
where None means omit; for custom fields None means clear.
Common 422 (KanbanToolValidationError with parsed field_errors):
type mismatch — e.g. writing "hi" into a numeric slot, or a value
not in options for a dropdown-typed slot. Inspect the slot's
type/options via list_custom_field_definitions(board_id)
before writing if the slot purpose is uncertain.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| slot | Yes | ||
| value | Yes |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| description | No | |
| board_id | No | |
| workflow_stage_id | No | |
| swimlane_id | No | |
| position | No | |
| priority | No | |
| color | No | |
| due_date | No | |
| start_date | No | |
| tags | No | |
| assigned_user_id | No | |
| archived_at | No | |
| block_reason | No | |
| subtasks_count | No | |
| subtasks | No | |
| comments_count | No | |
| timers_total | No | |
| time_trackers | No | |
| created_at | No | |
| updated_at | No | |
| size_estimate | No | |
| size_estimate_description | No | |
| time_estimate | No | |
| search_tags | No | |
| card_color | No | |
| card_color_in_rgb | No | |
| card_color_invert | No | |
| card_type_id | No | |
| recurring_schedule | No | |
| reminders_schedule | No | |
| linked_tasks | No | |
| linked_tasks_status | No | |
| task_dependencies | No | |
| collaborators | No | |
| attachments | No | |
| attachments_count | No | |
| created_by_id | No | |
| moved_at | No | |
| postponed_until | No | |
| subtasks_completed_count | No | |
| external_id | No | |
| external_link | No | |
| custom_fields | No | |
| is_archived | Yes | True iff the task has an archival timestamp. |
| is_blocked | Yes | True iff the task has a non-empty block reason. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations (which indicate idempotentHint true) by detailing the exact wire behavior: value=None sends null explicitly (not omission), which differs from update_task. It also describes the error condition for type mismatches, providing valuable behavioral insights.
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 concise and well-structured, with each sentence adding value. It is front-loaded with the core action and uses clear, direct language without unnecessary verbosity.
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 (3 parameters, output schema exists, annotations present), the description is comprehensive. It explains slot numbering, value handling, error conditions, and integration with sibling tools. The output schema exists but is not discussed, which is acceptable per the evaluation rules.
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 adds meaning to the slot parameter (numbered 1..15 inclusive) and the value parameter (any type, sent verbatim, None to clear). The task_id parameter is implied from the context but not explicitly described. Since schema coverage is 0%, this description compensates effectively for most parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Set or clear one of the 15 custom_field_* slots on a task', specifying the exact resource and operation. It distinguishes itself from the sibling tool 'update_task' by explicitly noting the difference in handling None values, making the purpose 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 provides explicit guidance on when to use the tool, including pairing with 'list_custom_field_definitions' to learn slot labels/types, and when to pass value=None to clear a slot. It also warns about common 422 errors and suggests inspecting slot type/options, offering clear context for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new time tracker on a task for the authenticated user.
Returns the created TimeTracker. The new timer starts in the
running state (ended_at is None); call stop_timer when
work pauses or ends.
board_id is required by the Kanban Tool API but may be omitted
here — when not supplied the tool resolves it via an internal
get_task(task_id) call (one extra HTTP round-trip). Pass it
explicitly when you already have it (e.g. you just listed tasks for a
board) to avoid the second request. Either way, the resulting wire
body sends both ids.
Note: timers are per-user — starting one creates a record for the
authenticated user only. Use whoami if you need to know whose
timer it is.
Common 422: the API rejects starting a timer on a task whose board
you don't have access to with a typed KanbanToolValidationError.
Verify the task is on a board you can list via list_boards.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| board_id | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| user_id | No | |
| board_id | No | |
| task_id | No | |
| started_at | No | |
| ended_at | No | |
| listed | No | |
| sprint_id | No | |
| seconds_from_resumed_sprint | No | |
| position | No | |
| highlighted_at | No | |
| enlist_at | No | |
| created_at | No | |
| updated_at | No | |
| is_running | Yes | True iff the timer is still active (no ``ended_at`` set). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (only idempotent hints), but the description details the running state, per-user nature, board_id resolution mechanism with extra round-trip, and error conditions. No contradictions with annotations.
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 thorough but slightly verbose; however, every sentence adds value. It front-loads the core purpose and organizes additional details in separate paragraphs.
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 presence of an output schema, the description covers return value characteristics, error handling, performance optimization, and user scope. Nothing essential is missing.
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 0% schema description coverage, the description fully explains both parameters: task_id as required, board_id as optional with performance implications. Adds meaning beyond the schema's type and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Start a new time tracker on a task for the authenticated user,' providing a specific verb and resource. It clearly distinguishes from sibling tools like stop_timer and list_my_timers.
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 explicit guidance: when to use (starting a timer), when to call stop_timer, tips for optimizing board_id, and common error scenarios. References sibling tools like whoami and list_boards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running time tracker. Returns the stopped TimeTracker.
ended_at is an ISO 8601 timestamp; defaults to the current UTC
time if not provided. Stopping an already-stopped timer is harmless —
the API just updates the ended_at to the new value.
Wire shape: PUT /time_trackers/{id}.json with a flat
{"ended_at": ...} body. Same flat-body convention as the
subtask endpoints — no {"time_tracker": {...}} envelope.
Raises KanbanToolHTTPError(404) if the timer id is unknown or
belongs to another user.
| Name | Required | Description | Default |
|---|---|---|---|
| timer_id | Yes | ||
| ended_at | No |
| Name | Required | Description |
|---|---|---|
| id | No | |
| user_id | No | |
| board_id | No | |
| task_id | No | |
| started_at | No | |
| ended_at | No | |
| listed | No | |
| sprint_id | No | |
| seconds_from_resumed_sprint | No | |
| position | No | |
| highlighted_at | No | |
| enlist_at | No | |
| created_at | No | |
| updated_at | No | |
| is_running | Yes | True iff the timer is still active (no ``ended_at`` set). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations. It explains that stopping an already-stopped timer updates ended_at (non-idempotent if different timestamps), the wire shape (PUT with flat body), and raises 404. Annotations provide readOnlyHint false, destructiveHint false, idempotentHint false, which are consistent and basic; the description enriches them with specific behaviors.
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 concise: three sentences cover main action, parameter details, wire shape, and error condition. Every sentence adds value without repetition. It front-loads the primary purpose and follows with essential details, making it efficient for an agent to parse.
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 and the presence of an output schema (presumably documenting return fields), the description covers inputs, behavior, error handling, and wire shape. It is largely complete but could explicitly mention that the returned 'TimeTracker' is the updated object after stopping. Still, it provides sufficient context for correct invocation.
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 bears full responsibility. It adds valuable detail for ended_at: 'ISO 8601 timestamp; defaults to current UTC time'. However, for timer_id, it provides no extra explanation beyond the schema's minimum and required status. While timer_id is obvious from context, a fuller description could have specified 'the ID of the running time tracker to stop'.
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 action: 'Stop a running time tracker. Returns the stopped TimeTracker.' The verb 'stop' combined with 'time tracker' precisely defines the resource and action, and the return type is specified. This effectively distinguishes it from sibling tools like start_timer (starts), delete_timer (deletes), and list_my_timers (lists).
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 explains usage context: it stops a running timer, and 'stopping an already-stopped timer is harmless' implying it can be used for ongoing or already-stopped timers. It also describes error conditions (404 for unknown or wrong user). However, it does not explicitly contrast with alternatives like delete_timer for removal, but the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partial update of an existing subtask. Returns the updated Subtask.
Only kwargs the caller passes are sent — None means omit, not
clear. Use this to mark complete (is_completed=True), rename
(name="..."), or change the assignee (assigned_user_id=42).
The position field is read-only on this endpoint; use
reorder_subtasks to change ordering.
Common 422 (KanbanToolValidationError with parsed field_errors):
assigned_user_id not a collaborator on the parent task's board —
use list_board_collaborators(board_id) to confirm before retrying.
| Name | Required | Description | Default |
|---|---|---|---|
| subtask_id | Yes | ||
| name | No | ||
| is_completed | No | ||
| assigned_user_id | No |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| is_completed | No | |
| position | No | |
| task_id | No | |
| assigned_user_id | No | |
| deleted_at | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: partial update semantics (None means omit), common 422 error with field_errors, and returned object. No contradiction with annotations.
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?
Concise, well-structured sentences with no redundancy. Every sentence adds value and is 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?
With an output schema present, the description appropriately covers usage, parameters, errors, and limitations. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema by explaining that None means omit not clear, and mentions that assigned_user_id must be a collaborator. However, not all parameters are explicitly described.
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?
States 'Partial update of an existing subtask' with specific verb and resource, differentiates from siblings like delete_subtask and reorder_subtasks.
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?
Explicit examples of when to use (mark complete, rename, change assignee) and when not to (position is read-only, use reorder_subtasks). Also provides error handling guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update a task's fields. Only the kwargs you pass are sent;
None means omit, not clear (the API ignores nulls, doesn't wipe).
Field set mirrors create_task; same wire conventions for priority,
tags, and date fields. assigned_user_id sets the single assignee —
Kanban Tool tasks have one assignee, not a list. For column/lane/position
changes prefer move_task — it's the intent-revealing surface for that
workflow.
Raises ValueError if every field is None (no-op guard).
Common 422s (KanbanToolValidationError with parsed field_errors):
lane_id from a different board → use get_board(board_id).columns
on the destination board first; assigned_user_id not a board
collaborator → list_board_collaborators(board_id) to confirm.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| name | No | ||
| description | No | ||
| board_id | No | ||
| lane_id | No | ||
| swimlane_id | No | ||
| position | No | ||
| priority | No | ||
| color | No | ||
| due_date | No | ||
| start_date | No | ||
| tags | No | ||
| assigned_user_id | No |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | Yes | |
| description | No | |
| board_id | No | |
| workflow_stage_id | No | |
| swimlane_id | No | |
| position | No | |
| priority | No | |
| color | No | |
| due_date | No | |
| start_date | No | |
| tags | No | |
| assigned_user_id | No | |
| archived_at | No | |
| block_reason | No | |
| subtasks_count | No | |
| subtasks | No | |
| comments_count | No | |
| timers_total | No | |
| time_trackers | No | |
| created_at | No | |
| updated_at | No | |
| size_estimate | No | |
| size_estimate_description | No | |
| time_estimate | No | |
| search_tags | No | |
| card_color | No | |
| card_color_in_rgb | No | |
| card_color_invert | No | |
| card_type_id | No | |
| recurring_schedule | No | |
| reminders_schedule | No | |
| linked_tasks | No | |
| linked_tasks_status | No | |
| task_dependencies | No | |
| collaborators | No | |
| attachments | No | |
| attachments_count | No | |
| created_by_id | No | |
| moved_at | No | |
| postponed_until | No | |
| subtasks_completed_count | No | |
| external_id | No | |
| external_link | No | |
| custom_fields | No | |
| is_archived | Yes | True iff the task has an archival timestamp. |
| is_blocked | Yes | True iff the task has a non-empty block reason. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes behavior beyond annotations: null means omit not clear, ValueError for no-op, common validation errors. No contradiction with annotations (destructiveHint=false, readOnlyHint=false).
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 well-structured with paragraphs and bullet points, front-loaded with core purpose. It is slightly lengthy but remains clear and organized.
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 13 parameters and 0% schema description coverage, the description adequately explains semantics, error handling, sibling tool relationships, and common issues. Output schema exists but not needed for completeness.
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?
Although schema coverage is 0%, the description adds meaning for key parameters like assigned_user_id and references conventions for priority, tags, date fields. It doesn't cover all 13 parameters individually but provides enough 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 'Partially update a task's fields' and specifies that only passed kwargs are sent. It distinguishes from move_task and create_task, showing unique 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?
Explicitly states when to prefer move_task for column/lane/position changes. Warns about common 422 errors and directs to use get_board and list_board_collaborators. Provides clear when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the authenticated user's profile.
Returns the User you're acting as — id, name, role flags, locale,
timezone. Use this to resolve "me" / "myself" references in user
requests (assign to me → assigned_user_id from this response)
or to show the LLM whose perspective it's operating from.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| name | No | |
| initials | No | |
| is_account_admin | No | |
| is_account_owner | No | |
| is_project_manager | No | |
| is_suspended | No | |
| last_activity_on | No | |
| last_login_at | No | |
| created_at | No | |
| timezone | No | |
| locale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds value beyond the readOnlyHint annotation by detailing the returned fields and use cases. No contradictions with annotations.
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 with minimal redundancy. Front-loaded purpose, then details and usage guidance. Every sentence earns 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?
Fully adequate given zero parameters, an output schema, and the tool's simple nature. Covers purpose, return fields, and usage context.
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 in the input schema, so the description doesn't need to add semantic meaning. Perfectly fine.
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?
Clearly states it fetches the authenticated user's profile with specific fields (id, name, role flags, locale, timezone). The verb 'fetch' and resource 'profile' are precise, distinguishing it from sibling tools like get_user which likely retrieves other users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use the tool: to resolve 'me'/'myself' references or to show the LLM's perspective. While it doesn't mention alternatives or when not to use it, the context is clear for a simple identity tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource and action (e.g., add_comment vs add_subtask, start_timer vs stop_timer). There is no overlap in purpose, and descriptions clearly differentiate them.
Almost all tools follow a consistent verb_noun pattern in snake_case (e.g., create_task, list_boards, delete_comment). Exceptions like 'ping' and 'whoami' are standard conventions and do not disrupt coherence.
With 26 tools, the set is slightly larger than ideal but still well-scoped for a comprehensive Kanban server. Each tool serves a clear purpose without redundancy.
The surface covers core workflows (CRUD for tasks, subtasks, comments, timers, boards, users, search, and custom fields). Minor gaps include the absence of a delete_task tool and an update_comment tool, but these are acceptable for the domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Remote MCP for Kanban AI boards—manage projects, tasks, and comments from AI tools.
AI-native Kanban board — connect Claude to claim, work and move your tasks over MCP.
Kanban board for teams and coding agents: manage tasks, subtasks, sprints and wiki pages via MCP.
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/VeryLongOrgNameSuchWow/kanbantool-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
