Atwork

Update Sheet Field

sheet.update_attribute

DestructiveIdempotent

Update an existing attribute (field) on a sheet. Pass only what changes. Call sheet.schema first for the field's id, its live option ids, its current default and its archived choices.

Basics: name, description, icon, dataType, isUnique (Title, Short Text, URL, Phone Number, Email; on a field that already holds duplicates it fails with UNIQUE_HAS_DUPLICATES and nothing changes, so ask the user to remove them first), and default, the value new rows start with (choices, members, teams, jobs, Date).
Format: number (format such as Euro or Dollar, decimals, showAs), date (dateFormat, timeFormat), checkboxStyle, selectStyle, language (Code), and relation on a Relation field: subtitle (a related field shown under each link), view and form (by name, of the related sheet), filter (which related rows can be picked, in sheet.read's filters shape). Under options: formula/returnType (Formula), relation/field/function (Mirror, Rollup), stars (Rate, 2–20), workflow (Button, by name), template (Summary), allowedFiles (any / images / documents / media / custom), allowedExtensions (with custom, e.g. ["pdf"]) and maxFiles (1–100, null for no limit) (File List). Every setting is merged into the field's live settings; a setting for another type is refused, naming the types it applies to, and an unknown name is refused listing the valid ones.
Choices of a Status/Select/Multi-Select field: option edits are a MERGE, so reuse a live option's id to rename or recolour it in place, omit the id to add a new choice, and list ids in removeOptionIds to delete choices. Leaving an option out never deletes it. Never invent an option id — rows reference options by id and a wrong id is rejected. archived: true hides a Select/Multi-Select choice from pickers while rows keep it (Status choices cannot be archived). isDefault: true makes a choice the default (a Multi-Select adds it to its defaults), false takes it out. order lists the choice ids in their new order, every live id exactly once. On a Status field each choice sits in a stage bucket; sheet.schema reports it as stage (Todo / InProgress / Complete). Pass stage on an item to put a new choice in that stage or move a live one (keep its id); a new choice defaults to Todo, and a Status order may also name just one stage's choices. stage is rejected on Select / Multi-Select and on an older Status field whose choices are not in stages.
Not here: a relation's two-way setting (turning it off deletes the reverse field for good), a relation's target sheet (fixed once created), Pipeline stages (their ids are stored in the rows) and the Duration format. Point the user to the field's settings in the panel.
A dataType change follows a fixed compatibility list: a type that is not offered is refused with DATA_TYPE_CHANGE_NOT_ALLOWED, listing the allowed types, and nothing is changed. A change that would empty or shorten values is refused with DATA_TYPE_CHANGE_BLOCKED, carrying the counts, before → after samples and the views and workflows that use the field, and nothing is changed; show that to the user and call again with confirmLoss: true only once they accept the loss. In a chat the user confirms the loss on a card instead: the call waits for it and applies the change once they accept.

Input Schema

Name	Required	Description
`date`	No	Date only: how the date and the time are written.
`icon`	No	A Bootstrap icon name, e.g. `bi-star`.
`name`	No
`order`	No	Choice ids in their new order, each live id exactly once. On Status, either every choice or every choice of one stage; a choice keeps its stage.
`number`	No	Number only: currency or number format (e.g. Euro), decimal places, and how it shows (NUMBER, BAR…).
`default`	No	The value new rows start with, as a human value: a choice title, a member, team or job name (a list for list fields), `creator` for whoever adds the row, or `today` for a Date's creation day. null clears it.
`options`	No
`sheetId`	Yes
`dataType`	No
`isUnique`	No	Title, Short Text, URL, Phone Number and Email only: refuse duplicate values.
`language`	No	Code only.
`relation`	No	Relation only: how linked rows are shown and picked.
`attributeId`	Yes
`confirmLoss`	No	Apply a dataType change even though it empties or shortens values. Only after reading the preview.
`description`	No
`selectStyle`	No	Select / Multi-Select only.
`checkboxStyle`	No	Checkbox only.
`removeOptionIds`	No

Output Schema

Name	Required	Description
`ok`	Yes	The change was applied
`name`	Yes	Its name after the change
`changed`	Yes	The inputs that were applied, e.g. name, number, order, default
`attributeId`	Yes	The field that changed

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 8, 2026

addedInput schema / properties / options / properties / allowedExtensions

Added value: +{
+  "description": "File List only: the extensions a Custom rule takes, without the dot, e.g. [\"pdf\", \"docx\"].",
+  "items": {
+    "maxLength": 11,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 30,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / options / properties / allowedFiles

Added value: +{
+  "description": "File List only: which files it takes; `media` is audio and video, `custom` takes allowedExtensions.",
+  "enum": [
+    "any",
+    "images",
+    "documents",
+    "media",
+    "custom"
+  ],
+  "type": "string"
+}

addedInput schema / properties / options / properties / maxFiles

Added value: +{
+  "anyOf": [
+    {
+      "maximum": 100,
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "File List only: at most this many files (1–100); null removes the limit."
+}

Changed1 schema field changedNov 5, 2026

changedInput schema / properties / relation / properties / form / description

Previous value: -"The related sheet's form or peek a link opens"New value: +"The related sheet's record layout (a peek of kind record) a link opens a row in"

Changed1 schema field changedNov 4, 2026

changedInput schema / properties / dataType / enum

Previous value: -[
-  "Short Text",
-  "Long Text",
-  "Number",
-  "Date",
-  "DateRange",
-  "Email",
-  "URL",
-  "PhoneNumber",
-  "CheckBox",
-  "Status",
-  "Select",
-  "Multi-Select",
-  "Employee",
-  "Employee List",
-  "Team",
-  "Team List",
-  "Job",
-  "Job List",
-  "Actor",
-  "File List",
-  "Document",
-  "Location",
-  "Address",
-  "Duration",
-  "Link",
-  "Vote",
-  "Goal"
-]New value: +[
+  "Short Text",
+  "Long Text",
+  "Number",
+  "Date",
+  "Email",
+  "URL",
+  "PhoneNumber",
+  "CheckBox",
+  "Status",
+  "Select",
+  "Multi-Select",
+  "Employee",
+  "Employee List",
+  "Team",
+  "Team List",
+  "Job",
+  "Job List",
+  "Actor",
+  "File List",
+  "Document",
+  "Location",
+  "Address",
+  "Duration",
+  "Link",
+  "Vote",
+  "Goal"
+]

Changed28 schema fields changedOct 27, 2026

addedInput schema / properties / checkboxStyle

Added value: +{
+  "description": "Checkbox only.",
+  "enum": [
+    "checkbox",
+    "toggle",
+    "switch"
+  ],
+  "type": "string"
+}

addedInput schema / properties / date

Added value: +{
+  "description": "Date only: how the date and the time are written.",
+  "properties": {
+    "dateFormat": {
+      "enum": [
+        "Compact",
+        "Full Date",
+        "Relative",
+        "Month/Day/Year",
+        "Day/Month/Year",
+        "Year/Month/Day"
+      ],
+      "type": "string"
+    },
+    "timeFormat": {
+      "enum": [
+        "12 hour",
+        "24 hour"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / default

Added value: +{
+  "anyOf": [
+    {
+      "minLength": 1,
+      "type": "string"
+    },
+    {
+      "items": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "minItems": 1,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The value new rows start with, as a human value: a choice title, a member, team or job name (a list for list fields), `creator` for whoever adds the row, or `today` for a Date's creation day. null clears it."
+}

addedInput schema / properties / icon

Added value: +{
+  "description": "A Bootstrap icon name, e.g. `bi-star`.",
+  "maxLength": 80,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / isUnique

Added value: +{
+  "description": "Title, Short Text, URL, Phone Number and Email only: refuse duplicate values.",
+  "type": "boolean"
+}

addedInput schema / properties / language

Added value: +{
+  "description": "Code only.",
+  "enum": [
+    "plain",
+    "html",
+    "json",
+    "typescript",
+    "javascript",
+    "sql",
+    "css",
+    "markdown"
+  ],
+  "type": "string"
+}

addedInput schema / properties / number

Added value: +{
+  "description": "Number only: currency or number format (e.g. Euro), decimal places, and how it shows (NUMBER, BAR…).",
+  "properties": {
+    "decimals": {
+      "maximum": 10,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "format": {
+      "enum": [
+        "Number",
+        "Number with commas",
+        "Percent",
+        "Dollar",
+        "Euro",
+        "Riyal",
+        "Rand",
+        "Real",
+        "Pound",
+        "Ruble",
+        "Rupee",
+        "Rupiah",
+        "Yen",
+        "Yuan",
+        "Won",
+        "Canadian dollar",
+        "Franc"
+      ],
+      "type": "string"
+    },
+    "showAs": {
+      "enum": [
+        "NUMBER",
+        "BAR",
+        "RING",
+        "GAUGE",
+        "RATE"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / options / properties / field

Added value: +{
+  "description": "Mirror: the related sheet's field to show. Rollup: the Number field to aggregate (not for COUNT).",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / options / properties / formula

Added value: +{
+  "description": "Formula only: fields in braces, e.g. `{Price} * {Quantity}`; functions IF, round, days_between…",
+  "maxLength": 2000,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / options / properties / function

Added value: +{
+  "description": "Rollup only: how the related rows are aggregated.",
+  "enum": [
+    "COUNT",
+    "DISTINCT_COUNT",
+    "SUM",
+    "AVG",
+    "MIN",
+    "MAX"
+  ],
+  "type": "string"
+}

addedInput schema / properties / options / properties / items / items / properties / archived

Added value: +{
+  "description": "Select / Multi-Select only: true hides the choice from pickers; rows keep it. false brings it back.",
+  "type": "boolean"
+}

addedInput schema / properties / options / properties / items / items / properties / isDefault

Added value: +{
+  "description": "true makes this choice the field's default for new rows (on Multi-Select, adds it); false removes it.",
+  "type": "boolean"
+}

addedInput schema / properties / options / properties / items / items / properties / title / description
```
Added value: +"Required for a new option; a live one keeps its title."
```
removedInput schema / properties / options / properties / items / items / required
```
Removed value: -[
-  "title"
-]
```

addedInput schema / properties / options / properties / relation

Added value: +{
+  "description": "Mirror / Rollup only: the name of a Relation field on this sheet.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / options / properties / returnType

Added value: +{
+  "description": "Formula only: what it returns. Default number.",
+  "enum": [
+    "number",
+    "text"
+  ],
+  "type": "string"
+}

addedInput schema / properties / options / properties / stages

Added value: +{
+  "description": "Pipeline only: the stages in order; won stages `succeed`, lost ones `failed`.",
+  "items": {
+    "properties": {
+      "color": {
+        "type": "string"
+      },
+      "outcome": {
+        "description": "Default open",
+        "enum": [
+          "open",
+          "succeed",
+          "failed"
+        ],
+        "type": "string"
+      },
+      "title": {
+        "maxLength": 80,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "title"
+    ],
+    "type": "object"
+  },
+  "maxItems": 30,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / options / properties / stars

Added value: +{
+  "description": "Rate only: number of stars (2–20), default 5.",
+  "maximum": 20,
+  "minimum": 2,
+  "type": "integer"
+}

addedInput schema / properties / options / properties / template

Added value: +{
+  "description": "Summary only: text with fields in braces, e.g. `{Company} — {Stage}`.",
+  "maxLength": 4000,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / options / properties / workflow

Added value: +{
+  "description": "Button only: the name of a workflow on this sheet with a manual trigger.",
+  "minLength": 1,
+  "type": "string"
+}

removedInput schema / properties / options / required
```
Removed value: -[
-  "items"
-]
```

addedInput schema / properties / order

Added value: +{
+  "description": "Choice ids in their new order, each live id exactly once. On Status, either every choice or every choice of one stage; a choice keeps its stage.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / relation

Added value: +{
+  "description": "Relation only: how linked rows are shown and picked.",
+  "properties": {
+    "filter": {
+      "anyOf": [
+        {
+          "properties": {
+            "conditionOperator": {
+              "enum": [
+                "AND",
+                "OR"
+              ],
+              "type": "string"
+            },
+            "filters": {
+              "items": {
+                "properties": {
+                  "attribute": {
+                    "description": "A field name of the related sheet",
+                    "minLength": 1,
+                    "type": "string"
+                  },
+                  "conditionOperator": {
+                    "enum": [
+                      "AND",
+                      "OR"
+                    ],
+                    "type": "string"
+                  },
+                  "filters": {
+                    "items": {},
+                    "type": "array"
+                  },
+                  "queryOperator": {
+                    "minLength": 1,
+                    "type": "string"
+                  },
+                  "value": {}
+                },
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "filters"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Which related rows can be picked, in sheet.read's `filters` shape, fields and values by name"
+    },
+    "form": {
+      "anyOf": [
+        {
+          "minLength": 1,
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The related sheet's form or peek a link opens"
+    },
+    "subtitle": {
+      "anyOf": [
+        {
+          "minLength": 1,
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "A related sheet's field shown under each link; null clears it"
+    },
+    "view": {
+      "anyOf": [
+        {
+          "minLength": 1,
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The related sheet's view the picker lists rows from"
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / selectStyle

Added value: +{
+  "description": "Select / Multi-Select only.",
+  "enum": [
+    "dropdown",
+    "toggle"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / attributeId

Added value: +{
+  "description": "The field that changed",
+  "type": "number"
+}

addedOutput schema / properties / changed

Added value: +{
+  "description": "The inputs that were applied, e.g. name, number, order, default",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / name

Added value: +{
+  "description": "Its name after the change",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "ok"
-]New value: +[
+  "ok",
+  "attributeId",
+  "name",
+  "changed"
+]

First observedOct 20, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial behaviour beyond them: UNIQUE_HAS_DUPLICATES fails with nothing changed, option edits are a MERGE so omission never deletes, wrong option ids are rejected, and DATA_TYPE_CHANGE_BLOCKED returns counts, before→after samples and dependent views/workflows before anything is applied. The chat-card confirmation flow and the merged-settings refusal rules are genuinely useful operational context, though the section is dense enough that an agent may need to re-read it.

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

Conciseness3/5

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

The core statement and the schema prerequisite are correctly front-loaded, and the bulleted grouping by concern (Basics / Format / Choices / Not here / dataType change) aids scanning. However, the block is very long and repeats detail already present in schema descriptions — e.g. "stars (Rate, 2–20)", "maxFiles (1–100, null for no limit)", "[\"pdf\"]" — so a meaningful share of lines do not add value over structured fields.

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 an 18-parameter, deeply nested mutation with merge semantics, this description covers prerequisites, partial-update behaviour, per-type settings, error codes and their recovery paths, and what is deliberately out of scope. With an output schema present, it does not waste space on return values, and nothing an agent needs in order to call it safely appears missing.

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 61% schema description coverage across 18 parameters, the description carries meaning the schema cannot: which types `isUnique` applies to and how it fails, what `default` accepts ("a choice title, a member, team or job name ... `creator` ... `today`", null clears), that `order` must list every live id exactly once and on Status may cover one stage, and that option `id` reuse renames in place. It also encodes constraints absent from the schema, such as Status-only `stage` being rejected on Select/Multi-Select and archived choices not existing for Status.

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 first sentence names a precise verb and resource ("Update an existing attribute (field) on a sheet") and adds "Pass only what changes", which pins it as a partial-update operation. "Existing" implicitly separates it from sheet.add_attribute, sheet.remove_attribute and sheet.restore_attribute in the sibling list.

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 an explicit prerequisite ("Call `sheet.schema` first for the field's `id`, its live option ids, its current default and its `archived` choices") and a clear exclusion section ("Not here: a relation's two-way setting ... a relation's target sheet ... Pipeline stages ... the Duration format") with a stated alternative, "Point the user to the field's settings in the panel." The confirmLoss escalation path is also spelled out with its ordering condition.

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?