ghl_project_get_list_users

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds genuine behavior: RBAC filtering semantics (inaccessible ids omitted rather than erroring), no PII returned, and that skip/limit page across the combined direct+inherited set. The unrelated RBAC/lexorank/delete-cascade preamble adds noise rather than clarity for this 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 majority of the text is irrelevant boilerplate about task batch-get, lexorank `position`, recurring task fields, `updatedAt` sync, and delete cascades — none of which pertain to listing list users. The tool-specific content is buried after this preamble instead of 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 read-only paginated list tool with full param coverage and annotations, the relevant essentials are present: resource scope, auth scope (projects/workspace.readonly), endpoint, pagination behavior, and the shape hint (`source`: direct|inherited). No output schema exists, so the modest return-value description is acceptable.

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 baseline is 3, and the description earns a bump by explaining that `skip`/`limit` apply to the combined users list rather than one of the two sources. Minor inconsistency: it references a `total` value that is not an input parameter, which could mislead slightly.

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 operative sentence — 'Lists users with access to the list as one unified users page' — gives a specific verb and resource, and the hierarchy preamble situates a list inside spaces -> folders -> lists, which implicitly separates it from the folder/space user tools. It never names those siblings explicitly, so an agent still has to infer which scope tool to pick.

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 real usage context: there is no `query` filter, results merge direct and inherited access, and revocation is a separate DELETE endpoint — all of which steer invocation. No explicit 'use this instead of X when Y' routing against ghl_project_get_folder_users / ghl_project_get_space_users, which keeps 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.