Ferret

Change many things at once

bulk_update_items

Instructions

Makes one change to up to 200 items in one go: move them to a location (action move, locationId; null: no location), give them a category (category, categoryId; null: none), or add or remove a tag (tag / untag, tag). Use it for "move everything on the garage shelf to the basement" — get the ids from list_items or search_inventory first, and say what you're about to change before doing it. Things inside a box move with the box; move the box itself. Returns how many were changed and which failed, and why. To delete items use remove, one at a time.

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": {
      "action": "<action>",
      "ids": "<ids>"
    },
    "name": "bulk_update_items"
  }
}

Input Schema

Name	Required	Description
`ids`	Yes	The items' ids, from list_items or search_inventory
`tag`	No	For tag and untag: the tag's name (a new name makes the tag)
`action`	Yes	What to do to every one of them
`categoryId`	No	For category: the category, from list_categories; null: none
`locationId`	No	For move: where to, from list_locations; null: no location

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2026.11.6Nov 6, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations only declare the safety profile (not read-only, not open-world, not destructive), and the description adds genuinely new behavior: the 200-item cap, that contents of a box move with the box, and a partial-failure return of counts plus per-item failure reasons. It also implicitly warns that this is a broad multi-item mutation worth confirming first. A slight gap remains on whether partial application is atomic or best-effort beyond the failure list.

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 scope, then the mode breakdown, then prerequisites and the delete alternative; every clause carries operational information. It is dense but not padded, though the quoted example and the reminder to narrate the change make it longer than strictly necessary.

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 still tells the agent what comes back (how many changed, which failed, and why). Combined with the id-source prerequisite, the item cap, container/contents behavior, and the delete alternative, an agent has everything needed to invoke this correctly.

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 each property already documents its own semantics, including the null meanings for locationId and categoryId. The description restates the action-to-parameter mapping (move/locationId, category/categoryId, tag/untag/tag) but adds no format, constraint, or edge-case detail beyond the schema, so it sits at baseline.

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 with scope: one change applied to up to 200 items, enumerating the four action modes (move, category, tag, untag). It explicitly separates itself from update_item and remove, so an agent can distinguish it from siblings 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?

Gives a concrete when-to-use scenario ("move everything on the garage shelf to the basement"), a prerequisite ordering (get ids from list_items or search_inventory first), and an explicit exclusion routing deletes to remove one at a time. The advice to announce the change before executing is extra operational guidance rather than filler.

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