Skip to main content
Glama

BoardMark

by ai.boardmark
OverviewDiscussionsAdmin

Delete a comment (requires version) — leaves a tombstone

delete_comment
DestructiveIdempotent

Delete a comment (requires version) — leaves a tombstone.

The author or a project_admin may delete; an imported comment whose Jira author was not matched only a project_admin. The file stays with an empty body and deleted: true, so its seq and replies remain; the old text stays in history. Returns the tombstone.

Only when the user asked. The author or a project_admin may delete (403 not_author otherwise). Pass seq and version from list_comments. Leaves a tombstone: the body is emptied and deleted: true is set, so the seq, replies and links stay; the old text stays in history. 409 comment_deleted = already deleted.

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

NameRequiredDescriptionDefault
seqYesThe comment number (`seq`, as in `#c-3`).
reasonNoSpec 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. board-mcp records it; the service accepts and ignores it.
versionYesVersion of the file you read. Required on every delete (spec principle 7).
issue_keyYesIssue key `{PROJECT}-{n}`, e.g. `KJ-101`.
project_keyYesProject key, e.g. `KJ`. 2–10 chars, uppercase letters and digits, starts with a letter.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • 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. board-mcp records it; the service accepts and ignores it.",
+  "maxLength": 200,
+  "type": "string"
+}
  2. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Goes well past the annotations (destructiveHint/idempotentHint) by spelling out exactly what the destructive operation does: body emptied, deleted: true, seq/replies/links preserved, old text retained in history, and it returns the tombstone. It also documents the concurrency protocol (version from latest read, 409 version_conflict with details.current, re-read and re-apply, never overwrite blindly), which is the behavior an agent most needs before writing.

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 content is right but it is stated two and three times: 'leaves a tombstone' appears in the title line, again in paragraph two ('The file stays with an empty body and deleted: true'), and again in paragraph three ('Leaves a tombstone: the body is emptied...'), and the author/project_admin rule is duplicated verbatim. Roughly half the text could be removed with zero information loss, which is the opposite of front-loaded economy.

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

Completeness5/5

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

For a destructive mutation with no output schema, this covers everything an agent needs to call it safely: mandatory version sourcing, permission matrix, both error codes and their recovery, and the exact post-state of the resource. Nothing material is left unstated.

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 100% and every parameter already carries a description, so the baseline is 3. The description does add real value on `version` (where to source it, how to recover from a version_conflict) and `seq` (get it from list_comments), but it says nothing about the optional `reason` parameter, so the add is partial rather than a full supplement.

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 first line states a specific verb and resource (delete a comment) plus its two defining traits: version is mandatory and the delete is a soft delete ('leaves a tombstone'). This clearly separates it from update_comment and the other delete_* siblings without needing to open 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?

It gives an explicit gating condition ('Only when the user asked'), permission rules (author or project_admin; imported unmatched Jira comments need project_admin), and the exact failure modes 403 not_author and 409 comment_deleted. What's missing is a named alternative — it never says 'to change text use update_comment' — so the agent must infer the escape hatch rather than being routed to it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All BoardMark toolsInspect
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