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

With no annotations, the description does carry a genuine behavioral disclosure: the call fails when the tag doesn't exist. However, it says nothing about idempotency (what happens if the tag is already on the task), required permissions, or whether the operation is reversible — all relevant 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?

Three short sentences, but the second and third say the same thing: "Tag must exist in space" and "Will fail if tag doesn't exist." That redundancy costs a point; the core constraint is nonetheless front-loaded before the failure note.

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 three-parameter mutation with a fully documented schema and no output schema, the description covers the essential constraint that would otherwise cause a runtime failure. Only the duplicate-tag behavior is left unaddressed.

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 each parameter is documented in the schema, including the custom-ID support for task_id and the multi-workspace condition for workspace_id. The description adds no parameter meaning beyond what the schema already states, 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?

The description names a specific verb and resource ("Add existing tag to task") and states the key precondition that the tag must pre-exist in the space. It does not mention the obvious sibling, clickup_remove_tag_from_task, so the agent gets no explicit routing signal, which keeps it out of 5 territory.

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 precondition (tag must exist in space) implies this is for attaching already-created tags rather than creating them, but the description never says what to do if the tag doesn't exist or which sibling handles removal. Usage is inferable but not 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?

With no annotations, the description carries the burden of behavioral disclosure. It explains the directional semantics of the dependency, which is important, but does not mention permissions, idempotency, side effects on existing dependencies, or likely error conditions.

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 concise sentences with the core behavior front-loaded, followed by enum semantics and an alternative-tool redirect. No unnecessary repetition 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 simple mutation tool with fully documented parameters and no output schema, the description gives enough information to call it correctly and choose the right dependency type. It could be stronger by noting permission requirements or what happens if the dependency already exists, but the core operational semantics are 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining exactly what 'waiting_on' and 'blocking' mean in terms of task ordering, and it clarifies the directional roles of task_id and depends_on.

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 ('Set a directional dependency') and immediately clarifies the two directional modes. It also explicitly distinguishes the tool from the sibling 'add_task_link' for non-blocking associations.

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?

Explicitly says when to use 'waiting_on' versus 'blocking' and names the alternative tool for non-blocking associations. This gives an agent clear routing guidance without needing to infer from schemas.

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?

With no annotations, the description carries the full burden. It usefully discloses the key behavioral trait — the association is bidirectional and non-blocking — which is the main semantic ambiguity for a link operation. However, it says nothing about idempotency, what happens when the link already exists, permission requirements, or what the call returns, so a mutation tool remains under-described on 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?

Three short sentences, zero filler, with the definition of the operation front-loaded ahead of the disambiguation note. Every sentence 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?

For a 3-parameter mutation with no output schema and no annotations, the description covers purpose, effect, and the sibling alternative well enough to call it correctly. The remaining gap is post-call behavior — whether an existing link errors or is a no-op, and what comes back — which an agent would still have to discover.

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 task_id, links_to, and workspace_id are all fully documented in the schema, including custom-ID support and the multi-workspace caveat. 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 ("Link two tasks together") and immediately qualifies the relationship type ("bidirectional association with no ordering or blocking"). This clearly separates it from the dependency sibling without requiring the schema to be opened.

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?

Explicitly names the alternative tool and the condition that selects it: "For blocking/dependency relationships, use add_task_dependency instead." An agent can route between the two link-style tools with no inference.

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?

No annotations are provided, so the description carries the burden, and it discloses the two behaviors that matter most: the task stays in its original list (non-destructive additive mutation) and the operation is gated on a workspace-level feature flag. It does not say what failure looks like when the ClickApp is disabled or what the response returns, which keeps it below 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?

Two short sentences, zero filler. The distinguishing semantic (additive, keeps home list) is front-loaded ahead of the prerequisite, so an agent reading only the first clause already has the key fact.

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 three-parameter additive mutation with fully documented params and no output schema, the description covers purpose, side effect, and prerequisite — enough to call it correctly. The remaining gap is post-call behavior (error when the ClickApp is missing, what is returned), which is minor but not covered anywhere else since annotations are absent.

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%, including how to obtain list_id and task_id (clickup_get_list, clickup_search) and the workspace_id multi-workspace caveat, so the schema does the heavy lifting. The description's only added signal is the word "additional," which reinforces list_id's meaning but adds nothing new. 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 ("Add a task to an additional list") and immediately disambiguates the most likely confusion by noting it "keeps current home list" — i.e., this is additive, not a move. An agent can distinguish it from clickup_move_task and clickup_remove_task_from_list 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 parenthetical clarifies the additive use case and the second sentence gives a hard prerequisite (Tasks in Multiple Lists ClickApp enabled), which is real routing guidance. It stops short of naming the alternative explicitly ("use clickup_move_task to relocate a task") or stating what to do when the ClickApp is off, so it is clear context rather than full when/when-not guidance.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the derived-value behavior ('tool will calculate missing values') and the required inputs, but says nothing about permissions, error cases, or what the call returns/converts side effects beyond creation.

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?

Front-loads the core action in the first sentence, then adds the parameter-combination rule and optional fields. Four short sentences with little waste, though the third sentence partly repeats the second's constraint.

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 unannotated mutation tool with no output schema, the description covers the essential calling contract (required inputs, value-derivation) but omits return values or confirmation of what gets created, leaving a gap an agent might need when chaining calls.

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 eight parameters including formats and the duration/end_time alternative. The description's restatement of the (start+duration) OR (start+end) rule adds convenience but no meaning beyond the schema, 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 ('Add a manual time entry to a task'), and the word 'manual' implicitly separates it from the timer-based clickup_start_time_tracking and the read-only clickup_get_time_entries. It does not explicitly name those siblings, but the action 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?

Gives clear conditional usage: provide either (start + duration) OR (start + end), with the tool filling in missing values. It lacks an explicit 'use X instead when...' pointer to the timer tools, but the input-combination guidance is concrete and actionable.

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?

With no annotations, the description carries the full burden. It discloses a real constraint (base64 payloads should stay under ~200KB) and implies auth via auth_header, but says nothing about required ClickUp permissions, whether an existing attachment is duplicated or replaced, or what the call returns. Adequate, but gaps remain 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 sentences, front-loaded with the action and the required parameter, then the modes, then the escape hatch to the sibling tool. No 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 6-parameter attachment tool with a fully described schema, the description covers input modes, the one constraint that matters (payload size), and the alternative route for local files. It stops short of describing the resulting attachment record or behavior on repeat uploads, which is the main remaining hole given no output schema.

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 earns an extra point by stating combination semantics the schema does not express — that file_data needs file_name and that file_url is the mutually exclusive alternate path — and adds a size bound the schema lacks. It does not explain auth_header or workspace_id beyond the schema text.

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?

Specific verb+resource ("Attach file to task") with the required key stated immediately. It also enumerates the two supported input modes (base64+filename, URL), so the agent knows precisely which shapes of call are valid.

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?

Explicit when-to-use rules per source type (base64 for files under ~200KB, URL for http/https) plus an explicit when-not that routes local files to the sibling tool request_attachment_upload. Both the alternative and the selecting condition are named.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses Markdown support and threaded-reply behavior, but says nothing about permissions, notification semantics, rate limits, mutation effects, or what happens on failure 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 three short sentences, front-loads the core action, and immediately clarifies Markdown support and threading. It contains 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?

The schema is rich and fully described, and the description covers the key targeting and threading mechanics. Still, for a mutation tool with no annotations or output schema, it omits important context such as sibling disambiguation and notification or permission behavior, so it is only adequately 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 all seven parameters are already well documented in the schema. The description reinforces entity_type, entity_id, and reply_to_id, but adds no meaningful parameter semantics beyond the schema, which matches the baseline for high 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 states a specific verb and resource: creating a comment or threaded reply on a task, list, or view. It is clear what the tool does, but it does not distinguish itself from the sibling clickup_create_task_comment, which likely overlaps for 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?

It gives usage mechanics for target selection (entity_type + entity_id) and threading (reply_to_id), which implies when those options apply. However, it does not state when to use this versus clickup_create_task_comment or when not to use it, leaving the main alternative implicit.

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?

No annotations are provided, so the description carries the full behavioral burden. It says nothing about permission requirements, what visibility settings actually do (PUBLIC vs PERSONAL vs HIDDEN), whether the parent container must exist or be accessible, or what is returned after creation — all relevant 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?

Two short sentences with the core action front-loaded. The second sentence is largely redundant with the schema's required list, but the overall size is appropriate and wastes no space.

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 five parameters, a nested parent object, and no annotations or output schema, so behavioral context matters. The schema fully documents parameters, but the description omits what a created document contains, how visibility affects access, and how the parent id/type must correspond — leaving an agent to guess at runtime behavior.

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%, including enum values for parent.type and visibility, so the schema does the heavy lifting. The description's mention of name/parent/visibility/create_page is redundant with the schema and adds no new meaning; workspace_id is never referenced.

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 gives a specific verb and resource ('Create a document') and names the valid parent container types (space, folder, list), which separates it from clickup_create_document_page or clickup_create_list. It does not explicitly name the sibling it differs from, so an agent must infer that this creates the document container rather than a page inside one.

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 only restates which parameters are required, which the schema already enforces. There is no guidance on when to use this versus clickup_create_document_page, clickup_create_folder, or clickup_create_list, and no prerequisites or exclusions are mentioned.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: it doesn't say the operation mutates persistent state, whether it requires write permissions, whether a created page can be deleted, or what is returned. For a creation/mutation tool with zero annotation coverage 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?

A single front-loaded sentence with no filler, but the terseness is under-specification rather than disciplined concision given the tool's complexity.

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 7 parameters, a mutation side effect, no annotations, and no output schema, the description should at minimum cover the write semantics and the parent/sub-page behavior. It covers none of these, leaving the agent reliant entirely on the schema.

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 document_id (including URL parsing), workspace_id, content_format enum, and parent_page_id. The description adds no parameter 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?

The description states a specific verb and resource ('Create a new page in a ClickUp document'), which is clearly distinguishable from clickup_create_document and clickup_update_document_page. However, it never explicitly names those siblings or states the relationship, so it stops short of full differentiation.

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 guidance on when to use this versus clickup_create_document or clickup_update_document_page, nor any mention of prerequisites such as needing an existing document_id or how sub-pages differ from top-level pages. The agent must infer all of this.

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?

No annotations are provided, so the description must carry the full behavioral burden. It indicates a create/mutation operation and restates the override_statuses flag, but says nothing about required permissions, idempotency, duplicate-name handling, or what the tool returns. This is a significant gap for a mutation tool with zero annotation coverage.

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 four short sentences with no wasted words. The core action is front-loaded, and the follow-up sibling reference earns its place by clarifying the workflow.

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 create tool with no annotations and no output schema, the description is minimally adequate: it covers the main parameter choice and the after-creation workflow. However, it omits key context such as permission requirements, side effects, or what the created folder response contains, and it does not mention the workspace_id parameter despite the schema covering 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 schema already documents all five parameters, including the space_id preference and override_statuses semantics. The description repeats the space_id-vs-space_name choice but adds no format, constraint, or usage detail beyond what the schema 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 states a specific verb and resource: 'Create folder in ClickUp space.' It also distinguishes the workflow from the similar 'clickup_create_list_in_folder' sibling by noting that lists are added after folder creation. It is clear but not as sharply differentiated as the highest-scoring examples.

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 gives explicit guidance on how to identify the target space ('Use space_id (preferred) or space_name + folder name') and points to the sibling tool for the next step. It lacks an explicit 'when not to use' statement, but the context for use is clear.

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?

No annotations are provided, so the description carries the full burden. It adds real value by clarifying that space_name or space_id is effectively required even though the schema marks only 'name' as required, but it says nothing about permissions, duplicate-name behavior, defaults for the list status, or what the response contains. For a creation tool with zero annotation coverage this is adequate but thin.

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 sentences, front-loaded with the action, then prerequisites, then the routing rule. Every sentence carries distinct information with no repetition of the 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?

There is no output schema and no annotations, so the description is the only place to learn what comes back (e.g., the new list's ID for follow-up calls) and whether workspace_id is typically needed. Those gaps matter for a 9-parameter mutation tool, though the core routing and prerequisite information is present.

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 nine parameters thoroughly, including the space_id vs space_name tradeoff and the resolve_assignees hint. The description only restates the required/one-of pattern, adding no syntax or format detail beyond the schema — baseline 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?

States a specific verb and resource ("Create a list in a ClickUp space") and immediately distinguishes itself from the closest sibling by scoping itself to space-level creation. An agent can tell this apart from clickup_create_list_in_folder 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?

Explicitly names the alternative tool and the condition that selects it ("For lists in folders, use clickup_create_list_in_folder"). It also states the required identifier pair up front, so there is no inference needed about prerequisites.

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?

With no annotations, the description carries the full behavioral burden. It discloses that this is a creation operation and names required fields, but it does not mention permissions, side effects, duplicate-name behavior, or what happens when folder_id is invalid.

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 four short sentences with the purpose front-loaded and no wasted text. The prerequisite guidance is placed after the core action, which is appropriate.

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?

It covers the essential creation action and required fields, but omits the conditional workspace_id use and does not describe return behavior despite there being no output schema. For a mutation tool with no annotations, this leaves important context 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 schema already documents all five parameters. The description repeats the two required fields and mentions content/status support, but adds no syntax or conditional guidance beyond the schema, such as when workspace_id is needed.

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: creating a list inside a ClickUp folder. The folder scope helps distinguish it from a generic list creation tool, but it does not explicitly contrast with the sibling clickup_create_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?

It gives a concrete prerequisite and alternative workflow: use clickup_get_folder when you only have a folder name. It does not explain when to use this tool versus clickup_create_list or clickup_create_folder.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully notes that this is a personal reminder and explains timezone handling, but it omits permissions, what the created reminder looks like, and any 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?

Two tight sentences with no wasted wording. Required fields and formatting constraints are front-loaded for quick parsing.

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-reminder tool with a fully described schema and no output schema, the description covers the essentials needed to call it correctly. Minor gaps remain around return behavior and optional parameters, but the schema fills those in.

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 four parameters thoroughly. The description reinforces the required fields and date format but adds little beyond the schema and does not cover optional parameters.

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 personal reminder in the ClickUp workspace. The 'personal' qualifier helps distinguish it from task creation, though it does not explicitly name sibling tools like clickup_create_task or clickup_update_reminder.

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?

Provides prerequisite guidance by naming required title and due_date fields and giving date/time formats. It does not state when to use this instead of creating a task, searching reminders, or updating an existing reminder.

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?

No annotations are provided, so the description carries the full burden. It conveys the write nature and the list prerequisite, but says nothing about permission requirements, failure behavior, or what happens when list_id is invalid. For a 15-param mutation tool this leaves the agent with real 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?

Two tight sentences, no filler, and the required-input constraint plus prerequisite are front-loaded before the optional capability notes.

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 create tool with no output schema and no annotations, the description covers the essentials and the schema handles the rest. Return shape and error behavior are absent, but they are minor given the schema richness.

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 93%, so the schema already documents most parameters in depth (including the extensive custom_fields value formats). The description adds a little on assignees (emails/usernames/"me") and task_type by name, though the assignee claim slightly conflicts with the schema's 'use clickup_resolve_assignees to convert'. 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 ('Create a task in a ClickUp list') and immediately names the two required inputs, distinguishing it from siblings like create_list, create_folder, and update_task 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?

Gives an explicit prerequisite workflow ('always ask the user which list') and names the required fields. It doesn't cover when to use this vs. update_task or move_task, but the create-vs-update distinction is implied strongly enough by the verb.

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?

No annotations are provided, so the description carries the full burden. It discloses deprecation status and that the tool is retained for stale listings, but it does not describe what happens when called, such as notification behavior, permissions, or whether it still creates comments exactly as before.

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 tightly written sentences with the deprecation warning front-loaded. Every sentence earns its place by either flagging deprecation or directing to the replacement.

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 deprecated alias, the description gives enough context to route correctly: it identifies itself as legacy and names the replacement. It leaves minor behavioral gaps around comment creation side effects, but the schema fully covers the parameters and the main purpose is migration guidance.

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 documents all five parameters. The description adds only a migration note that the replacement uses entity_id instead of task_id, which is useful but does not add meaning for the other parameters such as assignee or notify_all.

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 ('creating a task comment') and explicitly identifies itself as a legacy alias for clickup_create_comment. An agent can immediately tell what it does and how it differs from the replacement.

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?

Explicitly says to prefer the replacement tool and explains that this legacy name is only kept for clients with stale tool listings. It names the alternative and the condition under which this tool should not be chosen.

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?

With no annotations, the description carries the full burden; it does disclose the critical trait that the deletion is permanent ("cannot be undone"). It says nothing about permission requirements, whether deleted comments can be recovered by an admin, or what the call returns, leaving real gaps 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?

Three short sentences, front-loaded with the action and immediately followed by the irreversibility warning and the ID discovery path. No 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 simple two-parameter destructive tool with no output schema, the description covers the action, its irreversibility, and how to source the ID. Missing only permission/authorization context that would fully round out a delete 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?

Schema description coverage is 100%, and the schema already documents both comment_id and when workspace_id is needed. The description only restates comment_id, adding no syntax or format detail beyond the schema, 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 ("Delete a comment") plus the identifying parameter (comment_id). The delete verb makes it unambiguously distinct from clickup_update_comment and clickup_create_comment.

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?

Tells the agent where to obtain the required ID (clickup_get_task_comments or clickup_get_threaded_comments), which is the key prerequisite for calling it. It does not state exclusions or when a different tool (e.g., update_comment) should be used instead, but the destructive verb makes that largely self-evident.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the operation is destructive and requires user confirmation, but it does not state irreversibility, permission requirements, or side effects such as what happens to related data.

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 and front-loads the core action. The second sentence adds a critical safety instruction without wasted 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 destructive task-deletion tool with no annotations and no output schema, the description is minimally adequate: it names the action and adds a confirmation requirement. It still omits important behavioral context such as irreversibility and permission expectations.

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 workspace_id are already documented in the input schema. The description repeats the custom-ID support for task_id but adds no substantive parameter guidance 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 uses a specific verb and resource: 'Delete a task by task_id'. It also notes support for custom IDs like 'DEV-1234', which clarifies scope and distinguishes it from task-reading or task-updating 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?

It gives one important usage rule: 'Always confirm the task_id with the user before deleting.' However, it does not explain when to choose this tool over alternatives or when deletion should not be used.

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?

With no annotations, the description carries the full burden and does so: it discloses that the URL is short-lived (~5 minutes), potentially single-use on private-attachment workspaces, and must be fetched immediately and exactly once. This is precisely the operational constraint an agent would otherwise violate.

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?

Front-loaded with the action and the URL hazard, followed by the failure-recovery instruction. Every sentence carries distinct operational information with no restatement of the name or 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?

A download tool with no output schema still gets its return described (short-lived download URL plus attachment metadata), plus the expiry/single-use semantics and the retry policy. Nothing an agent needs to call 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 all three parameters are already documented in the schema, including the page_id URL hint and the attachment_id provenance. The description adds no syntax or format detail beyond that, 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 (download a ClickUp doc page attachment) and names the sibling that produces the required attachment ID, so the agent can place it in the workflow without opening schemas.

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?

Explicitly directs the agent to get attachment IDs from clickup_list_document_page_attachments and states the recovery path if the URL expires ('call this tool again for a fresh URL'). The 'when-not' behavior (do not preview, HEAD-request, retry, or store) is 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?

No annotations are provided, so the description carries the full behavioral burden and does: it discloses short-lived expiry (~5 minutes), single-use semantics on private-attachment workspaces, and the non-idempotent consequence of burning the URL. This is exactly the kind of trait an agent could not infer from name or schema alone.

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?

Front-loaded with purpose and output, then the critical short-lived/single-use constraint, then the retry path — a sensible order. Slightly redundant in restating the attachment-ID lookup that the schema already documents, and the IMPORTANT/do-not list is dense, but every sentence carries actionable 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?

For a simple three-parameter read tool with no output schema, the description covers purpose, prerequisites, return shape, temporal constraints, and error recovery. Nothing an agent needs to call 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 task_id, workspace_id, and attachment_id are already documented in the schema. The description repeats the attachment_id sourcing hint but adds no syntax, format, or constraint information 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?

Opens with a specific verb+resource ('Download a ClickUp task attachment') and immediately distinguishes itself from the sibling clickup_download_document_page_attachment by scoping to task attachments. The output shape (short-lived URL + metadata) is stated up front, so an agent knows exactly what it gets.

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?

Explicitly routes the agent to clickup_get_task with include: ["attachments"] to obtain the required ID, states the fetch exactly once rule, and gives a concrete recovery path ('call this tool again for a fresh URL') when a download fails. It even names anti-patterns (preview, HEAD-request, retry, store) — no ambiguity remains.

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?

With no annotations, the description carries the full burden and does so well: workspace scoping is session-derived and non-overridable, operators returning full objects can produce very large results (with the JMESPath `query` mitigation), errors carry upstream status/operationId/body, and timed-out calls must not be retried because they may have completed. That last point is exactly the kind of non-obvious behavior an agent would otherwise get wrong.

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?

Front-loaded with the core action and then layered with usage, prerequisites and caveats; nearly every sentence adds distinct information. It runs long for a tool description, and the catalog-growth aside could be trimmed, but there is no 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 generic multi-purpose dispatcher with no annotations and no output schema, the description supplies everything needed to invoke it correctly: discovery step, alternative routing, workspace scoping, response-size control, and error/retry semantics. There is no output schema, and the description compensates by describing the shape and hazards of returned data.

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 documents all 7 parameters and the enum values; baseline would be 3. The description adds real meaning on top: it clarifies that `query` is a JMESPath projection to shrink oversized responses, that `operation_id` is only needed when get_operators lists several for a pair, and that workspace_id is auto-filled from the session.

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 ("Run one enabled Unified API operator (a `<model>.<operator>` pair)") and frames it as the escape hatch beyond the dedicated clickup_* tools. An agent can immediately distinguish it from the ~55 siblings that each do one concrete ClickUp 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?

Gives explicit positive and negative selection criteria: reach for it "when no dedicated tool fits the request or when a request spans many objects," and "Prefer a dedicated clickup_* tool when one covers the whole request in a single call." It also names a required prerequisite ("Call clickup_get_operators first") and the constraint that only enabled pairs are callable.

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?

With no annotations the description carries the full burden and does so: it discloses the OR-within / AND-across filter semantics, the 100-per-page pagination contract with has_more/next_page and the mandatory repeat loop, and the silent-failure trap where one bad field_id drops all custom field filters. These are non-obvious behaviors an agent would otherwise get wrong.

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?

Front-loads purpose, then filter logic, then alternatives and prerequisites, then pagination. Density is justified by 17 parameters, though the pagination warning is stated twice within the paragraph (once in prose, once in the parenthetical loop instruction) and could be tightened.

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 17-parameter, no-output-schema tool the description covers the gaps that matter: pagination completeness, filter logic, ID-resolution prerequisites, and dispatch to sibling tools. Return-value shape is partially covered via has_more/next_page, which is the only output structure the agent must reason about.

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, but the description adds real cross-parameter meaning: the OR-within/AND-across combination rule, the requirement for numeric assignee IDs with a named resolver tool, and the YYYY-MM-DD date convention. It stops short of covering the operator/value semantics, which the schema already handles well.

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?

Opens with a specific verb+resource ('Retrieve tasks with combined filters') and enumerates the filter dimensions, then explicitly distinguishes itself from clickup_search (keyword) and clickup_get_task (single task by ID). An agent can route correctly without opening any 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?

States when to use it ('Best for filtering tasks by structured field values'), when not to (text/keyword search → search; single task → clickup_get_task), and prerequisites with the exact sibling tools to call first (clickup_get_custom_fields for field IDs, clickup_resolve_assignees for assignee IDs).

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?

With no annotations, the description carries the full burden, and it does disclose the key outcome: it returns the member object or null if not found, which tells the agent to handle a miss explicitly. It says nothing about auth requirements, ambiguous matches when a name is shared by multiple members, or whether email lookup is exact-match.

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, zero waste, with the lookup semantics front-loaded and the return contract immediately after. Nothing is redundant or 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 2-parameter read tool with full schema documentation and no output schema, the description covers purpose and the null-return contract adequately. It could add a note on multiple-match behavior or default workspace resolution, but no essential calling information 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 coverage is 100%, including the note that workspace_id is only needed with multiple workspaces, so the schema already does this work. The description only echoes the name_or_email semantics and adds nothing 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?

States a specific verb and resource ('Get a member in the ClickUp workspace') plus the lookup key ('by name or email'), so the agent knows exactly what the tool retrieves. It does not explicitly name the sibling it differs from (e.g. clickup_get_workspace_members for listing all members), so it falls 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 single-lookup framing implies when to use it (you already know a name or email), but it never states when to prefer clickup_get_workspace_members or clickup_resolve_assignees instead. Usage must be inferred from the phrasing rather than read directly.

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?

With no annotations, the description carries the burden and delivers two useful disclosures: the return shape (a map of task IDs to status history and current status time data) and a hard workspace prerequisite (the 'Total time in Status' ClickApp must be enabled). It does not cover rate limits or pagination, keeping it from 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?

Three tight sentences: purpose first, return format second, prerequisite last — appropriately front-loaded with no filler. Slightly cramped phrasing ('current status time data') but nothing 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 two-parameter read tool with no output schema, the description covers purpose, the return structure, and a critical enablement prerequisite. An agent could call it correctly; only pagination/rate-limit behavior is unaddressed, 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 coverage is 100%, so task_ids (1-100) and workspace_id are already fully documented in the schema. The description's 'up to 100 tasks' merely restates maxItems and adds no syntax or format detail beyond the schema, 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 (get) and resource (time multiple tasks spent in each status), scoped as a bulk operation up to 100 tasks. It implicitly distinguishes itself from the single-task sibling via 'bulk' and 'multiple tasks', but never names clickup_get_task_time_in_status 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 'bulk operation, up to 100 tasks' framing implies when to use this over the single-task variant, and the ClickApp prerequisite is a real gating condition. However, it never states when NOT to use it or points to the single-task alternative by name, so routing 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?

No annotations are provided, so the description carries the full burden. It usefully discloses pagination support, the reply/thread relationship, and channel URL shapes, but says nothing about ordering, whether results are permission-scoped, what limits apply, or what a message object contains. Adequate but with clear gaps for a read tool with zero annotation coverage.

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?

Four short sentences, each carrying distinct information: purpose, thread routing, pagination, and ID discovery. Front-loaded with the core action and free of 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 five-parameter read tool with a fully documented schema, no output schema, and no annotations, the description covers purpose, threading, pagination, and ID acquisition. Return-value shape and result ordering are unstated, but the agent has enough 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 coverage is 100%, so the schema already documents limit, cursor, workspace_id, and content_format, making 3 the baseline. The description adds genuine value by explaining where channel_id comes from via the URL patterns (/<ws>/v/cn/<channel_id> or /<ws>/chat/r/<channel_id>), which the schema does not.

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 messages for a chat channel') and immediately names the sibling tool that handles the adjacent case (clickup_get_chat_message_replies for threads). An agent can distinguish this from clickup_get_chat_channels and clickup_send_chat_message without opening any 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?

Explicitly routes thread retrieval to clickup_get_chat_message_replies when has_replies=true, which is a real when-to-use-this-vs-alternative signal. It also explains how to obtain channel_id from channel URLs. It does not say when not to use this (e.g., browsing channels first), keeping it below a 5.

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?

No annotations are provided, so the description carries the full disclosure burden. It only notes 'pagination support', which the schema's cursor field already documents; it says nothing about ordering, whether archived/private channels are included, or what permissions are needed.

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 short, front-loaded sentence with zero filler. It is efficient, though the terseness is partly under-specification rather than deliberate compression.

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 three optional, fully documented parameters, this is close to adequate. However, with no annotations and no output schema, the description should at minimum note that results are paginated channel objects whose IDs feed the message 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?

Schema description coverage is 100%, with limit, cursor, and workspace_id all documented in-schema, so baseline 3 applies. The description adds no parameter-level meaning beyond repeating that pagination exists.

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?

Specific verb + resource: 'List chat channels in the workspace', which is clearly distinct from the sibling clickup_get_chat_channel_messages that operates inside a channel. It does not name a sibling explicitly, so it stops short of 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?

No explicit when-to-use, when-not-to-use, or alternative is stated. Usage is only implied: an agent can infer this is the discovery step that yields channel IDs for the message-reading siblings, but the description never says so.

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?

With no annotations, the description carries the disclosure burden and does well: it reveals pagination support and the non-obvious behavior that the id may be a reply inside the thread rather than the root, which explains empty results. It omits permission/auth requirements and response shape, keeping it just short of full 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?

Front-loaded with the core action, then the URL/routing caveat, then the fallback. Every clause is functional, though the parenthetical listing two URL shapes is dense and could be trimmed slightly.

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 paginated read tool with no output schema, the description covers the ambiguous input case, the pagination capability, the sibling to avoid, and the recovery step when results are empty. An agent has everything needed to call 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema for message_id: where the id comes from (chat thread URLs), and that it may resolve to a reply rather than a thread root. The remaining params (limit, cursor, content_format, workspace_id) are left entirely to 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?

States a specific verb and resource ('Get threaded replies for a chat message') plus the keying parameter (message_id). It also explicitly contrasts itself with clickup_get_task and clickup_get_chat_channel_messages, so the agent can separate it from the nearest siblings without reading schemas.

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?

Gives concrete routing rules: chat thread URLs end in a message id and should be passed here, not to clickup_get_task. It also supplies a fallback path — if no replies return, use clickup_get_chat_channel_messages on the channel to find the thread root.

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?

With no annotations, the description carries the full burden, and it does disclose the key behavioral trait that there may be no running entry ("if any"). However it does not say what the empty case looks like (null, empty object, error) or note that this is a non-mutating read, which an agent would otherwise learn from 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 with the scope qualifier front-loaded and zero filler. Nothing in it 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 zero-required-parameter getter this is close to sufficient, but with no annotations and no output schema, the description is the only place a return shape or empty-result behavior could be stated, and it omits both.

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 workspace_id semantics (digits only, only needed with multiple workspaces) are fully handled by the schema, establishing the baseline of 3. The description adds nothing, and its "No parameters needed" line is mildly at odds with an optional workspace_id that an agent in a multi-workspace setup should pass.

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?

"Get the currently running time entry" is a specific verb plus resource with a clear scope qualifier (currently running). It does not name the sibling clickup_get_time_entries, which is the tool an agent would confuse it with, so differentiation is left implicit.

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 "if any" implies this is the right call when you want the active timer rather than a history, but no explicit when/when-not guidance or comparison to clickup_get_time_entries is given. Usage is inferable only from the word "currently".

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?

No annotations are provided, so the description carries the full burden and does a fair job: it discloses the return payload shape (IDs, types, options) and the multi-scope batching behavior, which an agent needs to plan a call. Gaps remain on auth/permission requirements and on whether specifying a list also returns inherited folder/space 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?

Four short sentences, front-loaded with the verb and scope, then return contents, then usage, then the batching note. No filler or restatement of the title.

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 zero required parameters and no output schema, the description covers the return contents and scope semantics well. It does not say what happens when no scope parameter is supplied, which is a real ambiguity for an all-optional tool, and permissions are unaddressed.

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 each parameter is self-documenting, so the baseline is 3. The description adds a cross-parameter insight the schema cannot express — that several scope parameters may be combined in one call — which meaningfully changes how an agent fills the object.

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?

Specific verb ('Get custom field definitions') plus the exact resource and the four supported hierarchy levels, and it names what is returned (field IDs, types, dropdown/label options). No sibling tool in the list does field-definition discovery, so differentiation is immediate.

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?

'Use this to discover available custom fields before setting values on tasks' gives a concrete when-to-use tied to a downstream action. It also states that multiple scopes can be queried at once, which guides invocation. It stops short of naming exclusions or an alternative tool, but none of the siblings is a plausible substitute.

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?

No annotations are provided, so the description carries the behavioral burden. It discloses that this is a content-retrieval operation and that page IDs must be discovered first, but it does not mention permissions, rate limits, response size, or error behavior.

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 zero wasted text. The discovery prerequisite follows immediately after 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 straightforward read tool with a fully described input schema and no output schema, the description provides enough context to invoke it correctly. It could additionally mention return format or expected content shape, but the schema's content_format parameter covers format selection.

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 semantics are already well documented, including the ClickUp URL mapping for document_id and page_ids. The description adds only the page-ID prerequisite and no additional parameter 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?

States a specific verb and resource ('Get the full content of specific pages by page ID') and distinguishes itself from the discovery sibling by directing the agent to list_document_pages first.

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?

Gives clear prerequisite guidance: use list_document_pages first to discover page IDs. It does not name when-not-to-use cases or other alternatives, but the routing context is explicit.

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?

With no annotations, the description carries the full behavioral burden. "Get" implies a read operation and the name-resolution behavior is useful context, but it does not describe permissions, error behavior, ambiguity handling, or return characteristics.

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 tightly written sentences with the core action and use case front-loaded. There is no filler or redundant explanation.

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 fully documents parameters, but there is no output schema and the description only says "folder details" without indicating what is returned. For a read tool with no annotations, this leaves an agent with limited 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 description coverage is 100%, so all five parameters are already documented in the schema. The description only restates the primary folder_id/folder_name and space lookup idea, adding no syntax or edge-case meaning 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 states a specific verb and resource: "Get folder details" by folder_id or folder_name. It is clearly distinct from create_folder/update_folder by name, but does not explicitly differentiate from other read tools such as get_list or get_workspace_hierarchy.

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 gives a clear use case: "Use to resolve folder names to IDs." This tells the agent when the tool is useful, though it does not name alternatives or state when not to use it.

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?

With no annotations, the description carries the full burden; it partially meets it by enumerating returned fields (id, name, content, space info, statuses) and the absence of an output schema makes that valuable. However, it omits permission/auth needs, and says nothing about what happens when list_name matches multiple lists or no list at all — a real risk given the tool performs a name search.

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 sentences: identity, return payload, intended use. The lookup key is front-loaded and nothing is repeated from the schema verbatim beyond the parameter names.

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 three-parameter read tool with no output schema, the description covers what is returned and what each input mode is for, which is most of what an agent needs. The remaining gap is behavior under ambiguity or non-match when resolving a list by name.

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 three parameters, and the baseline is 3. The description adds only that either list_id or list_name may be used; workspace_id scoping and the name-search behavior are left entirely to 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?

States a specific verb and resource ('Get list details') and names the lookup keys (list_id or list_name). The resource ('list') is distinct from read siblings like clickup_get_folder and clickup_get_workspace_hierarchy, though the description never names an alternative to disambiguate further.

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?

'Use to resolve list names to IDs' gives a concrete use case that an agent can act on, and the 'by list_id or list_name' phrasing clarifies the two entry modes. It offers no exclusions or alternatives (e.g., use get_workspace_hierarchy to discover list names), 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.

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

With no annotations, the description carries the full burden and does disclose important behavior: the output is Markdown, it includes HTTP routes, parameters, and request/response body schemas, only enabled operators are shown, and the catalog grows over time. It does not explicitly state that the tool is read-only or mention auth/rate-limit implications, which keeps it short of a 5 for a no-annotation 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 front-loaded with the core behavior and then layered with routing guidance. Every sentence earns its place: it explains what is returned, when to call it, why it exists, and how it relates to `clickup_execute_operator` without padding.

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 and no annotations, the description still explains the return format and content in enough detail for an agent to use it correctly. It covers scope, filtering context, catalog growth, and the relationship to the execution tool, leaving no critical ambiguity for this read-only metadata 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?

Schema description coverage is 100%, so all three filtering parameters (`models`, `workspace_id`, `model_operators`) are already documented in the schema. The description does not add filtering syntax or use-case guidance beyond that baseline, which is appropriate but not value-adding.

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: it lists enabled Unified API operators as `<model>.<operator>` pairs along with routes, parameters, and schemas. It immediately distinguishes this catalog from the dedicated `clickup_*` tools and names `clickup_execute_operator` as the companion tool, so an agent can identify its role without opening the 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?

It explicitly says when to call it: whenever no dedicated tool fits, when a request spans many objects, and always before `clickup_execute_operator`. It also establishes the negative case by framing dedicated tools as the default alternative, and tells the agent to use this catalog instead of inferring capability from names or descriptions.

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?

With no annotations provided, the description carries the full burden. It discloses the return format (Markdown with a Mermaid ER diagram) and that the call is purely informational background, but it does not say whether output can be large, whether it is scoped/safe to call repeatedly, or what happens when no models are enabled.

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 tight clauses: what it returns, then when to use it versus alternatives. No restatement of the name or filler, and the usage constraint is front-loaded enough to guide a decision.

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 zero-required-parameter read tool with a fully documented schema, the description covers purpose, output shape, and usage routing. The only real gap is that it does not indicate the diagram's scope/volume so an agent can judge whether to set tier or entities_only.

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 defines tier, names, detailed, workspace_id, and entities_only with meaning. The description adds no parameter guidance — notably it does not mention that tier/names narrow the diagram or that entities_only strips relationships, so it neither compensates nor detracts.

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: returns the entity-relationship schema for the models behind the enabled Unified API operators, including the output format (Markdown + Mermaid ER diagram). It distinguishes itself from the dedicated clickup_* tools, though "Unified API operators" is internal jargon an agent may only recognize after calling clickup_get_operators.

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?

Explicitly frames the tool as optional background before a clickup_execute_operator call and explicitly says it is not needed for the dedicated clickup_* tools. Both the when-to-use and the when-not-to-use are named, along with the alternative 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?

With no annotations, the description carries the burden and does well: it discloses the default compact response shape (large sections as counts, e.g. custom_fields_count: 3) and the expansion mechanism, which is real behavioral context beyond the parameter names. It doesn't cover permissions/auth for private tasks or error behavior, so it stops short of 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?

Front-loaded with the core operation and default response behavior, then parameter guidance, then the URL caveat. It is dense and lengthy but nearly every clause carries actionable information; the URL disambiguation sentence is long but prevents a real misfire.

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, no annotations, and a compact-by-default response, the description must explain what comes back — and it does (core fields always included, sections as counts, 10k truncation noted in schema). Minor gaps remain around access/permission failures and pagination, but nothing an agent needs to call 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 coverage is 100% and the schema already documents include, task_id, workspace_id, and expand_statuses richly, so the baseline is 3. The description adds workflow meaning on top: it shows a concrete include example and ties expand_statuses to update_task, which helps the agent choose values rather than just describe 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?

States a specific verb (retrieve) and resource (ClickUp task by ID) with scope details (custom IDs like 'DEV-1234'). It explicitly disambiguates from clickup_get_chat_message_replies for chat-thread URLs, so an agent can tell it apart from siblings 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?

Gives explicit when-to-use guidance for each optional parameter: use include for full sections, expand_statuses=true to discover valid statuses for update_task, and a URL disambiguation rule routing chat-thread URLs to another tool. This covers both selection and invocation context.

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?

No annotations are provided, so the description carries the full burden. It implies a read-only operation ('Get') and notes pagination support via start/start_id, but does not explicitly state safety (read-only), default page size, ordering, or error behavior. It does hint that only top-level comments are returned (by directing replies to another tool), which is useful but not fully spelled out.

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 sentences, front-loaded with the core purpose, followed by the alternative condition and pagination note. Every sentence adds actionable information with 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 read tool with no output schema, the description covers the essential aspects: what it returns (comments with reply_count), when to use a sibling, and pagination. It omits finer details like default page size or error handling, but is sufficient for correct selection and 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%, so the schema already documents all four parameters thoroughly. The description reinforces pagination via start/start_id but adds no syntax or semantics beyond what the schema provides. Baseline 3 is appropriate when 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?

States a specific verb and resource ('Get task comments') plus a key return detail ('with reply_count per comment'). It explicitly distinguishes itself from the sibling 'clickup_get_threaded_comments' by directing the agent to that tool for replies, so an agent can tell them apart without opening schemas.

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?

Gives an explicit alternative: 'Use clickup_get_threaded_comments for replies when reply_count > 0.' This is a clear when-to-use-other condition. It does not cover all possible alternatives (e.g., whether to use this vs. a general task fetch), but the main sibling is handled well.

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?

With no annotations, the description carries the behavioral burden. It usefully discloses the output shape and the ClickApp prerequisite, but it does not explicitly state read-only behavior, permission requirements, error behavior when the ClickApp is disabled, or rate limits.

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 tightly written sentences: purpose first, return values second, prerequisite third. Every sentence adds useful information without repetition 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 a simple two-parameter read tool with full schema coverage and no output schema, the description explains the result at a useful level and states the ClickApp prerequisite. It is nearly complete, though it could mention error handling when the required ClickApp is not enabled.

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 are already well documented in the input schema. The description does not add parameter-specific meaning beyond the schema, which is the expected baseline when schema coverage is high.

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: getting time a task spent in each status. It also clarifies the return content, current status plus full history. However, it does not explicitly distinguish this from the bulk sibling clickup_get_bulk_tasks_time_in_status or other time-related tools, so it falls short of the top score.

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 an important prerequisite: the 'Total time in Status' ClickApp must be enabled. It implies use for a single task's status-time breakdown, but it does not explicitly say when to use this instead of clickup_get_bulk_tasks_time_in_status, clickup_get_time_entries, or other alternatives.

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?

With no annotations, the description carries the full behavioral burden; 'Get' implies a safe read but that is never asserted. It does not disclose pagination, permission requirements, or whether traversal is recursive or one level deep, which matters for a 'threaded' resource.

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, and the action statement is front-loaded ahead of the prerequisite hint. Nothing could be removed 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?

There is no output schema and no annotations, so the description should say what a reply object contains and whether the result is nested or flat. It covers the input side adequately but leaves the return shape and access requirements undocumented.

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 are already documented, and the description adds no syntax beyond the workflow hint for comment_id. The workspace_id parameter is not mentioned at all in the description; baseline 3 applies since the schema does the work.

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 threaded replies for a comment') scoped by comment_id, which clearly separates it from clickup_get_task_comments and clickup_get_chat_message_replies. It does not explicitly name the nearest sibling as the thing it is not, so it falls 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?

Explicitly prescribes the workflow: call clickup_get_task_comments first and look for reply_count > 0, which tells the agent exactly when this tool applies and how to obtain the required comment_id. It gives no when-not guidance or pruning condition (e.g. what to do if reply_count is 0), keeping it below a 5.

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?

With no annotations, the description carries the full burden and does disclose a genuinely important default: omitting assignee silently narrows results to the authenticated user. It also discloses the workspace-wide default when task_id is omitted. It does not cover pagination, result limits, or permissions, which is a notable gap for a list 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 tight sentences, front-loaded with purpose then the two mode rules, with the highest-risk caveat flagged by 'IMPORTANT'. No filler; each sentence carries a distinct decision the caller must make.

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?

All six parameters are optional and the description covers the two defaults an agent could get wrong (assignee scope, task scope), which is the main risk surface. Missing return-shape and pagination context is only partly excused by the absence of an output schema.

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 in structured fields, including the assignee default and date format patterns. The description largely restates that guidance rather than adding new semantics (e.g. no timezone handling, no behavior when start_date > end_date). 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 time entries") plus the filter dimensions, and clarifies the two query modes (task-scoped vs workspace-wide). It does not explicitly distinguish itself from the close sibling clickup_get_current_time_entry, leaving the agent to infer the plural/collection distinction.

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?

Explicitly says to pass task_id to scope to one task or omit for workspace-wide results, and gives a clear rule for the assignee parameter ('any' vs user IDs vs omission). It stops short of naming the alternative tool (e.g. get_current_time_entry) for running-timer queries, so routing against siblings is only implicit.

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?

No annotations exist, so the description carries the full burden. It does disclose pagination ('cursor') and depth control, and 'Get' signals a read operation, but it says nothing about the response shape, ordering of results, or behavior when space_ids matches nothing. Adequate but thin for a tool with zero annotation coverage.

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, and the primary capability is front-loaded before the routing caveat. Nothing could be removed 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?

All five parameters are optional, the schema is self-documenting, and the description covers the two behaviors (pagination, depth) an agent must understand to call it well. With no output schema, a brief note on what the hierarchy response looks like would close the remaining 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%, so all five parameters including the max_depth enum are fully documented in the schema. The description's mention of 'pagination and depth control' echoes but does not extend those semantics — baseline 3 applies when 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 names a specific verb and resource — 'Get workspace hierarchy (spaces, folders, lists)' — and scopes it with 'pagination and depth control', so an agent knows exactly what comes back. It distinguishes itself implicitly from the many sibling resolvers ('most tools resolve names automatically') rather than naming specific ones like clickup_get_folder or clickup_get_list, so it falls just 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?

'Use only when you need the workspace structure' is an explicit use condition, and 'most tools resolve names automatically' is an explicit when-not cue that steers the agent away from calling it gratuitously. It stops short of naming the alternative tools to use instead, which is what a 5 would require.

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?

No annotations are provided, so the description carries the burden. It discloses the read-only nature implicitly through 'List all members' and names the workflow constraint, but says nothing about pagination, permissions, or what member fields come back. For a simple read tool that is acceptable 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?

Two tight sentences with the core purpose front-loaded and the usage caveat immediately after. Every sentence earns its place and there is no 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 zero-required-parameter read tool with a fully documented schema and no output schema, the description covers what it is and when to use it. The only minor gap is not characterizing the member records returned, which is largely inferable from the tool name.

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 the single workspace_id parameter is fully documented there, including 'only needed when you have multiple workspaces'. The description adds no parameter guidance 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?

Specific verb plus resource ('List all members in the workspace') with scope made explicit. It distinguishes itself from the assignee-resolution siblings by saying those resolve automatically and this is only for the full member 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?

Explicitly states the when-not: most tools resolve assignees automatically, so use this only when the full member list is needed. That is a clear routing rule that steers the agent away from this tool in the common case.

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?

With no annotations, the description carries the full burden, and 'list metadata' does convey a read-only, non-destructive operation. However, it does not disclose pagination behavior, required access to the page/workspace, or that results are paginated metadata rather than file contents — details that matter for a zero-annotation 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?

A single front-loaded sentence with no wasted words; the key scope qualifier ('metadata') and the clarifying parenthetical come early. It is efficient, though the brevity contributes to the gaps noted elsewhere.

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 say what the returned metadata looks like (names, IDs, URLs, sizes), but it only says 'metadata.' Pagination is covered by the schema's cursor/limit, so the main missing piece is the shape of returned data for an otherwise simple list 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?

Schema coverage is 100%, so limit, cursor, page_id, and workspace_id are all documented in the schema, including the page_id discovery hint. The description adds no parameter meaning beyond the schema, 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?

The description uses a specific verb (list) with a clearly scoped resource (metadata for files attached to a ClickUp doc page) and clarifies the contents are images and files embedded in page content. It implicitly separates itself from the download sibling by emphasizing 'metadata' only, though it never names that sibling.

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 word 'metadata' implies this is for discovery rather than retrieval, hinting that downloading should use a different tool, but the description never states when to use this versus clickup_download_document_page_attachment. No prerequisites or exclusions are given, leaving usage to inference.

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?

No annotations are provided, so the description carries the disclosure burden. It usefully discloses that no content is returned, but says nothing about ordering, pagination, or what the returned 'structure' looks like; with no annotations, a read-only listing tool needs a bit more 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?

Two short sentences, zero waste, with the scope constraint ('no content') front-loaded ahead of the routing hint. Every clause 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?

For a simple read-only listing tool with 100% schema coverage and no output schema, the description covers purpose, scope, and the alternative tool. Minor gaps remain around ordering/pagination and the shape of the returned structure, but nothing an agent needs to select and invoke 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 all three parameters (document_id, workspace_id, max_page_depth) are fully documented in the schema, including URL parsing hints and the -1 convention. The description adds no parameter-level information 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 states a specific verb and resource ('List page names and structure of a document') and immediately scopes it with '(no content)'. It is clearly distinguishable from the sibling clickup_get_document_pages, which fetches full content.

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 names the alternative explicitly ('Use get_document_pages to fetch full page content') and gives the condition that selects it (needing content rather than just names/structure). Nothing is left to inference.

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?

With no annotations, the description carries the full load and does the most important part well: it discloses that source tasks are consumed (i.e., a destructive, non-trivially-reversible operation) and that destination field values win on conflict. It stops short of covering permission requirements or what happens to subtasks/comments/attachments of the consumed tasks.

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?

Four short sentences, front-loaded with the core action and the survival/consumption semantics. The final sentence about custom IDs duplicates the schema and is the one piece of low-value text.

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 3-parameter mutation tool with no annotations and no output schema, the description supplies the critical behavioral facts — destructive merge semantics and conflict resolution direction. Gaps remain around permissions and the shape of the result, which the agent must guess given no output schema.

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 restates target-vs-source roles and the custom-ID support, but that same custom-ID note ('DEV-1234') is already in the schema for both task_id and source_task_ids, so it adds no new meaning. The workspace_id parameter is never mentioned in the description.

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?

Specific verb (merge) plus resource (tasks) plus a precise statement of the two roles: source tasks are absorbed, target survives. This is clearly distinguishable from adjacent siblings like clickup_move_task, clickup_delete_task, or clickup_update_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?

The description implies usage (consolidating duplicates, since sources are consumed) but never states when to choose merge over the obvious alternatives — move_task, add_task_link, delete_task, or update_task. No exclusions or prerequisites are given, leaving the agent to infer the selection criteria.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It never says what happens on the source side (removal from the old list), whether statuses or custom field values are remapped across lists, what permissions are required, or whether the move is reversible — all material 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?

Two sentences, front-loaded with the action, with no filler. The parenthetical custom-ID note overlaps with the schema slightly but is short enough not to be 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 3-parameter mutation with no annotations and no output schema, the description covers inputs and the name-resolution detour but omits the outcome semantics an agent needs (what changes in the destination list, what is lost). Adequate but with a real 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%, so all three parameters are already documented, including custom-ID support and the workspace_id conditional. The description merely restates required parameters and duplicates the custom-ID note, adding no syntax or format detail 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?

"Move a task to a new home list" gives a specific verb (move) and resource (task), and the destination is stated. It does not differentiate from close siblings like clickup_add_task_to_list or clickup_remove_task_from_list, so an agent must infer whether this relocates versus adds a secondary location.

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 states prerequisites (both IDs required) and routes the agent to clickup_get_list when only a list name is known, which is genuinely useful. It gives no when-not guidance or comparison against add_task_to_list / remove_task_from_list, which is the most likely ambiguity given the sibling set.

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?

With no annotations, the description must carry the behavioral load. It usefully clarifies that only the association is removed and the tag persists in the space, but says nothing about idempotency, behavior when the tag is absent, or required 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?

Two short sentences with zero waste, and the most decision-relevant fact (the association-only removal) is front-loaded right after the verb statement.

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?

Parameters are fully covered by the schema and there is no output schema to explain, but for an unannotated mutation tool the description leaves gaps around failure modes and side effects beyond the tag-persistence note. Adequate, not 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 all three parameters (task_id, tag_name, workspace_id) are already documented in the schema, including custom-ID support and the multi-workspace note. The description adds nothing beyond that, 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 ('Remove tag from task'), clearly distinct from the sibling clickup_add_tag_to_task. It stops short of naming the sibling or a scope constraint, 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 only implied by the name and the 'remove tag-task association' note; there is no explicit when-to-use, no exclusions, and no reference to alternatives such as add_tag_to_task or update_task.

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?

No annotations are provided, so the description carries the full burden. It does not say this is an irreversible mutation, whether the dependency is fully deleted or just unlinked, whether permissions or task ownership are required, or what the call returns — all significant 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?

A single clean sentence with no filler, so nothing is wasted. But it is under-specified rather than concise: the space saved could have carried the scope or sibling differentiation an agent needs.

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-annotation mutation tool with no output schema and four parameters, the description is too thin. The rich schema covers inputs, but nothing covers irreversibility, required permissions, or error behavior when no dependency 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%, including the enum for 'type' and notes on custom IDs and the optional workspace_id, so the schema does the heavy lifting. The description adds no parameter meaning beyond that, which is the baseline-3 case.

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 ("Remove a dependency between two tasks") so the action is unambiguous. However, it does not distinguish this from the sibling clickup_add_task_dependency or clarify how a dependency differs from a link (clickup_remove_task_link), which matters given both exist.

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 versus add_task_dependency or remove_task_link, no mention of prerequisites (dependency must already exist), and no note on what happens if the dependency is absent. Usage is only inferable from the 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?

With no annotations, the description carries the full burden, and it does disclose two useful behavioral facts: the ClickApp feature gate and the home-list restriction. It says nothing about permissions required, whether the operation is idempotent, or what happens if the task isn't in that list — meaningful gaps for an unannotated mutation tool. Note the home-list caveat is also already duplicated in the list_id/task_id schema descriptions.

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, both front-loaded with the operation and its hard constraint, with zero redundant phrasing. Nothing could be removed 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 3-parameter mutation with no output schema and no annotations, the description covers the two gotchas an agent most needs (feature gate, home-list restriction) and the schema completes parameter documentation. The remaining omission is failure-mode behavior, which is a minor gap at this complexity level.

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 are already documented with guidance (including the clickup_get_list pointer for list IDs and the custom-ID support for task_id). The description adds only the conceptual framing of 'additional list', which is baseline-level value when 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?

States a specific verb+resource ('Remove a task from an additional list') and immediately bounds scope with the home-list exclusion, which distinguishes it from clickup_add_task_to_list and clickup_move_task. It doesn't name the sibling that performs the inverse operation, so the differentiation is inferential rather than explicit.

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?

Gives a clear precondition ('Requires the Tasks in Multiple Lists ClickApp to be enabled') and an explicit when-not ('cannot remove from home list'). No alternative tool is named for the home-list case, leaving the agent to guess whether clickup_move_task or clickup_update_task is the fallback.

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?

With no annotations provided, the description carries the full burden and does not meet it. It does not disclose that this only severs the link relationship (leaving both tasks intact), whether the operation is idempotent when no link exists, or what permissions/authorization are required 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?

A single front-loaded sentence with zero waste. It is efficient, though its brevity shades into under-specification rather than true economy.

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 mutation tool with no annotations and no output schema, one sentence is not enough: the agent gets no confirmation of what the response looks like, no failure modes, and no linkage to the add/remove dependency siblings. The thorough param schema partially offsets this, but the description itself is thin.

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 and links_to are fully documented with custom-ID support and a pointer to clickup_search, and workspace_id explains its conditional use. The description adds nothing beyond the schema, 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 (remove) and resource (a link between two tasks), so the operation is unambiguous. However, it offers no differentiation from the close siblings clickup_add_task_link (the inverse) or clickup_remove_task_dependency, which an agent must distinguish by name alone.

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 statement of when to use this tool, no prerequisites (e.g., the link must already exist), and no mention of alternatives such as removing a dependency instead. The agent is left to infer the entire selection context 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?

With no annotations, the description carries the burden and does disclose key traits: the credentials are short-lived, the tool does not perform the upload itself (the caller must 'follow the returned instructions to upload it with a native HTTP client'), and there is no size ceiling ('any size'). It stops short of stating how long the ticket lives, whether the attachment is auto-registered on the task after upload, or any permission/auth requirements, which are meaningful gaps for a two-step mutation flow.

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, both load-bearing: the first front-loads the returned payload shape (valuable because there is no output schema), the second handles routing. The parenthetical listing the four returned fields is dense but earns its space by substituting for a return-value 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?

For a tool with no annotations and no output schema, the description does the heavy lifting by enumerating the returned fields and describing the required follow-up HTTP step. It is missing only edge-case guidance such as ticket expiry duration, failure recovery if the upload times out, and whether the caller must confirm the attachment afterward.

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 each parameter already carries its own description, including the custom-ID support and the file_name default behavior. The description adds no parameter-level detail beyond the local-file framing, 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 short-lived, structured upload details') and enumerates exactly what is returned (upload URL, ticket, HTTP method, multipart field name). It also explicitly scopes the operation to LOCAL files and names the sibling it is not (attach_task_file), so an agent can distinguish it 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?

Gives an explicit when-to-use condition ('attach a LOCAL file (any size) to a task') and an explicit when-not with the correct alternative named ('For small base64 payloads or web URLs, use attach_task_file instead'). No inference is required to route between the two attachment tools.

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?

No annotations are provided, so the description carries the full disclosure burden. It conveys that this is a read-only conversion with no side effects implied, but does not state what happens for unresolved or ambiguous names, nor whether it errors or returns partial results.

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 core purpose followed by usage guidance. No wasted text.

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 2-parameter conversion tool with no output schema, the description is largely complete. A minor gap is failure/ambiguity behavior on unresolvable names, but nothing critical for correct invocation 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 coverage is 100%, so both parameters are already documented in the schema, including the 'me' and workspace_id semantics. The description adds no parameter detail beyond what the schema provides, making 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: converting names/emails/'me' into numeric ClickUp user IDs. The scope is precise and an agent can distinguish it from sibling tools like get_workspace_members or find_member_by_name.

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?

Gives a clear use case ('use when you need IDs for filters, e.g., search, filter_tasks') and a when-not hint ('most task tools resolve assignees automatically'). It does not name a specific alternative resolver tool, but the guidance is actionable.

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?

With no annotations, the description carries the burden and does it well: it discloses the pagination contract (next_cursor present means a single call is incomplete and the agent MUST loop), plus date-format and timezone semantics. It stops short of stating whether all parameters are optional and what happens if keywords is omitted, so a search with only filters is left unaddressed.

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?

Five sentences, each carrying distinct information, with scope and the sibling alternative front-loaded before the finer filter and pagination details. No filler or restatement of the tool name.

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, nested-object tool with no output schema, the description covers the highest-risk behavior (incomplete pagination) and the format of date filters. Since no output schema exists, some burden remains to describe what a result actually contains beyond next_cursor, and that gap is not filled.

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 goes beyond it by explaining the cursor loop contract, which is a stateful behavior the schema only gestures at. Date format and timezone are restated but not extended, and the nested location/asset_types filters are left entirely to 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 and resource ("Search across all workspace content") and enumerates the asset types covered (tasks, docs, dashboards, attachments, whiteboards, chats, forms). It also explicitly contrasts itself with filter_tasks, so an agent can distinguish it from the nearest sibling 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?

It gives both sides of the routing decision: use this for keyword/text matching across all content types, and use filter_tasks instead when filtering tasks by field values such as status, priority, tags, or dates. No exclusion is left implicit.

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?

With no annotations, the description carries the full behavioral burden. It does disclose pagination via cursor and that date filters are interpreted in the caller's timezone, which is genuinely useful context. It omits any statement of scope (all workspaces vs. one), default result set size, or what a returned reminder contains.

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?

Four short sentences, front-loaded with the core action, then filters, then the date-format caveat, then pagination. No sentence is redundant and nothing important is buried.

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 read-only, fully-optional-parameter search tool with complete schema coverage, this is nearly sufficient: formats, timezone semantics, and cursor pagination are all covered. The remaining gap is scope — whether results span all workspaces unless workspace_id is supplied — which the schema hints at but the description does not confirm.

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 eight parameters are already documented with formats, enums, and bounds. The description mostly restates the date format the schema already specifies; its one real addition is the 'in your timezone' interpretation note. 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 opens with a specific verb and resource: 'Search and list your reminders.' This clearly separates it from the create/update reminder siblings by operation type. It doesn't explicitly name those siblings, 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?

It lists the available filter dimensions (type, status, completion, since date), which implies when the tool is useful. However, it gives no explicit when-to-use vs. when-not guidance and never points to clickup_create_reminder or clickup_update_reminder as the write-side alternatives.

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?

No annotations are provided, so the description carries the full behavioral burden. It states that the tool sends a message and supports threading/markdown/post types, but says nothing about required permissions, side effects, rate limits, or expected response behavior for this 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 front-loaded with the core action, followed by the key threading condition and format support. It contains no filler and every sentence contributes to understanding the 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?

The schema is rich and fully documents the 11 parameters, which offsets much of the description's brevity. However, with no annotations and no output schema, the description could do more to explain behavioral context such as permissions or return values for a chat-sending 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?

Schema description coverage is 100%, so all parameters are already documented in the input schema. The description reinforces parent_message_id for threading and mentions markdown/post support, but adds little semantic detail beyond the schema itself, 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?

The description gives a specific verb and resource: send a message or threaded reply to a chat channel. It also distinguishes chat messaging from adjacent comment/task tools by naming the channel scope, and indicates support for post 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?

It gives one useful conditional: provide parent_message_id for threaded replies. However, it does not explain when to use the tool instead of alternatives such as comments, nor when to choose 'message' versus 'post' beyond the schema's enum constraints.

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?

No annotations exist, so the description carries the full burden. It usefully discloses the one-timer-at-a-time constraint, but leaves open what happens when a timer is already running (error, replacement, or silent no-op), whether the operation is idempotent, and what is returned.

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?

Four short sentences, front-loaded with the action and followed by capabilities, a constraint, and a caution. Nothing is padded, though the final advisory sentence is slightly redundant with the schema's own 'omit for best compatibility' note.

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 mutation tool with no annotations and no output schema, the description covers the core action and the key concurrency constraint. It still omits failure behavior, permission needs, and what the agent gets back, which matters for a tool that can conflict with a running timer.

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 of the five parameters is already documented in the schema and the baseline is 3. The description adds only a light usage hint ('omit extra parameters unless specifically needed') that is not parameter-specific.

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 ('Start time tracking on a task') that an agent can distinguish from stop_time_tracking and add_time_entry without opening the schema. It doesn't explicitly name sibling tools, but the action 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?

The description implies when to use it (starting a timer on a task) and adds a constraint ('Only one timer can be running at a time'), but it never names alternatives like stop_time_tracking or add_time_entry, nor says when a logged time entry is preferable to a live timer.

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?

With no annotations, the description carries the full burden. It discloses the return outcome ('Returns the completed time entry details') and that description/tags are applied to the entry, which is real added context, but says nothing about failure modes (no active timer), idempotency, or permission requirements 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?

Three short sentences, zero waste, with the core action front-loaded followed by accepted inputs and return behavior in a logical order.

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?

Adequate for a simple mutation: it covers action, inputs, and return value without an output schema needing further explanation. However, edge-case behavior (no running timer, behavior of tags on the completed entry) is left unstated for a no-annotation 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema, making 3 the baseline. The description's mention of 'description and tags' merely restates two schema fields and adds no semantics for workspace_id.

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 ('Stop the currently running time tracker') with scope ('currently running'), which cleanly separates it from clickup_start_time_tracking and clickup_add_time_entry. The follow-on sentences add what it accepts and what it returns.

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 'currently running' – the agent can infer this applies only when a timer is active – but there is no explicit when-to-use, no mention of what happens if no timer is running, and no named alternatives such as add_time_entry for manual logging.

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