Label Tools

Five tools for managing labels: get (list a project's labels), create, update, delete, and sync-issue-labels (set the labels on a single issue).

Labels are project-scoped tags you attach to issues to categorise them. To see which labels an issue carries, read prepare-issue-context (full {id, name, color} objects), search-issues / get-my-issues ({id, name} objects in labels, plus label_ids). To resolve a label_id to its colour, use get-labels or prepare-project-context.

Permission Model

• Getting labels: requires Labels: Read permission
• Creating labels: requires Labels: Create permission
• Updating labels: requires Labels: Update permission
• Deleting labels: requires Labels: Delete permission
• Setting an issue's labels (sync-issue-labels): requires Issues: Update permission — attaching labels is an edit to the issue, not a label mutation
• Project owners and admins bypass all permission checks

Enums

Colors

Value	Color
0	Grey
1	Green
2	Blue
3	Red
4	Purple
5	Yellow
6	Orange
7	Teal
8	Pink
9	Indigo

get-labels

List a project's labels with id, name, color, and display order. Read-only and safe to call repeatedly.

Parameters

Parameter	Type	Required	Description
project_id	integer	Yes	The project to get labels for

Behavior

• Returns labels ordered by their display order
• Each label includes id, name, color (0–9), order, created_at, and updated_at
• Use label.id as label_ids when filtering search-issues or attaching labels via create-issue / sync-issue-labels
• Marked as #[IsReadOnly] and #[IsIdempotent]

Example Prompt

What labels does the kendo project have?

create-label

Create a new label in a project.

Parameters

Parameter	Type	Required	Description
project_id	integer	Yes	The project to create the label in
name	string	Yes	Label name (max 255 characters, unique within the project)
color	integer	Yes	Color code (0–9, see table above)
order	integer	No	Display order (default 0, minimum 0)

Behavior

• Label names must be unique within the project — a duplicate name is rejected with a clear message
• Response includes created_at and updated_at (ISO 8601)
• Requires Labels: Create permission

Example Prompt

Add a red label called "Urgent" to the kendo project

update-label

Rename or recolor an existing label.

Parameters

Parameter	Type	Required	Description
label_id	integer	Yes	The label to update
name	string	No	New name (omit to keep current; must stay unique in the project)
color	integer	No	New color code (0–9, omit to keep current)

Behavior

• Only provided fields change; omit name or color to keep the current value
• A renamed label must stay unique within its project
• Response includes created_at and updated_at (ISO 8601)
• Requires Labels: Update permission

Example Prompt

Rename the "Urgent" label to "Critical" and make it purple

delete-label

Permanently delete a label.

Destructive

This action cannot be undone. The label is detached from any issues that carry it first, then removed. The issues themselves are kept — only the label association is dropped.

Parameters

Parameter	Type	Required	Description
label_id	integer	Yes	The label to delete

Behavior

• Issues that carried the label are preserved — only the association is removed
• Requires Labels: Delete permission

Example Prompt

Delete the "Deprecated" label from the kendo project

sync-issue-labels

Set, replace, or clear the labels on an existing issue. Pass the complete list of label IDs the issue should carry — this replaces the current set exactly.

Parameters

Parameter	Type	Required	Description
issue_id	integer	No*	The numeric ID of the issue
issue_key	string	No*	The issue key, e.g. KD-0042
label_ids	array	Yes	Complete list of label IDs the issue should carry (must belong to the same project, at most 500). Replaces the current set. Pass [] to clear all labels.

* Provide exactly one of issue_id or issue_key.

Behavior

• Replaces the issue's label set exactly with label_ids — labels not listed are detached
• Pass [] to remove all labels from the issue
• All label IDs must belong to the issue's project; a cross-project or unknown id is rejected with the same error (no existence leak)
• Requires Issues: Update permission (attaching labels is an edit to the issue)
• The response returns the issue's resulting labels as {id, name, color} objects, plus the issue's own created_at/updated_at (ISO 8601)

Example Prompt

Set the labels on KD-0042 to "Backend" and "Urgent"

See Also

• Issues — create-issue accepts label_ids; search-issues filters by label_ids
• Resources — Read project and issue data, including labels
• Projects Guide — Understanding labels and the board