Skip to main content
Glama

Mark an item as bought

shopping_set_bought

Mark an open shopping item as bought or reopen it. Uses optimistic locking; pass the item's updatedAt and boughtAt from shopping_list to prevent concurrent edits.

Instructions

Mark one open item as bought, or put a bought item back on the open list (bought=false). Any member may do it. It only changes the bought state: to rename the item or change its quantity use shopping_update, and to delete it use shopping_remove. Uses optimistic locking: call shopping_list first and pass the item's updatedAt and boughtAt unchanged. If someone changed the item in between, the call fails with 409 shopping_item_changed and nothing is written: read the list again and decide again. If the item is already in the requested state the call succeeds without changes. Marking as bought records the caller as boughtBy and sets boughtAt to now; reopening clears both. Reopening can fail with 409 shopping_item_duplicate when another open item has the same name. Returns the updated item; item_not_found for an unknown id.

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>",
      "bought": "<bought>",
      "expectedUpdatedAt": "<expectedUpdatedAt>",
      "expectedBoughtAt": "<expectedBoughtAt>"
    },
    "name": "shopping_set_bought"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesId of the shopping item, from shopping_list.
boughtYestrue marks the item as bought by the caller; false reopens a bought item.
wgCodeNoShare code of the flat (code from wg_list). Leave it out when the account belongs to one flat.
expectedBoughtAtYesThe item's boughtAt exactly as returned by shopping_list, or null if it is still open. Guards against concurrent edits.
expectedUpdatedAtYesThe item's updatedAt exactly as returned by shopping_list (ISO 8601 with offset). Guards against concurrent edits.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.1
    • addedInput schema / properties / bought / description
      Added value: +"true marks the item as bought by the caller; false reopens a bought item."
    • addedInput schema / properties / expectedBoughtAt / description
      Added value: +"The item's boughtAt exactly as returned by shopping_list, or null if it is still open. Guards against concurrent edits."
    • addedInput schema / properties / expectedUpdatedAt / description
      Added value: +"The item's updatedAt exactly as returned by shopping_list (ISO 8601 with offset). Guards against concurrent edits."
    • addedInput schema / properties / id / description
      Added value: +"Id of the shopping item, from shopping_list."
  2. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only declare readOnly=false, idempotent=false and destructive=false; the description goes far beyond by disclosing the optimistic-locking protocol, the exact 409 shopping_item_changed failure with 'nothing is written', the no-op success when already in the requested state, the side effects (records caller as boughtBy, sets boughtAt to now; reopening clears both), and the secondary 409 shopping_item_duplicate risk on reopen.

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?

The core action is front-loaded, followed by alternatives, then the concurrency contract, then side effects and error cases in a logical order. Every sentence carries distinct operational information, with no restatement of the name or filler.

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 5-parameter mutation with no output schema, the description covers everything an agent needs: preconditions, exact error codes and recovery action, side effects, idempotent no-op case, and the note that it returns the updated item. Nothing material is left to inference.

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 schema carries the baseline, but the description still adds real meaning: it tells the agent where the expectedUpdatedAt/expectedBoughtAt values must come from (shopping_list, passed unchanged) and what a conflict means operationally. wgCode is left to the schema, which already explains it, so this is short of a 5.

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?

The first sentence names a specific verb plus resource ('Mark one open item as bought') and covers the reverse direction ('put a bought item back on the open list'), so an agent can distinguish it from shopping_update and shopping_remove named later in the text.

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?

Explicit boundaries are given: this tool only changes bought state, and renaming/quantity changes belong to shopping_update while deletion belongs to shopping_remove. It also states who may call it ('Any member may do it') and the prerequisite sequencing ('call shopping_list first and pass the item's updatedAt and boughtAt unchanged').

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