Skip to main content
Glama

BoardMark

by ai.boardmark
OverviewDiscussionsAdmin

Create an issue (key is assigned by the server)

create_issue

Create an issue (key is assigned by the server).

The key (e.g. KJ-102) is assigned by the server. priority is highest, high, medium, low or lowest (default medium) — set it when the user or the issue makes it clear. status defaults to the first status of the project (Backlog on kanban and pipeline boards). sprint has no default (scrum only — kanban and pipeline issues have none): omit it (or null) for the backlog, or pass a sprint id. Several sprints can be active at once when the project has parallel sprints on — if the user says "the current sprint" and list_sprints (state=active) shows more than one, ask which. Custom fields (spec D129): pass values in fields keyed by the field id from get_project fields — text / select / customer / url / person = string (select: one of the field's options; person: a user id from list_people), number / money = number (money is kept with 2 decimals in template_settings.currency), date = YYYY-MM-DD. Only fields whose types include the issue's type are accepted and required ones must be present (else 400 invalid_field_value, details.expected = required); an id the project does not define → 400 unknown_field; a formula field is never written (400 formula_readonly — read it in computed). Sales & Billing (D130): a deal is a task (customer, amount, quote_no, payment_terms, sent_at, signed_at, valid_until, owner); an installment is a subtask with parent = the deal key and fields amount, bill_on, due_on (invoiced_at, invoice_no, paid_at, paid_amount come later) — its state Not yet → Invoiced → Paid is derived from invoiced_at / paid_at, not from status, so leave status out. Service desk: a request is a task — set fields.requester to the person you take it for (ask who when unclear); sla_due defaults from urgency and the project's sla_days. Budget planning: a budget line is a task with planned (and actual); remaining is a formula. Roadmap & Goals (D131): a goal is a task with start and end (required, YYYY-MM-DD), quarter, owner, reach / impact / confidence / effort; score, progress and linked are computed (formula / rollup → 400 formula_readonly if sent). A key result is a subtask of the goal. Feedback / Idea box (D143): an idea is a task, a bug a bug (no epic or subtask); area is optional; new posts start in New. links may point at issues of other projects of the company (you must open both — 403 link_target_forbidden) and, with type delivers, at a release KEY/R-n. working / touches (D179) may be set on create when you create a card you start at once. Body: Optional colour (D137, use sparingly; markdown stays the main format): <mark>text</mark> highlights (yellow; or <mark data-color="green">), <span data-color="red">text</span> colours text; colours yellow, green, red, blue, purple (e.g. green = passed / expected, red = bug / actual, purple = question); any other HTML is shown as plain text; keep the open and close tag in the same paragraph.

Input Schema

NameRequiredDescriptionDefault
bodyNo
typeYes
titleYes
fieldsNoCustom field values (spec D129 (3), (6)), keyed by the project's field ids (get_project `frontmatter.fields`): text / select / customer / url / person = string, number / money = number, date = `YYYY-MM-DD`. Merged key by key with the stored values; `null` deletes a key. Unknown id → 400 `unknown_field` (details.field); wrong type, option not in `options`, bad date or url → 400 `invalid_field_value` (details.field, details.expected); formula field → 400 `formula_readonly`; a `required` field missing on create → 400 `invalid_field_value`.
labelsNo
parentNo
pointsNo
reasonNoSpec D144: why you make this change (≤ 200 characters). Optional, but give it when you act as an agent account — it is shown in the agent's run log ("moved KJ-12 To Do → In Progress because <reason>"). board-mcp records it in `agent.run`; board-core / board-files accept it and ignore it (it never changes the file, the version or the history).
sprintNo
statusNoDefaults to the first status of the project.
releaseNoReleases on only (D113); a planned release of this project.
touchesNoSpec D179: the files, modules or APIs your work changes (≤ 10 entries of ≤ 120 characters, e.g. `board-core/internal/engine/`), the complete list. `null` or [] clears it.
workingNoSpec D179: what you are doing on this card, how and why (markdown, ≤ 600 characters) — read by the next agent or person on a linked card. Write it when you start and again only when your approach changes, not every step. `null` or "" clears it. Stamps `working_at` / `working_by`; cleared by board-core when the issue enters a done status.
assigneeNoA person `usr_…` or an agent account `agt_…` (D144) from list_people.
priorityNohighest / high / medium / low / lowest; default medium (D89).medium
severityNoBug severity (D113), every plan.
project_keyYesProject key, e.g. `KJ`. 2–10 chars, uppercase letters and digits, starts with a letter.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / touches
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "maxLength": 120,
+        "minLength": 1,
+        "type": "string"
+      },
+      "maxItems": 10,
+      "type": "array",
+      "uniqueItems": true
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Spec D179: the files, modules or APIs your work changes (≤ 10 entries of ≤ 120 characters, e.g. `board-core/internal/engine/`), the complete list. `null` or [] clears it."
+}
    • addedInput schema / properties / working
      Added value: +{
+  "description": "Spec D179: what you are doing on this card, how and why (markdown, ≤ 600 characters) — read by the next agent or person on a linked card. Write it when you start and again only when your approach changes, not every step. `null` or \"\" clears it. Stamps `working_at` / `working_by`; cleared by board-core when the issue enters a done status.",
+  "maxLength": 600,
+  "type": [
+    "string",
+    "null"
+  ]
+}
  2. Changed3 schema fields changed
    • changedInput schema / properties / assignee / anyOf
      Previous value: -[
-  {
-    "description": "User id: `usr_` + ULID.",
-    "pattern": "^usr_[0-9A-HJKMNP-TV-Z]{26}$",
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "description": "Who an issue can be assigned to or @mentioned (spec D144): a person `usr_…` or an agent account `agt_…` listed by list_people for the project. One pattern (not anyOf) so generated types and MCP tool inputs stay a plain string.",
+    "pattern": "^(usr|agt)_[0-9A-HJKMNP-TV-Z]{26}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / assignee / description
      Added value: +"A person `usr_…` or an agent account `agt_…` (D144) from list_people."
    • addedInput schema / properties / reason
      Added value: +{
+  "description": "Spec D144: why you make this change (≤ 200 characters). Optional, but give it when you act as an agent account — it is shown in the agent's run log (\"moved KJ-12 To Do → In Progress because <reason>\"). board-mcp records it in `agent.run`; board-core / board-files accept it and ignore it (it never changes the file, the version or the history).",
+  "maxLength": 200,
+  "type": "string"
+}
  3. First observed

TDQS

A3.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing defaults for status, priority and sla_due, which fields are computed and reject writes (400 formula_readonly), the specific 400/403 error codes and their meanings, the cross-project link restriction (403 link_target_forbidden), and that the key is server-assigned. This is the kind of behavior an agent cannot get from the schema or annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core facts are front-loaded, but the body is a single dense paragraph of several hundred words stitched together with internal spec references (D129, D130, D131, D137, D143, D179) that the agent cannot resolve. Domain playbooks for sales, service desk, budget, roadmap and feedback could be structured or trimmed rather than run together.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 17-parameter mutation tool with no output schema, it covers defaults, error modes and the major domain shapes well. But it never says what the call returns (whether the created issue/key comes back), leaves several parameters unexplained, and the phantom `links` parameter creates a mismatch with the schema the agent will actually see.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 59% schema coverage, the description does add real semantics for `fields` (id keys from get_project, per-type value mapping, required/unknown/formula failure modes), `priority`, `status` and `sprint`. However it silently omits meaning for labels, points, parent, assignee, release, severity and reason, and it discusses a `links` parameter that does not exist in the schema (additionalProperties is false) — a misleading detail that offsets some of the added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a clear verb and resource ('Create an issue') and adds the non-obvious fact that the key is server-assigned, which an agent needs so it doesn't try to supply one. It does not explicitly distinguish itself from update_issue or name a sibling, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to guidance: set priority only when the user or issue makes it clear, omit sprint for the backlog, ask which sprint when parallel sprints are active, ask who the requester is when unclear, and leave status out for installments. That is real decision guidance, though there is no explicit statement of when not to use this tool versus alternatives such as update_issue.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All BoardMark toolsInspect
Try in Browser
Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources