new_project

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

With no annotations, the description carries the full burden and discloses key non-obvious behaviors: the project exists only in memory until save_project is called, the project name is inherited from the .stu filename, and there is no settable project-name field. It also states exact-match requirements against the catalog, which is important acceptance behavior.

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 front-loaded with a one-sentence purpose, then gives focused parameter constraints and the critical persistence trait. Every sentence adds value; there is no filler.

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 invocation parameters, required catalog matching, and the in-memory-then-save lifecycle, which is sufficient for correct calling. It does not describe return values or error behavior, and with no output schema some agents might want that, but it does not compromise correct invocation.

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% description coverage, so the description fully compensates by detailing both parameters: cpu_part_number must exactly match a catalog CPU reference with examples, and cpu_version is the required firmware version offered by the catalog with an example. This is more than enough to invoke the tool correctly.

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 and resource: 'Create a new project from scratch for a given PLC CPU.' This clearly distinguishes it from open_project and change_cpu, and the subsequent save_project reference further disambiguates the lifecycle.

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 establishes clear context for when to use: creating a new project rather than opening an existing one, and it names save_project as the follow-up for persistence. It does not explicitly list when not to use it, but the 'from scratch' framing and memory-only caveat provide enough guidance.

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