create_folder

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). The description adds genuinely new behavioral facts: access control is only settable at the top level, nested folders inherit it, and folders cannot be deleted via the API. It does not address the non-idempotent hint, i.e. what happens when the same folder name or path is created twice.

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?

Four short sentences, purpose front-loaded, with the caveats following in descending order of importance. Every sentence carries information; the stray line breaks are the only cosmetic flaw.

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?

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. The description supplies the operationally important constraints for a mutation tool. Remaining gaps are duplicate-creation behavior and which of the mutually exclusive location parameters to choose.

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 coverage is 100%, so the baseline is 3, and the description does add one useful constraint tying parameters together: access_control_type only applies to a folder created by name with no parent. However, it never explains the selection logic among the six optional parameters — name vs. path, parent_id vs. parent_path — which is the most consequential semantic question for this tool.

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 first sentence gives a specific verb and resource ('Creates a folder'), and the second sentence carves out a boundary against the upload flow ('Uploads create folders on demand'), which implicitly separates it from upload_file. What keeps it from a 5 is that 'mainly for setting access control' narrows the stated purpose in a way that could make an agent think plain folder creation is not the intended use.

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 states a concrete when-to-use case (pre-creating a top-level folder so access control exists before content lands) and effectively a when-not-needed case (uploads auto-create folders). It does not cover edge cases such as what to do if the folder already exists or how this interacts with list_folders to check first.

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