BoardMark

Bring back an older version as a NEW version (history is never rewritten). Also undeletes a deleted doc. Brief: project admins only (403 `doc_admin_only`).

restore_doc_version

Bring back an older version as a NEW version (history is never rewritten). Also undeletes a deleted doc. Brief: project admins only (403 doc_admin_only).

Undo a bad edit: brings back the version at at (a commit from get_doc_history) as a NEW version — history is never rewritten. version = the doc's current version from get_doc, or null when the doc is deleted (this also undeletes it). Brief (project admins only, 403 doc_admin_only), notes and handoffs.

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
`at`	Yes	The `commit` of the version to bring back (get_doc_history).
`kind`	Yes
`slug`	Yes	File name of a doc without `.md`: lowercase a–z 0–9 and `-` (brief, notes, company brief) or `H-{n}` (handoffs).
`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
`version`	Yes	Current version of the doc; null when it is deleted.
`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.2/5.0

Behavior4/5

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

Goes well past the annotations by disclosing that history is never rewritten (non-destructive append), that a null version triggers undelete, the admin-only gate with 403 `doc_admin_only`, and 409 `version_conflict` handling with re-read/re-apply/ask-user guidance. The concurrency paragraph is partly boilerplate lifted from issue tools (get_issue, list_comments, list_sprints), which weakens the specificity a bit.

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 core behavior is front-loaded, but the description opens by duplicating the title verbatim, then repeats the 'NEW version — history is never rewritten' claim three times. The trailing WRITE paragraph is generic write-tool boilerplate referencing issue and comment tools irrelevant to restoring a doc.

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 mutation with no output schema, it covers permissions, the failure mode (409 with details.current/details.current_version) and the version-lock contract, which is what an agent needs to call it safely. It does not say what the call returns (presumably the new version number), leaving one 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?

With 71% schema coverage the baseline is 3, and the description earns more: it ties `at` to the `commit` field returned by get_doc_history, explains `version` = current version from get_doc or null-when-deleted, and enumerates the `kind` values (brief, notes, handoffs) that the schema leaves undocumented. `message` and `reason` semantics are left to the schema.

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 ('brings back the version at `at` as a NEW version') and adds a second, distinct behavior ('also undeletes a deleted doc'). That instantly separates it from update_doc, create_doc and get_doc_history in the sibling list.

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 a concrete scenario ('Undo a bad edit') and names the upstream tools that supply its inputs (get_doc_history for `at`, get_doc for `version`), including the null-version case for deleted docs. It never explicitly says when to prefer update_doc over a restore, so it stops short of full when/when-not routing.

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?