ghl_project_get_folder_lists

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds pagination behavior and names the `nextCursor`-style cursor paging, but items like RBAC filtering, subtask omission, and destructive-delete warnings describe other endpoints rather than this read tool. Net value beyond annotations is modest.

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 tool-specific part is two tight, well-structured sentences. The opening paragraph is shared boilerplate about lexorank, recurring tasks, task search and delete cascade behavior that does not apply to this read-only folder-lists call and pushes the actual purpose down the page.

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 4-parameter list endpoint with full schema coverage, annotations and no output schema, the description is sufficient to call it correctly. The only gap is that a reader must filter out irrelevant project-management boilerplate to find the relevant 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 description coverage is 100%, so limit, cursor, anchorId and folderId are already documented. The description only restates that limit/cursor should be used to page; it adds no syntax or semantics for anchorId or the cursor format 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?

The second section states a specific verb and resource: 'Get Lists In Folder' returns `lists[]` and explicitly contrasts with `items`, which is a useful disambiguation. However, the first paragraph is a generic project-management hierarchy primer that is not specific to this tool, which dilutes the front-loaded purpose.

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 through the example sequence ('open a folder view, then Create List In Folder for a client project') and the mention of paging through full result sets. There is no explicit statement of when NOT to use it or which sibling (e.g. get_space_lists, get_task_lists) to pick for a different scope.

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