Skip to main content
Glama

Use up stock

inventory_consume

Record everyday item use by decreasing stock without going below zero; crossing the low-stock threshold adds the item to the shopping list and notifies flat members.

Instructions

Records that stock of one item was used up by lowering its quantity; use it for everyday use (someone took a roll) instead of inventory_update. Stock never goes below 0. When this use takes the item from above threshold to at or below it, the item is added to the shopping list and the other flat members get a low-stock notification (not the caller). Returns the item, clamped (true when the change was limited at 0), autoPushedShoppingItemId (shopping item created, or null) and a notification warning. Concurrent uses are applied one after another; a rare race gives 409 version_conflict, then retry. Unknown ids give 404 item_not_found. To restock or correct stock use inventory_update.

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>",
      "delta": "<delta>"
    },
    "name": "inventory_consume"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesId of the supply item that was used, from inventory_list.
deltaYesWhole units used, as a negative number in the item unit (for example -1 when one piece or roll was taken).
wgCodeNoShare code of the flat (code from wg_list). Leave it out when the account belongs to one flat.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.1.1
    • addedInput schema / properties / delta / description
      Added value: +"Whole units used, as a negative number in the item unit (for example -1 when one piece or roll was taken)."
    • addedInput schema / properties / id / description
      Added value: +"Id of the supply item that was used, from inventory_list."
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations, it discloses the clamping rule ('Stock never goes below 0'), the side effects (item added to the shopping list, low-stock notification sent to other flat members but not the caller), the return payload, concurrency behavior with a 409 version_conflict retry path, and a 404 item_not_found case. This is exactly the mutation-side-effect 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.

Conciseness4/5

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

The core purpose and the sibling routing are front-loaded, and the dense single paragraph carries no filler. It is on the long side, packing side effects, return fields, and error codes into one block, but each sentence contributes operational information.

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?

With no output schema, the description compensates by naming the returned fields (clamped, autoPushedShoppingItemId, notification warning) and the error codes. For a three-parameter mutation with side effects, nothing an agent needs to call it correctly is missing.

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 description coverage is 100%, and the schema already explains that delta is a negative whole-unit count and that wgCode is the flat share code. The description adds no parameter-level detail beyond that, so the 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?

The description opens with a specific verb and resource: 'Records that stock of one item was used up by lowering its quantity.' It immediately distinguishes the operation from inventory_update by naming the sibling and the everyday-use scenario, so an agent can select it 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?

It gives explicit when-to-use guidance ('everyday use (someone took a roll)') and an explicit when-not with the alternative ('instead of inventory_update', reinforced by 'To restock or correct stock use inventory_update'). Both directions of the routing decision are stated.

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