ghl_project_create_task_comment

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the bar is lower; the description still adds the write scope, the v3 version header, server-side sanitisation to a published allowlist, and the exact response envelope `{ "comment": { … } }`. It does not explicitly state that repeated calls create duplicate comments, though that is implied by the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Roughly two-thirds of the text is generic API-wide preamble about hierarchy, lexorank positions, recurring-task fields, and delete cascades that is irrelevant to creating a comment. The actually useful sentences (purpose, threading, sanitisation, response) are pushed to the back rather than front-loaded.

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

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

For a create tool with 3 params, no output schema and full schema coverage, the description supplies endpoint, auth scope, input format, sanitisation behavior, threading constraint and return shape. An agent could call it correctly from this; only idempotency/duplicate behavior on retry is left implicit.

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% (baseline 3), but the description adds a real constraint the schema does not: replies are limited to one level, so a reply's parent must itself be top-level. It also reinforces that the field is TipTap body and sanitised to an allowlist, adding meaning beyond the property descriptions.

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

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

The description gives a precise verb+resource: 'Creates a top-level comment or a one-level reply (parentCommentId)', which clearly separates it from list/update/delete task comment siblings. However, this is buried after five sentences of unrelated project-management boilerplate (lexorank, recurring tasks, delete cascades) that do not describe this tool.

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

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

It states you can create either a top-level comment or a one-level reply, which implicitly tells the agent how to use parentCommentId, but it never says when to use this versus update_task_comment or list_task_comments, nor does it name prerequisites beyond the OAuth scope. Usage is implied rather than spelled out.

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