Skip to main content
Glama

aamio_outbox_forget

DestructiveIdempotent

Stop waiting for an unsettled message by removing it from the outbox and pending list; the returned outcome reports never_sent, attempted, refused, delivered, unknown, or not_found.

Instructions

Stop waiting for one unsettled message. The entry leaves the outbox and it is gone from aamio_pending. A send still working on proof of work is stopped before anything leaves this machine; anything already away cannot be recalled. outcome in the answer says which of five it was: never_sent, attempted, refused, delivered or unknown, and not_found when this outbox never had that id. Only never_sent lets you compose something else. attempted covers a server error, which does not prove the message is absent, and refused is only what the service said no to. It says neither that the message was delivered nor that it was not: it says you have stopped waiting for an answer that is not coming. Take aamio_receipt first if you need a record of what passed through the thread.

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": {
      "id": "<id>"
    },
    "name": "aamio_outbox_forget"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesthe message_id of one unsettled message

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.36
    • addedInput schema / properties / id / maxLength
      Added value: +64
    • addedInput schema / properties / id / minLength
      Added value: +1
  2. Addedv0.6.32

TDQS

A4/5.0
Behavior5/5

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

Annotations already flag this as destructive and open-world, and the description goes well beyond them: it explains that a proof-of-work send is halted before anything leaves the machine, that anything already away cannot be recalled, and what the entry's removal does to aamio_pending. It also enumerates the outcome values and carefully delimits what each proves (attempted does not prove absence, refused is only a service rejection). That is exactly the interpretive context annotations cannot carry.

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

Conciseness3/5

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

The core action is front-loaded in the first two sentences, which is good. But the outcome discussion runs long and circles: 'It says neither that the message was delivered nor that it was not' restates the earlier caveats about attempted and refused, and the repeated 'stop waiting' framing is redundant for a one-parameter tool.

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?

There is no output schema, so the description must explain the response, and it does by enumerating the outcome values and their meanings. For a destructive, idempotent mutation tool it covers reversibility and side effects well. It omits any mention of permissions or whether a repeat call returns not_found by design, which is a minor gap.

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 the single id parameter is already documented as 'the message_id of one unsettled message'. The description reinforces that the id must belong to this outbox and that an unknown id yields not_found, but adds no format or syntax detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete action and object: it stops waiting on one unsettled message and removes it from the outbox so it disappears from aamio_pending. That is far more specific than the metaphorical tool name 'forget'. It implicitly separates itself from aamio_outbox_retry and aamio_pending, though it never names the retry sibling as the alternative path.

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 a clear precondition (one unsettled message, identified by its id) and an explicit sequencing rule: 'Take aamio_receipt first if you need a record of what passed through the thread.' It also states that only a never_sent outcome lets you compose something else, which is actionable decision guidance. It stops short of an explicit when-not-to-use-this-use-that comparison against the retry tool.

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