ghl_project_create_space_list

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds useful context beyond them: the POST endpoint, the required OAuth scope 'projects/workspace.write', and the hierarchy position of lists. It does not describe the create response or duplicate-name behavior, but it adds meaningful operational context for a creation 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 actual operation is buried after a long general project-management preamble covering task batch-get, lexorank positions, recurring tasks, task search, and delete cascades — most of which is irrelevant to creating a list. That preamble dilutes the purpose and makes the description poorly 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?

Given the simple create operation, 100% schema coverage, and existing annotations, the description supplies the endpoint, OAuth scope, and hierarchy context needed to call the tool correctly. It lacks return-value details, but with no output schema and a straightforward creation endpoint, it is complete enough.

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 the nested body fields (name, color, userIds, isPrivate, locationId) are thoroughly documented in the schema itself. The description does not add parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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 names a specific verb and resource — 'Create List In Space' / 'Creates a list directly under a space' — and explicitly distinguishes the alternative path: 'Prefer Create List In Folder when the list should live inside a folder.' An agent can identify the operation and its scope without opening the schema.

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 gives a clear selection rule against the folder-based sibling: use this tool when the list should live directly under a space, otherwise prefer creating it in a folder. It does not enumerate when not to use the tool beyond that alternative, but the practical routing guidance is explicit.

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