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

Annotations already establish the safety posture (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the description need not restate mutation/destruction. It adds meaningful context beyond annotations: conflict semantics ('with conflicts rejected'), versioning requirements ('expected_version', 'stale writes fail'), and constraint pitfalls ('resource_type is link-only', 'never memory_id'). No contradiction with annotations.

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?

Roughly 110 words for a tool with 36 parameters and 8 schema variants — every sentence carries a distinct constraint and the core purpose is front-loaded. However, it is a single dense paragraph with heavy semicolon use, which reduces scannability when an agent needs to quickly locate the rule for a specific variant.

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?

Output schema exists, so return values need no explanation. The description covers all variants except the Settings mutation (entity='settings', action='save') and never mentions the idempotent replay key (client_mutation_id). Both are discoverable in the schema's oneOf branches and parameter descriptions, so the gap is minor, but for a tool this complex a complete walkthrough would include them.

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 baseline is 3. The description adds conditional selection semantics the flat schema doesn't convey: which parameters pair with which action, when project_id must be omitted, the memory_ref vs memory_id pitfall, and the top-level content/tags vs patch.content/patch.tags alternative. Some details duplicate schema descriptions (stale writes fail), but the selection logic and negative constraints are genuine added value.

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 opening sentence 'Create or mutate an authorized project' states a specific verb and resource while explicitly distinguishing the tool from read paths: 'use open_project_workspace or get_project_summary to read.' The body enumerates the entity variants (project, memory, decision, document, conversation), so an agent can tell this is the project-scoped mutation surface rather than one of the many read/sibling tools.

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?

Explicitly names the read alternatives and tells the agent when NOT to use this tool ('to read'). Per-variant selection rules are spelled out: 'Project create requires entity="project", action="create", and name, and omits project_id. Other actions require project_id.' Similar conditional guidance is given for memory, decision, document, and conversation mutations, leaving little to inference.

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