BoardMark

Create or replace one md file (validated exactly like the typed operations)

write_file

DestructiveIdempotent

Create or replace one md file (validated exactly like the typed operations).

version: null creates the file and fails with 409 if it already exists. An existing comment cannot be changed here (403) — use update_comment / delete_comment (D90). project.md (D102): the status keys color, meaning, source and removing are kept from the stored file (values sent are ignored) — they change only through the web column editor. Columns need Premium here too (D102, D100): on a company that is not on Premium, a project.md write whose statuses differ from the stored ones in any way (a status added, removed, renamed, reordered, or its category changed — colour / meaning are ignored as above) → 403 plan_required (details.plan premium; board-tenant unreachable → 503 unavailable), with one exception on every plan: adding the default Backlog column to a kanban board (D61, board-web's "Add Backlog column") — {id: backlog, name: Backlog, category: todo} put first while every stored status stays as it was, in the same order (transitions may change with it). On Hold (D81) stays on update_project_settings on every plan. On Premium the write is checked like update_board_columns: at least one done-category column (422 no_done_column), names unique ignoring case and surrounding spaces (422 duplicate_name, details.names), a stored kanban / pipeline Backlog column stays first (422 backlog_column, D105), and a column being emptied by a column job cannot be dropped (409 column_job_running, details.ids); like before, write_file does not move issues of a removed status (use the column editor for that). Other keys of project.md are not affected.

Validated exactly like the typed tools. Prefer the typed tools (update_issue, add_comment, …) — use this for md content they do not cover. version: null creates a new file (409 if it already exists). docs/… paths are refused here: write project docs with create_doc / update_doc / delete_doc / restore_doc_version. Existing comments are edited only with update_comment / delete_comment. project.md: keep statuses as you read them — changing the board columns (add, remove, rename, reorder, category) needs the Premium plan (else 403 plan_required) and is meant for the web column editor; template, fields, saved_filters and timeline are read-only here too (the field editor, the filter popover and the Fields settings in the web app). An issue's fields in its frontmatter is checked exactly like update_issue fields (400 unknown_field / invalid_field_value / formula_readonly — rollup fields included) and its links like link_issues (cross-project keys, delivers → KEY/R-n).

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
`body`	Yes
`path`	Yes	A path inside `/c/{company_id}/p/{project_key}/` (spec §3.3). Nothing outside this layout can be written. `releases/…` (D113) are read here but written only through the release operations; people who do not manage releases (and their agents) read them as get_release shows them (gate / baseline / scope_log blanked; diff and history of a release file → 403), and every read answers 403 feature_disabled while releases are off. `docs/…` paths (D76) can be read, listed, diffed and shown in history here, but are written only through the docs operations (write_file refuses them).
`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).
`message`	No	Commit message; generated when omitted.
`version`	Yes
`frontmatter`	Yes
`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?

Annotations only say this is a destructive, non-read-only write; the description adds substantial behavior beyond that: 409 on `version: null` create collisions, 403 on comment files, Premium plan gating for `project.md` `statuses` with the Backlog-column exception, 422 codes (no_done_column, duplicate_name, backlog_column), 409 column_job_running, and a full version-conflict recovery protocol (re-read, re-apply, retry, ask the user). It also discloses a consequential side effect — write_file does not move issues of a removed status.

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 first sentence is a good front-load, but the body is a dense wall of spec citations (D90, D102, D61, D81, D105, D113, D76, D144) with clear duplication: the `version: null` / 409 rule appears twice near-verbatim, "validated exactly like the typed tools" is restated, and the project.md Premium/statuses constraint is explained twice. That redundancy crowds out the information an agent actually needs at call time.

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, high-complexity write tool with no output schema and a free-form `frontmatter` object, the description covers the critical decision points: allowed paths, plan gating, conflicts, and validation parity with typed tools. It does not describe the response payload or the success/history shape, which would matter given idempotentHint=true and a destructive write.

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 moderate (57%) and `body` and `frontmatter` are undocumented in the schema, but the description compensates by explaining `version` semantics (null creates, otherwise from latest read), `frontmatter` validation (project.md read-only keys, issue `fields` validated like update_issue, `links` like link_issues), and which reads supply the version. `body` is left entirely implicit, which is the only real gap.

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?

The description opens with a specific verb+resource ("Create or replace one md file") and immediately frames the scope against siblings by saying it is "validated exactly like the typed operations" and should be preferred only for md content the typed tools do not cover. Combined with the path pattern, an agent can tell this is a raw file-write escape hatch rather than an issue/comment/doc operation.

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?

It names alternatives and the conditions that select them explicitly: "Prefer the typed tools (update_issue, add_comment, …)", docs paths go through create_doc / update_doc / restore_doc_version, existing comments only via update_comment / delete_comment, and release files via the release operations. When-not-to-use is as clearly stated as when-to-use.

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?