skill_create

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

With no annotations provided, the description fully carries the transparency burden. It discloses the exact actions (creates directory, writes SKILL.md), the additive non-overwriting constraint, failure conditions (name invalid or already exists), and the placeholder insertion for empty bodies. This is thorough behavioral disclosure beyond what structured annotations could provide.

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 structured into labeled sections (function_purpose, Description, Constraints, Args, Returns) making it highly scannable and organized. While longer than the minimal ideal, each section contributes necessary information without redundancy or filler, earning a solid 4.

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 6-parameter creation tool with no annotations, the description is remarkably complete. It covers purpose, detailed constraints, parameter semantics, failure conditions, and return value structure. The agent has everything needed to select and invoke the tool correctly in context.

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% parameter description coverage, but the Args section directly compensates by explaining all 6 parameters with types and semantic meaning. It adds valuable guidance like 'hyphen-case recommended' for name, 'optional list of tool names' for allowed_tools, and the behavior for empty bodies, going beyond mere type definitions.

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 opens with a specific verb-resource pair: 'Create a new skill directory containing a SKILL.md per Agent Skills Spec.' This clearly identifies the tool's function and distinguishes it from sibling read-only tools like skill_list_all and skill_get_detail. It also clarifies the deliverable (SKILL.md file), making the purpose 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 provides clear contextual guidance: it is for creating new skills, is additive only, and fails if the skill already exists or the name is invalid. However, it does not explicitly specify when NOT to use this tool or point to alternatives (e.g., for updating existing skills), so it stops short of a 5.

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