create_folder

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

With no annotations provided, the description carries the full behavioral burden. It discloses a create mutation and optional nesting, but it does not state important behaviors such as idempotency (what if a folder with the same name exists), required parent existence, permissions, or what happens on failure/success. The only added note about optional nesting is already derivable from the schema (parent_id non-required), so it adds little beyond the structured data.

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 extremely lean: two sentences, four main pieces of information, no redundancy. The purpose is front-loaded ('Create a new folder') and the only nuance (optional nesting) follows directly. Every word earns its place, and the structure is ideal for a search model.

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?

Although the operation is relatively simple, the description is not complete enough for correct invocation. It doesn't mention the existence of a parent (e.g., that parent must already exist) or the output/return value (no output schema). An agent cannot tell from this description what success looks like or whether there are preconditions, side effects, or uniqueness constraints—important gaps for a create operation.

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?

The schema has 0% description coverage, so the tool description must compensate for the undefined parameter semantics. It does add the note that the folder may be nested under a parent, clarifying the parent_id purpose, but it does not describe the name parameter beyond its existence or any constraints. It fails to explain that 'parent' means a folder ID, the expected naming conventions, or how nested paths work, leaving the agent to infer too much.

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 a verb and resource: 'Create a new folder.' It also adds a key scoping nuance, 'Optionally nested under a parent,' which distinguishes it from sibling tools like update_folder, delete_folder, and create_note without needing to inspect those schemas. The resource and action are unambiguous.

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 offers no guidance on when to use this tool vs alternatives. It does not mention any exclusions, prerequisites, or competing tools, leaving the agent to infer solely from the tool name. Without context such as 'Use this when you need to create a folder and not when...' the selection criteria are absent.

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