clickup_doc_create

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

With no annotations, the description carries the full burden. It discloses that the doc starts with no pages, which informs behavior. It also mentions the return value includes the doc id. It does not cover auth needs or rate limits, but overall it adequately describes the non-destructive creation 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?

The description is three sentences, front-loaded with the main action, and each sentence adds value: creation, follow-up action, and optional attachment plus return value. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description mentions the return value (created doc object with id). It covers the core purpose, initial state, and optional parent placement. It does not mention error conditions or permissions, but for a straightforward create tool it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so baseline is 3. The description adds some context about the parent being optional and that team_id can be omitted to use default, but these nuances are already implied by the schema's optionality. It does not significantly enhance parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a ClickUp doc, specifies it starts with no pages and references the sibling tool for adding pages. It also mentions optional parent attachment, distinguishing it from other doc-related tools like clickup_doc_add_page or clickup_doc_edit_page.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (creating a new doc) and what to do next (add pages via clickup_doc_add_page). It also notes the optional parent attachment. However, it does not explicitly state when not to use it or list alternatives beyond the sibling tool.

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