Skip to main content
Glama
Sign In
Ferret

Ferret

by ferret-project
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Use up or restock

adjust_stock

Increment or decrement a tracked consumable's stock count when items are used up or bought, logging the change, keeping counts at zero minimum, and updating its shopping-list status automatically.

Instructions

Counts consumables up or down — filters, batteries, bulbs: negative delta for used up ("we used the last AA pack" → -1), positive for bought more. Use it whenever the person uses up or buys something tracked; it never goes below 0, logs the change in the item's stock history, and moves the item on or off the shopping list. To set an exact count (after a recount), use update_item's quantity. Returns the new count.

Input Schema

NameRequiredDescriptionDefault
idYesThe item's id, from search_inventory
noteNoWhy, for its stock history ("used for the guest room")
deltaYesHow many used (negative) or bought (positive); not 0

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.1
    • addedInput schema / properties / delta / description
      Added value: +"How many used (negative) or bought (positive); not 0"
    • addedInput schema / properties / id / description
      Added value: +"The item's id, from search_inventory"
    • addedInput schema / properties / note / description
      Added value: +"Why, for its stock history (\"used for the guest room\")"
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Beyond the annotations (readOnly=false, destructive=false), the description discloses the clamping floor ("never goes below 0"), a history side effect ("logs the change in the item's stock history"), and an inventory-state side effect ("moves the item on or off the shopping list"). These side effects are exactly what an agent needs before mutating stock; only the absence of any note about error behavior or idempotency keeps it short of a 5.

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 operation and sign convention are front-loaded in the first sentence, with usage, side effects, alternative routing, and return value following in a tight sequence. No sentence is redundant or restates structured fields verbatim.

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?

With no output schema, the description supplies the return value ("Returns the new count"), and it covers side effects and the sibling alternative for a three-parameter mutation tool. The only gap is that it doesn't say what happens on an unknown id or a delta that would push below zero (clamped vs. error), which slightly matters for an agent planning a call.

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 a natural-language-to-value mapping example that the schema does not provide, helping the agent translate conversational input into the correct delta sign. The optional `note` parameter is left to the schema, which already documents it adequately.

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?

"Counts consumables up or down" states a specific verb and resource, and the negative/positive delta semantics with a concrete example ("we used the last AA pack" → -1) make the operation unambiguous. It also explicitly separates itself from update_item's exact-count behavior, so an agent can pick correctly without opening either 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?

"Use it whenever the person uses up or buys something tracked" gives a clear activation condition, and "To set an exact count (after a recount), use update_item's quantity" names the alternative plus the condition that selects it. Both when-to-use and when-not-to-use are covered with no inference required.

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