create_folder

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

With only default false annotations, the description carries the burden of exposing behavior. It does well by disclosing the smart type-defaulting, the parent-child constraints, and the suite leaf-node rule. It does not mention side effects like return behavior or permissions, but the important behavioral traps are covered.

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 description is compact and front-loads the most important invocation detail with the 'IMPORTANT' note. Every sentence contributes either definition, hierarchy context, a default behavior, or the alias route, with no filler.

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?

The description plus rich schema covers creation intent, defaulting, and nesting rules thoroughly, making the tool safely selectable and callable. The only notable omission is the lack of any description of the response/return value, and there is no output schema to compensate.

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?

Because the input schema already covers 100% of parameters and even documents the auto-detection behavior for type and the 'suites cannot be parents' rule, the description adds little parameter-specific semantics beyond restating that context. The schema is doing the heavy lifting here.

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 clearly states the tool creates a folder or suite in a project and explains the structural difference: folders can nest, suites are leaf nodes. This active verb + resource pairing is unaffected, and the explicit mention of the create_suite alias helps differentiate it from a closely related sibling.

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 provides concrete, actionable usage rules: omit 'type' to use smart defaults (folder at root, suite when nested), and use the create_suite alias for suite-specific creation. This gives the agent a clear decision procedure for invoking the tool correctly and when to favor an alternative.

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