create_skill_draft

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

Annotations already declare destructiveHint=true and non-idempotent, and the description adds concrete behavior beyond them: an existing unregistered file at the draft path 'can be overwritten without confirmation' while only registered slug collisions are rejected, plus the advice to inspect the draft destination first. It also clarifies the non-obvious global-scope behavior that the physical file is not moved into user memory and that audit/snapshot writes use the project writer.

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 intent and alternative are front-loaded well, but the body is dense and partly redundant with the schema, restating the two draft paths and the global-scope registration nuance that the parameter descriptions already cover. Every sentence is informative, yet the same facts are repeated rather than compressed.

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 a destructive write tool with an output schema present, the description covers the safety profile, scope semantics, overwrite risk, and the validate-before-publish workflow, so an agent has what it needs. It stops short of noting permissions/auth requirements, which is the only notable omission.

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 schema already defines all six parameters, but the description adds real meaning: the exact draft paths per scope (.umem/drafts/skills/<slug>/SKILL.md vs drafts/skills/<slug>/SKILL.md) and the defaulting rule that omitted/empty triggers fall back to the skill name and that supplied raw_markdown takes precedence. It goes somewhat beyond a baseline 3 by clarifying cross-parameter interaction.

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 uses a specific verb+resource ('Create an editable skill draft') and explicitly bounds the scope ('without canonical publication or native runtime writes'), then names the sibling it is contrasted with: create_skill for direct canonical creation. An agent can distinguish this from create_skill/publish_skill 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.

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

It states when to use it ('when content needs review'), names the alternative for the other case ('use create_skill for direct canonical creation'), gives a prerequisite ('Project scope requires initialization'), and adds a follow-up path ('Validate with validate_skill before publish_skill'). Exclusions and routing are explicit.

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