Skip to main content
Glama

clear_start_after

DestructiveIdempotent

Clears a card's start_after only when the read schedule still matches; changed cards are refused with a conflict, preventing stale overwrites.

Instructions

Clear a card's start_after only if it is still exactly the schedule you read (compare-and-clear). Pass the start_after, version, start_after_origin and start_after_receipt_id from get_task. A changed card is refused with 409 cas_conflict and its current values — nothing is written; re-read before deciding anything. Repeating a call with the same idempotency_key returns the first receipt (replayed=true). Does not touch human gates, dependencies, waits or due_date.

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": {
      "task_id": "<task_id>",
      "expected_start_after": "<expected_start_after>",
      "expected_version": "<expected_version>"
    },
    "name": "clear_start_after"
  }
}

Input Schema

NameRequiredDescriptionDefault
reasonNoWhy the date is no longer needed, max 500 chars; stored on the clear receipt.
task_idYesThe card (UUID or 6-12 hex short id).
expected_originNoThe card's start_after_origin as you read it: agent_evidence, human_explicit or legacy_unknown. Required for an agent.
idempotency_keyNoKey of this clear, max 200 chars; reuse it when you repeat the same call. Generated when omitted.
expected_versionYesThe card's version as you read it.
schedule_receipt_idNoThe card's start_after_receipt_id as you read it. Required for an agent unless the origin is legacy_unknown.
expected_start_afterYesThe card's start_after as you read it, RFC3339.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.7

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is partly carried structurally. The description still adds real value beyond them: 409 cas_conflict semantics, 'nothing is written' on refusal, replay behavior with replayed=true, and the untouched-surface list. Strong added context, though the success-path receipt contents are left unspecified and no output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, each doing distinct work: the operation and its invariant first, then required inputs, then the failure mode, then idempotency, then the exclusion list. No filler or restatement of the name.

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 destructive, idempotent mutation with 7 parameters and no output schema, the description covers preconditions, failure behavior, replay semantics and scope boundaries. What is missing is the shape of the success receipt, though 'nothing is written' and replayed=true give partial coverage.

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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: the expected_* fields are values 'as you read them' from get_task and drive the compare-and-clear check, and idempotency_key reuse controls replay. Minor friction in that it refers to fields by their source names (start_after, version, start_after_origin, start_after_receipt_id) rather than the schema's expected_* prefixes.

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 ('Clear a card's start_after') plus the governing constraint ('only if it is still exactly the schedule you read') and names the pattern, compare-and-clear. An agent can distinguish this from generic task mutation tools without opening the 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?

Gives concrete preconditions ('Pass the start_after, version, start_after_origin and start_after_receipt_id from get_task'), the failure path ('re-read before deciding anything'), and an explicit scope exclusion ('Does not touch human gates, dependencies, waits or due_date'). It stops short of naming a sibling to use for those other cases, so guidance is clear but not fully routing.

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