Skip to main content
Glama
Teamwork

Teamwork

Official
by Teamwork
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Remote

twprojects-update_custom_item_record

Update specific fields on a custom item record in Teamwork. Only supplied fields change, leaving others untouched. Use to modify contracts, leads, deals, or other user-defined entities.

Instructions

Update a record on a custom item type. Only the fields you supply are changed; others are left as-is. Set section_id to null to remove the record from any section. Custom items are user-defined entity types — Contracts, Leads, Deals, or anything else a customer has set up on a project. Use these tools when the user refers to an entity that is NOT a built-in Teamwork concept (Task, Tasklist, Project, Milestone, Comment, Notebook, Company, Team, User, Tag). If you don't recognise an entity name in the user's request, assume it is a custom item and call twprojects-list_custom_items on the relevant project to confirm.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYesRecord ID to update.
nameNoNew display name for the record.
section_idNoNew section ID, or null to remove the record from any section.
field_valuesNoField values to set on the record. Each entry is {field_name, value}. Field names are matched case-insensitively against the custom item type's fields. Values are coerced by field type: dropdown/multiselect accept option labels or option twIds; date/time/datetime accept ISO-8601 strings; checkbox accepts bool or yes/no/true/false; number accepts numeric or numeric string; user accepts a user ID (or array of IDs for multi-user fields). To clear a field, send null.
clear_sectionNoSet to true to explicitly clear the record's section. Use this instead of section_id when you want null semantics.
custom_item_idYesCustom item type ID the record belongs to.
position_after_idNoMove the record after the given record ID.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv1.39.3
    • removedInput schema / properties / clear_section / anyOf
      Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedInput schema / properties / clear_section / type
      Added value: +"boolean"
    • removedInput schema / properties / field_values / anyOf
      Removed value: -[
-  {
-    "items": {
-      "properties": {
-        "field_name": {
-          "description": "Display name of the field, case-insensitive.",
-          "type": "string"
-        },
-        "value": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "number"
-            },
-            {
-              "type": "boolean"
-            },
-            {
-              "items": {
-                "anyOf": [
-                  {
-                    "type": "string"
-                  },
-                  {
-                    "type": "number"
-                  }
-                ]
-              },
-              "type": "array"
-            },
-            {
-              "type": "object"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "description": "Value to set. Type depends on the field — see the tool description."
-        }
-      },
-      "required": [
-        "field_name",
-        "value"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedInput schema / properties / field_values / items
      Added value: +{
+  "properties": {
+    "field_name": {
+      "description": "Display name of the field, case-insensitive.",
+      "type": "string"
+    },
+    "value": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "items": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              }
+            ]
+          },
+          "type": "array"
+        },
+        {
+          "type": "object"
+        }
+      ],
+      "description": "Value to set. Type depends on the field — see the tool description."
+    }
+  },
+  "required": [
+    "field_name"
+  ],
+  "type": "object"
+}
    • addedInput schema / properties / field_values / type
      Added value: +"array"
    • removedInput schema / properties / name / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedInput schema / properties / name / type
      Added value: +"string"
    • removedInput schema / properties / position_after_id / anyOf
      Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedInput schema / properties / position_after_id / type
      Added value: +"integer"
    • removedInput schema / properties / section_id / anyOf
      Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedInput schema / properties / section_id / type
      Added value: +"integer"
  2. Addedv1.26.0
  3. Removedv1.25.0
  4. Addedv1.21.2

TDQS

A4.5/5.0
Behavior4/5

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

Annotations only provide generic hints (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds meaningful behavioral context: partial update semantics ('Only the fields you supply are changed'), section removal via null, and field value coercion rules. It doesn't describe output or error behavior, but the mutation semantics are well disclosed.

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 description is well-structured: it leads with the operation and update semantics, then explains the custom item concept and usage guidance. It is slightly redundant with schema details about section_id and clear_section, but the organization is logical and scannable.

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 mutation tool with no output schema, the description covers when to use it, how to identify custom items, what partial update means, and how to handle sections. It omits return format and error cases, but given the rich parameter schema and clear selection guidance, this is a minor gap rather than a serious deficiency.

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 description coverage is 100%, so the schema already documents all seven parameters in detail. The description adds value by emphasizing the partial-update behavior and clarifying the custom-item context, which helps the agent reason about which parameters to supply. This goes slightly beyond the baseline expected for fully covered schemas.

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 a record on a custom item type.' It clarifies that custom items are user-defined entity types and contrasts them with built-in Teamwork concepts, making it easy to distinguish this tool from sibling update tools that target tasks, projects, companies, and other built-ins.

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?

The description explicitly tells the agent when to use this tool: when the user refers to an entity that is not a built-in Teamwork concept. It also instructs the agent to call twprojects-list_custom_items when an entity name is unrecognized, providing a concrete fallback path and clear decision guidance.

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