gopan

Overview Schema Source Related Servers Discussions Admin

create_folder

Creates a new folder under a specified parent ID/path or at root, and assigns a numbered name if a sibling already exists. Use create_directories to build nested paths safely.

Instructions

Create one new folder inside parent_id or parent_path (omit both for the root). If a sibling with the same name already exists, the new folder gets a numbered name instead of failing; the returned node shows the name actually used. To create a whole nested path in one call, reusing folders that already exist, use create_directories. Requires files:write; pass idempotency_key to make retries safe.

Input Schema

Name	Required	Description
`name`	Yes	new folder name
`parent_id`	No	parent folder UUID; omit for root
`parent_path`	No	absolute parent folder path instead of parent_id
`idempotency_key`	No	stable retry key, maximum 128 bytes

Output Schema

Name	Required	Description	Default
`id`	Yes
`kind`	Yes
`mime`	No
`name`	Yes
`path`	No
`size`	No
`sha256`	No
`parent_id`	No
`updated_at`	Yes
`stats_stale`	No
`subtree_bytes`	No
`subtree_count`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 7, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations only declare destructiveHint=false, so the description carries most of the burden and does well: it discloses name-collision behavior (auto-numbering rather than failure), that the returned node reflects the actual name used, the files:write permission requirement, and idempotency_key's retry-safety role. It stops short of describing failure modes beyond collisions, but covers the behavior an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with the core action and parent scoping, then collision semantics, then the alternative sibling, then prerequisites. Every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return format needn't be explained, yet the description still flags that the returned node shows the resolved name. Prerequisites, collision handling, root default, and the sibling alternative are all covered for a 4-param mutation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds meaning by framing parent_id vs parent_path as mutually exclusive alternatives with a root default, and by explaining why idempotency_key matters (safe retries) rather than just that it exists.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create one new folder') plus its scope ('inside parent_id or parent_path'). It explicitly distinguishes itself from the sibling create_directories, so an agent can pick correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete routing rules: omit both parent args for root, and use create_directories instead when creating a whole nested path. It names the alternative and the condition that selects it, leaving nothing to inference.

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