Click on "Deploy 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., "@@kanbio/mcp show me my open tickets assigned to me"
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.
MCP server for Kanbio, the mini-Jira. It lets your AI (Claude Code, Claude Desktop, Cursor or any MCP client) read tickets, comment, change their status and create them, as you, through a personal access token.
It runs locally over stdio (npx -y @kanbio/mcp) and calls the Kanbio REST API.
In Kanbio, open Conectar con IA in the sidebar and create a token:
Leer y comentar (default): read tickets and comment.
Personalizado: pick the permissions (create, edit, change status, assign, plan sprints).
Projects: all yours (also the ones you join later) or some of them.
Expiration: 30 days, 90 days or never.
The token (kbn_…) is shown once. Kanbio shows the configuration ready to paste for each
client. A token never does more than you can do in Kanbio, and you can revoke it at any time.
Related MCP server: Issue Tracker MCP
Two environment variables:
Variable | Value |
| URL of the Kanbio API, e.g. |
| Your token, |
claude mcp add kanbio -e KANBIO_API_URL=https://kanbio.example.com/api -e KANBIO_TOKEN=kbn_... -- npx -y @kanbio/mcpAdd -s user (before --) to have it in every project. On Windows use -- cmd /c npx -y @kanbio/mcp.
Settings → Developer → Edit Config (claude_desktop_config.json):
{
"mcpServers": {
"kanbio": {
"command": "npx",
"args": ["-y", "@kanbio/mcp"],
"env": {
"KANBIO_API_URL": "https://kanbio.example.com/api",
"KANBIO_TOKEN": "kbn_..."
}
}
}
}Restart Claude Desktop afterwards.
Settings → MCP → Add new MCP server, or ~/.cursor/mcp.json (all projects) /
.cursor/mcp.json (one project) with the same mcpServers block as Claude Desktop.
Any MCP client that runs stdio servers: command npx, args -y @kanbio/mcp, and the two
variables above.
Tickets are identified by key (PROJ-12) and projects by key (PROJ). People by me, email or
name; sprints by active, backlog or name.
Tool | What it does | Permission |
| Projects the token reaches, with your role |
|
| Search by project, status, assignee, sprint and text, with a limit |
|
| A ticket with its description and comments |
|
| Sprints of a project |
|
| Members of a project (email and role) |
|
| Tickets assigned to you |
|
| Comment, with mentions (shown "via AI") |
|
| Move along the workflow, To Merge included |
|
| Assign or unassign |
|
| Create a ticket (backlog or a sprint) |
|
| Edit title, description, type, priority, points, labels |
|
| Move tickets to a sprint or the backlog |
|
No tool deletes anything. Read tools are marked readOnlyHint; write tools
destructiveHint: false, so clients can ask before running them.
Workflow: To Do → In Progress → [To Merge →] To Test → Done | Rejected; Done and Rejected can go back to To Test or In Progress.
API errors come back as plain sentences the AI can act on: a missing permission (403) names it and says not to retry, an invalid status change lists the allowed next statuses, an expired or revoked token (401) says how to create a new one, and 429 asks to wait a minute.
The token acts as you, limited to its permissions and projects. Start with Leer y comentar.
Text in tickets and comments is data written by people: an AI may be tricked by it (prompt injection). Keep write permissions to what you need and let your client confirm write tools.
Comments written with a token show vía IA in Kanbio, and the token's last use is visible on the Conectar con IA screen. Revoke it there if something looks wrong.
npm install
npm run build # dist/index.js
npm test # build + node:test
KANBIO_API_URL=http://localhost:4000/api KANBIO_TOKEN=kbn_... npm run inspectUse a local build from Claude Code:
claude mcp add kanbio-dev -e KANBIO_API_URL=http://localhost:4000/api -e KANBIO_TOKEN=kbn_... -- node /path/to/kanbio-mcp/dist/index.jsRequires Node.js 20 or newer.
Releases go to npm from GitHub Actions with trusted publishing (OIDC, no npm token):
Bump version in package.json (and package-lock.json: npm version <x.y.z> --no-git-tag-version), commit.
Tag it v<x.y.z> and push the tag. .github/workflows/publish.yml checks that the tag matches the version,
builds, tests and runs npm stage publish: the version goes to npm's staging area, not live yet.
A maintainer approves it with 2FA, in the Staged Packages tab on npmjs.com or with
npm stage approve <stage-id> (npm stage list shows the id). Only then it is published, with provenance.
The very first version is published by hand (npm publish --access public from a logged-in npm account), and then
the trusted publisher is set up on npmjs.com for aritzbl/kanbio-mcp and the publish.yml workflow.
Add a comment to a ticket as the token owner; Kanbio shows it with a "via AI" badge. To mention people, list them in mentions (email or name): each "@Name" already in the text becomes the mention, the rest are mentioned at the start. Mentioned people get a notification. Needs the comments:write permission.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Ticket key, e.g. PROJ-12 (case does not matter). | |
| text | Yes | Comment text (plain text). | |
| mentions | No | People to mention: emails or names of project members. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds real behavioral facts beyond them: the comment is attributed to the token owner and visibly badged "via AI" to other users, mentions trigger notifications to those people, and the call requires comments:write. These are the side effects an agent must know before invoking.
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?
Front-loads the mutation and its attribution, then covers mentions and the permission requirement in three compact sentences. Dense but each clause carries information; only the badge detail is arguably decorative.
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 3-parameter write tool with no output schema and full schema coverage, the description covers identity, user-visible effect, notification side effect, mention mechanics, and auth requirement. It does not say what the call returns or how duplicate/duplicate-mention edge cases resolve, but nothing critical to calling it correctly 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?
Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics the schema does not: the `mentions` array interacts with `text` by consuming existing "@Name" occurrences, and any unmatched entries are appended at the start of the comment. That parsing rule is not derivable from the schema's per-field descriptions.
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 a specific verb+resource ("Add a comment to a ticket") plus the identity the comment is attributed to ("as the token owner"). No sibling tool does this, so the agent can distinguish it immediately from update_ticket or create_ticket.
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?
Usage is implied by the exclusive nature of the operation — none of the siblings post comments — but the description never explicitly says when to use this versus e.g. update_ticket for discussion-style text, nor any exclusions (e.g. closed tickets). It gives operational context (mentions, permission) rather than selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign a ticket to a project member ("me", email or name), or unassign it with "none". The person must be a member of the ticket's project. Needs the tickets:assign permission.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Ticket key, e.g. PROJ-12 (case does not matter). | |
| assignee | Yes | "me", "none" to unassign, an email or a name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotent=true, destructive=false, readOnly=false. The description adds useful behavioral context beyond that: the membership requirement and the tickets:assign permission needed to succeed.
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 tight sentences with no waste; the assign/unassign duality and the special values are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with full schema coverage and annotations, the description supplies the permission and membership prerequisites an agent needs. Nothing critical is missing, though return behavior is unspecified (no output schema exists).
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 100% and both parameters are fully documented, so the description's explanation of 'me'/'none'/email/name largely restates the schema. Baseline 3 applies.
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 a specific verb (assign) and resource (ticket) and covers the unassign case explicitly. No sibling tool overlaps with assignment, so it is unambiguous against the list of related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the 'me'/'none' shortcuts and the constraint that the assignee must be a project member. It gives clear operating context but doesn't need to name alternatives since none exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a ticket to another status. Kanbio enforces the workflow: To Do → In Progress → [To Merge →] To Test → Done | Rejected; Done and Rejected can go back to To Test or In Progress. To Merge is optional and only reachable from In Progress. An invalid move is rejected with the allowed next statuses. Needs the tickets:status permission.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Ticket key, e.g. PROJ-12 (case does not matter). | |
| status | Yes | Status id: todo (To Do), in_progress (In Progress), to_merge (To Merge), qa (To Test), done (Done), rejected (Rejected). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing the state machine, the optional To Merge branch, the rejection-with-allowed-statuses error behavior, and the required tickets:status permission. These are exactly the traits an agent needs before invoking a mutation.
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?
Front-loaded with the core action, then the workflow graph in compact arrow notation. Dense but every clause carries information; the arrow chain requires a second read but is not padded.
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?
No output schema exists, and the description covers success semantics (valid transitions), failure semantics (rejection with allowed statuses), and authorization requirements. Nothing an agent needs to call this safely 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?
Schema coverage is 100% and the enum already lists the statuses, so the baseline is 3. The description adds transition semantics that constrain which status values are actually reachable, which is genuine value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Move a ticket to another status'), which cleanly separates it from siblings like update_ticket or assign_ticket. The workflow chain immediately clarifies the scope of the operation.
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 defines valid transitions and notes that invalid moves are rejected with the allowed next statuses, giving the agent enough to call correctly. It does not name a sibling alternative, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a ticket in a project, reported by the token owner. It starts in To Do. Optionally assign it (needs tickets:assign) or plan it into a sprint (needs sprints:write); otherwise it goes to the backlog. Needs the tickets:create permission.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | bug, task or story (user story). | |
| title | Yes | ||
| labels | No | ||
| sprint | No | "active" (the active sprint), "backlog", or a sprint name. | |
| project | Yes | Project key, e.g. PROJ (see list_projects). | |
| assignee | No | "me", an email, or a name of a project member. | |
| priority | No | medium | |
| description | No | ||
| story_points | No | Fibonacci: 1, 2, 3, 5, 8, 13, 21. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (non-readonly, non-idempotent, non-destructive), the description discloses the created ticket's initial status, who the reporter is, the backlog default when no sprint is given, and the three permission scopes required. These are exactly the mutation-time facts an agent cannot derive from structured fields.
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 compact sentences, front-loaded with what is created and where it starts, followed by optionality and then the hard permission gate. No filler sentences.
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 9-parameter write tool with no output schema, the description covers creation scope, defaults, and auth, which is the bulk of what's needed. It does not say what comes back (ticket key/ID) nor that repeating the call creates duplicates given the non-idempotent annotation, a minor remaining gap.
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 56%, and the description adds real semantics for two key params: omitting 'sprint' means backlog, and supplying 'assignee' triggers an extra permission requirement. It says nothing about labels, priority, description, or story_points, so several params remain schema-only.
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 a specific verb and resource ('Create a ticket in a project') plus scope details an agent needs: the reporter is the token owner and the ticket starts in To Do. The optional assign/sprint clauses also separate it from assign_ticket and move_to_sprint, which do those actions after 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?
Makes the branching condition explicit: assign and sprint are optional, and without the sprint the ticket lands in the backlog. Permission prerequisites for each optional path (tickets:assign, sprints:write, tickets:create) are spelled out. It stops short of naming sibling tools as alternatives, but the inline-vs-separate-tool choice is implied clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one ticket by key: status, type, priority, assignee, sprint, description and its comments (threads, oldest first; "via AI" marks comments written through a token).
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Ticket key, e.g. PROJ-12 (case does not matter). | |
| include_comments | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: comments are returned oldest-first and comments written through a token are flagged 'via AI', which an agent could not derive from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the field inventory earns its place. It is dense — a compact field list plus a parenthetical — but nothing is redundant.
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 no output schema, the description correctly takes on the burden of describing return contents, and it does so thoroughly for a read tool. The remaining gap is the undocumented include_comments toggle, which matters for anyone wanting a cheaper fetch.
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 50%: 'key' is fully documented in the schema (format, case-insensitivity), but 'include_comments' has no schema description at all. The description mentions comments as part of the payload but never explains that include_comments controls them or what omitting them does.
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 a specific verb ('Read') and resource ('one ticket by key') and enumerates the returned fields, which cleanly separates it from search_tickets and the list tools. An agent can tell this is the single-record fetch without opening the schema.
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 phrase 'by key' implies the selection condition, but there is no explicit when-to-use versus search_tickets (which is the natural alternative for non-key lookups) or update_ticket/change_status. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the members of a project with their email and role (pm, dev, qa), e.g. to assign or mention someone.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project key, e.g. PROJ (see list_projects). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully discloses the returned fields (email, role), but says nothing about ordering, pagination/truncation for large projects, or whether role values are exhaustive. Some added value beyond annotations, but not rich.
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?
One sentence, front-loaded with the verb and resource, then the return fields, then the use case. No filler or restatement of the title.
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 single-parameter, read-only listing tool with no output schema, the description covers purpose, returned fields, and a motivating use case. Minor gaps (result size limits, role completeness) remain but are not blocking.
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 100% for the single parameter, and the schema itself documents the project key format and points to list_projects. The description adds no parameter detail, which is acceptable given the schema does the work — baseline 3.
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 a specific verb and resource ("List the members of a project") and adds the shape of what comes back: email plus role with the enumerated values pm, dev, qa. No sibling is about project membership, so it is distinguishable by resource alone, though it does not name an alternative explicitly.
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?
"e.g. to assign or mention someone" gives a concrete context that tells an agent why to reach for this tool rather than list_projects or search_tickets. No when-not-to-use or exclusion language, which keeps it at a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Kanbio projects this token can reach, with their key (used by the other tools) and your role in each.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: results are filtered to the token's permissions and each entry carries the caller's role, which sets expectations about non-exhaustive results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, front-loading the resource and scope before the return detail. Every clause carries 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?
With no parameters and no output schema, the description must describe the return values, and it does: project key plus the caller's role, scoped by token access. Nothing needed to call it correctly 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?
The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed and instead describes the shape of the response.
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 a specific verb (list) and resource (Kanbio projects) plus the scope constraint 'this token can reach'. It also names what comes back (key and role), which distinguishes it unambiguously from the ticket-oriented siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'key (used by the other tools)' implicitly tells the agent this is the entry point that yields identifiers other tools need. There is no explicit when-not or named alternative, but the practical context 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 sprints of a project (planned and active; completed ones on request), with dates and goal.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project key, e.g. PROJ (see list_projects). | |
| include_completed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: completed sprints are excluded by default and only returned on request, and results carry dates and goal — which matters since there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with the resource first and the default-scope qualifier immediately after. No filler and nothing redundant.
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 read tool with annotations carrying the safety profile and the description covering default filtering and return content, this is nearly complete. Minor gap: nothing about result volume or ordering if a project has many sprints.
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 50%: `project` is documented in the schema while `include_completed` has no description there. The description's clause about completed sprints 'on request' effectively explains that flag, compensating for the gap rather than repeating the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list sprints of a project) plus the exact scope returned: planned and active by default, completed on request, including dates and goal. An agent can distinguish this from siblings like list_projects or move_to_sprint without inspecting schemas.
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 phrase 'completed ones on request' implies how to widen the default scope, but there is no explicit when-to-use/when-not-to guidance or named alternative. The connection to list_projects for obtaining a project key lives only in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move one or more tickets to a sprint ("active" or a sprint name) or back to the backlog ("backlog"). Completed sprints are not allowed. Needs the sprints:write permission.
| Name | Required | Description | Default |
|---|---|---|---|
| keys | Yes | ||
| sprint | Yes | "active" (the active sprint), "backlog", or a sprint name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it a non-destructive, idempotent mutation. The description adds real behavioral context beyond them: the completed-sprint restriction and the required sprints:write permission — both critical before calling.
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?
One tight sentence, front-loaded with the action and destination, followed by the key constraints. 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?
For a 2-param mutation with annotations covering safety and no output schema, the description covers permissions, allowed target values, and the completed-sprint exclusion. Return behavior isn't described but isn't essential here.
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 50%, so the description helps: it clarifies that 'sprint' accepts 'active', 'backlog', or a sprint name (matching and reinforcing the schema), and the plural phrasing signals the keys array. It doesn't mention the 50-ticket max, which the schema carries.
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 a specific verb (move) plus resource (tickets) plus destination (sprint or backlog). Clearly distinct from siblings like assign_ticket, change_status, or list_sprints.
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?
Gives clear context: move to 'active', a named sprint, or 'backlog', and excludes completed sprints. It doesn't name alternatives (e.g., use list_sprints to find a sprint name), but the when-to-use is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tickets assigned to the token owner across their projects, most recently updated first. Open ones only unless include_done.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| include_done | No | Also list Done and Rejected tickets. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: implicit owner-scoping, the default open-only filter, and most-recently-updated ordering. It stops short of describing pagination or what happens at the limit boundary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with scope and ordering front-loaded before the filter caveat. Every clause carries 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?
For a simple two-parameter read tool with no output schema, the description covers scope, default filtering, and sort order. The only meaningful omission is limit/pagination behavior, which leaves some ambiguity about result-window semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: include_done is documented in the schema, and the description reinforces its effect on the default filter. The limit parameter has no description in either place, so the agent learns nothing about it (max 50, default 20) from the description.
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 states a specific resource (tickets) with clear scope (assigned to the token owner, across their projects) and ordering. It is readily distinguishable from siblings like search_tickets or list_projects, though it never names the alternative explicitly.
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?
'Open ones only unless include_done' implies the default usage context, and 'assigned to the token owner' narrows the use case. However, there is no explicit guidance on when to prefer this over search_tickets or get_ticket, so the agent must infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search tickets across your projects, most recently updated first. Every filter is optional and they combine (AND). Returns one compact line per ticket; use get_ticket for the full ticket.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Words in the key, title or description. | |
| limit | No | ||
| sprint | No | "active" (each project's active sprint), "backlog", or a sprint name (needs project). | |
| status | No | Any of these statuses. | |
| project | No | Project key, e.g. PROJ (see list_projects). | |
| assignee | No | "me", "none" (unassigned), an email or a name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: results are ordered by most recently updated and returned as one compact line per ticket, with get_ticket for full detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and scope. Every sentence adds useful information without repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter search tool with no output schema, the description covers the essential behavior: ordering, compact output, optional filters, AND combination, and the full-detail alternative. The main omission is explicit differentiation from my_tickets, but otherwise an agent has enough to call the 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?
Schema description coverage is high at 83%, so the schema already documents most parameter meaning. The description adds that all filters are optional and combine with AND, but does not provide additional syntax or per-parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: search tickets across projects, with ordering. It distinguishes the tool from get_ticket by naming that sibling for full ticket details, but does not explicitly differentiate it from my_tickets or other listing siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that every filter is optional and filters combine with AND, and it points to get_ticket when the compact result is insufficient. It lacks explicit when-not guidance relative to siblings such as my_tickets, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit the fields of a ticket: title, description, type, priority, story points or labels. Only the fields given change. Status, assignee and sprint have their own tools. Needs the tickets:edit permission.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Ticket key, e.g. PROJ-12 (case does not matter). | |
| type | No | ||
| title | No | ||
| labels | No | Replaces every label. | |
| priority | No | ||
| description | No | New description; null clears it. | |
| story_points | No | Fibonacci: 1, 2, 3, 5, 8, 13, 21; null clears them. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the mutation is non-destructive and idempotent, so the safety profile is covered. The description adds real value beyond that: partial-update semantics and the required 'tickets:edit' permission. It doesn't mention what happens on a no-op call or what comes back, but with annotations present the bar is lower.
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 compact sentences, front-loaded with the action and field list, then the partial-update rule, then the sibling exclusions and permission. Zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, partial-update behavior, sibling routing and the required permission for a 7-parameter mutation with idempotent/destructive annotations. Without an output schema the return value is unexplained, and edge cases like an empty payload or label-replacement semantics are left to the 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 description coverage is 57%, so type, title and priority rely on enum/shape alone; the description at least enumerates the field names, mapping them to parameters. But it adds no semantics beyond the names — the important behaviors ('labels replace every label', 'null clears') live only in the schema descriptions. Baseline 3 for a partially covered schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (edit) plus resource (ticket) with an explicit enumeration of the mutable fields: title, description, type, priority, story points, labels. It also names what it does not handle — 'Status, assignee and sprint have their own tools' — which cleanly separates it from change_status, assign_ticket and move_to_sprint.
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?
States both when to use it (editing the listed fields) and when not to, routing status/assignee/sprint changes to their dedicated sibling tools. 'Only the fields given change' also tells the agent it can pass a single field without touching the rest.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1add_commentassign_ticketchange_statuscreate_ticketget_ticketlist_memberslist_projectslist_sprintsmove_to_sprintmy_ticketssearch_ticketsupdate_ticketScored across 12 tools
Each tool targets a distinct action-resource pair: status, assignee, and sprint moves are deliberately split into change_status, assign_ticket, and move_to_sprint, and update_ticket explicitly excludes them. The only slight overlap is my_tickets vs search_tickets, but the descriptions make the boundary clear (assigned-to-me shortcut vs filtered search).
The set is overwhelmingly consistent verb_noun (list_projects, create_ticket, update_ticket, change_status, assign_ticket, move_to_sprint, search_tickets, get_ticket). The single deviation is my_tickets, a noun-only name with no verb, which breaks the pattern but is still readable.
Twelve tools is well within the ideal range and each one maps to a concrete workflow step (discovery, read, search, create, edit, status, assign, sprint, comment, members). No tool appears redundant or filler.
Ticket lifecycle is well covered: create, read, search, edit, status transitions with documented workflow, assignment, sprint placement, and commenting via get_ticket. Minor gaps exist (no ticket delete/archive, no sprint creation despite list_sprints, no comment editing), but core agent workflows are not blocked.
Opinionated sprint tracker. Read/update tickets, sprints, velocity from Claude/Cursor/Zed.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task and sprint coordination for humans and AI agents, with scoped API keys and full audit trail.