ghl_project_create_space

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

Annotations already establish the mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the bar is lower. The description does add genuinely non-obvious behavior — a default list is seeded server-side but not returned on the public response — plus the OAuth scope and the `isPrivate` -> non-empty `userIds` coupling. It does not say what happens on duplicate names or how the new space is identified in the response.

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 tool guidance (three short lines: purpose, seeded-list caveat, endpoint/scope) is buried after a long API-wide preamble about task batch-get RBAC, lexorank positions, recurring-task field names, and search `updatedAt` — none of which bears on creating a space. Front-loading is poor and much of the text does not earn its place.

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 two-parameter create call with full schema coverage and no output schema, the description covers prerequisites (write scope), channel caveat via schema, and the surprising bit that a default list exists but is not returned. Missing only error/duplicate behavior and what identifier the created space returns, which is a minor gap.

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 the schema already documents `name`, `color` enum, `userIds`, `isPrivate`, and `locationId` in detail. The description adds only the privacy/userIds dependency, which the schema itself also states. Baseline 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 tool-specific sentence states a concrete verb and resource: "Creates a top-level space (optional privacy + `userIds` when private)." 'Top-level' usefully distinguishes it from sibling creators like `ghl_project_create_space_folder` and `ghl_project_create_space_list`. However, roughly two-thirds of the text is a generic PROJECT MANAGEMENT API preamble that does not describe this tool's 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?

The hierarchy line (spaces -> folders -> lists -> tasks) implies where a space sits, which is some help in choosing it over folder/list creation. But there is no explicit when-to-use statement, no named alternative, and no prerequisite guidance beyond the scope string.

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