ClickUp MCP by usefulapi

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

Annotations carry the only real behavioral signal (destructiveHint=true, title), and the description's 'WRITE:' prefix largely duplicates it. It adds the concrete endpoint, which is mildly useful, but says nothing about side effects such as notifications, webhooks, or permission requirements 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?

Three short clauses, zero filler, and the most decision-relevant fact (WRITE, create task in a list) is front-loaded, with the path-param gotcha surfaced before the endpoint reference.

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 11-parameter tool with no output schema, the schema already documents all fields and the description covers the two most error-prone points (required name, list_id placement). It stops short of indicating what comes back (e.g. the new task id) or any permission prerequisite, which would be the only additions left.

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 every parameter is already documented, including the note that list_id is a path param. The description restates that same routing fact and the name-required rule, adding emphasis but no detail the schema lacks. Baseline 3 is correct.

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 a specific verb and resource ('create a new task in a list') and prefixes it with 'WRITE:' so the agent can instantly separate it from read siblings like clickup_get_task or clickup_search_tasks. Also names the exact REST endpoint, removing any ambiguity about what the call does.

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 'WRITE:' marker plus the endpoint imply when this tool applies, and it flags that `name` is required. But it never names an alternative (e.g. clickup_update_task for modifying existing tasks, or create_task_comment for adding notes), so the agent must infer the boundary itself.

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

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

Annotations already carry destructiveHint=true, so the write/side-effect profile is declared in structured data; the description's 'WRITE:' restates it and adds the endpoint but not much else. It does not clarify notification side effects, permissions, or rate limits, so it adds only modest context beyond annotations.

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 short sentences, front-loaded with the operation type and resource, then the key required-argument fact and the REST mapping. No filler; every clause carries 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 comment-creation tool with a fully-described 4-param schema and no output schema, the description covers purpose, required params, and endpoint. It leaves minor gaps around notification behavior and permission requirements, but nothing an agent strictly needs to invoke 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 all four parameters (task_id, comment_text, assignee, notify_all) are already documented in the schema. The description only restates that comment_text is required and task_id is a path param, adding no new semantics. Baseline 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?

Starts with an explicit 'WRITE: add a comment to a task' verb+resource, and the REST endpoint (POST /task/{task_id}/comment) confirms the operation. An agent can immediately distinguish this mutation tool from the read-side sibling clickup_get_task_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 'WRITE:' prefix implicitly signals this is the mutating counterpart to the read comment tools, but the description never explicitly says when to use this versus clickup_get_task_comments or clickup_get_list_comments, nor states any prerequisites. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful context by identifying the credential source (the current API token) and the underlying REST route, but says nothing about what the returned user object contains or any failure mode for an invalid token.

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 short sentences, front-loaded with the purpose before the endpoint mapping. Nothing is padded or redundant.

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?

A zero-parameter read whose safety profile comes from annotations; no output schema exists so return values need not be documented. Marginally incomplete because the shape of the returned user (the reason to call it) is left unstated.

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?

Zero parameters with 100% schema coverage, so the baseline of 4 applies. There is nothing for the description to disambiguate.

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 a specific verb and resource: fetch the user bound to the current ClickUp API token. No sibling tool retrieves the authenticated identity (they list/read tasks, lists, folders, spaces), so the description alone lets an agent tell it apart without opening a schema.

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 'the current ClickUp API token' implies this is the identity/whoami call, which is enough to infer usage. However, it never states when an agent should reach for it (e.g., to resolve the current user's ID before a write) and names no alternative, since none exists.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying REST endpoint mapping, which is mild context, but says nothing about pagination, ordering, or result size limits for what is inherently a potentially large collection.

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 short sentences with the core action front-loaded and no wasted words. The trailing REST endpoint reference is only marginally useful but costs almost nothing.

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 single-parameter read tool the description is adequate, but with no output schema it does not describe the return shape, pagination, or comment body/content structure, which an agent would need to consume results 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?

Only one parameter exists and schema description coverage is 100%, so the schema fully documents list_id. The description mirrors it in the endpoint path but adds no format or constraint details beyond what the schema provides, making the baseline 3 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 a specific verb and resource ('Get the comments on a list') that clearly identifies the operation. It does not explicitly disambiguate from the sibling clickup_get_task_comments, though the list-vs-task resource distinction is implied by the name and endpoint.

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 on when to use this tool versus alternatives such as clickup_get_task_comments, nor any stated prerequisites or exclusions. The usage context is only inferable from the name and endpoint.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, so the description only needs to add context. It contributes the REST mapping (GET /task/{task_id}), which is mildly useful for orientation, but says nothing about permissions, error behavior for missing ids, or payload size.

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 short, front-loaded sentences with zero filler; the purpose leads and the endpoint mapping follows as a compact secondary 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 single-resource read with annotations covering the safety profile, full schema coverage, and no output schema, the definition is nearly sufficient. It omits any note on failure behavior or response contents, but nothing essential to invoking it correctly is missing.

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 both task_id and include_subtasks are already documented in the schema. The description adds no format, id-source, or subtask-serialization detail beyond what the schema provides, so the baseline 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?

States a specific verb and resource ('Get a single task by id') and the singular 'single task' implicitly separates it from the sibling clickup_get_tasks. It does not explicitly name or contrast against siblings like clickup_search_tasks, so it stops short of a 5.

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 guidance on when to use this tool versus clickup_get_tasks, clickup_search_tasks, or clickup_get_task_comments. Retrieval-by-id is implied by 'by id', but there are no conditions, prerequisites, or exclusions stated.

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

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

The readOnlyHint annotation already tells the agent this is a safe read, so the description's only addition is the underlying REST endpoint path. It discloses nothing about pagination, ordering, comment threading, or permission requirements, which matter for a comments-listing 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?

Two short sentences, front-loaded with the purpose and followed by the endpoint mapping; no padding. The endpoint restatement is marginally redundant but compact.

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 one-parameter read with no output schema, so the description ought to say something about the returned comment structure or default pagination. It covers the invocation correctly but leaves the response shape entirely unspecified.

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 task_id parameter, so the schema carries the parameter documentation burden. The description only echoes the path template 'GET /task/{task_id}/comment' and adds no format or sourcing guidance beyond it. Baseline 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 states a specific verb and resource ('Get the comments on a task') and disambiguates the target by naming the task. It is clear enough to act on, but it never distinguishes itself from the sibling clickup_get_list_comments, which retrieves comments for a list rather than a task.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the alternative clickup_get_list_comments or the related clickup_create_task_comment. The agent must infer selection purely 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.

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the REST endpoint mapping and confirms pagination/filtering behaviour, but says nothing about default page size, max results, or what a page returns — the pagination mention is a pointer rather than a disclosure.

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 short sentences, behaviour stated first and the API mapping second. Nothing is wasted, though the raw REST path adds little selection value for an agent choosing a 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 an 11-parameter read-only list tool with 100% schema coverage and no output schema, the description is adequate but thin: it never notes that results are scoped to a single list, how pagination terminates, or that filters combine. An agent can call it, but edge guidance is missing.

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 11 parameters including archived defaults and filter semantics are already documented in the schema. The description only restates 'optional filters and pagination' generically without naming or clarifying any parameter, so baseline 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?

States a specific verb and resource ('Get the tasks in a list') plus its two behavioral axes (optional filters, pagination). The phrase 'in a list' implicitly separates it from clickup_get_task (single task) and clickup_search_tasks (cross-list search), though it never names those siblings.

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?

Usage is implied by the required list_id and the 'in a list' scoping, but there is no explicit guidance on when to prefer this over clickup_search_tasks or clickup_get_task. No exclusions, prerequisites, or alternative routing are provided.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the backing REST endpoint (GET /space/{space_id}/list), which is useful provenance, but says nothing about pagination, result limits, or handling of archived entries beyond what the schema already states.

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, zero waste, with the scoping constraint front-loaded before the endpoint reference. Nothing could be trimmed without losing 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 read-only list endpoint with annotations covering safety and a fully documented two-parameter schema, this is nearly sufficient. The only gap is lack of note on pagination or result shape, which is minor given no output schema exists.

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 both parameters (space_id, archived) are already documented in the schema, including the archived serialization detail. The description adds no parameter-level meaning beyond that, so the baseline 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?

States a specific verb and resource ('list the lists') plus a precise scope qualifier ('that live directly in a space, not inside a folder'), which distinguishes it from the sibling clickup_list_lists and clickup_list_folders without opening either schema.

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 'not inside a folder' clause implies when this tool applies, but it never names the alternative to use for folder-nested lists (clickup_list_lists) or states an explicit when-not condition. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds only the REST endpoint mapping and says nothing about pagination, result ordering, whether nested lists are returned, or archived-item behavior beyond what the schema already documents.

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 short sentences, front-loaded with the action and scope; nothing is padded. The second sentence is mildly redundant with the first but adds the REST mapping, which is genuinely useful for an agent reasoning about ClickUp's API.

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-only list tool with full schema coverage and readOnlyHint annotations, the definition is minimally viable. It omits pagination/truncation behavior and any hint about what is returned, which matter because no output schema exists.

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 both parameters (space_id, archived) are already documented in the schema; baseline 3 applies. The REST path does reinforce that space_id is a path parameter, but no additional semantics or format details are contributed.

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 a specific verb and resource ("List folders") and scopes it to a space, plus the underlying REST call GET /space/{space_id}/folder. It does not explicitly distinguish itself from hierarchy-adjacent siblings like clickup_list_folderless_lists or clickup_list_lists, but the noun alone is specific enough to pick the right tool.

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?

There is no when-to-use guidance, no prerequisites (e.g., needing a space_id obtained from clickup_list_spaces), and no mention of alternatives for enumerating containers. Usage is only implied by the tool name and the REST path.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds only the REST endpoint mapping, which is not behavioral context. It says nothing about pagination, result limits, or ordering, so it contributes little beyond the annotations.

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 short sentences, front-loaded with the action and scope, with the endpoint reference as a compact secondary detail. Nothing is wasted.

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 read tool with complete schema documentation and a readOnly annotation, the description covers the essentials. Only minor gaps remain (e.g., no mention of result volume or pagination behavior), which are unlikely to block 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 description coverage is 100%: folder_id and the archived flag (including its serialization and default) are fully documented in the schema. The description adds no parameter meaning beyond what is already present, so the baseline 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?

Names a specific verb (List) and resource hierarchy (lists inside a folder), which cleanly distinguishes it from clickup_list_folderless_lists and clickup_list_folders by scope. It stops short of explicitly naming that sibling, so it is clear but not maximally differentiating.

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 'inside a folder' implies the selection condition (use this when lists live under a folder, use list_folderless_lists otherwise), but no alternative is named and no prerequisites are stated. Usage 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.

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds only the REST endpoint mapping, which is developer trivia rather than behavioral context. It discloses nothing about pagination, rate limits, auth needs, or return shape.

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 short sentences, front-loaded with the action and scope. The trailing 'ClickUp REST: GET /team/{team_id}/space' is marginally redundant for an agent but harmless and brief.

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, the description should ideally hint at what a space contains or the return shape, but it does not. For a simple read-only list tool the essentials are present, so it is minimally adequate rather than rich.

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 both team_id and archived are already documented in the schema. The description adds the parenthetical '(team)' clarifying team_id as workspace id, but nothing beyond the schema. Baseline 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?

States a specific verb+resource+scope: 'List spaces in a workspace (team).' This clearly differs from siblings such as list_folders and list_lists that operate on other resources. It does not explicitly name which sibling to prefer, but the resource noun is 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?

Usage is only implied by the resource name — an agent can infer it lists spaces, but there is no statement of when to use this versus list_folders or list_workspaces, nor prerequisites like required access. Adequate but with clear gaps.

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

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

readOnlyHint=true already declares the safety profile. The description adds genuine context beyond annotations: the workspace/team naming discrepancy, the fact that returned ids are the team_id parameter used elsewhere, and the underlying REST endpoint. It does not mention auth scope requirements or empty-result behavior, keeping it short of a 5.

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 plus a terse endpoint note. The essential fact (ids = team_id) is front-loaded and nothing is padded.

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 no-parameter, no-output-schema read tool, the description supplies everything an agent needs: what it returns, the team/workspace naming trap, and how the output feeds downstream tools.

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?

Zero parameters, so the baseline is 4 per the rubric. There is no parameter semantics to explain, and the description correctly focuses on the return-value identity (team_id) instead.

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 a specific verb (List) and resource (workspaces) and immediately resolves the naming ambiguity by noting the ClickUp API calls these "teams". It also explains what the returned ids are for, which distinguishes it clearly from siblings like clickup_get_authorized_user.

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 clearly — call this to obtain the team_id values consumed by other tools. It does not name an explicit alternative or exclusion, but no sibling overlaps meaningfully with workspace enumeration, so the guidance is sufficient in practice.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description owes less. It adds useful provenance by naming ClickUp's "Get Filtered Team Tasks" and the underlying REST route GET /team/{team_id}/task, but says nothing about result caps, pagination behavior, or filtering semantics beyond the schema. 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?

Three short fragments, nothing redundant, and the scope statement is front-loaded before the API provenance. Slightly telegraphic (sentence fragments rather than prose) but effectively zero waste.

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 12-parameter filtered-read tool where the schema documents every parameter and annotations cover safety, the description gives enough to route and call correctly. It does not note pagination limits or return shape, but no output schema exists and a task-list return is self-evident.

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 12 parameters are already documented in the schema (including sort, due-date bounds, and closed-task handling). The description adds only scope framing (workspace vs spaces/folders/lists) which loosely maps to team_id/space_ids/project_ids/list_ids. 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 a specific verb and resource ("Search/filter tasks") plus the scope boundary: workspace-wide with optional narrowing to spaces/folders/lists. This is clear enough to separate it from list-scoped siblings like clickup_get_tasks, though it never names those siblings explicitly.

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 "across a whole workspace (team), optionally scoped to spaces/folders/lists" implies when this tool is appropriate (broad cross-container search), but there is no explicit when-to-use statement or named alternative to clickup_get_tasks. Usage must be inferred from the scope wording.

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

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

Annotations supply destructiveHint=true, so the safety bar is partly covered. The description adds genuinely useful behavior — patch semantics where unspecified fields are left untouched — but says nothing about what a destructive update can clobber, permission/auth requirements, or validation failures.

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?

Three compact fragments, front-loaded with the WRITE marker and the key patch-semantics rule. The trailing REST endpoint restatement is mildly redundant but cheap and aids traceability.

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 10-parameter mutation tool with no output schema and only a destructiveHint annotation, the description is adequate but thin: it omits return/confirmation behavior, permission requirements, and side effects of re-parenting or archiving.

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% (10/10 params documented, including priority enum mapping and Unix-ms date formats), so the schema carries parameter meaning. The description adds no parameter-level detail beyond the schema, making the baseline 3 correct here.

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 a specific verb and resource plus scope ("update fields on an existing task"), which implicitly separates it from clickup_create_task and clickup_get_task. It stops short of naming an alternative sibling explicitly, so it is clear but not fully differentiated.

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?

Usage is implied by the mutation framing and the note that only passed fields change, so an agent can infer this is the incremental-edit path. There is no explicit when-to-use statement, no prerequisite (e.g. that the task must already exist and be accessible), and no named alternative.

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