spine_create_project

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

With no annotations, the description carries the burden and does disclose the key traits: exactly what gets created (one 'root' bone), that overwrite replaces an existing file, that project must end in .json, and that spine_version falls back to $SPINE_VERSION or 4.3.00. It omits failure behavior (bad path, non-.json extension) and whether directories are created, which for a file-writing mutation is a remaining gap.

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 opening sentence front-loads the action and artifact, and the Args block is tightly scoped to one line per parameter with no filler. The parenthetical about spine_import_data is slightly buried at the end of the project entry rather than surfaced up front, which costs a bit of scannability.

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 an eight-parameter file-creating mutation with no annotations and an output schema (so return values needn't be described), the definition covers what is produced, how to convert it, and overwrite semantics. It is only missing edge-case behavior such as what happens with an existing file when overwrite is false or an invalid extension.

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 0%, so the description had to compensate and does: all eight parameters are documented in the Args block with meaning beyond the schema, including the .json extension constraint on project, the file-name default for name, the $SPINE_VERSION fallback, and what the image/audio folders map to in the skeleton. This is exactly the case where prose must carry parameter semantics and it succeeds.

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?

States a specific verb and resource ('Create a new Spine 4.x skeleton JSON file') and disambiguates the output from sibling tooling by naming spine_import_data as the path to the binary .spine format. An agent can tell this apart from spine_import_data or spine_list_projects from the first sentence alone.

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?

Gives a clear usage context via the progress note that the editor's .spine format is binary and must be reached through spine_import_data after this call. It does not explicitly say when not to use it (e.g., check spine_list_projects first, or the consequence of overwrite=false on an existing path), so it stops short of full when/when-not guidance.

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