Create package

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

Annotations already indicate this is a write operation (readOnlyHint false, destructiveHint false). The description adds context about creating a scaffold and directory structure, but does not disclose potential behavior such as whether existing files in the target directory would be overwritten or if the directory must be empty. More detail on side effects would be valuable.

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 well-structured with a brief opening sentence followed by a bullet list of use cases and a closing note about next steps. It is appropriately sized, front-loads the main purpose, and avoids unnecessary fluff, though a few of the bullet items overlap slightly.

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?

The description covers the tool's purpose, usage guidelines, and integration with sibling tools. However, with no output schema, it does not explain what the tool returns after creation (e.g., a success message, package path, or file listing). It also lacks details on prerequisites or behavior with existing directories, leaving some contextual gaps.

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 only 50% (ctx lacks a description). The description does not mention the ctx parameter at all, nor does it add meaningful information about package_dir beyond what the schema already provides. Since the description should compensate for low schema coverage, this is a notable gap.

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 clearly states the tool creates a new Tenzir package scaffold, with specific actions listed (starting a project, setting up directory structure, initializing metadata). It uses a specific verb+resource ('Create a new Tenzir package scaffold') and distinguishes from sibling tools by mentioning package_add_operator and package_add_test as follow-up steps.

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 lists when to use the tool ('Use this tool to: Start a new Tenzir package project...') and provides alternatives for subsequent steps ('After creation, use package_add_operator... and package_add_test...'). This gives clear context on both when to use and what to use instead for related tasks.

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