Atwork

Update Items By Filter

item.update_where

Destructive

Set the same field values on EVERY row of one sheet that matches a filter, in ONE call — e.g. "Country = Germany where Country is DE or Deutschland". Prefer it over reading rows and calling item.update_many whenever the rows to change are described by a condition. filter is { operator: AND|OR, conditions: [{ column, operator, value }] } (≤ 10 conditions, operators as in sheet.aggregate) and fields maps field name → ONE literal human value (≤ 30); columns take names or codes and option/member values are matched as in item.update_humanized. File List fields are set per row with item.update_many, not here. Rows already holding the values are left alone; archived and read-only rows are skipped. When more than 20 rows would change, the user confirms first: in a chat on a preview card (the call waits for it); over MCP the call is refused with ROWS_NEED_CONFIRM, the count and a sample, and nothing changes — show the user and call again with confirmRows set to that count only once they accept. At most 1,000 rows per call — narrow the filter otherwise. The change is one batch: item.undo_batch with the returned batchId and sheetId restores the previous values. Returns { batchId, updated, unchanged, skipped, skippedCount, url }.

Input Schema

Name	Required	Description
`fields`	Yes	Attribute name/code → human value, as in item.create_humanized, at most 30 per row. Select/Status/Member/Team/Job values are matched to the sheet's real options.
`filter`	Yes
`sheetId`	Yes
`confirmRows`	No	MCP only: the number of rows the user accepted after a ROWS_NEED_CONFIRM refusal. Needed when more than 20 rows would change; never set it before the user agrees.

Output Schema

Name	Required	Description
`url`	Yes	Panel link to the sheet
`batchId`	Yes	Id of the batch; pass it with sheetId to item.undo_batch to undo the whole batch. Null when nothing was written
`created`	Yes	Rows created
`sheetId`	Yes	Sheet the rows are in
`skipped`	Yes	Rows left unchanged and why; at most 20 are listed
`spaceId`	Yes	Space of that sheet; null for a sheet outside a space
`stopped`	No	Set when a row failed unexpectedly: rows after it were not attempted; the rest stay written
`updated`	Yes	Rows updated
`unchanged`	Yes	Matching rows that already held every value
`skippedCount`	Yes	All rows skipped, including ones not listed
`nothingToChange`	No	Set when every matching row already held the values

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 8, 2026

addedInput schema / properties / confirmRows

Added value: +{
+  "description": "MCP only: the number of rows the user accepted after a ROWS_NEED_CONFIRM refusal. Needed when more than 20 rows would change; never set it before the user agrees.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

Changed1 schema field changedNov 6, 2026

changedOutput schema / properties / batchId / description

Previous value: -"Id of the batch; pass it to item.undo_batch to undo the whole batch. Null when nothing was written"New value: +"Id of the batch; pass it with sheetId to item.undo_batch to undo the whole batch. Null when nothing was written"

AddedNov 4, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Beyond the destructive/non-idempotent annotations it discloses non-obvious behavior: rows already holding the values are untouched, archived and read-only rows are skipped, >20 rows triggers a confirmation gate (chat preview card vs MCP ROWS_NEED_CONFIRM refusal with nothing changed), a 1,000-row ceiling, and undo via item.undo_batch with the returned batchId. The only gap is that the 'skipped' counters and what counts as a read-only row are not fully explained, but the safety-relevant behavior is well covered.

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 action is front-loaded in the first clause and nearly every sentence carries operational information (limits, skips, confirmation, undo, return shape). It is a dense single block, though, and splitting the confirmation and undo behavior into separate sentences would improve scannability.

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 destructive bulk-mutation tool with nested filter objects, the definition covers eligibility, safety gates, size limits, reversibility and the return shape, so an agent can call it correctly without further probing. The existence of an output schema makes the brief return listing a bonus rather than a requirement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 50% schema coverage, the description compensates heavily: it spells out the filter shape, the ≤10 condition cap, that operators match sheet.aggregate, that fields map names to one literal human value (≤30) and that columns accept names or codes with option/member values resolved like item.update_humanized. It also explains confirmRows as the count returned by ROWS_NEED_CONFIRM and warns never to set it before user agreement — meaning the schema cannot supply.

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 (set field values), resource (every row of one sheet matching a filter) and scope constraint (same values, one call), plus a concrete example condition. It also differentiates from siblings by naming item.update_many and item.update_humanized as related-but-different operations.

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?

Explicitly says when to prefer this tool over the alternative: 'Prefer it over reading rows and calling item.update_many whenever the rows to change are described by a condition.' It also carves out when NOT to use it — File List fields must go through item.update_many — and explains the confirmation branch that determines whether to call again with confirmRows.

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

All Atwork 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?