This server lets an AI assistant operate a ClickUp workspace through MCP — finding, reading, creating, updating, deleting, and administering tasks, lists, docs, people, time, and more, with profile-based write restrictions.
Workspace discovery: list workspaces, spaces, folders, lists, seats, and members; search across tasks, docs, chats, attachments, and dashboards.
Tasks: list, get, create (single/bulk), update (single/bulk), delete, link/unlink, assign, set status/priority/dates, add tags, dependencies, custom fields, attachments, and reminders.
Task context: comments and threaded replies, checklists and checklist items, task members, subtasks, and due/start date handling.
Structure management: create/update/delete folders and lists, create lists from templates, and manage list statuses (list, create, update, delete, reorder).
Docs: get, list, search, create, update; manage pages (list, create, update, delete) with content formats.
Custom fields: list/create/update/delete field definitions, and get/set/remove/bulk-set values on tasks.
Dependencies: create, get, update, delete, bulk, graph, conflict/resolve/timeline analysis at task and workspace level.
Time tracking: list/create/update/delete time entries, start/stop/current timer, filter by task/date/assignee, billable flags.
Chat: list/get/create/update/delete channels, members/followers, send/update/delete messages, replies, reactions, tagged users, unread counts, search.
Goals: list, get, create, update, delete goals and key results.
People administration: list/invite/update/remove users, guests, groups; manage guest access to tasks/lists/folders; view workspace seats.
Webhooks: list, create, update, delete webhooks, and process incoming payloads with HMAC validation.
Views: list/create/get/update/delete views, set filters/grouping/sorting/settings, duplicate, share, and get tasks from a view.
Project intelligence: health, bottlenecks, velocity, dependencies, sprint, workload, risk, and time-report analysis.
Safety profiles: read is observe-only; agent is append-only; core covers normal editing; full adds membership, guest, and webhook administration. Attachment reads can be confined with CLICKUP_ATTACH_ROOT.
Provides comprehensive ClickUp integration with tools for managing tasks, lists, docs, chat, goals, webhooks, guests, time tracking, dependencies, and project intelligence analysis.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ClickUp MCP Server list tasks in Marketing list"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for ClickUp, built around two ideas:
Everything takes human names. find(scope: "Cavalry/Findings", assignee: "me", due: "overdue") — no IDs, no walking the tree to discover them. Names that don't resolve raise an error listing the valid options, because a confidently empty result is worse than a failure.
You choose what it can do. Four capability profiles, enforced on every outgoing request. Hand an unattended agent the agent profile and it can create tasks and comments but cannot alter or delete anything that already exists.
18 tools, 354 tests. Version 4.3.0 — see CHANGELOG.md. A heavily renovated fork of nsxdavid/clickup-mcp-server.
Status: 4.x is new. It has been through five adversarial red-team rounds but has not yet run in production. The previous 3.x line is still shipped in this repo and still what the reference deployment runs — see Running 3.x.
Get a token from ClickUp → Settings → Apps → API Token (it starts with pk_). The workspace is discovered automatically — there is nothing else to configure.
No install:
{
"mcpServers": {
"clickup": {
"command": "npx",
"args": ["-y", "github:benthesoundguy/clickup-mcp-server"],
"env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
}
}
}Or from a clone, which is what you want if you plan to change anything:
git clone https://github.com/benthesoundguy/clickup-mcp-server
cd clickup-mcp-server
npm install # builds automatically
npm run check # verifies the token and connects — do this before wiring up a client{
"mcpServers": {
"clickup": {
"command": "node",
"args": ["/absolute/path/to/clickup-mcp-server/build/v4/index.js"],
"env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
}
}
}The shape above works as-is in Claude Desktop, Claude Code, Cursor, Cline, and Windsurf — they all use the mcpServers key. Two clients differ:
VS Code (.vscode/mcp.json) uses servers instead of mcpServers. Same inner shape. Copying a Cursor config unchanged is the most common setup mistake.
Zed (settings.json) uses context_servers, and nests the command:
{ "context_servers": { "clickup": { "command": { "path": "node", "args": ["/path/to/build/v4/index.js"] } } } }Claude Code can skip the file entirely:
claude mcp add clickup --env CLICKUP_API_TOKEN=pk_... -- npx -y github:benthesoundguy/clickup-mcp-serverIf you would rather not paste a token into a client config — desktop apps rewrite those files and can persist a stale copy — put it in a .env next to the install and omit the env block entirely:
echo 'CLICKUP_API_TOKEN=pk_your_token_here' > .envThe server looks in <cwd>/.env, <install>/.env, and <install>/../.env, in that order, and says which one it used at startup. The token from the file outranks the environment, so rotating it in one place actually takes effect. Every other setting works the other way round — an explicit value in your client config always wins, so a stray .env can never widen MCP_PROFILE. Set MCP_STRICT_ENV=1 on a server to switch the whole lookup off.
npm run check # from a clone
node build/v4/index.js --checkThis prints every input the server resolved — which .env it found and what it applied, whether the token is present and the right shape, the active profile and tool count, the Node version and build stamp — and then actually connects to ClickUp and reports who you are and your rate budget. It never prints the token, so the output is safe to paste into an issue.
If the token is missing, the server does not die silently in stdio mode. It starts, registers its tools, and every call answers with what's wrong and how to fix it, so the problem shows up in your conversation rather than in a log file you have to go find. (In HTTP mode it still exits 1 — an unattended deployment should fail loudly.)
Related MCP server: ClickUp MCP Server
One binary, four profiles, selected with MCP_PROFILE. Install once and add a client entry per profile, enabling whichever a given agent should have.
| tools | schema cost | What it can do |
| 11 | 2,236 tok | Observe only. No write of any kind can leave the process. |
| 12 | 2,635 tok | Read, plus append: create tasks, comments, chat messages, checklist items, time logs. Cannot alter or delete anything existing. |
| 16 | 4,129 tok | Everything a normal user does. No membership, guest, or webhook administration. |
| 18 | 4,748 tok | Unrestricted, including membership and webhooks. |
Schema cost is what the tool definitions consume in the model's context on every request, before any work happens. For comparison, 3.x costs ~18,600 tokens for 88 tools.
agent is the interesting one. It can add but never alter or destroy, so the worst an unattended agent can do is create clutter you can delete. That guarantee is enforced in three layers, and only the third is a security boundary:
Tool filtering — which tools appear at all (context cost + tool selection)
Action filtering — which actions a tool advertises (context cost + honesty)
Write policy — an allowlist checked on every outgoing request, including uploads ← the guarantee
Layers 1 and 2 depend on every tool being tagged correctly by every future contributor. Layer 3 does not: it inspects the actual request on its way out, so a mistagged tool, a refactor, or an endpoint added next year cannot widen a profile. The test suite proves this by calling core-only handlers directly with an agent context — bypassing layers 1 and 2 entirely — and asserting nothing reaches the wire.
Things that look additive but are excluded from agent on purpose: attaching a tag, setting a custom field, and adding a dependency all mutate an existing task; creating a webhook starts streaming your data to an external endpoint. Append-only and safe are not the same property.
core and not fullfull grants membership administration — inviting a user consumes a billable seat, removing one changes a real person's access — plus webhooks, which send workspace data off-site. None of that is what a first connection is for, and a default nobody changes has to be the safe one. Ask for administration by name when you want it; until you do, the refusal tells you exactly how.
attach reads a file from the machine the server runs on. That is a resource the write policy cannot see — it inspects URLs, and a file read has no URL — so it is governed separately by CLICKUP_ATTACH_ROOT:
Set → reads are confined to that directory. Containment is checked against the file's real path, after resolving .. and every symlink.
Unset → core and full may read any file the process can. Under agent, attach is not offered at all (12 tools instead of 13), because there is no safe default root: the working directory is usually the project directory, which is where .env lives.
A misconfigured root is fatal at startup rather than ignored — a boundary that silently isn't there is worse than none.
Tool | Min profile | Job |
| read | Query tasks anywhere. Scope, status, assignee, tags, due date — all by name. |
| read | One task in full, optionally with comments and subtasks. |
| read | Workspace structure, printing the exact paths other tools accept. |
| read | What values are legal here — statuses a list accepts, tags in a space, assignable people. |
| read | Identity, workspace, rate-limit budget, server health. |
| read | Search ClickUp Docs, or read one. |
| read | Read a task's comment thread, or post to it. |
| read |
|
| read | Inspect a list's custom fields, or set one by name. |
| read |
|
| read |
|
| agent | Create one or more tasks — pass an array for bulk. |
| agent | Upload a local file to a task (max 25MB). See above. |
| core | Update, move, assign, close, or delete — pass several IDs for bulk. |
| core |
|
| core |
|
| full | Members, guests, seats, groups, invitations, admin rights. |
| full |
|
Tools narrow rather than vanish where it makes sense: under read, comment shows only its reading arguments and checklist advertises only list, so the schema tells the truth about what this connection can do instead of advertising actions that would be refused.
Never return a confident wrong answer. ClickUp makes this easy to get wrong, because it answers bad input with cheerful nonsense:
Request | ClickUp says | Which reads as |
|
| "Sam has no work" — there is no Sam |
|
| a filtered search that wasn't |
|
| "moved" — it didn't move |
|
| "moved" — silently ignored |
|
| a permissions problem — it's a typo |
|
| an outage — it's a bad enum |
So this server resolves names and raises on ambiguity ("Findings" matching four lists is an error naming all four, never a coin flip); raises rather than returning empty when a filter value doesn't resolve; validates enums client-side against what the list actually accepts; verifies writes it cannot trust by reading the object back; and never overstates a count — a query that stopped paging reports 100+ matches, and any client-side filter reports how much it actually scanned.
Errors say what failed, why, and what to do next, with the valid options listed.
Variable | Default | Notes |
| — | Required. ClickUp personal API token. |
|
|
|
| unset | Absolute directory that |
| discovered | Only needed if the token can see several workspaces and you want a specific one. |
|
| Set to |
|
| Bind address. Loopback by default — put a proxy or tunnel in front rather than binding |
|
| Also selects HTTP mode if set. |
| generated | Static bearer token, min 16 chars. Optional once |
| — | Authorization server issuer URL. Setting it makes this an OAuth resource server. |
| — | Required with OAuth. This server's canonical URI — the audience inbound tokens must name. Never inferred from the request. |
|
| Override, if your issuer mints a different audience value. |
| discovered | Signing keys, if the issuer publishes no discovery document. |
| — | Advertised in the metadata document. Informational. |
| off | Set to |
| off in strict | Re-enables the |
| off | Disables the |
| — | Cloudflare Access team. Enables Access JWT validation. |
| — | Access application AUD tag. Required alongside the team domain — neither alone enables anything. |
The server speaks streamable HTTP, and accepts three independent credentials. Any one of them authenticates a request; they are meant to coexist, because different clients can present different things.
Credential | For | Set with |
OAuth 2.1 access token | Hosted clients — claude.ai connectors, ChatGPT connectors, anything spec-compliant |
|
Cloudflare Access JWT | An origin behind a CF Tunnel |
|
Static bearer token | Scripts, n8n, curl, CI |
|
MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
MCP_PROFILE=core CLICKUP_API_TOKEN=... node build/v4/index.jsGET /health is an unauthenticated probe reporting version, active profile, tool count and attachment root.
This server does not need to be an OAuth provider, and isn't one. Since the 2025-06-18 MCP spec, an MCP server is a resource server: it names the authorization server it trusts and validates the tokens that server issues. Login, consent and token issuance belong to your IdP — Cloudflare Access, WorkOS, Auth0, Descope, Stytch, Keycloak, anything with OIDC discovery.
MCP_TRANSPORT=http \
MCP_PUBLIC_URL=https://mcp.example.com \
MCP_OAUTH_ISSUER=https://your-idp.example.com \
CLICKUP_API_TOKEN=pk_... node build/v4/index.jsThat is the whole configuration. The server then:
serves RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource, naming your issuer, unauthenticated;
answers an unauthenticated request with 401 and a WWW-Authenticate header pointing at that document, which is how a client discovers where to log in;
discovers your issuer's signing keys via /.well-known/openid-configuration (or RFC 8414), or uses MCP_OAUTH_JWKS_URL if you set it;
validates every token: RS256 pinned, signature against the issuer's JWKS, exp, nbf, iss, and aud — the token must name this server.
That last check is the one that matters. Without it, a token your IdP minted for some other service could be replayed here. It's why MCP_PUBLIC_URL is required rather than inferred: the expected audience must never come from the request, because the Host header is set by the caller.
MCP_AUTH_TOKEN becomes optional once an issuer is configured — an OAuth-only deployment doesn't need a shared password it never uses.
Note on Dynamic Client Registration. The 2026-07-28 spec deprecated DCR in favour of Client ID Metadata Documents. That change lands on authorization servers and clients; a resource server is unaffected either way, which is a good reason to delegate rather than roll your own AS.
Claude's custom connector UI accepts OAuth fields only — Authorization URL, Token URL, Client ID, Client Secret. There is no field for a static bearer token or a custom header (#112, #411). So:
With OAuth configured, connect it as a normal custom connector. This is the intended path.
Without OAuth, the only way in is the token-in-URL form, /mcp/<token>, enabled with MCP_ALLOW_TOKEN_IN_PATH=1. It works, but it puts a credential in a URL where proxies log it, which is why strict mode refuses it. Treat it as a workaround, not a deployment.
Set CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD and the server validates the Cf-Access-Jwt-Assertion header Access puts on every request it forwards: RS256 against the team JWKS, plus exp, iss, and aud. Both Access flows validate through one path — a browser login carries email, a service token carries common_name.
This is defence in depth. A request reaching the origin without passing through Access — a tunnel misconfiguration, a second ingress, something on the host's network — cannot impersonate an Access-authenticated caller. It fails closed: alg is pinned to RS256 (so alg: none and HS256 confusion are rejected), an unreachable JWKS denies rather than bypasses, and the JWKS URL comes from configuration, never from the token.
Bearer auth keeps working. A request is authorized by a valid Access JWT or a valid bearer token, so header-capable agents need no changes.
The origin does not serve /.well-known/oauth-* — with Managed OAuth enabled, Access is the authorization server and serves discovery at the edge.
MCP_STRICT_ENV=1)The posture for an unattended deployment. Secrets must come from the environment, the server never invents or persists a credential, and it exits 1 with an actionable message rather than starting misconfigured. It also refuses the URL-path token form, which lands the credential in proxy access logs.
This matters because the .env-file lookup deliberately outranks process.env — a desktop host rewrites its own config file from memory on quit, so the file has to win there. On a server that precedence is backwards: a stray .env in the working directory would silently outrank the systemd unit. Strict mode turns the lookup off.
See deploy/DEPLOY.md for the full recipe: VPS setup script, hardened systemd unit, Cloudflare Tunnel, and connecting it to Claude.
The tool names are entirely different — 4.x is a rewrite, not a rename. Anything holding hard-coded 3.x tool names (saved prompts, agent instructions, scripts) needs updating.
The mapping is mostly many-to-one:
3.x | 4.x |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Not carried over: project_intelligence (the eight local analysis reports) and reminders_create. Status management — creating, renaming, reordering statuses — is also absent; meta reads statuses but does not change them. If you need any of these, run 3.x.
3.x is still built and shipped from this repo:
npm run start:v3 # via the package script
node build/index.js # the 3.x entry point directlyPoint an MCP client at build/index.js instead of build/v4/index.js to keep using it.
The reference systemd unit in deploy/ is deliberately still pinned to 3.x, because a running service should not change major version because a package default moved underneath it. Migrate it by pointing ExecStart at build/v4/index.js and setting MCP_PROFILE explicitly.
Not bugs here — the API genuinely lacks these, and this server reports the limit rather than faking around it.
Tasks cannot be moved between lists. POST /list/{dest}/task/{id} returns 200 {} and does nothing without the "Tasks in Multiple Lists" ClickApp; PUT with list_id is silently ignored; /move 404s. update's move path reads the task back and fails loudly rather than reporting a move that didn't happen.
Attachments have no list endpoint — task reads them off the task object. Uploads are multipart-only, capped at 25MB.
Docs cannot be renamed or deleted, and pages cannot be deleted.
Custom field definitions can be listed and created, not edited or deleted.
Date custom fields require Unix milliseconds; YYYY-MM-DD is rejected by ClickUp for those. Task due_date/start_date accept both and are converted here.
Status and tag names are stored lower-cased; matching here is case-insensitive throughout.
Lists override their space's statuses constantly, so "what statuses are valid" is a per-list question. meta answers it per list.
ClickUp answers an invalid enum with HTTP 500, so enums are validated client-side before sending.
The rate limit is roughly 100 requests/minute per token, shared across everything using it. whoami reports the live budget; the server paces itself against the x-ratelimit-* headers.
Process ClickUp webhook events without external infrastructure:
WEBHOOK_PORT=3001 WEBHOOK_SECRET=your_secret node build/webhook-receiver/index.jsHMAC-SHA256 validation over the raw request body; when a secret is configured, unsigned requests are rejected
Structured event parsing — type, object, operation, changes, user, timestamp
Optional forwarding to a callback URL (WEBHOOK_FORWARD_URL)
Pure Node.js http, zero extra dependencies
npm install
npm run build
npm test # 354 tests, mocked HTTP — no token needed
npm run smoke # live CRUD walk (needs CLICKUP_API_TOKEN; creates and
# deletes its own sandbox in your workspace)Architecture notes for 4.x live in src/v4/README.md; the design rationale and measurements are in V4-PLAN.md.
Call whoami. It reports the running build's version and stamp. MCP hosts spawn their own server process at session start and hold it, so a rebuild does not reach an already-running session — if the stamp predates your change, restart the host app. This accounted for several phantom bug reports before the tool existed.
MIT — see LICENSE. Fork of nsxdavid/clickup-mcp-server by David Whatley.
Manage attachments on ClickUp tasks. Use "list" to see existing attachments, "create" to attach by URL, or "upload" to upload a file (base64-encoded).
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Required for create: the public URL of the file to attach | |
| action | Yes | Action to perform | |
| task_id | Yes | The ID of the task | |
| file_data | No | Required for upload: base64-encoded file content | |
| file_name | No | Display name for the file (create/upload) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that 'list' shows existing attachments, 'create' attaches by URL, and 'upload' sends base64-encoded content, which is useful behavioral context. However, it does not mention permissions, potential side effects, error behavior, or response format, leaving gaps for a tool with both read and write actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly structured sentence that leads with the tool's purpose and immediately enumerates the three actions. Every phrase adds value, with no wasted words or redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three actions, the description adequately covers what each action does, and the schema covers parameter requirements. It lacks output/return details and broader behavioral context, but given the tool's moderate complexity and strong schema coverage, it is reasonably complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for each parameter (e.g., 'Required for create: the public URL' and 'Required for upload: base64-encoded file content'). The description's mention of 'attach by URL' and 'base64-encoded' adds little beyond what the schema already provides, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear action-resource pairing: 'Manage attachments on ClickUp tasks.' It then enumerates three distinct modes (list, create, upload) with specific meanings, distinguishing it from other tools and clarifying scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides specific guidance on which action to use: 'Use list to see existing attachments, create to attach by URL, or upload to upload a file (base64-encoded).' This gives clear context for the tool's actions, though it does not explicitly mention when not to use it or compare to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage ClickUp chat channels. Use action to list, get, create, update, delete, create DM, search, view stats, or mark as read.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Channel name (create, update, search) | |
| type | No | Channel type (create) | |
| action | Yes | Action to perform | |
| user_ids | No | User IDs for DM channel (dm) | |
| channel_id | No | Required for get, update, delete, stats, mark_read | |
| description | No | Channel description (create, update, dm) | |
| workspace_id | No | Required for list, create, dm, search | |
| team_member_ids | No | Member IDs to add (create) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only says 'Manage' and lists actions without disclosing side effects (e.g., destructive nature of delete), permissions, or behavioral nuances. This is particularly lacking for a tool with mutating and read-altering actions like mark_read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the resource and the full list of actions. It is slightly dense due to the enumeration of nine actions, but it avoids redundancy and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 actions, 8 parameters, no output schema, and no annotations, a one-line description is insufficient. The schema covers input requirements, but the description does not explain what each action returns, behavior differences, or prerequisites, making it incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for all 8 parameters, including which actions require which fields (e.g., channel_id for get/update/delete/stats/mark_read). The description adds no additional parameter-level meaning beyond restating the action names that are already in the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Manage ClickUp chat channels' and enumerates all supported actions (list, get, create, update, delete, dm, search, stats, mark_read). This distinguishes it from sibling tools like channels_members and channels_messages, though the verb 'Manage' is somewhat generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists the actions to perform but provides no explicit guidance on when to use this tool versus alternatives such as channels_members or channels_messages. Usage is implied through the action enumeration, but there are no contextual triggers or exclusionary notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage members of a ClickUp chat channel. Use action to list members, list followers, add, or remove.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| user_id | No | Required for add/remove: the user ID | |
| channel_id | Yes | The ID of the channel |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral aspects. It lists the actions (list, followers, add, remove) but does not explain side effects, permissions required, or return formats. For add/remove, it implies mutation but does not clarify whether changes are reversible or what happens on failure. This is a significant gap for a multi-action tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences. The first sentence states the purpose and resource, the second lists the actions. It is front-loaded and contains no filler, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has multiple actions and no output schema, the description is too sparse. It does not explain what each action returns, what 'followers' means, or any prerequisites. An agent would struggle to know what to expect after calling 'add' or 'remove'. The description is not complete enough for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents all parameters. The description adds the action enum values (list, followers, add, remove) in prose, but this duplicates schema information and adds no extra meaning for user_id or channel_id. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages members of a ClickUp chat channel and enumerates the specific actions (list, followers, add, remove). This distinguishes it from related sibling tools like channels_messages or tasks_members_list. However, the verb 'manage' is somewhat generic, and the description could be more specific about the resource being channel members rather than just 'members'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for ClickUp chat channel member operations but provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions or prerequisites. The context is clear enough for basic selection, but it falls short of the level of guidance seen in tools that name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage messages in a ClickUp chat channel. Use action to list, send, update, delete, manage replies, reactions, tagged users, unread count, or search messages.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (list, replies_list) | |
| query | No | Search query (search) | |
| action | Yes | Action to perform | |
| cursor | No | Pagination cursor (list, replies_list) | |
| content | No | Message content (send, update, replies_create) | |
| reaction | No | Reaction emoji/text (reactions_create, reactions_delete) | |
| channel_id | No | Required for list, send, reactions, tagged, unread, search | |
| message_id | No | Required for update, delete, replies, reactions | |
| workspace_id | No | Required for search | |
| content_format | No | Content format (list, replies_list) | |
| parent_message_id | No | Parent message for threaded reply (send) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of disclosing behavioral traits. It only lists actions without explaining side effects (e.g., deletion permanence, permission requirements, or whether 'unread' lists or marks messages). No information about return values or pagination behavior is given either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently lists the tool's purpose and actions. It is concise and front-loaded, though the enumeration of actions becomes somewhat listy. It avoids unnecessary filler and is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 11 parameters, 12 actions, no output schema, and no annotations. The description only states action names without providing essential context like the workspace_id requirement for search, the ambiguity of 'unread' (count vs mark), or how responses are structured. It falls short of the burden placed on it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented. The description adds no additional meaning beyond the schema, merely listing actions. It does not clarify parameter-action dependencies that aren't already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('messages in a ClickUp chat channel') and the available actions (list, send, update, delete, replies, reactions, tagged users, unread, search). This distinguishes it from sibling comment tools like tasks_comments or comments_replies_create, which operate on non-chat comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The resource context is clear (chat channel messages), implying when this tool should be used. However, there is no explicit "use this instead of X" or when-not-to-use guidance, especially in contrast to comment-related tools, so it remains implied rather than directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new checklist in a ClickUp task. Returns the created checklist details.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the checklist | |
| task_id | Yes | The ID of the task to create the checklist in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the tool returns created checklist details, which is useful. However, it omits other behavioral aspects such as permissions, error handling, or idempotency, leaving the agent with limited insight into side effects or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that directly states the action and the return value. It is front-loaded with the key verb and resource, with no unnecessary words or repetition. This is an example of appropriate conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required parameters, no nested objects, no output schema), the description covers the essential context: what it does, where it operates, and what it returns. While it could elaborate on the return details, the description is complete enough for an agent to select and invoke the tool correctly for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (task_id and name), achieving 100% schema description coverage. The description's mention of 'in a ClickUp task' aligns with the schema but adds no new meaning beyond what is already documented. Therefore, the description does not enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new checklist in a ClickUp task, using a specific verb and resource. It distinguishes itself from sibling tools like checklists_update and checklists_delete by targeting creation. The mention of returning created checklist details further clarifies its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool when you need to create a checklist within a task. However, it does not explicitly state alternatives or when not to use it. The purpose is clear enough that an agent could infer appropriate usage, but direct guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a checklist from a ClickUp task. Removes the checklist and all its items.
| Name | Required | Description | Default |
|---|---|---|---|
| checklist_id | Yes | The ID of the checklist to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses a key behavioral trait: deletion cascades to all items in the checklist. However, it does not mention irreversibility, required permissions, or what happens if the checklist ID is invalid. This is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the verb and resource, and every word adds value. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and no output schema, the description is sufficiently complete. It states the action, scope, and cascade effect. It doesn't cover error cases or permissions, but these are not critical for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter is already described as 'The ID of the checklist to delete'. The description adds no additional meaning about the parameter itself, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Delete a checklist from a ClickUp task') and its scope ('Removes the checklist and all its items'). It is distinct from sibling tools like checklists_update or checklists_items_delete, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., deleting individual checklist items). The context is implied by the name and description, but there is no mention of when this is preferable over checklists_items_delete or other deletion tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new item in a ClickUp checklist. Supports optional assignee and resolved status.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the checklist item | |
| assignee | No | The ID of the user to assign to the checklist item | |
| resolved | No | Whether the checklist item is resolved | |
| checklist_id | Yes | The ID of the checklist to create the item in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool supports optional assignee and resolved status, which is helpful, but it does not mention side effects, required permissions, error behavior, or prerequisites beyond the parameters. The description is adequate for a simple create operation but lacks deeper behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core purpose and adds optional parameter context. Every word earns its place, and it is appropriately sized for a tool with a simple, well-documented schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the essential function and optional parameters. There is no output schema, so the description need not explain return values. It is complete enough for an agent to select and invoke the tool correctly, though additional context about prerequisites (e.g., needing an existing checklist) could enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter text, so the baseline is 3. The description adds that assignee and resolved are 'optional,' which reinforces the schema's required-field list, but it does not significantly enhance understanding beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Create a new item in a ClickUp checklist.' This distinguishes it from sibling tools like checklists_items_update and checklists_items_delete, and it correctly scopes the operation to checklist items rather than checklists themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to create checklist items) but offers no explicit guidance on when not to use it or which alternatives might be more appropriate (e.g., creating a checklist vs. an item). There are no stated exclusions or preconditions, so usage context is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an item from a ClickUp checklist.
| Name | Required | Description | Default |
|---|---|---|---|
| checklist_id | Yes | The ID of the checklist containing the item | |
| checklist_item_id | Yes | The ID of the checklist item to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It merely repeats the action implied by the name ('Delete') without adding important context such as irreversibility, permission requirements, or potential cascading effects. The description adds no safety or side-effect information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately conveys the tool's purpose with no unnecessary words. It is well-structured and front-loaded, consistent with best practices for simple delete operations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with two well-documented parameters and no output schema, the description is sufficiently complete. It conveys the core action and resource, though it could optionally mention whether the deletion is permanent or if any response is expected, but such details are not critical for usability here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as both checklist_id and checklist_item_id have descriptions. The tool description adds no extra parameter meaning beyond the schema, which itself adequately documents the two required IDs, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the specific resource ('an item from a ClickUp checklist'), making it unambiguous and distinguishing it from siblings like checklists_delete (which deletes a whole checklist) and checklists_items_create/update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use by stating it deletes an item, but it does not explicitly mention when to use this tool instead of alternatives such as deleting the entire checklist. No exclusions or alternative tool references are provided, leaving the context to be inferred from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing ClickUp checklist item's properties including name, assignee, and resolved status.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The new name of the checklist item | |
| assignee | No | The ID of the user to assign to the checklist item | |
| resolved | No | Whether the checklist item is resolved | |
| checklist_id | Yes | The ID of the checklist containing the item | |
| checklist_item_id | Yes | The ID of the checklist item to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the action and the fields, without revealing whether updates are partial or full, what permissions are needed, what happens to unspecified fields, or what response to expect. This is a mutation tool, so such missing context is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource. It contains no redundancy, jargon, or filler, making it efficient and easy to parse for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple and the schema fully documents all parameters, so the description is adequate for basic usage. However, it omits the response format, partial-update semantics, and any required permissions, which are useful for an agent to invoke it correctly in a real workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description lists the updatable fields (name, assignee, resolved) but those are already described in the schema, adding no extra semantic value. It does not clarify parameter formats, constraints, or relationships beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('Checklist item'), and enumerates the specific properties that can be changed (name, assignee, resolved status). This distinguishes it from sibling tools like checklists_items_create and checklists_items_delete, as well as checklists_update which targets the checklist itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an existing checklist item needs modification, but it does not explicitly contrast with create/delete alternatives or mention any prerequisites. There is no guidance on when to prefer this tool over siblings, so the agent must infer the context from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing ClickUp checklist's name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The new name of the checklist | |
| checklist_id | Yes | The ID of the checklist to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It accurately states that the operation updates the name, but it omits any context about permissions, error behavior, or whether other checklist attributes are left unchanged. For a simple rename, this is minimally adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that communicates the core purpose without any wasted words. It is highly scannable and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema, no annotations) and the clarity of the description, the description sufficiently covers the primary operation. It could be more complete with usage guidelines, but for such a straightforward rename action, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both required parameters ('name' and 'checklist_id') adequately documented in the schema. The description adds no additional parameter semantics beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('update') and resource ('existing ClickUp checklist's name'), which precisely distinguishes this tool from siblings like checklists_create, checklists_delete, and the checklists_items_* tools. It leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (rename a checklist) but does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. With clear sibling distinctions available, a little more guidance (e.g., 'Use only for renaming; use checklists_items_update to modify checklist items') would improve this score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a comment from ClickUp.
| Name | Required | Description | Default |
|---|---|---|---|
| comment_id | Yes | The ID of the comment to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description alone must disclose behavioral traits. It only states the destructive action but does not mention irreversibility, effects on replies, authentication needs, or response behavior. This is minimal disclosure beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and target. There is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, so the description covers the core purpose. However, it lacks any context about side effects, authorization, or exclusions (e.g., whether replies are cascaded), making it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with a clear description for the 'comment_id' parameter. The tool description adds no extra meaning beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a comment from ClickUp' uses a specific verb and resource, clearly distinguishing this tool from siblings like comments_update or comments_replies_create. It is unambiguous and directly states the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, prerequisites, or potential consequences. There is no mention of edge cases like deleting comments with replies or permission requirements, leaving the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new threaded comment (reply) to a parent comment. Supports notification settings.
| Name | Required | Description | Default |
|---|---|---|---|
| comment_id | Yes | The ID of the parent comment | |
| notify_all | No | Whether to notify all assignees | |
| comment_text | Yes | The text content of the comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the core behavior (creating a reply) and mentions notification settings, but it does not explain any side effects, permission requirements, or what happens with notify_all (e.g., default behavior). This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundancy. It front-loads the core purpose and includes the extra feature (notification settings) in a compact manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool without output schema or annotations, the description covers the core purpose and a key feature. It lacks details about response format or error conditions, but the tool is simple enough that this is not a major gap. It is nearly complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (comment_id, comment_text, notify_all) are documented in the schema. The description adds minimal additional meaning beyond noting notification settings, which aligns with the notify_all parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (create) and resource (a threaded reply to a parent comment), clearly distinguishing it from sibling tools that create top-level comments or list replies. It precisely identifies the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for replying to an existing comment rather than creating standalone comments. It does not explicitly name alternatives, but the phrase 'to a parent comment' provides clear context for when to use it. Lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get threaded comments (replies) for a parent comment. Returns comment details with pagination support.
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Pagination start (timestamp) | |
| start_id | No | Pagination start ID | |
| comment_id | Yes | The ID of the parent comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'Returns comment details with pagination support,' which is a basic return-format note, but it does not explicitly state that this is a read-only operation or describe any potential side effects. It also lacks details about ordering, depth of replies, or whether the parent comment itself is included in the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose. Every word adds value, and there is no redundancy or filler. It efficiently conveys both the primary action and the key supporting detail about return format and pagination.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, no output schema), the description provides a minimal but adequate overview. It mentions pagination and comment details, but it does not elaborate on the exact return structure, limits, or how pagination parameters interact. Since there is no output schema, the description could have offered more context, but it is not severely incomplete for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for all three parameters (start, start_id, comment_id), so the description does not need to explain them. The tool description adds no extra meaning beyond the schema's existing descriptions, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get threaded comments (replies) for a parent comment.' It uses a specific verb and resource, and the mention of 'parent comment' distinguishes it from other comment-listing tools like tasks_comments_list or views_comments_list. The added note about returning comment details with pagination support further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool—when you need replies to a specific parent comment—and clarifies that it returns threaded replies, not all comments. However, it does not explicitly list alternatives or state when not to use it, though the context is clear enough for an agent to select it over sibling comment-list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing ClickUp comment's properties including text, assignee, and resolved status.
| Name | Required | Description | Default |
|---|---|---|---|
| assignee | No | The ID of the user to assign to the comment | |
| resolved | No | Whether the comment is resolved | |
| comment_id | Yes | The ID of the comment to update | |
| comment_text | Yes | The new text content of the comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It indicates mutation ('update') but does not explain whether all properties are replaced, how partial updates are handled, what happens if the comment_id does not exist, or any permission requirements. This is a significant gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the verb and resource, and provides a concise list of relevant properties. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple update with 4 parameters and no output schema, but the description omits behavior like whether optional parameters (assignee, resolved) can be updated independently or must accompany comment_text. It also doesn't indicate response or error behavior. Understanding the required comment_id/comment_text is left to the schema, which is reasonable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description merely lists fields ('text, assignee, and resolved status') already documented in the schema, adding no extra semantic detail about parameter usage, types, or relationship to the update operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Update'), the resource ('an existing ClickUp comment'), and its scope ('properties including text, assignee, and resolved status'). This distinguishes it from sibling tools like comments_replies_create and comments_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the tool's intended use—modifying an existing comment's properties—which is implicitly distinct from creating or deleting comments. However, it does not explicitly mention alternatives or provide when-not-to-use guidance, so it lacks full exclusionary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List, create, update, or delete custom field definitions. Use "list" to get field schemas, "create" to add a field, "update" to modify it, or "delete" to remove it.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Required for create: the field name. Optional for update. | |
| type | No | Required for create: field type (text, number, date, checkbox, dropdown, etc.) | |
| action | Yes | Action to perform | |
| options | No | Dropdown options (required for dropdown type) | |
| field_id | No | Required for update, delete: the custom field ID | |
| required | No | Whether the field is required | |
| scope_id | No | The ID of the list, folder, space, or workspace (list, create) | |
| scope_type | No | The scope level (list, create) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It mentions 'delete' and 'update' without warning about side effects, irreversibility, permission requirements, or response behavior. It essentially restates the action enum from the schema without adding meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences long, front-loaded with the resource and actions, no wasted words. It is concise and structured well.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a multi-action CRUD with 8 parameters, and there is no output schema. The description covers the high-level operations but omits behavioral details like error cases, scope requirements, or return values. The input schema compensates somewhat by fully documenting parameters, making the description minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 8 parameters, so the baseline is 3. The description adds minimal value beyond the schema by linking 'list' to 'field schemas,' but it does not explain conditional requirements or parameter relationships that aren't already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List, create, update, or delete custom field definitions.' It uses specific verbs and identifies the resource, distinguishing it from the sibling tool 'custom_fields_values' which handles values rather than definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides sub-action guidance ('Use list to get field schemas, create to add a field, etc.'), giving clear context for internal actions. However, it offers no explicit guidance on when to choose this tool over alternatives like custom_fields_values or other mutation tools, and no exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get, set, remove, or bulk-set custom field values on ClickUp tasks. Use "get" to read all field values on a task, "set" to write a value, "remove" to clear it, or "bulk_set" to set values across multiple tasks in one operation. For dropdown/labels fields, pass the option UUID (get UUIDs from custom_fields tool with action="list"). For date fields, pass a Unix timestamp in milliseconds. For people fields, pass {add:[user_ids], rem:[user_ids]}. For location fields, pass {lat:number, lng:number, formatted_address?:string}.
| Name | Required | Description | Default |
|---|---|---|---|
| value | No | Required for set: the value. Format depends on field type: text/url/email/phone → string number/rating → number checkbox → boolean date → Unix timestamp ms dropdown → option UUID labels → array of option UUIDs people → {add:[ids], rem:[ids]} location → {lat, lng, formatted_address} | |
| action | Yes | Action to perform | |
| task_id | No | Required for get, set, remove: the task ID | |
| updates | Yes | Array of {task_id, field_id, value} objects (bulk_set only) | |
| field_id | No | Required for set, remove: the custom field ID | |
| continue_on_error | No | Continue if an individual update fails (bulk_set) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral context. It discloses input formats for various field types, which is useful, but it does not mention potential side effects, error behavior, permission requirements, or idempotency. For a mutation-capable tool, this is a moderate transparency level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact paragraph that front-loads the core purpose and then methodically explains each action and field format. Every sentence adds value, and the structure is logical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main operations and all field type formats, which is substantial for a tool with 6 parameters and multiple actions. Given the absence of an output schema, it does not describe return values, but that is not essential. It could have added a note about what 'get' returns, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, and the description largely mirrors the schema's parameter details, especially for the 'value' parameter. It does add a cross-tool reference for UUIDs, but overall it does not significantly enhance understanding beyond the schema's own explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly lists the verbs 'get, set, remove, or bulk-set' and identifies the resource as 'custom field values on ClickUp tasks'. This clearly distinguishes it from sibling tools like 'custom_fields' which likely manage field definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance for each action: 'Use "get" to read all field values on a task, "set" to write a value, "remove" to clear it, or "bulk_set" to set values across multiple tasks'. It also directs users to the 'custom_fields' tool to obtain option UUIDs for dropdowns/labels, showing awareness of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage task dependencies. Use action to create, get, update, delete, view dependency graph, check/resolve conflicts, view timeline impact, or bulk create.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| task_id | No | Required for create, get, graph, conflicts, resolve, timeline | |
| depends_on | No | Required for create, conflicts: the task this one depends on | |
| dependencies | No | Array of dependencies for bulk create | |
| workspace_id | No | Required for bulk | |
| dependency_id | No | Required for update, delete | |
| dependency_type | No | Dependency type (create, update) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It only lists action names that already appear in the schema enum, without explaining side effects, permissions, reversibility, or what operations like 'resolve' or 'timeline' actually do. This is insufficient for a tool that performs both reads and mutations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences that front-load the core purpose and then efficiently list the available actions. Every word contributes to understanding the tool's scope, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 7 parameters, 9 actions, no output schema, and no annotations. The description only gives a high-level action list and does not explain use cases, prerequisites, return behavior, or potential side effects. It is not complete enough for an agent to confidently select and invoke the correct action without further investigation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level semantics beyond what the schema already provides; it merely mentions actions without mapping them to specific parameters, leaving the schema to carry the explanatory load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages task dependencies, which is a specific resource type, and enumerates the distinct operations (create, get, update, delete, graph, conflicts, resolve, bulk, timeline). This distinguishes it from sibling tools like tasks_link/unlink and dependencies_workspace, which handle different aspects of dependencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the context that this tool is for task dependencies and instructs the user to pick an action, implying usage. However, it does not explicitly state when to use this tool over alternatives like dependencies_workspace, nor does it provide exclusion criteria or prerequisites for specific actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage dependencies at the workspace level. Use action to list all dependencies, view stats, or export/import the dependency graph.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Dependency graph data to import (import) | |
| page | No | Page number for paginated results (list) | |
| action | Yes | Action to perform | |
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not reveal whether import merges or replaces the existing graph, what the export format is, how pagination behaves for list, any permission requirements, or side effects. For a multi-action tool, this omission is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence front-loaded with the tool's purpose ('Manage dependencies at the workspace level'), followed by concrete examples of actions. There is no redundancy or wasted wording, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four distinct actions, no output schema, and no annotations, the description should provide more comprehensive context. It omits return formats, import behavior, pagination details for list, and action-specific requirements, leaving an agent under-equipped to invoke the tool correctly in all scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as every parameter has a description in the schema. The tool description adds minimal semantic value beyond restating that 'action' determines the operation, so the baseline score of 3 is appropriate when the schema already documents parameter meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's resource (workspace-level dependencies) and enumerates specific operations (list, view stats, export/import). This distinguishes it from sibling tools like 'dependencies' by explicitly stating 'workspace level'. However, 'Manage' is a somewhat generic verb, and the sibling differentiation is implied rather than stated outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for workspace-level dependency management by describing the available actions, but it provides no explicit guidance on when to use this tool over alternatives (e.g., the 'dependencies' sibling for task-level dependencies) and does not mention exclusions or prerequisites. This is clear enough for basic context but lacks explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage ClickUp docs and pages. Use action to get, list, create, update docs, or list, create, update, delete pages, or search docs.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Doc/page name (create, update, pages_create, pages_update) | |
| limit | No | Max docs to return (list) | |
| query | No | Required for search: the search query | |
| action | Yes | Action to perform | |
| cursor | No | Pagination cursor (list, search) | |
| doc_id | No | Required for get, update, pages_*: the doc ID | |
| content | No | Doc/page content in HTML format (create, update, pages_create, pages_update) | |
| deleted | No | Include deleted docs (list) | |
| page_id | No | Required for pages_update, pages_delete: the page ID | |
| archived | No | Include archived docs (list) | |
| scope_id | No | The list or folder ID (create) | |
| sub_title | No | Page subtitle (pages_create, pages_update) | |
| scope_type | No | Where to create the doc (create) | |
| template_id | No | Create doc from a template (create) — get template ID from templates tool | |
| workspace_id | No | The ID of the workspace (get, list, search) | |
| content_format | No | Content format (pages_list) | |
| parent_page_id | No | Parent page ID for sub-pages (pages_create) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description should disclose behaviors. It merely says 'manage' and lists actions without explaining side effects (e.g., delete irreversibility), permissions, or response formats. Insufficient transparency for a multi-action tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, no fluff. Efficient use of words for a broad management tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 17 parameters and no output schema, the description is too minimal. It doesn't explain action-specific prerequisites, return values, or temporal effects. Schema fills some gaps, but the description should provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, so baseline is 3. The description adds no extra parameter semantics beyond grouping actions by docs vs pages, which is already evident from the schema. Marginal value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages ClickUp docs and pages, enumerating specific actions (get, list, create, update docs; list, create, update, delete pages; search docs). This distinguishes it from sibling tools focused on tasks, lists, and other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use vs alternatives. It only describes the tool's actions, leaving the agent to infer that it's for any docs/pages operation. Lacks exclusions or alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new folder in a ClickUp space with the specified name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the folder | |
| space_id | Yes | The ID of the space to create the folder in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, placing the full burden on the description. It does not disclose permissions, idempotency, side effects, or return behavior. For a create operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It effectively communicates the core purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two parameters, making the description minimally adequate. However, it does not mention what happens on success (e.g., returns the created folder) or any error cases, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters described. The description adds no additional meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create), the resource (folder), and the location (in a ClickUp space). It distinguishes from sibling tools like folders_update and folders_delete by specifying the creation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a folder but offers no explicit guidance on when to choose this over alternatives. It does not mention exclusions, prerequisites, or relationships to similar tools like lists_create, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a folder from ClickUp. Removes the folder and its contents.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | Yes | The ID of the folder to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the destructive cascade behavior ('removes the folder and its contents'), but it does not mention permanence, required permissions, or other side effects, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the action ('Delete a folder') and then clarifying the effect. Every word earns its place, with no unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with a single parameter, the description covers the primary purpose and the cascade effect. However, the absence of annotations and the lack of details on reversibility or authorization leave the description somewhat incomplete for full autonomous use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the only parameter (folder_id) with 100% coverage. The description adds no extra meaning beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a folder from ClickUp' with a specific verb and resource, and adds 'Removes the folder and its contents' to clarify the scope of the deletion. This distinguishes it from sibling operations like folders_update or lists_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It simply states the action without mentioning context, prerequisites, or exclusions, leaving the agent without direction on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing ClickUp folder's name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The new name of the folder | |
| folder_id | Yes | The ID of the folder to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions the update action but does not state whether permissions are required, whether the operation is irreversible, what happens to the previous name, or what the response contains. For a mutation tool, this is a significant lack of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and free of redundancy. It conveys the essential purpose without any fluff or unnecessary detail, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple update operation with full schema coverage for its two parameters. The description, while terse, adequately explains the core function for an agent to select and invoke the tool. However, the lack of any behavioral details (e.g., error handling, return value) prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters clearly described ('The new name of the folder' and 'The ID of the folder to update'). The description adds no additional meaning beyond what the schema already provides, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('existing ClickUp folder'), and the specific attribute ('name'), distinguishing it from siblings like folders_create and folders_delete. It uses a specific verb+resource construction that leaves no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for renaming a folder but provides no explicit guidance on when to use it versus alternatives, no exclusions, and no mention of related tools. This is implied usage rather than explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new goal in a ClickUp workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the goal | |
| due_date | No | Due date as Unix timestamp in milliseconds | |
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses only the action (creating a goal) but lacks information about permissions, side effects, return values, or idempotency. For a mutation operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that conveys the essential purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with a well-documented schema, the description is minimally adequate. However, without annotations or an output schema, it would benefit from mentioning what the tool returns (e.g., created goal ID) or any necessary prerequisites, leaving the context slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — each parameter (name, due_date, workspace_id) has a clear description in the schema. The tool description itself adds no further parameter explanation, but the schema fully covers the semantics, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and identifies the resource ('a new goal') and location ('in a ClickUp workspace'), making the tool's purpose unmistakable. It clearly differentiates from sibling tools like goals_update, goals_delete, or goals_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage from the verb 'Create' — the tool should be used when creating a new goal. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a ClickUp goal by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| goal_id | Yes | The ID of the goal to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the deletion, which is essentially redundant with the tool name, and fails to disclose whether the deletion is permanent, cascades to associated data, or requires specific permissions. This is a significant gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action and resource. There is no fluff or repetition, and it is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is minimally sufficient, but it lacks important context such as whether deletion is hard or reversible and what happens to associated key results or tasks. Without annotations, this makes it incomplete for an agent to fully assess the operation's impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the required goal_id parameter, so a baseline of 3 is appropriate. The description's 'by ID' adds no new meaning beyond the schema's 'The ID of the goal to delete', but it does confirm the parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a ClickUp goal by ID' uses a specific verb and resource, clearly distinguishing it from sibling tools like goals_get or goals_update. It also specifies the deletion mechanism (by ID), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you want to delete a goal) but provides no explicit guidance on alternatives or exclusions. It does not mention that goals_update could be used for toggling status instead, nor does it state prerequisites like 'goal must not have associated key results'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific ClickUp goal by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| goal_id | Yes | The ID of the goal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Get details' without revealing the return format, any authorization requirements, potential errors, or whether the operation is read-only. This is minimal for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 10 words with no filler. It is appropriately sized for a simple get-by-ID operation and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has low complexity (one parameter, no output schema, no annotations). The description covers the core action adequately, but it omits any indication of what details are returned or any special behavior. It is sufficient for a simple get but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single parameter goal_id with a description that fully covers its meaning (100% schema coverage). The description's phrase 'by ID' adds no new semantic value beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and identifies the resource as 'details of a specific ClickUp goal by ID', clearly distinguishing it from sibling tools like goals_list (lists goals) and goals_update/delete. It clearly states the action and the target resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when you have a specific goal ID and need its details, but it does not explicitly state when not to use it or mention alternatives like goals_list for listing all goals. The guidance is implicit, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a key result under a ClickUp goal.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the key result | |
| type | Yes | The type of key result (e.g. "number", "currency", "percentage", "automatic") | |
| unit | No | The unit for the key result value | |
| goal_id | Yes | The ID of the goal | |
| target_value | No | The target value for the key result |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action without mentioning side effects, permissions, prerequisites (e.g., goal must exist), or return value. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that gets straight to the point. It contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, 3 required, no output schema, and no annotations. The description is too sparse to fully guide an agent: it lacks return value details, prerequisites, and usage guidance. While the schema explains parameters, the overall context is incomplete for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters, so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already provides, but it does not need to compensate for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the specific resource ('a key result under a ClickUp goal'), which distinguishes it from sibling tools like goals_key_results_update and goals_key_results_delete. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for creating key results, but it does not explicitly state when to use it over alternatives or provide any exclusions or prerequisites. The sibling tool names offer context, but the description itself does not guide tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a key result from a ClickUp goal.
| Name | Required | Description | Default |
|---|---|---|---|
| goal_id | Yes | The ID of the goal containing the key result | |
| key_result_id | Yes | The ID of the key result to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Delete', which conveys destructiveness, but does not mention irreversibility, permissions, cascading effects, or any operational consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler words. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with two well-described parameters, the description is adequate but not exhaustive. The lack of annotations and output schema leaves some context missing, but the tool's simplicity reduces the need for more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters with clear descriptions, covering 100% of parameters. The description adds nothing beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), the target resource (key result), and the container (ClickUp goal). It distinguishes itself from sibling tools like goals_delete and goals_key_results_create/update by specifying exactly what is being deleted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives or any prerequisites. The description only states the action without offering context on exclusions or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a key result under a ClickUp goal.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name for the key result | |
| goal_id | Yes | The ID of the goal containing the key result | |
| key_result_id | Yes | The ID of the key result to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden but discloses no behavioral traits beyond the verb 'Update'. It does not mention permissions, partial update semantics, error behavior, or return format, leaving significant ambiguity for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. It efficiently communicates the core action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three parameters, the description is minimally adequate but lacks output/return information and behavioral details, especially given no output schema or annotations. It covers purpose but not side effects or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters (name, goal_id, key_result_id), so the description adds no extra meaning beyond the schema. The baseline for high coverage is 3, and no additional param guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('a key result') with context ('under a ClickUp goal'), clearly distinguishing it from sibling tools like goals_key_results_create and goals_key_results_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (updating an existing key result within a goal) but does not explicitly state when not to use it or name alternatives. It is clear enough for basic selection, but lacks exclusions or prerequites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all goals in a ClickUp workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It accurately suggests a read-only operation, but does not disclose details like pagination, response format, whether archived goals are included, or access requirements. Basic behavior is clear, but richer context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It wastes no space and directly states the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only list tool, the description is adequately complete: it states what is returned (all goals in the workspace) and implies the scope. It could be enhanced by mentioning special cases like pagination or empty results, but the tool is simple enough that the description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents workspace_id with 'The ID of the workspace' (100% coverage). The description does not add any additional meaning to the parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get all goals') and the resource ('goals') scoped to a ClickUp workspace. This distinguishes it from sibling tools like goals_get (which implies a single goal) and goals_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'all goals' clearly conveys that this tool is for listing the complete set of goals in a workspace, providing clear context for when to use it. It does not explicitly mention alternatives or exclusions, but the scope is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a ClickUp goal name and/or due date.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name for the goal | |
| goal_id | Yes | The ID of the goal to update | |
| due_date | No | New due date as Unix timestamp in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description alone must disclose side effects, permissions, or partial-update behavior. It only says 'update ... name and/or due date', which hints at optional fields but does not state what happens if only goal_id is provided, whether the goal must exist, or if changes are reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the action and object. It is appropriately concise for a simple update tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with full schema coverage, the description is minimally viable. It covers the purpose and key parameters but omits return-value expectations and permission requirements. The 'and/or' phrasing mitigates some ambiguity, but more context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all parameters (100% coverage), but the description adds the 'and/or' semantics, clarifying that name and due_date are independently optional and can be updated together or separately. This adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('a ClickUp goal'), and the specific mutable fields ('name and/or due date'). This distinguishes it from sibling tools like goals_create, goals_get, and goals_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating goal fields but does not explicitly state when to use this tool over alternatives. It lacks guidance on prerequisites like locating the goal_id or exclusions such as fields not updatable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage user groups in a ClickUp workspace. Use action to list, create, update, or delete groups.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Required for create: the group name. Optional for update. | |
| action | Yes | Action to perform | |
| group_id | No | Required for update/delete: the group ID | |
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility for behavioral disclosure. It lists the CRUD actions but does not elaborate on side effects, permissions, reversibility, or other operational consequences (e.g., what happens when a group is deleted). This is a notable gap for a mutation-capable tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that concisely communicates the tool's purpose and available actions. Every word earns its place, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple CRUD tool, the description gives a basic understanding, but it lacks information about output/return values for each action. Since there is no output schema, explaining what the tool returns (e.g., created group object, list of groups) would make the description more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all four parameters with 100% coverage, including conditional requirements. The description adds no extra parameter-level meaning beyond what the schema already provides, so this dimension is at the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages user groups and explicitly lists the four actions (list, create, update, delete). This makes the purpose specific and distinguishes it from sibling tools, none of which focus on groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs the agent to use the `action` parameter to select an operation, which is a direct usage guideline. While no explicit alternatives or exclusions are provided, since this is the only groups-related tool, the intended context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Grant a guest access to a specific location (task, list, or folder).
| Name | Required | Description | Default |
|---|---|---|---|
| guest_id | Yes | The ID of the guest | |
| location_id | Yes | The ID of the task, list, or folder | |
| location_type | Yes | The type of location | |
| permission_level | No | Permission level (read, write, comment) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action 'Grant access' but does not reveal whether the operation is additive or replaces existing permissions, what authorization is required, the effect of the optional permission_level parameter, or the response format. This is a significant gap for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that communicates the core purpose clearly without redundancy or unnecessary words. It is well-structured and front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters, no output schema, and no annotations. The description covers only the basic purpose, but omits critical behavioral aspects such as idempotency, default permission level, side effects on existing guest access, and any preconditions. For an agent to use this tool correctly in a real workflow, more contextual information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 parameters. The description adds no extra semantic detail beyond what the schema provides, but it does not mislead. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Grant') and clearly identifies the resource (guest access) and the target ('a specific location (task, list, or folder)'). It effectively distinguishes the tool from siblings such as guests_detach, guests_invite, and guests_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like guests_invite, guests_detach, or guests_update. It does not state any prerequisites, conditions, or exclusions, leaving the agent to infer usage solely from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a guest's access from a task, list, or folder.
| Name | Required | Description | Default |
|---|---|---|---|
| guest_id | Yes | The ID of the guest | |
| location_id | Yes | The ID of the task, list, or folder | |
| location_type | Yes | The type of location |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but does not mention whether the operation is irreversible, requires special permissions, handles idempotency (e.g., if the guest is not attached), or what the response indicates. For a mutating operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It clearly conveys the action and scope, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with three well-documented parameters, but the lack of annotations and output schema leaves gaps in behavior (e.g., error conditions, side effects, or distinction from guest removal). The description is minimal but not misleading—adequate yet not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all three parameters have descriptions), so the description adds little beyond what the schema already provides. The prose mentions 'task, list, or folder' which mirrors the location_type enum but provides no additional semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and clearly identifies the resource ('a guest's access') and the valid targets ('task, list, or folder'). This distinguishes it from sibling tools like guests_remove, which would remove the guest entirely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for removing access from a specific location, and the enum in the schema reinforces this. However, there is no explicit guidance on when to choose this over guests_remove or guests_attach, nor any exclusions. The context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a specific guest in the workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| guest_id | Yes | The ID of the guest | |
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It only states 'Get details,' implying a read operation, but does not disclose what response format to expect, whether special permissions are needed, or behavior when the guest is not found. This is a notable gap even for a simple get.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no redundant words. It immediately states the action and resource, making it easy to parse and act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get with two well-documented parameters and no output schema, the description is adequate but not rich. It does not describe return values, error cases, or relationship to other guest operations. Given the low complexity, this is a minimum viable description but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented. The tool description adds no extra meaning beyond 'specific guest' and 'workspace,' which matches the parameter descriptions. Baseline of 3 is appropriate because the schema handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('details about a specific guest'), scoped to a workspace. It clearly distinguishes the tool from sibling guest-management tools like guests_invite, guests_update, and guests_remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. It is implied that one uses it when needing details about a single guest, but there is no mention of exclusions, prerequisites, or alternative tools like lists or users_list. This falls short of clear usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invite a guest to a ClickUp workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | The email address of the guest | ||
| workspace_id | Yes | The ID of the workspace | |
| can_edit_tags | No | Whether the guest can edit tags |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. The description only names the action without explaining side effects (e.g., sending an email, creating a pending invitation), permission requirements, or the response format. This is a significant gap for an action that likely has side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no extraneous information. It is front-loaded with the action and target, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with 3 parameters, all well-documented in the schema, and no output schema. The description gives the essential purpose, but given the mutation side effects and the existence of related tools, it could be more complete. However, for a basic invite action, the description is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all three parameters (email, workspace_id, can_edit_tags). The description adds no additional meaning or context about these parameters. Baseline score of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Invite'), the target resource ('a guest'), and the context ('to a ClickUp workspace'). It is specific and distinct from sibling tools like users_invite (which invites users) and guests_attach (which likely attaches an existing guest), thus avoiding ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or scenarios where other guest-related tools (e.g., guests_attach, guests_update) would be more appropriate. Usage is only implied by the action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a guest from the workspace entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| guest_id | Yes | The ID of the guest to remove | |
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It implies irreversibility via 'entirely' but does not explain what happens to the guest's associated data, tasks, or comments, nor mention required permissions. For a destructive operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the action. Every word earns its place, with no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, delete-type tool with no annotations or output schema, the description is too minimal. It lacks information about irreversibility, downstream effects, and when it should be preferred over related tools like guests_detach.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters have clear descriptions in the schema. The tool description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove') and resource ('guest from workspace'), and the word 'entirely' differentiates it from sibling tools like guests_detach or guests_update. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as guests_detach or users_remove. It does not mention scenarios, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a guest's permissions or details in the workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| guest_id | Yes | The ID of the guest | |
| workspace_id | Yes | The ID of the workspace | |
| can_edit_tags | No | Whether the guest can edit tags |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries full responsibility for disclosing behavioral traits. It only says 'update' without explaining side effects, required permissions, reversibility, or what happens to existing settings. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded with the action ('Update') and clearly identifies the resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one mutable boolean parameter, the description is minimally adequate. However, the absence of annotations and output schema means the description could offer more context about what 'details' means or post-update effects. It does not fully compensate for missing structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters (100% coverage), so the schema handles parameter semantics. The description adds little beyond categorizing the parameters as 'permissions or details', which does not materially improve understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a guest's permissions or details in the workspace, which distinguishes it from sibling tools like guests_invite or guests_remove. However, 'permissions or details' is somewhat broad and does not specify the exact updatable field (e.g., can_edit_tags), so it falls short of maximal specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, excluded scenarios, or relationship to sibling tools like guests_attach or guests_update. The description only states what it does, not the usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new comment on a ClickUp list. Supports optional assignee and notification settings.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The ID of the list to comment on | |
| assignee | No | The ID of the user to assign to the comment | |
| notify_all | No | Whether to notify all assignees | |
| comment_text | Yes | The text content of the comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It mentions 'Supports optional assignee and notification settings,' but this only restates parameter semantics. It doesn't disclose permission requirements, side effects (e.g., whether notifications are sent immediately), or reversibility, leaving a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, approximately 15 words, with no extraneous content. It front-loads the action and mentions the key optional features, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is minimal. It adequately explains the core purpose but omits return value information, error scenarios, or behavioral details, leaving gaps in a context where the description must carry more weight.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's mention of 'assignee and notification settings' adds no new meaning beyond the schema properties. It doesn't clarify value formats, dependencies between parameters, or anything outside the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb+resource: 'Create a new comment on a ClickUp list.' It specifically identifies the target as a list, distinguishing it from sibling tools like tasks_comments_create and views_comments_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The description implies usage (when you want to comment on a list) but doesn't mention not using it for tasks or views, nor does it address prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comments for a ClickUp list. Returns comment details with pagination support.
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Pagination start (timestamp) | |
| list_id | Yes | The ID of the list to get comments for | |
| start_id | No | Pagination start ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that the tool returns comment details and supports pagination, which are useful behavioral traits. However, it does not mention authentication requirements, rate limits, or side effects (though 'get' implies read-only). It adds some context but is not exceptionally rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with purpose and containing no fluff. Every word adds value, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (single required parameter, no output schema), the description sufficiently covers the core behavior and pagination. It does not detail the return structure, but that is not required since no output schema exists and the endpoint is simple. Minor gaps include lack of explicit mention of authentication or error scenarios, but these are not critical for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a description. The tool description mentions 'pagination support' but does not add detail beyond the schema's parameter descriptions. The baseline of 3 applies as the schema handles parameter semantics adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get comments') and the resource ('for a ClickUp list'), distinguishing it from sibling comment tools like tasks_comments_list and views_comments_list. It also mentions the return of comment details, leaving no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (fetching comments for a list) but does not explicitly mention alternatives or when not to use this tool. Context is clear, but no exclusions or comparisons to sibling comment tools are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new list in a ClickUp folder or space with the specified name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the list | |
| container_id | Yes | The ID of the container to create the list in | |
| container_type | Yes | The type of container to create the list in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits on its own. It only states the basic creation action without mentioning permissions, uniqueness constraints, side effects, or error behavior, leaving the agent without important safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the verb and direct object. Every word serves a purpose with no unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a mutation tool with no annotations and no output schema, the description is under-specified. It does not explain return values, success/error states, container existence requirements, or how it differs from similar creation tools. More context is needed for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are fully described in the input schema (100% coverage), and the description's mention of 'with the specified name' merely echoes the schema. No additional semantic meaning is added, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create a new list') and the target resource ('a ClickUp folder or space'). It differentiates from sibling tools like lists_create_in_space by mentioning both folder and space containers, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus more specific alternatives such as lists_create_in_space or template-based creation tools. There are no exclusions, prerequisites, or contextual hints to help the agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new list in a ClickUp folder using an existing template.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the list | |
| folder_id | Yes | The ID of the folder to create the list in | |
| template_id | Yes | The ID of the template to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of explaining behavioral traits. It only states the basic creation operation without disclosing side effects, permission requirements, or constraints (e.g., whether the template must originate from the same folder).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that is immediately clear. It contains no filler and efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema is rich, but the description omits useful context such as any prerequisite conditions or expected response format. It is adequate but not enriched beyond the bare minimum.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all three required parameters with clear descriptions (folder_id, template_id, name). The description adds no additional parameter-level information, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create), the object (a new list), the location (ClickUp folder), and the method (using an existing template). This distinguishes it from siblings like lists_create_from_template_in_space and lists_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the intended use case is implied by the name and description, there is no explicit guidance on when to prefer this over alternatives like lists_create_from_template_in_space. No exclusion criteria or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new list in a ClickUp space using an existing template.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the list | |
| space_id | Yes | The ID of the space to create the list in | |
| template_id | Yes | The ID of the template to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'Create a new list' and offers no details about side effects, prerequisites, return values, or error behavior. For a mutation tool, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly communicates the tool's purpose. It is concise and front-loaded with the action and key context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only three required parameters, all schema-covered and no nested objects. The description is sufficient to understand what the tool does, but it doesn't mention the return value or any potential exceptions, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are already fully described in the input schema (name, space_id, template_id), so the description adds no additional semantic meaning. The baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new list'), the resource ('in a ClickUp space'), and the method ('using an existing template'). It distinguishes itself from sibling tools like lists_create_from_template_in_folder by explicitly saying 'space' vs folder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when you want to create a list from a template within a specific space. However, it doesn't explicitly mention alternatives like lists_create_from_template_in_folder or when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new list directly in a ClickUp space without placing it in a folder.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the folderless list | |
| space_id | Yes | The ID of the space to create the folderless list in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds one meaningful qualifier—the list is placed in a space rather than a folder—but it does not mention permissions, idempotency, error conditions, or what the response contains. This is adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and the key scoping detail. Every word earns its place; there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with two fully described parameters and no output schema, the description is largely complete. It covers what the tool does and where it applies. A minor gap is the absence of any indication about the response format, but this is not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (space_id and name) thoroughly, achieving 100% schema description coverage. The description adds no extra parameter-level detail, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new list') and the precise scope ('directly in a ClickUp space without placing it in a folder'), which distinguishes it from sibling tools like lists_create_from_template_in_space and lists_create. The verb+resource+scope is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (to create a folderless list directly in a space), and the phrase 'without placing it in a folder' implies a contrast with creating lists inside folders. However, it does not explicitly name alternatives or state when not to use it, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a list from ClickUp. Removes the list and its tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The ID of the list to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. It does disclose a critical side effect (removal of tasks), but does not mention whether the deletion is permanent, requires special permissions, or fails under certain conditions. This is a moderate level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short, front-loaded sentences that convey both the action and a critical side effect. There is no redundancy or extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema, the description sufficiently covers purpose and main consequence. It does not discuss prerequisites, error cases, or reversibility, but these are less critical for such a straightforward tool, so the description feels complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter list_id, and the schema already describes it as 'The ID of the list to delete'. The description adds no additional parameter semantics, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete), the target (a list from ClickUp), and adds a key differentiator: it also removes the list's tasks. This distinguishes it from sibling tools like lists_update or tasks_delete, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence 'Removes the list and its tasks' implicitly warns that this is the right tool when you want to delete both the list and its tasks, and not when you want to preserve tasks. However, there is no explicit mention of when to use it versus alternatives, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a specific ClickUp list including its name and content.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The ID of the list to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must communicate whether the operation is safe. The verb 'Get' indicates a read-only action, but the description does not disclose additional behavioral aspects such as error handling for invalid list IDs, auth requirements, or the full scope of returned data beyond 'name and content'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and resource. It avoids redundancy and is appropriately concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter, and the schema covers the parameter fully. The description conveys the purpose and hints at return content ('including its name and content'), which is adequate given the absence of an output schema and annotations. However, it could be slightly more explicit about the full return structure or common error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single parameter list_id with the description 'The ID of the list to get'. The tool description does not add new semantic detail about the parameter, so it remains at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves details for a specific ClickUp list, using the verb 'Get' with the resource 'list'. It distinguishes itself from sibling tools like lists_search and lists_list_in_space by specifying 'a specific' list, aligning with its input parameter list_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user needs details on a known, specific list, but it does not explicitly compare this tool with alternatives such as lists_search or lists_list_in_space. There is no when-not-to-use guidance, so the usage context is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get lists that are not in any folder within a ClickUp space.
| Name | Required | Description | Default |
|---|---|---|---|
| space_id | Yes | The ID of the space to get folderless lists from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It states a read-only operation ('Get') and the main scoping condition, but does not mention pagination, ordering, error cases, or return format. This is minimally transparent for a simple read, but lacks deeper behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It states the verb, resource, and scope efficiently, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool, the description adequately explains what it does and the input scope. However, the absence of an output schema and annotations means a bit more context about return value shape or pagination would improve completeness, though it is mostly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents space_id with a clear description, and coverage is 100%. The tool description adds no extra semantic value for the parameter beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a precisely scoped resource ('lists that are not in any folder within a ClickUp space'). This clearly distinguishes it from sibling tools like lists_get or lists_search, which operate on different list scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when folderless lists are needed. It provides clear context but does not explicitly mention alternatives or exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get members assigned to a ClickUp list. Returns user IDs, usernames, and emails.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The ID of the list to get members for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description bears the full burden. It discloses the return values (user IDs, usernames, emails) and implies a read-only operation via 'Get', but it does not address prerequisites, authentication, or behavior in edge cases (e.g., invalid list_id).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the primary function and return values, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read operation, the description is reasonably complete: it states the purpose and the output fields. However, without an output schema and with no annotations, it could mention potential error conditions or permission requirements, though its complexity is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with a description for list_id. The tool description adds no additional parameter-specific detail beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves members assigned to a ClickUp list, using the verb 'Get' and naming the resource. It also specifies the return fields, differentiating it from related tools like tasks_members_list by its list focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. The description implies the use case (getting list members) but does not mention sibling tools or exclusions, such as using tasks_members_list for task members.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for lists in a ClickUp folder or space. Returns list details including name and content.
| Name | Required | Description | Default |
|---|---|---|---|
| container_id | Yes | The ID of the container to get lists from | |
| container_type | Yes | The type of container to get lists from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must convey behavioral traits. It only mentions that results include name and content. It does not clarify whether all lists are returned, whether any filtering occurs, or the exact return format. The term 'search' is ambiguous given the schema has no query parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no redundant words. It front-loads the action and scope, and the mention of return details is directly useful. Excellent conciseness for the content provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 2 parameters and no output schema, the description is thin. It does not explain the exact behavior (e.g., returns all lists in a container), nor does it specify return values beyond 'name and content'. Missing usage guidance and behavioral context makes it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for both container_id and container_type, including enum values. The description adds minimal semantic value by restating 'folder or space' already captured in the schema, so it does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search for lists in a ClickUp folder or space' which clearly identifies the resource (lists) and scope (folder or space). The verb 'search' implies retrieval, though it may mislead since no search query parameter exists. Some differentiation from siblings is provided by supporting both folder and space types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like lists_list_in_space or lists_get. The description offers no exclusions, prerequisites, or hints about which container type is appropriate, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing ClickUp list's name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The new name of the list | |
| list_id | Yes | The ID of the list to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and does not mention permissions, reversibility, or side effects, which is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, direct and free of unnecessary words. It efficiently conveys the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and full schema coverage, the description is adequate but lacks usage guidelines and behavioral context, preventing it from being more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers both parameters fully (100%), so the description adds no additional meaning. The baseline of 3 applies as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update), the resource (existing ClickUp list), and the specific attribute (name), distinguishing it from sibling tools like lists_create, lists_delete, and lists_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze ClickUp project data and return actionable insights. Use "health" for a status overview, "bottlenecks" to find stuck workflows, "velocity" to measure completion rate, "dependencies" to trace dependency chains, "sprint" to check sprint readiness, "workload" to view team distribution, "risk" to surface tasks needing attention, or "time_report" for time tracking summaries. Every action handles edge cases.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Analysis to perform | |
| list_id | Yes | The ID of the ClickUp list to analyze | |
| end_date | No | End date in YYYY-MM-DD format (time_report only) | |
| start_date | No | Start date in YYYY-MM-DD format (time_report only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It states 'Every action handles edge cases,' which adds some behavioral insight, but it does not clarify whether operations are read-only, what output format is expected, or any rate limits or side effects. While the analytical nature is implied, these details are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, front-loaded with the main purpose, then listing eight actions with compact explanations. It is slightly long but every sentence contributes to understanding the actions. The final sentence 'Every action handles edge cases' is a useful behavioral note, though a bulleted list could improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With eight distinct actions and no output schema, the description does not specify return formats or examples for each action, leaving the agent uncertain about what 'actionable insights' look like. It also lacks guidance on handling overlaps with sibling tools like dependencies or time_entries_list. This makes the context incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters already have descriptions. The description adds value by explaining each action enum value (e.g., 'velocity' measures completion rate, 'risk' surfaces tasks needing attention), which the schema enum does not. It does not add further detail for list_id or the date parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Analyze ClickUp project data and return actionable insights,' identifying a specific verb and resource. It also enumerates eight distinct actions (health, bottlenecks, velocity, etc.), each with a brief purpose, which distinguishes this analytical tool from CRUD sibling tools like tasks_create or lists_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for each action (e.g., 'health' for status overview, 'bottlenecks' to find stuck workflows), enabling an agent to choose the appropriate analysis type. However, it does not explicitly mention when to use this tool over alternatives like tasks_list or time_entries_list, and offers no exclusions or 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage personal reminders in ClickUp. Use action "list" to search/filter, "create" to add, or "update" to modify or complete.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (list only) | |
| title | No | Required for create: title for the reminder | |
| action | Yes | Action to perform | |
| cursor | No | Pagination cursor (list only) | |
| due_date | No | Due date in YYYY-MM-DD or YYYY-MM-DD HH:MM format | |
| is_overdue | No | Filter overdue (list only) | |
| description | No | Description (create/update) | |
| reminder_id | No | Required for update: the ID of the reminder | |
| is_completed | No | Mark completed/incomplete (update only) | |
| reminder_type | No | Filter by type (list only) | |
| due_date_status | No | Filter by due date status (list only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only glosses the action enum (e.g., 'modify or complete') and does not explain side effects, required parameters for each action, output formats, or potential errors. The schema covers parameter applicability, but the description adds little beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, well-structured with front-loaded purpose and a clear action breakdown. Every word earns its place, no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-action tool with 11 parameters and no output schema, the rich schema descriptions compensate for the minimal description. The description conveys that the tool is a dispatcher for reminders and leaves parameter detail to the schema. It could add a note about typical use cases or required fields, but the current level is sufficient given high schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter details beyond what the schema already provides; it does not explain format, defaults, or relationships between parameters beyond the action enum, which is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: "Manage personal reminders in ClickUp," and explicitly enumerates the three actions (list, create, update) with their purposes (search/filter, add, modify/complete). This clearly distinguishes it from sibling tools like tasks, lists, or comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives in-tool action guidance but does not provide when-to-use vs alternatives. It never mentions that this tool is for personal reminders as opposed to tasks or checklists, nor does it note any prerequisites or exclusions. The guidance is limited to action dispatch, not tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get spaces from a workspace, or details of a specific space. Omitting space_id lists all spaces in the workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| space_id | No | Specific space ID — omit to list all spaces | |
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the core behavioral distinction between the two modes (list vs detail). The verb 'get' inherently implies a read operation with no side effects, and no further behavioral traits are necessary for this simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the verb and resource, with no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and full schema coverage, the description is adequate. It could mention return format or explicitly confirm read-only behavior, but for a straightforward get/list tool, the provided context is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both space_id and workspace_id already described. The description adds the note about omitting space_id, but this duplicates the schema's description. No extra semantic value beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource (spaces) and the action (get), and distinguishes between listing all spaces and retrieving a specific one. This differentiates from sibling tools like lists_list_in_space which operate on lists within spaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to omit space_id (list all) and when to provide it (details of a specific space), giving clear context for use. It does not explicitly mention alternatives or exclusions, but the two modes are well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage custom statuses on ClickUp lists. Use action to list current statuses, create, update, delete, or reorder them.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| list_id | Yes | The ID of the list to manage statuses on | |
| status_name | No | Required for create/update: the status name | |
| all_statuses | No | Full statuses array for create/update/delete/reorder operations | |
| status_color | No | Hex color for the status, e.g. "#000000" | |
| status_order | No | Order index for the status (reorder only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It lists actions like delete and reorder, but does not explain consequences (e.g., irreversibility), required permissions, or side effects. The description does not go beyond a basic action enumeration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, and every word earns its place. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters and no annotations or output schema, the description provides a clear overview of actions but omits usage nuances such as requiring the full statuses array for update/delete/reorder. The schema documents parameter details, so this is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema covers 100% of parameters descriptively, the description adds meaning to the 'action' enum by spelling out the exact actions (list, create, update, delete, reorder), which the schema does not elaborate. This adds value beyond the structured parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages custom statuses on ClickUp lists and enumerates specific actions: list, create, update, delete, reorder. This provides a specific verb+resource and distinguishes it from sibling tools, none of which focus on statuses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to manage statuses on a list), but it does not explicitly mention alternatives, exclusions, or prerequisites. The context is clear but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage space tags. Use action to list, create, update, or delete tags in a space.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Required for create: the tag name. For update: new name. | |
| action | Yes | Action to perform | |
| tag_bg | No | Background color hex for create/update, e.g. "#000000" | |
| tag_fg | No | Foreground color hex for create/update, e.g. "#FFFFFF" | |
| space_id | Yes | The ID of the space | |
| tag_name | No | Required for update/delete: the current tag name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It only lists actions and doesn't mention side effects, permissions, reversibility, or response formats. For a tool that can delete tags, such details are notably absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, with two short sentences. The first sentence ('Manage space tags.') is somewhat redundant with the second but not overly wasteful. It is front-loaded and easy to parse, earning a solid score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema provides full parameter details, and the actions are clear, but the description doesn't explain return values, error cases, or how to distinguish between assign/unassign operations. Given the CRUD nature and lack of an output schema, the description is minimally adequate but leaves gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully explains all parameters. The description adds no extra parameter semantics beyond restating the actions. A baseline of 3 is appropriate because the description doesn't compensate or add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it manages space tags and enumerates the four actions (list, create, update, delete), making the tool's purpose clear. It doesn't explicitly differentiate from sibling tools like tags_assign, but the use of 'manage' and the action list implies CRUD operations, which is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool—when you need to manage tags via CRUD actions—but doesn't explicitly mention alternatives like tags_assign or tags_unassign. There are no exclusions or conditional guidance, so it meets the 'implied usage' standard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a tag to a ClickUp task. The tag must already exist in the space.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| tag_name | Yes | The name of the tag to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It clearly notes that the operation adds a tag (a mutation) and includes a constraint (tag must exist). However, it does not disclose potential errors, idempotency, or permission requirements, which are relevant for a write operation with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It conveys purpose and prerequisite efficiently, making it well-structured and directly consumable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description covers the essential purpose and precondition. It lacks details on edge cases (e.g., duplicate tag assignment), but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a description only for 'tag_name' (50% coverage). The description adds a behavioral constraint on 'tag_name' (must already exist) but does not elaborate on 'task_id', which remains undocumented beyond its name. This partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and resource ('tag to a ClickUp task'), clearly distinguishing it from the sibling tool 'tags_unassign' which removes tags. The phrase 'to a ClickUp task' further scope the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: the tag must already exist in the space. This tells the agent when the tool can be used, but it does not explicitly state alternatives or when not to use it (e.g., for creating tags, use 'tags' instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a tag from a ClickUp task.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| tag_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the action without disclosing behavioral traits such as idempotency, behavior when the tag does not exist, permissions required, or whether the mutation is destructive. The description carries the full burden but offers no additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is appropriately sized for a simple tool. It is front-loaded with the action and resource, though it could include a bit more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, output schema, and the tool's simplicity, the description is incomplete. It does not explain what the response looks like, prerequisites, or edge cases. For a mutation tool with no additional structured metadata, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the tool description does not explain task_id or tag_name. While the parameter names are self-explanatory, the description adds no semantic value beyond the schema, and it fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (remove) on a specific resource (a tag from a ClickUp task), which distinguishes it from the sibling tool tags_assign. It is concise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a tag needs to be unassigned from a task, but it does not provide explicit when-to-use guidance, exclusions, or mention of alternatives like tags_assign. The context is clear but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new comment on a ClickUp task. Supports optional assignee and notification settings.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The ID of the task to comment on | |
| assignee | No | The ID of the user to assign to the comment | |
| notify_all | No | Whether to notify all assignees | |
| comment_text | Yes | The text content of the comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions optional assignee and notification settings but does not disclose behavioral traits such as required permissions, side effects, response format, or whether notifications are sent. It's a minimal statement of creation without deeper context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action. It contains no filler and every phrase adds value, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with complete schema coverage and no output schema, the description is adequate but not rich. It lacks guidance on when to use versus sibling comment tools and does not mention any behavioral side effects. It meets the minimum viable standard but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all parameters. The description adds minimal extra meaning by noting optionality of assignee and notify_all, which is already implicit from the schema's required list. This matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action with a specific verb and resource: 'Create a new comment on a ClickUp task.' It distinguishes from sibling tools like lists_comments_create and views_comments_create by explicitly mentioning 'task.' The optional assignee and notification settings further clarify scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage situations (when you want to comment on a task) but provides no explicit guidance on when to prefer this tool over alternatives like lists_comments_create or views_comments_create. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comments for a ClickUp task. Returns comment details including text, author, and timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Pagination start (timestamp) | |
| task_id | Yes | The ID of the task to get comments for | |
| start_id | No | Pagination start ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It states that it returns comment details and implies a read operation, which is helpful. However, it does not mention pagination behavior—despite the schema having start and start_id parameters—or any potential side effects or requirements. The description is not misleading but leaves out important behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the action ('Get comments') and includes only necessary information. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with three parameters and no output schema, the description covers the core purpose and return fields. However, it omits pagination behavior, which is a notable gap given the schema includes pagination parameters. It is minimally complete but fails to fully prepare an agent for paginated responses or edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters, so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already provides, such as explaining that task_id is the task to fetch comments for or that start/start_id control pagination. It does not degrade but also does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('comments for a ClickUp task'), and adds value by specifying what is returned (text, author, timestamps). This distinguishes it from sibling comment tools like views_comments_list or lists_comments_list, which target different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by scoping the tool to task comments and describing the return content, making when to use it obvious. However, it does not explicitly mention alternatives or when not to use it, which would have earned a 5. The phrase 'for a ClickUp task' implicitly differentiates it from comment tools for other resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new task in a ClickUp list with specified properties like name, description, assignees, status, and dates.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the task | |
| tags | No | The tags to add to the task | |
| parent | No | The ID of the parent task | |
| status | No | The status of the task | |
| list_id | Yes | The ID of the list to create the task in | |
| due_date | No | The due date of the task (Unix timestamp) | |
| priority | No | The priority of the task (1-4) | |
| assignees | No | The IDs of the users to assign to the task | |
| task_type | No | Task type name — e.g. "Bug", "Feature", "Milestone". Must match an existing task type in the workspace. | |
| notify_all | No | Whether to notify all assignees | |
| start_date | No | The start date of the task (Unix timestamp) | |
| description | No | The description of the task | |
| due_date_time | No | Whether the due date includes a time | |
| time_estimate | No | The time estimate for the task (in milliseconds) | |
| start_date_time | No | Whether the start date includes a time |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that it creates a task, without mentioning side effects, required permissions, irreversibility, or what the function returns. This lack of context is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundancy or filler. It efficiently conveys the core purpose and key property examples, earning a high score for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 15 parameters but full schema coverage, the description is adequate for identifying the purpose and available fields. However, since there is no output schema, the description does not clarify what the tool returns (e.g., created task object or ID), and it omits any preconditions or usage context. This is acceptable but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 15 parameters (100% coverage). The tool description adds minimal value by listing example properties like 'name, description, assignees, status, and dates' but does not explain any parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new task') and the target resource ('in a ClickUp list'), and it lists several example properties. However, it does not explicitly differentiate from the sibling tool 'tasks_create_bulk', though the phrase 'a new task' implies a single-task creation, which is a minor distinction gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention bulk creation or other related tools, leaving the agent to infer usage from the name alone. There are no explicit usage recommendations or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple tasks in a ClickUp list in a single operation. More efficient than creating tasks individually. Supports up to 50 tasks per call.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes | Array of tasks to create (1-50) | |
| list_id | Yes | The ID of the list to create tasks in | |
| continue_on_error | No | Continue creating remaining tasks if one fails |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the 50-task limit but omits important behavioral details like error handling, partial failure semantics, atomicity, and authentication requirements. The presence of 'continue_on_error' in the schema is not reflected in the description, leaving a significant transparency gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each earning its place: purpose, efficiency advantage, and limit. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk creation tool with no annotations and no output schema, the description provides the core purpose and a key constraint but lacks details on failure modes, return values, and operational behavior. The schema covers parameters, but behavioral completeness is only partially addressed, leaving a clear gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage of parameter descriptions, so the baseline is 3. The tool description adds no additional parameter-specific meaning beyond what the schema already offers, e.g., it doesn't explain the 'continue_on_error' behavior or task array semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create multiple tasks in a ClickUp list in a single operation,' specifying the verb, resource, and scope. It also distinguishes itself from individual creation by highlighting efficiency, which helps differentiate it from sibling tools like tasks_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context by noting it's 'More efficient than creating tasks individually,' implying when to use this tool. However, it doesn't mention exclusions or name alternative tools directly, so it misses the full 'when-not-to-use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a ClickUp task permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The ID of the task to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. The word 'permanently' conveys irreversibility, which is a key behavioral trait for a delete operation. However, it does not disclose potential side effects (e.g., deletion of subtasks or comments), permission requirements, or behavior on failure, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action. It contains zero redundant words and immediately conveys the tool's purpose, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no nested objects), the description is largely complete. It states the core operation and permanence, which is sufficient for a straightforward delete. However, it could be slightly more complete by mentioning when to use it or that it is irreversible in stronger terms, but for this low complexity, the essentials are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the task_id parameter (100% coverage), so the baseline is 3. The description adds no additional context about the parameter, such as how to retrieve a valid task ID or format expectations, but it also does not need to since the schema describes it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a ClickUp task permanently' clearly states the action (delete) and the resource (a ClickUp task), with the adverb 'permanently' adding important nuance. It distinguishes this tool from siblings like tasks_create and tasks_update by specifying the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of scenarios like removing obsolete tasks, nor any exclusions or preconditions. Sibling tools like tasks_update are not referenced, leaving the agent without comparison guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific ClickUp task. Returns comprehensive task data including description, assignees, status, and dates.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The ID of the task to get | |
| include_subtasks | No | Whether to include subtasks in the task details |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the type of data returned (description, assignees, status, dates), but doesn't mention potential behaviors like error responses, permissions, or default subtask handling beyond the schema. It's adequate for a read operation but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately states the tool's purpose and key return fields. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with two well-documented parameters and no output schema, the description adequately explains what the tool does and highlights key returned data. It lacks exhaustive detail but is sufficient for typical usage. A 4 because it gives a sense of the response contents without being overly verbose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with clear descriptions for both parameters. The tool description adds no additional parameter-specific meaning, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('a specific ClickUp task'), and the scope ('detailed information... comprehensive task data'). This distinguishes it from sibling tools like tasks_list or tasks_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single task's details, but it doesn't explicitly contrast with alternatives like tasks_list or state when not to use it. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an existing task to a ClickUp list.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The ID of the list to add the task to | |
| task_id | Yes | The ID of the task to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must disclose side effects. It only states the action 'Add' without mentioning permissions, idempotency, or what happens if the task is already in the list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy, front-loading the verb and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no output schema, the description covers the basic operation but lacks behavioral details such as response format or side effects, leaving some uncertainty.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters list_id and task_id are described in the schema with clear meanings. The description does not add further detail beyond restating that a task is added to a list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Add' and resource 'existing task' to a ClickUp list, clearly distinguishing from siblings like tasks_create (creating new tasks) and tasks_unlink (removing). It defines the exact operation scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing task' implies this is for linking an already-created task, not for creating one. However, it does not explicitly state when to prefer this over tasks_create or tasks_unlink, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks from a ClickUp list. Returns task details including name, description, assignees, and status.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | The page number to get | |
| list_id | Yes | The ID of the list to get tasks from | |
| reverse | No | Whether to reverse the order | |
| order_by | No | The field to order by | |
| subtasks | No | Whether to include subtasks in the results | |
| include_closed | No | Whether to include closed tasks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of transparency. It only mentions the output payload and does not disclose behavioral details such as pagination (page parameter), ordering (order_by, reverse), whether closed tasks are included, or subtask handling. The read-only nature is implied but not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Get tasks from a ClickUp list. Returns task details including name, description, assignees, and status.' Every word contributes to the core meaning, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters and no output schema, the description is inadequate. It does not explain how the parameters (page, reverse, order_by, subtasks, include_closed) affect the behavior or results, nor does it describe the response structure beyond a superficial list of fields. A more complete description would cover pagination, filtering, and output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all six parameters with 100% coverage, so the description adds no extra parameter semantics beyond that baseline. The schema's descriptions are sufficient, and the description does not need to repeat them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get tasks') and resource ('ClickUp list'), and lists the returned fields (name, description, assignees, status), which distinguishes it from sibling tools like tasks_get (which likely fetches a single task) or tasks_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as tasks_get, tasks_create, or tasks_update. There is no mention of typical use cases, prerequisites, or exclusions, leaving the agent to infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get members assigned to a ClickUp task. Returns user IDs, usernames, and emails.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The ID of the task to get members for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the operation and return values but does not confirm that the tool is read-only, mention permission requirements, or outline error behavior (e.g., non-existent task ID).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences that immediately state the action and the return fields. No redundant information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with no output schema, the description adequately covers what it does and what it returns. It lacks edge-case details (e.g., empty member list, pagination), but given the tool's simplicity, the description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (task_id is fully described as 'The ID of the task to get members for'), so the description adds no additional parameter-level meaning. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'members assigned to a ClickUp task,' and explicitly mentions the returned fields (user IDs, usernames, emails). This distinguishes it from sibling tools like tasks_get (task details) and lists_members_list (list members).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its purpose but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives such as lists_members_list for list-level members. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a task from a ClickUp list without deleting the task.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The ID of the list to remove the task from | |
| task_id | Yes | The ID of the task to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the critical non-destructive behavior, preventing accidental data loss. It does not mention reversibility or permissions, but the core behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the action and includes essential clarification. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter operation with no output schema, the description is sufficient for tool selection. It could mention edge cases like multi-list tasks, but the core behavior and distinction from deletion are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for both parameters, so the baseline is 3. The description offers no additional parameter-level information beyond the schema's clear definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove) and the object (task from a ClickUp list), and explicitly clarifies that the task is not deleted. This distinguishes it from siblings like tasks_delete and aligns with tasks_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without deleting the task' provides clear context for when to use this tool versus alternatives, particularly tasks_delete. However, it does not explicitly name alternatives or state exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing ClickUp task's properties including name, description, assignees, status, and dates.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The new name of the task | |
| status | No | The new status of the task | |
| task_id | Yes | The ID of the task to update | |
| due_date | No | The new due date of the task (Unix timestamp) | |
| priority | No | The new priority of the task (1-4) | |
| assignees | No | The IDs of the users to assign to the task | |
| task_type | No | Task type name — e.g. "Bug", "Feature", "Milestone". Must match an existing task type in the workspace. | |
| notify_all | No | Whether to notify all assignees | |
| start_date | No | The new start date of the task (Unix timestamp) | |
| description | No | The new description of the task | |
| due_date_time | No | Whether the due date includes a time | |
| time_estimate | No | The new time estimate for the task (in milliseconds) | |
| start_date_time | No | Whether the start date includes a time |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only says 'update' without mentioning permission requirements, side effects, whether unspecified fields remain unchanged, or what the response contains. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler or redundancy. It efficiently communicates the core purpose and key affected fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex 13-parameter mutation tool with no annotations and no output schema, yet the description only names a few property categories. It omits operational context such as status validity, task_type requirements, date/time units, and partial-update behavior, making it incomplete for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 13 parameters with descriptions. The tool description adds no new parameter semantics beyond listing a few field categories that are already present in the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'existing ClickUp task's properties', and lists common fields like name, description, assignees, status, and dates. It distinguishes from tasks_create and tasks_delete but does not explicitly differentiate from tasks_update_bulk, though the singular 'existing task' implies a single-task operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to choose this tool over alternatives such as tasks_update_bulk or tasks_create. There are no stated prerequisites, exclusions, or conditions for use beyond the implied 'update an existing task'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update multiple existing ClickUp tasks in a single operation. Each entry must include a task_id and the fields to update. Can batch-change status across tasks (set status per task), batch-reassign (set assignees array per task), or batch-add tags (set tags array per task). Supports up to 50 tasks per call.
| Name | Required | Description | Default |
|---|---|---|---|
| updates | Yes | Array of task updates (1-50) | |
| continue_on_error | No | Continue if an individual task update fails |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool modifies tasks ('Update'), that each entry requires a task_id, and that it supports batch operations and up to 50 tasks. However, it does not address failure behavior, atomicity, permissions, or the return payload. The continue_on_error parameter exists in the schema but is not explained in the description, and its implications for partial failures are not disclosed. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly three sentences, immediately stating the core purpose in the first sentence. It then specifies the key requirement (task_id) and gives concrete batch examples, ending with the limit. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk update tool with a nested array schema and no output schema, the description covers the essential aspects: purpose, required field, common batch patterns, and limit. It is missing some details like error handling semantics (though continue_on_error is in the schema, its behavior is not elaborated) and what the operation returns. However, the description is sufficient for an agent to select and invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how parameters are typically used: 'Can batch-change status across tasks (set status per task), batch-reassign (set assignees array per task), or batch-add tags (set tags array per task).' This clarifies the intended combinations and semantics, going beyond the raw schema field descriptions. It clearly states the requirement for task_id within each update entry.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Update multiple existing ClickUp tasks in a single operation.' It clearly distinguishes from the sibling tool tasks_update (singular) and other bulk tools like tasks_create_bulk by emphasizing the 'multiple tasks' and 'bulk' nature. The purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: 'Update multiple existing ClickUp tasks in a single operation' and describes specific batch use cases (status, assignees, tags). It does not explicitly mention alternatives or say when not to use it, but the context implies that it is for bulk updates as opposed to single-task updates via tasks_update. The 50-task limit is also stated, which guides usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get available templates in a ClickUp workspace. Scope type determines which templates are returned (task, list, or folder templates).
| Name | Required | Description | Default |
|---|---|---|---|
| scope_id | No | The ID of the list or folder (required for list/folder scope) | |
| scope_type | Yes | The type of templates to get | |
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action ('Get available templates') and repeats the scope_type effect, which is already in the schema. It does not mention authentication needs, rate limits, return structure, or any read-only guarantees. This is a significant gap for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and every word earns its place. It is appropriately sized for the tool's simplicity, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema or annotations, the description should ideally explain return values or edge cases. It clearly indicates that templates are returned and that scope_type affects the result, but it does not describe the response format, pagination, or any prerequisites like authentication. For a simple list-style tool this is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description mentions 'Scope type determines which templates are returned', which slightly reinforces the scope_type parameter, but it does not add any new meaning beyond what the schema already provides. No additional syntax, prerequisites, or examples are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get available templates in a ClickUp workspace', using a specific verb ('Get') and resource ('templates'). It further distinguishes from sibling tools like lists_create_from_template_in_folder by focusing on retrieval rather than creation, and clarifies the scope types (task, list, folder).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool is for fetching available templates in a workspace, and scope_type determines the category. It does not explicitly mention alternatives or when not to use it, but the distinction from sibling creation tools is implicit. It lacks exclusions or alternative tool recommendations, hence not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get time entries for a ClickUp team/workspace. Supports filtering by task, date range, and assignees.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | No | Filter by task ID (supports custom IDs like DEV-1234) | |
| team_id | Yes | The ID of the team (workspace) to get time entries for | |
| assignee | No | Filter by assignee user IDs. Pass "any" to get all users entries | |
| end_date | No | End date filter in YYYY-MM-DD or YYYY-MM-DD HH:MM format | |
| start_date | No | Start date filter in YYYY-MM-DD or YYYY-MM-DD HH:MM format | |
| is_billable | No | Filter by billable status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full transparency burden. It discloses filtering capability but does not mention read-only nature, pagination, response format, authentication requirements, or rate limits. For a list tool without an output schema, this is a significant behavioral gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and key filters without waste. It is concise and structured effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no output schema and no annotations, the description is adequate but minimal. It covers the core purpose and filters, but does not explain response structure, pagination, or how to obtain team_id. It is viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description merely summarizes the task/date/assignee filters without adding new meaning; the schema already provides formats, the 'any' assignee value, and field purposes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Get time entries for a ClickUp team/workspace' and lists the key filters (task, date range, assignee). This clearly distinguishes it from time-entry mutation tools like time_entry_create or time_entry_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading time entries with filtering, but it does not explicitly state when to use this tool over alternatives such as time_tracking_current or time_entry_create. It gives no exclusions or alternative recommendations, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new manual time entry for a task. Requires team_id, task_id, and start time. Optional duration or end_time.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Array of tag names to assign to the time entry | |
| start | Yes | Start time in YYYY-MM-DD HH:MM format (e.g., 2025-01-15 09:30) | |
| task_id | Yes | The ID of the task to add time to (supports custom IDs like DEV-1234) | |
| team_id | Yes | The ID of the team (workspace) to create the time entry in | |
| billable | No | Whether this time is billable | |
| duration | No | Duration in format like 1h 30m or 90m | |
| end_time | No | End time in YYYY-MM-DD HH:MM format | |
| description | No | Description for the time entry |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It mostly restates schema requirements and does not explain edge cases (e.g., what happens if both duration and end_time are provided, permission requirements, or the return value). The only added hint is 'manual' and the 'or' relationship between duration/end_time.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundant filler. Every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and required fields but omits return value behavior (no output schema) and any interaction with optional parameters like tags or billable. It is adequate for a straightforward create but lacks depth for a tool with 8 parameters and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline of 3. The description adds value by clarifying the optional duration/end_time relationship, suggesting they are alternatives rather than independent optional fields, which is not evident from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action with a specific verb ('Create'), resource ('manual time entry'), and object ('task'). It also distinguishes from siblings by emphasizing 'manual', separating it from time_tracking_start/stop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: 'manual' time entry suggests comparing to timer-based entry, and the required fields give a clear prerequisite. However, it does not explicitly name alternatives or when-not-to-use cases, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a time entry by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes | The ID of the team (workspace) containing the time entry | |
| entry_id | Yes | The ID of the time entry to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It states the action but omits any details about permanence, permissions, error behavior, or effects on related data, making it minimally informative for a mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words, efficiently communicating the core operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with no output schema and no annotations, the description is sparse. It fails to mention reversibility, authorization requirements, or what happens on invalid IDs, making it incomplete for a mutation that is likely destructive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents both parameters (team_id and entry_id) with descriptions, covering 100% of the schema. The tool description adds nothing beyond that, so it does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' with the resource 'time entry' and specifies the primary identifier ('by ID'), clearly distinguishing this from sibling tools like time_entry_create or time_entries_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no context for when to use this tool versus alternatives, such as time_entry_update or time_tracking_stop. It simply states the operation without any situational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing time entry. Supports changing start, duration, end time, description, and billable status.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Array of tag names to assign to the time entry | |
| start | No | New start time in YYYY-MM-DD HH:MM format | |
| team_id | Yes | The ID of the team (workspace) containing the time entry | |
| billable | No | Whether this time is billable | |
| duration | No | New duration in format like 1h 30m | |
| end_time | No | New end time in YYYY-MM-DD HH:MM format | |
| entry_id | Yes | The ID of the time entry to update | |
| description | No | New description for the time entry |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It lists the fields that can be changed but does not explain whether updates are partial or full, how conflicting fields like duration and end_time are handled, or any side effects such as tag replacement behavior. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary action, and contains zero waste. It is appropriately sized for the information provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema, no annotations), the description is too sparse. It does not explain update semantics, field interactions, or validation rules, leaving critical gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal value by grouping some fields (start, duration, end time, description, billable) but omits 'tags' and does not clarify semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update an existing time entry' with a specific verb and resource. It distinguishes itself from sibling tools like time_entry_create, time_entry_delete, and time_entries_list by indicating this modifies existing entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is implied clearly, but there is no explicit guidance on when to use this tool versus alternatives like time_entry_create or time_tracking_start. No exclusions or prerequisites are mentioned beyond what the schema implies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the currently running time entry, if any. Returns the active time entry details or an empty response.
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | Yes | The ID of the team (workspace) to check for running time entry |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It transparently states the return behavior (active entry details or empty response), which addresses the primary side effect and conditional outcome. However, it does not discuss permissions or error cases, leaving minor gaps for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the verb 'Get' and the resource. Every word earns its place, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple single-parameter tool with no output schema. The description covers the essential behavior and the empty-response case, which is adequate. It could be more specific about the structure of the returned time entry details, but given the tool's simplicity, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter, so the schema already documents team_id meaning. The tool description adds no additional parameter semantics beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the currently running time entry, using a specific verb and resource. It distinguishes itself from siblings like time_entries_list, time_tracking_start, and time_tracking_stop by focusing on the active entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking the active time entry but does not explicitly contrast it with alternatives such as time_entries_list. No when-to-use or when-not-to-use guidance is provided, so the context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start the timer on a ClickUp task. Only one timer can run at a time. Supports optional description and billable status.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Array of tag names to assign to the time entry | |
| task_id | No | The ID of the task to start tracking (supports custom IDs like DEV-1234) | |
| team_id | Yes | The ID of the team (workspace) to start tracking in | |
| billable | No | Whether this time is billable | |
| description | No | Description for the time entry |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It discloses the one-timer constraint, which is a key behavior, but does not explain what happens when a timer is already running (e.g., error vs. auto-replace). It also does not mention return values or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no fluff. The main action is front-loaded, and every sentence adds relevant information: purpose, constraint, and supported options.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter tool with no annotations and no output schema, the description is adequate but incomplete. It covers the core purpose and a key constraint, but fails to explain the behavior when a timer is already running or what the response contains. This leaves important gaps for an agent deciding to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description mentions 'description and billable status' as optional and refers to 'task' for task_id, but adds no additional syntax, format, or usage details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Start the timer on a ClickUp task,' which is a specific verb and resource. It distinguishes from sibling tools like time_tracking_stop and time_tracking_current, and mentions key attributes (one timer at a time, optional fields).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating 'Only one timer can run at a time,' implying the need to check for an existing timer (time_tracking_current) and stop it (time_tracking_stop), but it does not explicitly name alternatives. No exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the currently running timer. Returns the completed time entry details.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Array of tag names to assign to the time entry | |
| team_id | Yes | The ID of the team (workspace) to stop tracking in | |
| description | No | Description to update or add to the time entry |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It states the action and return value, but does not mention what happens if no timer is running, whether it requires prior start, or any side effects beyond stopping. This is incomplete for a mutation tool, as it lacks error behavior and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and includes the key return value. Every word is purposeful; there is no redundant phrasing or irrelevant detail, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, with 3 parameters and no output schema. The description explains the core behavior and return value, but lacks context about prerequisites (e.g., a timer must be running) and error scenarios. While it covers the main purpose, it does not fully equip an agent to handle edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (tags, team_id, description) already have clear descriptions in the schema. The tool description does not add any additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Stop' with a clear resource 'the currently running timer', and distinguishes this tool from siblings like time_tracking_start and time_tracking_current. It clearly states what the tool does and what it returns, making it easy to identify as the stop action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'currently running timer' implies the tool should be used when a timer is active, providing implicit context. However, it does not explicitly mention alternatives or exclusions, such as using time_tracking_current to check if a timer exists or when not to use this tool. The usage guidance is present but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invite a user to a ClickUp workspace by email.
| Name | Required | Description | Default |
|---|---|---|---|
| admin | No | Whether the user should be an admin | |
| Yes | The email address of the user to invite | ||
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action but does not disclose side effects (e.g., sends an invitation email), permission requirements, or reversibility. For a mutation tool, this lacks needed transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action verb and contains no redundant words. It is excellently sized and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple operation with a complete schema, the description is minimally adequate but lacks context about side effects, permissions, or return value. No output schema exists, so behavioral context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear per-parameter descriptions. The description adds no extra semantic meaning beyond mentioning 'by email', which does not surpass what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Invite' and clearly names the resource ('a user to a ClickUp workspace') and method ('by email'). This distinguishes it from sibling tools like guests_invite or users_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (inviting a user) but provides no explicit alternatives or when-not-to-use guidance. It does not mention that guests should use guests_invite or that existing users might need users_update.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all users in a ClickUp workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It implies a safe read operation but does not mention pagination, inclusion of guests, or authentication requirements, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence delivers the essential information without redundancy. It is appropriately front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple one-parameter list operation but lacks any detail about return values or user object structure. Given the absence of an output schema, this leaves some uncertainty.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter workspace_id with a clear description. The tool description adds no further parameter semantics, so the baseline 3 applies due to complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all users in a ClickUp workspace, using a specific verb ('list') and resource ('users') with scope. This distinguishes it from sibling tools like users_invite or users_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as guests_get or workspaces_list. The description lacks any mention of context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a user from a ClickUp workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The ID of the user to remove | |
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention that removal is destructive, likely irreversible, or may affect user assignments and content. The description essentially restates the action without adding context about consequences or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundant wording is perfectly sized for a two-parameter tool. It conveys the core action efficiently without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple, the complete absence of annotations and the sparse description leave out crucial context such as destructive side effects, permission requirements, or how the operation affects workspace data. For a mutation tool, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both user_id and workspace_id clearly described in the input schema. The description adds no additional parameter meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Remove' with a clear resource (user) and scope (workspace), making the tool's purpose unambiguous. It naturally distinguishes itself from sibling tools like users_invite (adds users) and users_list (lists users).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as users_invite or users_update, nor does it mention any prerequisites or limitations. The only implied context is the tool's name and description, which provide no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a user's details in the workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | The fields to update on the user | |
| user_id | Yes | The ID of the user to update | |
| workspace_id | Yes | The ID of the workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It states the action but does not mention permissions, idempotency, partial updates, error conditions, or the response shape. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words. It is front-loaded and appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a mutation tool with no annotations, no output schema, and an open-ended 'data' parameter, the description is too sparse to be complete. It does not specify what fields can be updated, whether updates are partial or full, or how the response is structured.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters with 100% coverage, so the baseline is 3. The description itself adds no parameter-level detail, and the 'data' parameter is open-ended without additional clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('update') and clearly identifies the resource ('a user's details') and scope ('in the workspace'). It is distinct from sibling tools like users_invite and users_remove, though it doesn't explicitly differentiate them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as users_invite or users_update. It simply states what it does, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage ClickUp views and view configurations. Use action to list, create, get, update, delete views, set filters/grouping/sorting/settings, duplicate, manage sharing, or get tasks in a view.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | View name (create, update, duplicate) | |
| page | No | Page number for pagination (view_tasks) | |
| type | No | View type 1-10 (create): 1=List, 2=Board, 3=Calendar, 4=Gantt, 5=Mind Map, 6=Map, 7=Timeline, 8=Activity, 9=Box, 10=Table | |
| action | Yes | Action to perform | |
| filters | No | JSON string for set_filters: an array of filter objects. Example: [{"field":"status","operator":"IN","values":["in progress","in review"]}] Operators: IN, NOT_IN, CONTAINS, DOES_NOT_CONTAIN, GREATER_THAN, LESS_THAN, BETWEEN, EQUALS, NOT_EQUALS, IS_EMPTY, IS_NOT_EMPTY | |
| list_id | No | Required for list, create: the list ID | |
| sort_by | No | Field to sort by (set_sorting) | |
| view_id | No | Required for get, update, delete, set_*, duplicate, sharing, view_tasks | |
| group_by | No | Field to group by (set_grouping) | |
| settings | No | JSON string for set_settings: view-type-specific settings. Pass updatable fields as JSON. | |
| sharing_id | No | Share target ID (sharing) | |
| sharing_type | No | Share target type: user, team, workspace (sharing) | |
| sharing_action | No | Share action (sharing) | |
| sort_direction | No | Sorting direction (set_sorting) | |
| group_collapsed | No | Collapse groups by default (set_grouping) | |
| group_direction | No | Grouping direction (set_grouping) | |
| include_content | No | Include view content when duplicating (duplicate) | |
| permission_level | No | Permission level: read, write (sharing) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose side effects, but it only lists operation names; 'delete' implies destruction, yet nothing explains irreversible changes, permission requirements, sharing side effects, or return/get behavior. It does not contradict annotations, but it omits consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences and no filler; the first sentence states the resource, the second lists operations. It is tight, though the operation list duplicates the action enum in the schema, so it earns 4 rather than 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 18-parameter multi-action tool with no output schema, the description is sparse: it doesn't explain which parameters each action requires or show examples. However, the schema's per-parameter descriptions cover all parameters with action-specific hints, making the pair reasonably complete but not fully integrated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-level detail beyond the schema, but schema coverage is 100% and includes action-specific notes (e.g., 'View name (create, update, duplicate)'), filters example/operators, and enums for sharing_action/sort_direction/group_direction. Therefore baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Manage ClickUp views and view configurations' and enumerates all supported actions (list/create/get/update/delete, set_filters, etc.), clearly distinguishing it from sibling comments tools like views_comments_list/create by focusing on view CRUD and configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use action to...' gives an imperative usage pattern, but there are no explicit when-to-use/when-not-to-use statements or alternatives. The boundary with views_comments_* tools is implied only by not listing comment operations in the action enum.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new comment in a ClickUp chat view. Supports notification settings.
| Name | Required | Description | Default |
|---|---|---|---|
| view_id | Yes | The ID of the chat view to comment on | |
| notify_all | No | Whether to notify all assignees | |
| comment_text | Yes | The text content of the comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'Supports notification settings' but does not disclose permissions, side effects, rate limits, or response behavior. As a create operation, mutation is implied, but no additional context is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, with the main action front-loaded. There is no redundant or filler content; every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple create tool with three well-documented parameters, the description is adequate but not complete. It lacks information about return values (e.g., created comment ID), error conditions, or permission requirements. Given no output schema and no annotations, more context would be helpful, but the description is not misleading.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all three parameters (view_id, notify_all, comment_text), covering 100% of the parameters. The description adds little beyond the schema, only reinforcing the 'notification settings' aspect. Baseline 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Create a new comment') and a specific resource ('ClickUp chat view'), which distinguishes it from sibling tools like tasks_comments_create and lists_comments_create. The phrase 'chat view' is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. With many sibling comment-creation tools, the description should clarify that this is for chat views specifically, but it only implies it. There are no exclusions or alternative tool names mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comments for a ClickUp chat view. Returns comment details with pagination support.
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Pagination start (timestamp) | |
| view_id | Yes | The ID of the chat view to get comments for | |
| start_id | No | Pagination start ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It only mentions returning comment details and pagination support, omitting whether the operation is read-only, any ordering, or what fields constitute 'details.' This is minimal for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the purpose and no filler. It earns its place by clarifying the specific resource and pagination capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one required parameter, but without an output schema, the vague 'comment details' leaves the return structure unclear. It also doesn't position itself among the numerous comment-related siblings, making it adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameter meaning is already documented. The description adds no new semantic detail beyond mentioning pagination support, which is already implied by the start and start_id parameters, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets comments for a ClickUp chat view, using a specific verb and resource. It distinguishes from siblings like tasks_comments_list and lists_comments_list by specifying 'chat view,' and mentions pagination support, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for chat view comments but does not explicitly contrast with alternatives or state when not to use it. Given multiple comment-list siblings, more explicit guidance would be beneficial, but the resource type provides some contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage ClickUp webhooks and parse incoming webhook events. Use action to list, create, update, delete webhooks, or process an incoming payload with optional HMAC validation.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| events | No | Event types to subscribe to (create/update) | |
| secret | No | The webhook secret for HMAC validation (process) | |
| status | No | Webhook status (update) | |
| payload | No | Required for process: the raw webhook payload from ClickUp (JSON object) | |
| endpoint | No | Required for create: the webhook endpoint URL | |
| space_id | No | Optional space ID to scope the webhook (create) | |
| signature | No | The X-Signature header value for HMAC validation (process) | |
| webhook_id | No | Required for update, delete: the webhook ID | |
| workspace_id | No | Required for list, create: the workspace ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of behavioral disclosure. It adds value by mentioning optional HMAC validation and processing of incoming payloads. However, it omits side effects (e.g., delete is irreversible), authentication needs, and expected return behavior, so it is only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the main purpose and enumerates operations without wasted words. It is efficient and appropriately sized for the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, 5 actions, no output schema), the description is too sparse. It fails to explain which parameters are required for each action (though schema hints exist), what the return values are, or typical use-case context, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all 10 parameters (100% coverage), so the description does not need to repeat them. It adds marginal value by mapping the action parameter to the five operations, but does not explain parameter interdependencies or provide additional context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages ClickUp webhooks and enumerates the specific actions (list, create, update, delete, process), making its purpose unambiguous. It also mentions parsing incoming webhook events, which distinguishes it from any sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs the reader to use the action parameter to select among operations, which is useful guidance for choosing an action. However, it does not provide explicit context about when to use webhooks versus alternatives (e.g., polling) or mention prerequisites like workspace setup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across all content in a ClickUp workspace — tasks, docs, chats, attachments, and more.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination | |
| query | Yes | The search query string | |
| per_page | No | Results per page | |
| asset_types | No | Filter by asset types | |
| workspace_id | Yes | The ID of the workspace to search in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains what content is searched (tasks, docs, chats, attachments) but does not disclose behavioral details such as pagination, relevance ordering, read-only nature, or authorization requirements. For a search tool, the read-only implication is helpful but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-constructed sentence that front-loads the primary action and object, followed by a concise list of content types. Every word contributes meaning; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and a fully described schema, the description provides adequate high-level context for a search tool. It does not mention return format or result structure, but the absence of an output schema and the straightforward nature of search reduce the burden. Slightly more detail about result behavior would be helpful, but current coverage is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete descriptions for all 5 parameters (100% coverage), so the description adds little beyond what is already structured. The mention of content types aligns with the asset_types parameter but does not add new meaning; thus the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Search') and a specific resource ('all content in a ClickUp workspace'), with illustrative content types (tasks, docs, chats, attachments). This differentiates it from sibling tools like lists_search and tasks_list, which search narrower scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for broad, cross-type searches across a workspace, but does not explicitly mention when to use this tool rather than more targeted search tools. The presence of sibling tools like lists_search suggests a need for exclusion guidance, which is only implicitly provided by the scope wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of all ClickUp workspaces accessible to the authenticated user. Returns workspace IDs, names, and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It indicates a read-only operation through 'Get' and 'Returns', and adds context about the authenticated user. However, it does not explicitly state that it is non-mutating, describe potential pagination, or clarify the scope of 'metadata', leaving some behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, immediately states the core action, and includes the essential return information with minimal waste. It is well-structureured and front-loaded, earning a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless tool with no output schema, the description sufficiently covers the purpose, scope, and return values. There are no complex configurations or hidden behaviors, so the description is complete enough for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description adds meaningful context by saying 'all' and 'accessible to the authenticated user', which clarifies the implicit filter. No parameter details are needed beyond what the schema already shows.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all ClickUp workspaces for the authenticated user, with a specific verb ('Get a list') and resource ('workspaces'). It also mentions the returned data (IDs, names, metadata), and distinguishes itself from sibling tools like workspaces_seats_get by focusing on workspaces generally.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user needs to retrieve all accessible workspaces, but it does not explicitly state when to use this tool versus alternatives such as workspaces_seats_get. No exclusions or alternative comparisons are mentioned, leaving the context clear but the guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about seats (user licenses) in a ClickUp workspace. Returns details about seat allocation and availability.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | The ID of the workspace to get seats information for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since there are no annotations, the description carries the burden. It clarifies that 'seats' means user licenses and states that it returns allocation/availability details. As a read-only 'get' operation, side effects are implicitly absent, providing adequate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that front-loads the action and resource, with no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read-only tool without an output schema, the description provides sufficient context: what it retrieves and what kind of details it returns. It omits return structure specifics, but the tool's simplicity lowers the completeness burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (workspace_id) is fully described in the schema with 100% coverage, so the description adds no additional meaning. Baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'seats (user licenses) in a ClickUp workspace', and specifies the return content ('details about seat allocation and availability'). No sibling tool targets seats, making it distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when seat/license information is needed, but it does not explicitly contrast with alternatives like users_list or workspaces_list. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.0.0attachmentschannelschannels_memberschannels_messageschecklists_createchecklists_deletechecklists_items_createchecklists_items_deletechecklists_items_updatechecklists_updatecomments_deletecomments_replies_createcomments_replies_listcomments_updatecustom_fieldscustom_fields_valuesdependenciesdependencies_workspacedocsfolders_createfolders_deletefolders_updategoals_creategoals_deletegoals_getgoals_key_results_creategoals_key_results_deletegoals_key_results_updategoals_listgoals_updategroupsguests_attachguests_detachguests_getguests_inviteguests_removeguests_updatelists_comments_createlists_comments_listlists_createlists_create_from_template_in_folderlists_create_from_template_in_spacelists_create_in_spacelists_deletelists_getlists_list_in_spacelists_members_listlists_searchlists_updateproject_intelligenceremindersspacesstatusestagstags_assigntags_unassigntasks_comments_createtasks_comments_listtasks_createtasks_create_bulktasks_deletetasks_gettasks_linktasks_listtasks_members_listtasks_unlinktasks_updatetasks_update_bulktemplatestime_entries_listtime_entry_createtime_entry_deletetime_entry_updatetime_tracking_currenttime_tracking_starttime_tracking_stopusers_inviteusers_listusers_removeusers_updateviewsviews_comments_createviews_comments_listwebhooksworkspace_searchworkspaces_listworkspaces_seats_getMany tools are entity-specific (tasks_, lists_, comments_) which helps, but there are overlapping creation tools like lists_create and lists_create_in_space, and multiple comment tools (tasks_comments_create vs comments_replies_create) that could confuse an agent. The generic noun tools (docs, spaces, views) also require reading descriptions to determine actions.
Most tools follow a noun_verb pattern (tasks_create, lists_update, users_invite), but there are inconsistencies: time_tracking_current, lists_search, and single-word manager tools (docs, views, tags) that use an action parameter instead of a verb in the name.
87 tools is far beyond the typical well-scoped range. While ClickUp is a broad platform, the sheer number requires significant navigation and increases the chance of selecting the wrong tool. Some consolidation via action parameters exists, but the count is still excessive.
The tool surface covers CRUD for tasks, lists, folders, comments, checklists, goals, time entries, users, guests, channels, and more, along with bulk operations and cross-cutting features like custom fields and dependencies. Minor gaps exist (no folder get/list, no space deletion) but overall coverage is thorough.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/benthesoundguy/clickup-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
