Skip to main content
Glama
trustxai

amazing-clickup-mcp

by trustxai
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

clickup_set_custom_field_value

Idempotent

Assign a value to a specific custom field on a ClickUp task. Handles all field types including text, number, date, dropdown, labels, and relationships.

Instructions

Set a Custom Field's value on a task.

Calls POST /task/{task_id}/field/{field_id}. The request body is POLYMORPHIC — the shape of value is decided by the field's type, which you can read with clickup_get_list_custom_fields. Send the wrong shape and ClickUp answers 400. drop_down / labels take the option UUIDs found in the field's type_config.options[], not the display labels.

Value by field type:

Field type(s)

value shape

Example

text, short_text, url, email, phone

JSON string

"Ada Lovelace"

number, currency, money

JSON number

8000

date

int64 unix milliseconds; pair with value_options={"time": true} to keep the time-of-day (else date-only)

1667367645000

checkbox

boolean

true

emoji / rating

integer (count of filled icons)

4

drop_down (single-select)

a single option UUID string

"03efda77-c7a0-42d3-8afd-fd546353c2f5"

labels (multi-select)

an array of option UUID strings (the full desired set)

["uuidA", "uuidB"]

tasks (task relationship)

object {"add": [task_id...], "rem": [task_id...]}

{"add": ["abcd1234"], "rem": ["jklm9876"]}

users (people)

object {"add": [user_id...], "rem": [user_id...]}

{"add": [123, 456], "rem": [987]}

location

object {"location": {"lat": <num>, "lng": <num>}, "formatted_address": <str>} (a Google place_id may be given instead of/with lat-lng)

see below

Note: labels differ from tasks/people — labels take a plain array of UUIDs (the complete desired selection), NOT an {add, rem} object; {add, rem} is only for the tasks-relationship and people field types.

When to Use:

  • To populate or overwrite a single Custom Field on one task after resolving its field_id (and any option UUIDs) via clickup_get_list_custom_fields.

When NOT to Use:

  • To clear a field — use clickup_remove_custom_field_value instead of sending an empty value.

  • To set many fields at once on create — pass the custom_fields array to the task create/update tools in the Tasks module instead.

Returns: A confirmation string (the endpoint returns an empty body on success).

Examples:

  • text: params = {"task_id": "9hz", "field_id": "", "value": "In review"}

  • number: params = {"task_id": "9hz", "field_id": "", "value": 42}

  • date+time: params = {"task_id": "9hz", "field_id": "", "value": 1667367645000, "value_options": {"time": true}}

  • drop_down: params = {"task_id": "9hz", "field_id": "", "value": "03efda77-c7a0-42d3-8afd-fd546353c2f5"}

  • labels: params = {"task_id": "9hz", "field_id": "", "value": ["uuidA", "uuidB"]}

  • tasks: params = {"task_id": "9hz", "field_id": "", "value": {"add": ["abcd1234"], "rem": []}}

  • location: params = {"task_id": "9hz", "field_id": "", "value": {"location": {"lat": -28.016, "lng": 153.4}, "formatted_address": "Gold Coast QLD, Australia"}}

  • custom id: params = {"task_id": "ABC-123", "field_id": "", "value": 42, "custom_task_ids": true, "team_id": "9007200144"}

Error Handling: 400 usually means the value shape does not match the field's type, or the field is not enabled for the task's custom task type; 404 means the task or field_id is wrong; if custom_task_ids=true you must also pass team_id.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Tool Definition Quality

A4.9/5.0
Behavior5/5

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

Adds extensive behavior beyond annotations: POST method, polymorphic value shape, error handling (400, 404, custom_task_ids requirement), return type (confirmation string), and distinction between labels and tasks/people field types. No contradiction with annotations.

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?

Well-structured with sections (header, endpoint, value table, usage, return, examples, error handling). Minor redundancy in examples, but overall organized and front-loaded with key purpose. Slightly verbose but efficient.

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?

Given the complexity of polymorphic value shapes and many field types, the description covers all necessary aspects: prerequisites, error handling, parameter dependencies, and output. Output schema exists but description provides sufficient return info ('confirmation string').

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?

Despite 0% schema description coverage, the tool description provides a full value shape table, examples, and parameter relationships (e.g., team_id required when custom_task_ids=true, value_options for date fields). Compensates fully for schema gaps.

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 clearly states 'Set a Custom Field's value on a task' and specifies the endpoint. It distinguishes from sibling tools like clickup_remove_custom_field_value and notes when to use alternative tools for bulk operations. The verb and resource are explicitly defined.

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?

Provides explicit 'When to Use' and 'When NOT to Use' sections, referencing alternatives like clickup_remove_custom_field_value for clearing and task create/update tools for multiple fields. Also mentions prerequisites such as resolving field_id via clickup_get_list_custom_fields.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/trustxai/clickup-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server