Skip to main content
Glama

BoardMark

by ai.boardmark
OverviewDiscussionsAdmin

Delete an attached file for good (spec D133): the uploader, or a company admin for any file

delete_attachment
DestructiveIdempotent

Delete an attached file for good (spec D133): the uploader, or a company admin for any file.

Removes the stored object and the attachment row at once — no trash, no restore (the web asks to confirm). Who: the person who uploaded it (uploaded_by) unless they are a viewer of the project; a company admin of the attachment's company for any file of an issue they can read (even as a viewer). An AI agent (token) only for files that same token uploaded (agent_token_id), never with admin power, and not when its user is a viewer. Allowed while the company is read-only or suspended (frees storage). Everyone else → 403 forbidden. Unknown id, a pending upload, or a project the caller cannot read → 404 not_found. Links to the file in the issue body or comments are not edited: they render as "file deleted". Publishes files.object.deleted and writes the audit event files.attachment_deleted (category content_delete, target {type: attachment, id, label: filename}).

Deletes an attached file for good (no undo); get the attachment_id from list_attachments. An agent may delete only files this same token uploaded (agent_token_id), else 403 forbidden. Ask the user before deleting.

Input Schema

NameRequiredDescriptionDefault
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.
attachment_idYes

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.6/5.0
Behavior5/5

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

Annotations already mark the tool as destructive, idempotent, and not read-only, but the description adds substantial context: no trash/restore, read-only/suspended company behavior, link rendering as "file deleted", emitted event, and audit event. It does not contradict the annotations.

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 core behavior and permissions are front-loaded, and most details earn their place for a destructive operation. However, the title wording and the agent-deletion restriction are repeated, which keeps it from being maximally concise.

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 tool with no output schema and complex permission rules, the description covers permanence, permissions, error responses, event publication, audit behavior, and the required ID source. An agent has enough context to invoke it correctly.

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 50%: the reason parameter is fully documented in the schema, but attachment_id has no schema description. The description compensates by saying to get attachment_id from list_attachments, though it does not discuss reason or add further parameter constraints.

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: permanently deleting an attached file, with no trash and no restore. It also distinguishes the retrieval path by naming list_attachments as the way to obtain the attachment_id.

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?

Explicitly defines who may delete, when an agent may delete, when admin power does not apply, and that the user should be asked before deleting. It also names list_attachments as the source of the required ID and gives clear failure conditions.

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
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