create_directory

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

With no annotations provided, the description carries the full burden. It discloses the critical behavior 'Automatically creates all parent directories (like 'mkdir -p')', which is non-obvious and important for the agent to know. It does not mention edge cases like existing directories or permissions, but the core behavior is well-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 front-loaded but contains redundancy: the first sentence and the 'Use for' section overlap in meaning. The keywords list and Chinese translation are nice for search/localization but add length without contributing new conceptual information. It is not overly long but could be tighter.

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 tool is simple (1 param, output schema provided). The description covers the main purpose, key behavior, and use cases well. It lacks details on error handling or idempotency, but for a basic create-directory tool the description is sufficiently complete.

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% (as noted in context signals), and the schema already explains the 'path' parameter clearly with examples and behavior. The tool description adds no extra parameter detail beyond what the schema provides, so a baseline score of 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 description clearly states the verb and resource: 'CREATE NEW DIRECTORIES and folder structures.' It also specifies the key behavior of automatically creating parent directories, which distinguishes it from sibling tools like create_file. The purpose is unmistakable and differentiates well.

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 description provides explicit use cases: 'Use for creating folders, setting up directory structures, organizing project layout.' This gives clear when-to-use guidance, though it does not explicitly mention when not to use it or name alternative tools. Context from siblings implies the distinction, so it's clear but not exhaustive.

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