ghl_project_get_folder

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

Annotations already declare readOnly, idempotent, non-destructive, so the description need not restate safety. It does add genuinely useful context beyond the schema: the endpoint path, the v3 Version header, and the required OAuth scope projects/workspace.readonly. However, most of the preamble (batch-get RBAC filtering, lexorank position, recurring tasks, delete cascades) does not apply to this tool and dilutes the behavioral signal.

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 actual purpose is buried after a long block of shared API boilerplate that is largely irrelevant to a single read. Two sentences of real content (purpose, endpoint, scope) are wrapped in eight sentences of noise, and the tool's own function is not 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 simple 2-param read with full schema coverage, annotations, and no output schema, the definition supplies the endpoint, version header, and auth scope, which is enough to call it correctly. Only a brief note on what a folder object contains is missing, which is minor.

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 both parameters are documented there, including the unusual locationId rules (APP channel only, ignored for OAuth/PIT). The description adds nothing about parameters 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?

"Get Folder — Fetches one folder by id" states a specific verb and resource, plus the exact endpoint GET /projects/folders/{folderId}. It is not confused with siblings such as ghl_project_get_space_folders or ghl_project_get_folder_lists, though it never names those siblings to make the distinction 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?

The description never says when to use this tool instead of get_space_folders, get_folder_lists, or get_list. The hierarchy preamble (spaces -> folders -> lists -> tasks) implies where folders sit but gives no selection guidance; the rest of the preamble concerns tasks, lexorank, and deletes, which are irrelevant to a single-folder read.

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