BoardMark

Edit your own comment (requires version)

update_comment

Destructive

Edit your own comment (requires version).

Only the comment's author may edit it (an agent: the owner of its token). Send the full new body and the version you read; stale → 409 version_conflict. Imported comments whose Jira author was not matched cannot be edited. No new notification is sent.

Edit a comment's text: only its author may (for an agent, the user who owns the token) — others get 403 not_author; an imported comment whose Jira author was not matched cannot be edited (403 import_author_locked). Pass the comment's seq and version from list_comments and the COMPLETE new body; attachments (optional) is the complete new list. Edit only when the user asks or to correct your own comment; no new email is sent. 409 comment_deleted = it was deleted — do not retry. Colour and highlighter in the body: see add_comment.

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
`seq`	Yes	The comment number (`seq`, as in `#c-3`).
`body`	Yes
`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).
`version`	Yes	Optimistic-lock version of the file; +1 on every write. Every write must send the version it read.
`issue_key`	Yes	Issue key `{PROJECT}-{n}`, e.g. `KJ-101`.
`attachments`	No	The complete new list; omitted = unchanged.
`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 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.4/5.0

Behavior5/5

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

Goes well past the annotations, which only say destructive/non-idempotent/non-read-only. It discloses the exact permission model (403 not_author, 403 import_author_locked), the optimistic-lock failure mode (409 version_conflict with details.current / current_version) and the required re-read/re-apply/retry protocol, the 409 comment_deleted no-retry rule, and that no email notification is sent — none of which is derivable 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.

Conciseness3/5

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

The content is front-loaded and the WRITE protocol is well separated, but the same facts are stated twice — author-only editing, import_author_locked, and 'no new notification' appear in both the opening paragraph and the 'Edit a comment's text' paragraph. Roughly a third of the text is redundant restatement.

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

Completeness4/5

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

For a destructive, version-gated write with no output schema, it covers permissions, conflict handling, and failure modes thoroughly. The remaining gap is the return value: an agent that must chain another write needs to know whether a new `version` is returned, which is neither in an output schema nor in the description.

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

Parameters4/5

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

Schema coverage is already 86%, so the baseline is 3, but the description adds real meaning: `seq` and `version` must come from a prior read (list_comments), `body` must be the COMPLETE replacement, and `attachments` is a full-list replacement. It still does not explain `reason` beyond the schema text.

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 and resource ('Edit your own comment') plus the hard prerequisite ('requires version'), which immediately separates it from add_comment and delete_comment. An agent can identify the operation and its scope 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.

Usage Guidelines4/5

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

Gives explicit selection guidance: 'Edit only when the user asks or to correct your own comment', and points to list_comments/get_issue as the source of `seq`/`version` and to add_comment for body formatting. It never names a sibling to use instead for the alternative case (add_comment vs delete_comment), so the routing is implied rather than fully enumerated.

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?