create_skill

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

Beyond the annotations, it discloses what is actually written (canonical content plus registration), the observable consequence of the sync flag (false avoids native copies, true synchronizes selected targets), the failure mode behind idempotentHint=false (repeated calls may conflict with an existing slug), and a hard precondition about project initialization. It also names the response contents, so an agent knows warnings and write references come back rather than a bare success.

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?

Purpose comes first, then sibling routing, then preconditions, then write behavior, then return values — a sensible front-loaded order for an agent scanning for a routing decision. Each sentence carries distinct information; none is filler, and the density is justified by a ten-parameter mutation tool.

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 non-idempotent write tool with ten parameters, this is complete: the agent learns when to pick it, when not to, what prerequisite must hold, what the sync flag changes on disk, what happens on repeat invocation, and roughly what comes back. Output-schema and annotation coverage are already supplied, and the description does not waste space duplicating them.

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 100%, so the schema already documents all ten parameters in detail, including the sync default and the targets fallback. The description restates the sync behavior but adds little syntax or semantics beyond what the schema provides. Baseline 3 is appropriate when the schema carries the parameter burden.

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 opening sentence gives a specific verb and resource ("Create a new canonical Agent Skill") and names the inputs it is built from (name, purpose, triggers, optional Markdown). This is immediately distinguishable from siblings such as create_skill_draft, import_skill, and adopt_skill, which the description names explicitly.

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 the selecting condition ("explicit new skill request") and then routes to three alternatives by name — import_skill for external/native directories, adopt_skill for existing canonical content, create_skill_draft for an editable draft. It also adds a second exclusion for the edit case ("use update_canonical_skill to edit it") and a precondition ("Project scope requires initialization"), leaving nothing to infer.

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