Skip to main content
Glama

Mark a document that had its day

flag_doc
Idempotent

Mark a document as no longer needed, saying the reason, for the person to delete; also when asked to «delete this document», which you cannot.

Instructions

Mark a document as no longer needed, saying the reason, for the person to delete; also when asked to «delete this document», which you cannot. The person sees the mark and why; the document is unchanged until they delete it, put it away or unmark it. One the person asks to put away is archive_doc; one to correct, edit_doc. Copies go in one call. One already marked is refused, or skipped in a set.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "doc": "<doc>",
      "body": "<body>"
    },
    "name": "flag_doc"
  }
}

Input Schema

NameRequiredDescriptionDefault
docYesThe id of the document to mark, not its title, or `sheet#heading` for an idea; a list is marked alike
bodyYesIn the person's language: what makes it old, and how you know
reasonNoA copy of another, moved into another (only once what it held worth keeping is there), superseded by another, wrong, obsolete, or a scratch nobody needs
insteadNoId of the document or task that holds it now; needed with duplicate_of, moved and superseded

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.47.0
    • changedInput schema / properties / doc / description
      Previous value: -"The id of the document to mark, not its title, or a list of ids marked alike"New value: +"The id of the document to mark, not its title, or `sheet#heading` for an idea; a list is marked alike"
  2. Changed4 schema fields changedv1.43.2
    • changedInput schema / properties / body / description
      Previous value: -"What makes it old and how you know, in the person's language: what it describes that no longer exists, and what replaced it"New value: +"In the person's language: what makes it old, and how you know"
    • changedInput schema / properties / doc / description
      Previous value: -"The id of the document to mark, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title. A list of ids marks them all alike in one go"New value: +"The id of the document to mark, not its title, or a list of ids marked alike"
    • changedInput schema / properties / instead / description
      Previous value: -"The id of the document or the task that holds what it said now. Needed with duplicate_of, moved and superseded"New value: +"Id of the document or task that holds it now; needed with duplicate_of, moved and superseded"
    • changedInput schema / properties / reason / description
      Previous value: -"Why it has had its day: a duplicate of another, moved into another (only once what it holds worth keeping is there), superseded by another, wrong, obsolete, or a scratch nobody needs"New value: +"A copy of another, moved into another (only once what it held worth keeping is there), superseded by another, wrong, obsolete, or a scratch nobody needs"
  3. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations declare readOnly/destructive false, but the description adds real behavioral context beyond them: the document is left unchanged until the person deletes, archives, or unmarks it, the person sees the mark and the reason, and repeats are refused or skipped within a set. The refusal-on-already-marked behavior is consistent with idempotentHint (no further state change), though it could have said more explicitly whether a refused call errors or returns quietly.

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 purpose and the delete-not-supported caveat are front-loaded, and nearly every clause carries information (alternatives, repeat handling, unchanged state). Some sentences are compressed to the point of strain — "One the person asks to put away is `archive_doc`" reads awkwardly — but nothing is padding.

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 four-parameter, non-destructive mutation with no output schema, the definition covers the action, the alternatives, the user-visible effect, and repeat handling. The remaining gap is the programmatic undo path (there is a `restore_doc` sibling, and only the person's unmarking is described), which an agent may need if asked to reverse a mark.

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%, so the field meanings, the `reason` enum, and the `instead` requirement are already documented; the description adds little beyond highlighting `reason`. "Copies go in one call" does reinforce that `doc` accepts a list, but the schema already states this, so baseline 3 applies.

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?

Opens with a specific verb and resource ("Mark a document as no longer needed") and states the differentiating scope: this is a soft mark for the person to act on, not a deletion. It explicitly names the sibling cases that look similar — `archive_doc` for put-away and `edit_doc` for corrections — so an agent can separate this tool from neighbors without opening 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete trigger (the document is old/no longer needed) plus an explicit redirect for a common mis-selection: when the person says «delete this document», which this tool cannot do. It also names the two nearest alternatives with the condition that selects each, so when-to-use and when-not-to-use are both covered.

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