BoardMark

Add a comment. Attach files first via request_upload → PUT → attach_file.

add_comment

Add a comment. Attach files first via request_upload → PUT → attach_file.

Body: markdown. 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. A new comment needs no version. To attach files, upload first (request_upload → PUT → attach_file) and pass the returned paths in attachments. To SHOW an image (screenshot) inline, also write ![file name](path) in the body where it belongs (a path with a space or a parenthesis goes in angle brackets: ![file name](<path>)) — BoardMark renders it as a picture and drops its chip; never paste base64 / data: URLs (they are not shown). To REPLY to a comment, pass its seq (from list_comments) as reply_to; omit it (or null) for a new top-level comment. Replying to a reply is fine: the server files it under that thread's top-level comment (returned frontmatter.reply_to) while frontmatter.in_reply_to keeps the comment you answered. A seq that does not exist on this issue → 400 validation_failed (field reply_to). The author of the comment you answer is notified by email. To mention someone (they get an email), write [@Their Name](mention:usr_…) with their user id and name from list_people (the reporter: the issue's reporter); only people who can open the project are notified. Commenting makes you (the token's user) a watcher of the issue.

Input Schema

Name	Required	Description
`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).
`reply_to`	No	Reply to comment `seq` (D59). Stored as `in_reply_to` = this seq and `reply_to` = its thread root (a reply to a reply belongs to the top-level comment); an unknown seq → 400 validation_failed.
`issue_key`	Yes	Issue key `{PROJECT}-{n}`, e.g. `KJ-101`.
`attachments`	No
`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.5/5.0

Behavior5/5

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

Discloses side effects that annotations cannot express: the answered author gets an email, mentioning a person emails them but only if they can open the project, and commenting makes the token's user a watcher. It also names the exact failure mode ('A seq that does not exist on this issue → 400 validation_failed (field reply_to)') and clarifies that replying to a reply re-files under the thread root.

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

Conciseness4/5

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

Long but front-loaded and dense — every sentence after the opening carries operational detail (colour semantics, image embedding, mention ids, threading). Slight deduction: the first sentence duplicates the title verbatim and the upload chain is stated twice.

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?

A mutation tool with no output schema; the description covers side effects, error mode and threading adequately. It never states what the call returns (e.g. the new comment's `seq`, which the agent needs for later reply_to targets), which is the main remaining gap.

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 67%, and the description compensates for the uncovered/underspecified parts: markdown/colour conventions with allowed values and semantics, inline image syntax including the angle-bracket escape for paths with spaces, the mention URI format sourced from list_people, and the reply_to threading rules. The `reason` parameter is documented only in the schema, keeping it from a 5.

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?

Opens with a specific verb+resource ('Add a comment') and immediately scopes it against its siblings: reply vs. new top-level comment, attachment flow via request_upload → PUT → attach_file, and mentions. An agent can distinguish this from update_comment, delete_comment and list_comments without opening any 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 routing rules: 'To REPLY to a comment, pass its seq... omit it (or null) for a new top-level comment', plus the prerequisite chain request_upload → PUT → attach_file. It does not explicitly say when to use update_comment instead of posting a new one, so it stops short of a full 5.

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?