Skip to main content
Glama
naw103

Foremerge

by naw103
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Discard work

discard_work
Destructive

Close an open intent you won't accept to release its claims and dismiss blocking conflicts, optionally recording a Git ref where unfinished work landed.

Instructions

Close one of your own intents that you will not take through accept_changeset. Call it before you stop working, whenever the intent is still open: an intent never closes itself, and an open one is compared against every later intent on the same scopes. Two cases. Work that will not be finished, for example a duplicate or work another agent took over: pass a reason. Work that reached Git without a passing named check, so it cannot be accepted: pass landed_ref as well, naming the commit or branch it landed in. Either way it sets the intent to DISCARDED, releases all of its active claims, and dismisses its OPEN or COORDINATING conflicts so they stop blocking the other party. With landed_ref the commit is checked and recorded, but the intent still ends DISCARDED, not ACCEPTED: nothing here says the work was verified. The history stays in the event log, but a discarded intent cannot be resumed; publish a new intent instead. Only the owner may discard, and not once the intent is ACCEPTED, COMMITTED or already DISCARDED. Returns the updated intent. To agree that two intents can coexist, use resolve_conflict instead.

Input Schema

NameRequiredDescriptionDefault
reasonYesWhy the work is being closed: why it was abandoned, or how it landed. Required and recorded in the event log.
agent_idYesYour agent id (agt_...). Must own the intent.
intent_idYesThe intent (int_...) to discard.
landed_refNoOnly for work that reached Git: the commit, branch or tag it landed in. Refused with INVALID_INPUT if it does not resolve to a commit, with TARGET_DIVERGED if the intent published a ChangeSet whose changes it does not hold, by ancestry or by content as record_commit checks, and with STALE_CHANGESET if that ChangeSet was published with uncommitted changes or before the repository's first commit.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.0
    • addedInput schema / properties / landed_ref
      Added value: +{
+  "description": "Only for work that reached Git: the commit, branch or tag it landed in. Refused with INVALID_INPUT if it does not resolve to a commit, with TARGET_DIVERGED if the intent published a ChangeSet whose changes it does not hold, by ancestry or by content as record_commit checks, and with STALE_CHANGESET if that ChangeSet was published with uncommitted changes or before the repository's first commit.",
+  "minLength": 1,
+  "type": "string"
+}
    • changedInput schema / properties / reason / description
      Previous value: -"Why the work is being abandoned. Required and recorded in the event log."New value: +"Why the work is being closed: why it was abandoned, or how it landed. Required and recorded in the event log."
  2. Changed3 schema fields changedv0.4.3
    • addedInput schema / properties / agent_id / description
      Added value: +"Your agent id (agt_...). Must own the intent."
    • addedInput schema / properties / intent_id / description
      Added value: +"The intent (int_...) to discard."
    • addedInput schema / properties / reason / description
      Added value: +"Why the work is being abandoned. Required and recorded in the event log."
  3. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare destructiveHint=true, but the description goes well beyond that: it states what specifically changes (intent set to DISCARDED, active claims released, OPEN/COORDINATING conflicts dismissed so they stop blocking the other party), that the event history is retained but the intent cannot be resumed, and that landed_ref does not imply verification ('still ends DISCARDED, not ACCEPTED'). It also discloses the return value. No contradiction with the destructive/readOnly hints.

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?

Front-loaded with the core action and organized by a 'Two cases' branch that makes the dense content scannable. It is longer than minimal—some explanation of state transitions and the landed_ref caveat could be trimmed—but virtually every sentence carries operational meaning.

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?

Covers all four parameters with their conditional usage, the post-call state of the intent and its claims/conflicts, the ownership and state preconditions, resume impossibility, and the return value. With no output schema, this is exactly the context an agent needs to call a destructive state-changing tool safely.

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 the baseline is 3, but the description adds genuine semantics the schema does not: the conditional relationship between the parameters ('pass a reason' alone vs 'pass landed_ref as well'), and the consequence of landed_ref (commit checked and recorded but intent still DISCARDED). It does not restate the error codes, which the schema already carries.

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 ('Close one of your own intents') plus the condition that distinguishes it ('that you will not take through accept_changeset'). It also names the sibling it must not be confused with ('To agree that two intents can coexist, use resolve_conflict instead'), so an agent can route correctly without opening a 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 explicit timing ('Call it before you stop working, whenever the intent is still open'), two enumerated usage cases (abandoned work vs work that landed without a passing named check), and a hard exclusion with an alternative (resolve_conflict). Preconditions are spelled out: only the owner, and not once ACCEPTED, COMMITTED or already DISCARDED.

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

Deploy Server

Other Tools