create-onedrive-folder

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

Annotations indicate readOnlyHint=false (it's a write), destructiveHint=true. The description adds value beyond annotations by explaining conflict behavior options (rename, replace, fail), which is behavioral context the annotations don't provide. It doesn't contradict annotations. Also includes a 'confirm' parameter for destructive gate, which aligns with destructiveness. Slight deduction for not mentioning other side effects, but solid overall.

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 concise: one opening sentence, a tip line, and then structured guidance. The most critical information (what body must contain, conflict behavior options) is front-loaded and formatted clearly. No wasted words; each part has purpose.

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?

For creating a folder, the description covers essential inputs: driveId, driveItemId, body requirements, conflict behavior. The schema is rich and well-covered. It could mention return values (since no output schema), but for creation tools, this is often obvious. Minor gap: unclear what happens on success (returns created folder item), but given the tool's simplicity, this is quite complete. Not a 5 because it lacks explicit mention of success behavior.

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 83%, high. The description adds critical meaning beyond schema: it explicitly says the body must include 'name' and 'folder' fields, and explains the conflictBehavior mechanism, which is not in the schema. This compensates well for the complexity of the body object. A 4 because it's genuinely helpful but could still deepen details like error handling.

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 states exactly what the tool does: 'Create a OneDrive folder' and specifies it creates inside a drive item. It clearly identifies the verb, resource, and context, and distinguishes from siblings like move-rename-onedrive-item and delete-onedrive-file which have different purposes.

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 explicitly instructs what the body must include ('name' and 'folder' fields) and how to use '@microsoft.graph.conflictBehavior' to control name conflicts. It implies the context of creation (inside a specified drive item) and is clear about required parameters, preventing incorrect usage.

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