create_project

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

With no annotations provided, the description carries the full burden of behavioral disclosure — and it exceeds expectations. It discloses the return value (session_token), side effect ('arms the chat exactly like init'), the no-double-confirm behavior, refusal conditions (existing paths, missing parents), and path-resolution rules (expand ~, home-relative interpretation). This provides far more than the annotation-level safety data would have, fully compensating for the absence of structured 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?

Every sentence earns its place: purpose, behavioral caveat, side effects, call conditions, path semantics, and refusal conditions are each covered once with no redundancy. The description is front-loaded with the core purpose and tapers into increasingly specific operational details, which is ideal for an agent scanning under time pressure.

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 1-parameter, no-output-schema, no-enum, no-nested-object tool, the description is complete: it covers the function, the return value, the state change, the error/refusal conditions, and the tricky interactive behavior (no second confirmation). The reference to 'exactly like init' conveniently routes the agent to sibling context without bloating the description. Nothing material is left unaddressed for its complexity profile.

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% (the `project` param's description is rich: 'Absolute path for the NEW project directory (must not exist yet; its parent must exist)'), which sets the baseline at 3. The tool description earns an additional point by contributing path-resolution semantics not in the schema — how to expand ~, interpret 'Desktop'/'Documents' as home-relative, and the instruction to resolve the absolute path autonomously. This is a genuine value-add beyond the schema.

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?

Uses a specific verb+resource pair ('Create a brand-new project DIRECTORY') and immediately clarifies the scope — git is NOT initialized, distinguishing it from the sibling `init`. The reader instantly knows what this does and how it differs from related tools. The parenthetical on git non-initialization specifically disambiguates from the sibling tool, satisfying the differentiation requirement.

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?

Explicit 'Call when...' language tells exactly when to invoke it, and 'Never suggest shell commands like mkdir instead' is an explicit exclusion of the alternative. The description also gives operational context about when to use this over the `init` sibling with the 'exactly like init' reference and explains the direct-call flow (no second ask). This is textbook when-to-use/when-not-to-use guidance.

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