Cloudlabels

Bulk update items

bulk_update_items

Destructive

Update up to 1000 existing items on one sheet. Each row is item_id plus fields, same field rules as update_item, including barcode checks. Item ids are trimmed and compared in lowercase, and each returned item_id is lowercase. This tool does not accept barcode_mode. An empty barcode is assigned when sequential assignment already works, Cloudlabels EAN-13 is on, or the GS1 prefix allocator is on. When assignment is refused, that row stays empty with barcodeSource unchanged and a barcode_note, and that row is still updated. Every row is checked before anything is written. Duplicate item ids, the same new barcode on more than one row, an id that is not in this organization, or invalid field values fail the whole batch and nothing is written. The same new barcode is compared after trim and ignores letter case, because stored barcodes are unique that way. Those rows are failed and the other rows are skipped. nothing_written is a best effort. It is true when no returned row has status updated, including when validation fails or the first save fails before any row is stored. A failed row on a save error can still be partly stored, for example when the row is written and a later step throws. Verify with get_item after a failure. nothing_written false means at least one returned row has status updated. A database constraint or an automatic barcode assignment collision can still fail one row while saving, after earlier rows are already saved. There is no database transaction for these updates. If a row fails while saving, earlier rows stay updated, that row is failed with a short reason, and later rows are skipped. Sending the same values again is safe: rows that already have those values are written again. The result lists every row as updated, failed, or skipped, with updated_count, failed_count, and skipped_count. It does not return count or error.

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

Input Schema

Name	Required	Description	Default
`items`	Yes
`sheet_number`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 30, 2026

TDQS

A3.9/5.0

Behavior5/5

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

The description adds substantial behavior beyond the annotations: barcode assignment rules, whole-batch validation before any write, non-transactional partial-save behavior, best-effort nothing_written semantics, and retry safety. It explains exactly what gets destroyed or left unchanged when a row fails. This is unusually rich context for a destructive bulk mutation.

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

Conciseness2/5

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

The core purpose is front-loaded, but the description is a dense, repetitive paragraph. The nothing_written semantics are explained across several sentences that restate the same condition, and the barcode-failure narrative is difficult to parse. Valuable details are present, but the structure and repetition hurt conciseness.

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?

For a destructive bulk mutation with no output schema, the description covers validation, partial writes, retry safety, barcode handling, and the result shape with updated_count, failed_count, and skipped_count. The main omission is the sheet_number parameter's behavior and default. Otherwise an agent has enough context to call it correctly and interpret failure.

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 0%, so the description must compensate. It explains that each row is item_id plus fields, that item ids are trimmed and lowercased, and that barcode rules follow update_item, but it never explains the sheet_number parameter or its 1-10 range. It partially compensates but leaves a notable gap.

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 states a specific verb and resource: update up to 1000 existing items on one sheet. It distinguishes itself from update_item by noting the shared field rules, and the word 'existing' separates it from create-style siblings. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'existing items' and the reference to update_item, but the description never explicitly says when to choose this over update_item or bulk_create_items. It also does not state prerequisites such as required permissions or when a single-item update is preferable. The guidance is adequate but not explicit.

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

All Cloudlabels tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?