BoardMark

Say you have read a handoff (members). An open handoff becomes acknowledged; the writer is told.

acknowledge_handoff

Say you have read a handoff (members). An open handoff becomes acknowledged; the writer is told.

When you have read a handoff addressed to you (list_docs for_me: true, or get_project docs.open_handoffs_for_me > 0), call this with the version from get_doc: an open handoff becomes acknowledged and its writer is told. Do this only after you have actually read it. It does not close the handoff (update_doc status: closed does).

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
`slug`	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.
`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.3/5.0

Behavior4/5

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

Annotations already declare non-read-only, non-destructive, non-idempotent, but the description adds the side effect that matters ('its writer is told') and a full 409 version_conflict protocol with details.current / details.current_version, re-read-and-retry, and 'never overwrite blindly; ask the user'. It stops short of saying what happens if you acknowledge twice, which matters given idempotentHint=false.

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?

The first two sentences are front-loaded and tight, and the open/close distinction is placed immediately after the action. The trailing WRITE paragraph is largely shared boilerplate that enumerates unrelated reads (list_comments, list_sprints, get_issue) not relevant to acknowledging a doc handoff, which is modest noise.

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?

No output schema exists, so the description carries the burden, and it covers preconditions, the version source, the notification side effect, and conflict recovery. Two gaps remain: nothing about repeated acknowledgments despite idempotentHint=false, and no explanation of whether `reason` is meaningful here.

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

Parameters3/5

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

Schema coverage is 75%, so the schema already documents project_key, version, and reason. The description adds real value for `version` by telling the agent where to obtain it (get_doc, get_issue, read_file) and that it is the latest read, but says nothing about `slug` (H- pattern) or when `reason` is worth sending, leaving it close to baseline.

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 ('Say you have read a handoff') plus the resulting state change ('an open handoff becomes acknowledged; the writer is told'). It explicitly distinguishes the adjacent operation by noting it does not close the handoff and that update_doc `status: closed` does, so an agent can separate it from update_doc without opening either schema.

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?

Gives concrete discovery paths that identify the precondition (list_docs `for_me: true`, or get_project `docs.open_handoffs_for_me` > 0), the required input source (the `version` from get_doc), and an exclusion ('Do this only after you have actually read it'). It also names the sibling that performs the different action (closing) instead of this one.

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

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?