BoardMark

Edit a doc (notes and handoffs: members; brief: project admins only, 403 `doc_admin_only`). Send the `version` from get_doc; change any fields in one call. Close a handoff with `status: closed`.

update_doc

Destructive

Edit a doc (notes and handoffs: members; brief: project admins only, 403 doc_admin_only). Send the version from get_doc; change any fields in one call. Close a handoff with status: closed.

Call get_doc first and pass its version. body is the COMPLETE new markdown (not a diff or an appended piece): take the current body from get_doc, change it and send all of it. Change any fields (title, body, and for handoffs to, issues, status) in ONE call — one call makes one new version. Keep working notes current: when you learn something the next person (or agent) needs — progress, decisions, rules, gotchas — add it to the notes; this is optional, use your judgement. Handoffs: status: closed closes one (or open reopens it); to say you have read one use acknowledge_handoff instead. One doc is at most 1 MB (413 doc_too_large). Notes: labels (D182) is the complete list, [] clears. Say in message what changed. The company brief is read-only here; the project brief is for project admins (403 doc_admin_only otherwise) — put what you learned in the working notes, never rewrite the rules. Optional colour (D137, use sparingly; markdown stays the main format): text highlights (yellow; or ), text 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.

WRITE: version = from your latest read (get_issue, list_comments, list_sprints, get_doc, read_file). 409 version_conflict (details.current, details.current_version): re-read, re-apply your change, retry — never overwrite blindly; when the changes disagree, ask the user.

Input Schema

Name	Required	Description
`to`	No	Handoffs only.
`body`	No	The complete new markdown body.
`kind`	Yes	Project docs (spec D76): `brief` = why the project exists, goals, business and tech structure; `notes` = working notes / progress; `handoffs` = hand-over to teams or the whole project; `company_brief` = the company's rules and guidelines (read-only in project routes).
`slug`	Yes	File name of a doc without `.md`: lowercase a–z 0–9 and `-` (brief, notes, company brief) or `H-{n}` (handoffs).
`title`	No
`issues`	No	Handoffs only.
`labels`	No	Notes only (D182): labels that scope the note to the cards carrying any of them — get_issue_context shows the matching notes (newest 3) in "Notes for this card". The complete list; [] clears. Other kinds → 400 validation_failed.
`reason`	No	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).
`status`	No	Handoffs only: close it, or reopen it. Acknowledge with acknowledge_handoff.
`message`	No	What changed, shown in the doc history.
`version`	Yes	Optimistic-lock version of the file; +1 on every write. Every write must send the version it read.
`project_key`	Yes	Project key, e.g. `KJ`. 2–10 chars, uppercase letters and digits, starts with a letter.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 22, 2026

addedInput schema / properties / labels

Added value: +{
+  "description": "Notes only (D182): labels that scope the note to the cards carrying any of them — get_issue_context shows the matching notes (newest 3) in \"Notes for this card\". The complete list; [] clears. Other kinds → 400 validation_failed.",
+  "items": {
+    "description": "Label: no whitespace or commas.",
+    "maxLength": 50,
+    "minLength": 1,
+    "pattern": "^[^\\s,]+$",
+    "type": "string"
+  },
+  "maxItems": 10,
+  "type": "array",
+  "uniqueItems": true
+}

Changed1 schema field changedOct 13, 2026

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"
+}

First observedOct 9, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well past the annotations: the 1 MB cap with 413 doc_too_large, the 403 doc_admin_only path, the fact that one call creates one new version, and a full conflict protocol (409 version_conflict with details.current/details.current_version → re-read, re-apply, retry, ask the user when in doubt). It also discloses that unrecognised HTML degrades to plain text, which is a real side effect the agent could not infer. This is consistent with destructiveHint=true and idempotentHint=false — the whole version/conflict story explains why retries are not safe.

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

Conciseness3/5

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

Information-dense and broadly front-loaded, but the version instruction appears four times (title, opening paragraph, 'Call get_doc first', WRITE section) and the title is pasted verbatim as the first sentence of the body. The colour/markup paragraph, while useful, is long relative to its importance compared with the conflict-handling text.

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

Completeness5/5

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

For a 12-parameter mutation with no output schema, the description covers everything needed to call it correctly: which doc kinds are writable, which fields belong to handoffs vs notes, the whole-body replacement rule, the concurrency contract, the size limit, and the history-visible `message`. Nothing material is left for the agent to guess.

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

Parameters5/5

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

Schema coverage is already 92%, so the baseline would be 3, but the description adds genuinely load-bearing semantics the schema lacks: `body` is the COMPLETE new markdown, not a diff or an append (the single most common failure mode here), `labels` is the complete list and [] clears it, `message` is what gets shown in history, and `version` must come from the latest read or get_issue/list_sprints/read_file.

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

Purpose5/5

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

States a specific verb+resource (edit a doc) and immediately scopes it by kind and by who may do it (notes/handoffs: members; brief: project admins, 403 doc_admin_only). It also names the sibling that covers the adjacent action (acknowledge_handoff for marking read), so the agent can tell it apart from create_doc, delete_doc and acknowledge_handoff without opening schemas.

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

Usage Guidelines5/5

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

Explicit when-to-use: 'Call get_doc first and pass its version', 'change any fields ... in ONE call', 'to say you have read one use acknowledge_handoff instead', and 'put what you learned in the working notes, never rewrite the rules' for the read-only company brief. It names the alternative tool and the condition that selects it, and states the exclusions (company_brief read-only, notes vs handoffs field scope).

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

All BoardMark tools Inspect

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

Need Help?